Python标准库之SQLite3

包含了连接数据库、处理数据、控制数据、自定义输出格式及处理异常的各种方法。

官方文档：sqlite3 --- SQLite 数据库的 DB-API 2.0 接口 — Python 3.13.1 文档

官方文档SQLite对应版本：3.13.1

SQLite主页：SQLite Home Page

SQL语法教程：SQL Tutorial

笔记日期：2024年10月24日

系统：Windows10

PEP 249 - DB - API 2.0：PEP 249 – Python Database API Specification v2.0 | peps.python.org

SQLite3版本：3.42.1（print(sqlite3.sqlite_version)）

Python版本：3.12

说明：sqlite3是Python自带的标准库不能直接更新版本，而是和Python一起安装的，若要用最新版的sqlite则直接更新Python到最新版即可。

sqlite3——SQLite数据库的DB-API2.0接口

SQLite是一个C语言库，它可以提供一种轻量级的基于磁盘的数据库，这种数据库不需要独立的服务器进程，也允许需要使用一种标准的SQL查询语言来访问它。一些应用程序可以使用SQLite作为内部数据存储。可以用它来创建一个应用程序原型，然后再迁移到更大的数据库，比如PostgreSQL或Oracle。

sqlite3模块由Gerhard Haring编写。它提供了PEP 249所描述的符合DB-API2.0规范的SQL接口，并要求使用SQLite3.15.2或更新的版本。

Python标准库之SQLite3 1

教程 7

参考 11

模块函数（5个） 11

1、sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL) 11

2、sqlite3.complete_statement(statement) 14

3、sqlite3.enable_callback_tracebacks(flag) 15

4、sqlite3.register_adapter(type, adapter, /) 16

5、sqlite3.register_converter(typename, converter, /) 18

模块常量（13个） 20

——事务提交方式（1个） 20

1、sqlite3.LEGACY_TRANSACTION_CONTROL 20

——自定义转换器（2个） 20

1、sqlite3.PARSE_COLNAMES 20

2、sqlite3.PARSE_DECLTYPES 21

——SQL语句操作状态（3个） 22

1、sqlite3.SQLITE_OK 22

2、sqlite3.SQLITE_DENY 22

3、sqlite3.SQLITE_IGNORE 22

——其他（2个） 24

1、sqlite3.apilevel 24

2、sqlite3.paramstyle 24

——显示SQLite版本（4个） 24

1、sqlite3.sqlite_version 24

2、sqlite3.sqlite_version_info 24

3、sqlite3.version 24

4、sqlite3.version_info 25

——显示线程安全级别（1个） 25

1、sqlite3.threadsafety 25

连接对象 26

class sqlite3.Connection 26

——Connection类对象方法（21个） 26

1、cursor(factory=Cursor) 26

2、blobopen(table, column, row, /, *, readonly=False, name='main') 27

3、commit() 28

4、rollback() 28

5、close() 29

6、create_function(name, num_args, func, *, deterministic=False) 29

7、create_aggregate(name, num_arg, aggregate_class) 30

8、create_window_function(name,num_params,aggregate_class,/) 32

9、interrupt() 34

10、set_authorizer(authorizer_callback) 35

11、set_progress_handler(progress_handler, n) 38

报错：sqlite3.OperationalError: interrupte 39

12、set_trace_callback(trace_callback) 39

13、enable_load_extension(enabled, /) 41

14、load_extension(path, /, *, entrypoint=None) 42

15、iterdump(*, filter=None) 43

16、backup(target, *, pages=-1, progress=None, name='main', sleep=0.250) 44

17、getlimit(category, /) 45

18、setlimit(category, limit, /) 46

19、getconfig(op, /) 46

20、setconfig(op, enable=True, /) 47

21、serialize(*, name='main') 47

22、deserialize(data, /, *, name='main') 48

——Connection类对象属性（6个） 49

1、autocommit 49

2、in_transaction 50

3、isolation_level 50

4、row_factory 51

5、text_factory 52

6、total_changes 53

游标对象 54

class sqlite3.Cursor 54

——cursor对象方法（9个） 54

1、execute(sql,parameters=(),/) 54

2、executemany(sql, parameters, /) 55

3、executescript(sql_script, /) 56

4、fetchone() 57

5、fetchmany(size=cursor.arraysize) 58

6、fetchall() 59

7、close() 59

8、setinputsizes(sizes, /) 60

9、setoutputsize(size, column=None, /) 60

——cursor对象属性（6个） 60

1、arraysize 60

2、connection 61

3、description 62

4、lastrowid 63

5、rowcount 64

6、row_factory 65

Row对象 66

class sqlite3.Row 66

——Row对象方法（1个） 67

1、keys() 67

Blob对象 69

class sqlite3.Blob 69

——Blob对象方法（5个） 70

1、close() 70

2、read(length=-1, /) 70

3、write(data, /) 70

4、tell() 70

5、seek(offset, origin=os.SEEK_SET, /) 71

PrepareProtocol 对象 73

class sqlite3.PrepareProtocol 73

异常（10个） 74

——用户操作错误（2个） 74

1、exception sqlite3.OperationalError 74

2、exception sqlite3.IntegrityError 74

——编程错误（2个） 74

1、exception sqlite3.DataError 74

2、exception sqlite3.ProgrammingError 74

——模块错误（3个） 75

1、exception sqlite3.InterfaceError 75

2、exception sqlite3.NotSupportedError 75

3、exception sqlite3.InternalError 75

——数据库错误（1个） 75

1、exception sqlite3.DatabaseError 75

——其他错误（2个） 75

1、exception sqlite3.Warning 75

2、exception sqlite3.Error 75

SQLite 与 Python 类型 77

命令行接口 78

常用方案指引 79

如何在 SQL 查询中使用占位符来绑定值 79

如何将自定义 Python 类型适配到 SQLite 值 80

如何编写可适配对象 81

如何注册适配器可调用对象 81

如何将 SQLite 值转换为自定义 Python 类型 82

适配器和转换器范例程序 84

如何使用连接快捷方法 85

如何使用连接上下文管理器 86

如何使用 SQLite URI 87

如何创建并使用行工厂对象 88

如何处理非 UTF-8 文本编码格式 89

说明 90

事务控制 90

通过 autocommit 属性进行事务控制 90

通过 isolation_level 属性进行事务控制 91

问答 93

问：关系型和非关系型（NoSQL）数据库的区别 93

问：增加数据到表后，没有用commit提交事务，实际上数据有保存到吗 93

事务的工作原理 93

教程

在本篇教程中，你将会使用sqlite3模块的基本功能创建一个存储Monty Python的电影作品信息的数据库。本篇教程假定您在阅读前对于数据库的基本概念有所了解，例如cursors与transactions。

首先，我们需要创建一个新的数据库并打开一个数据库连接以允许sqlite3通过它来动作。调用sqlite3.connect()来创建与当前工作目录下tutorial.db数据库的连接，如果它不存在则会隐式创建它：

import sqlite3

con = sqlite3.connect("tutorial.db")

上面的代码中，返回的Connection对象con代表一个与在磁盘上的数据库（on-disk database）的连接。

为了执行SQL语句并且从SQL查询中取得结果，我们需要使用游标（cursor）。在下面的代码中，我们调用函数con.cursor()创建了一个游标（Cursor）：

cur = con.cursor()

通过上面的操作，我们已经得到了与数据库的连接（connection）与游标（cursor），现在我们便可以在数据库中创建一张名为movie的表了，它包括电影名（title，在下方代码中对应“title”）、上映年份（release year，在下方代码中对应“year”）以及电影评分（review score，在下方代码中对应“score”）这三列。在本篇教程中，出于简洁的考虑，我们在创建表的SQL语句声明中列出表头名（column names），而没有像一般的SQL语句那样同时声明数据列的对应数据类型——这一点得益于SQLite的flexible typing特性，它使得我们在使用SQLite时，指明数据类型这一项工作时可选的。如下面的代码所示，我们通过调用函数cur.excute(...)执行创建表格的CREATE TABLE语句：

cur.execute("CREATE TABLE movie(title,year,score)")

我们可以通过查询SQLite内置的sqlite_master表以验证新表是否已经创建，本例中，此时该表应该已经包括了一条movie的表定义（更多内容请参考The Schema Table）。下面的代码将通过调用函数cur.excute(...)执行查询，把结果赋给res，而后调用res.fetchone()获取结果行：

>>>res = cur.execute("SELECT name FROM sqlite_master")

>>>res.fetchone()

('movie',)

我们可以看到表已被创建，因为查询结果返回了一个包含表名的tuple。如果我们在sqlite_master中查询一个不存在的表spam，则res.fetchone()将返回NOne：

>>>res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")

>>>res.fetchone() is None

True

现在，让我们再次调用cur.execute(...)去添加由SQL字面量（literals）提供的两行数据：

cur.execute("""

INSERT INTO movie VALUES

('Monty Python and the Holy Grail', 1975, 8.2),

('And Now for Something Completely Different', 1971, 7.5)

""")

INSERT语句将隐匿地创建一个事务（transaction），事务需要在将更改保存到数据库前提交（更多细节参考事务控制）。我们通过在一个连接对象（本例中为con）上调用con.commit()提交事务。

con.commit()

我们可以通过执行一个SELECT查询以验证数据是否被正确地插入表中。下面的代码中，我们使用我们已经很熟悉的函数cur.execute(...)将查询结果赋给res，而后调用res.fetchall()返回所有的结果行：

>>>res = cur.execute("SELECT score FROM movie")

>>>print(res.fetchall())

[(8.2,), (7.5,)]

上面的代码中，结果是一个包含了两个元组（tuple）的列表（list），其中每一个元组代表一个数据行，每个数据行都包括该行的score值。现在，让我们调用cur.executemany(...)再插入三行数据：

data = [

("Monty Python Live at the Hollywood Bowl", 1982, 7.9),

("Monty Python's The Meaning of Life", 1983, 7.5),

("Monty Python's Life of Brian", 1979, 8.0),

]

cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)

con.commit() # 记得在执行INSERT之后提交事务

请注意，占位符（placeholders）？是用来在查询中绑定数据data的。在绑定Python的值到SQL语句中时，请使用占位符取代格式化字符串（string formatting）以避免SQL注入攻击（更多细节请参见如何在SQL查询中使用占位符来绑定值）。

同样的，我们可以通过执行SELECT查询验证新的数据行是否已经插入表中，这一次我们将迭代查询的结果：

>>>for row in cur.execute("SELECT year, tile FROM movie ORDER BY year"):

print(row)

(1971, 'And Now for Something Completely Different')

(1975, 'Monty Python and the Holy Grail')

(1979, "Monty Python's Life of Brian")

(1982, 'Monty Python Live at the Hollywood Bowl')

(1983, "Monty Python's The Meaning of Life")

如上可见，每一行都是包括（year，title）这两个元素的元组（tuple），它与我们查询中选中的数据列相匹配。

最后，让我们先通过调用con.close()关闭现存的与数据库的连接，而后打开一个新的连接、创建一个新的游标、执行一个新的查询以验证我们是否将数据库写入到了本地磁盘上：

con.close()

new_con = sqlite3.connect("tutorial.db")

new_cur = new_con.cursor()

res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")

title, year = res.fetchone()

print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')

new_con.close()

现在您已经成功地使用模块sqlite3创建了一个SQLite数据库，并且学会了以多种方式往其中插入数据与检索值。

参考

模块函数（5个）

1、sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)

sqlite3.connect()是Python的sqlite3模块中用于连接SQLite数据库的函数。通过这个方法，可以创建一个数据库连接对象，以便执行SQL查询和操作数据库。

参数

database(path-like object)：要连接的数据库文件的路径。如果文件不存在，SQLite会自动创建一个新的数据库。

你可以传入":memory:"来创建一个仅存在于内在中的SQLite数据库，并打开它的一个连接。

timeout(float)：在尝试获取锁时的超时时间（以秒为单位）。默认为5秒。

当一个表被锁定时连接在最终引发OperationalError之前应该等待多少秒。如果另一个链接开启了一个事务来修改一个表，该表将被锁定直到该事务完成提交。

detect_typs(int)：用于指定如何检测类型。可以是以下值的组合：

0：默认值，不进行类型检测

1：检测DATE和TIME类型

2：检测NUMERIC类型

3：检测所有类型

控制是否以及如何使用由register_converter()注册的转换器将并非由SQLite原生支持的数据类型转换为Python类型。将它设置为PARSE_DECLTYPES和PARSE_COLNAMES的任意组合（使用|，即按位或）来启动它。如果两个旗标都被设置则列名将优先于声明的类型。即使设置了detect_types，依然无法对生成的字段（例如max(data)）进行类型检没此时它将改为返回str。当使用默认值（0）时，类型检测将被禁用。

isolation_level(str|None)：指定事务的隔离级别。可以是以下值：

None：自动提交模式（表示禁止隐式地开启事务）

""：事务模式

"DEFERRED"（默认值）：延迟事务

"IMMEDIATE"：立即事务

"EXCLUSIVE"：独占事务

除非Connection.autocommit设为LEGACY_TRANSACTION_CONTROL（默认值）否则没有任何影响。

check_same_thread(bool)：如果为True（默认），则同一连接只能在创建它的线程中使用。

ProgrammingError将在数据库连接被它的创建者以外的线程使用时被引发。

如果为False，则连接可以在多个线程中被访问；写入操作需要由用户者进行序列化以避免数据损坏。请参阅thraedsafety了解详情。

factory(Connection)：用于创建连接对象的工厂类，默认为Connection。

如果您不想使用默认的Connection类创建连接，那么您可以通过传入一个自定义的Connection类的子类给该参数以创建连接。

cached_statements(int)：指定缓存的SQL语句的数量，默认为128.

该参数指明sqlite3模块应该为该连接进行内部缓存的语句（statements）数量。

uri(bool)：如果为True，则database参数被视为URI。

参数database将会被解释为一个由文件路径与可选的查询字符串组成的URI（uniform resource identifier，统一资源标识符）链接。链接的前缀协议部分（chema part）必需是“file:”，后面的文件路径可以是相对路径或绝对路径。查询字符串允许向SQLite传递参数，以实现不同的

autocommit(bool)：控制PEP 249事务处理行为。autocommit目前默认值为LEGACY_TRANSACTION_CONTROL。在未来的Python版本中默认值将变为False。

返回类型：Connection

在3.4版本发生变更：增加了uri参数

在3.7版本发生变更：database现在可以是一个path-like object对象了，而不仅仅是字符串

在3.10版本发生变更：增加了sqlite3.connect/handle审计事件

在3.12版本发生变更：增加了autocommit形参

在3.13版本发生变更：形叁timeout，detect_types，isolation_level，check_same_thraed，factory，cached_statements，和uri用作为位置参数做法已被弃用。它们将在Python3.15中成为限仅关键字形参。

示例：

import sqlite3

# 连接到数据库（如果数据库不存在，则创建一个新的数据库）

con = sqlite3.connect('test.db')

# 创建一个游标对象

cursor = con.cursor()

# 创建一个表

cursor.execute('''

CREATE TABLE IF NOT EXISTS users (

id INTEGER PRMARY KEY,

name TEXT NOT NULL,

age INTEGER

)

''')

# 插入数据

cursor.execute('''

INSERT INTO users (name, age) VALUES (?, ?)

''',('大飞', 32))

# 提交事务

con.commit()

# 查询数据

cursor.execute('SELECT * FROM users')

rows = cursor.fetchall()

# 打印查询结果

for row in rows:

print(row) # (None, '大飞', 32)

# 关闭游标和连接

cursor.close()

con.close()

2、sqlite3.complete_statement(statement)

用于检查给定的SQL语句是否完整。

这个方法在处理多行SQL语句时特别有用，可以帮助确定当前的SQL语句是否可以被执行。

如果传入的字符串语句（statement）看起来像是包括一条或多条完整的SQL语句，那么该函数将返回True。请注意，除了检查未封闭的字符串字面（unclosed string literals）以及语句是否以分号结束外，它不会执行任何的语法检查（syntactic verification）与语法解析（synatatic parsing）。

参数类型：str

返回值：True｜False

示例：

>>>sqlite3.complete_statement("SELECT foo FROM bar;")

True

>>>sqlite3.complete_statement("SELECT foo")

False

该函数可能在这样的情形下非常有用：在通过命令行（command-line）输入数据时，可使用该函数判断输入文本是否可以构成一个完成的SQL语句，或者判断在调用函数execute()前是否还需要额外的输入。

3、sqlite3.enable_callback_tracebacks(flag)

用于启用或禁用回调函数的追踪信息。可以帮助开发者追踪回调函数的调用情况。

是否启用回调回溯（callback trackbacks）。默认情况下，在SQLite中，您不会在用户定义的函数、聚合函数（aggregates）、转换函数（converters）、验证回调函数（authorizer callbacks）等中等到任何回溯信息。如果您想调试它们，您可以在将形式参数flag设置为True的情况下调用该函数。之后您便可以从sys.stderr的回调中得到回溯信息。使用False将再次禁用该功能。

备注：用户自定义函数回调中的错误将被记录为不可引发的异常。请使用不可引发的钩子处理器执行对失败回调的内省。

参数类型：bool，设置为True则启用回调追踪；如果设置为False（默认），则禁用回调追踪。默认情况下是禁用的。

示例：

import sqlite3

# 启用回调追踪

sqlite3.enable_callback_tracebacks(True)

def my_callback(statement):

print("Callback called with statement:", statement)

# 创建一个数据库连接

connection = sqlite3.connect(':memory:')

# 设置回调函数

connection.set_trace_callback(my_callback)

# 创建一个游标

cursor = connection.cursor()

# 创建一个表

cursor.execute('CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)')

# 插入数据

cursor.execute('INSERT INTO test (value) VALUES (?)', ('Hello',))

# 查询数据

cursor.execute('SELECT * FROM test')

# 获取并打印查询结果

rows = cursor.fetchall()

for row in rows:

print(row)

# 关闭游标和连接

cursor.close()

connection.close()

输出：

Callback called with statement: CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)

Callback called with statement: BEGIN

Callback called with statement: INSERT INTO test (value) VALUES ('Hello')

Callback called with statement: SELECT * FROM test

(1, 'Hello')

4、sqlite3.register_adapter(type, adapter, /)

用于注册自定义适配器，以便将特定类型的Python对象转换为SQLite数据库可以存储的格式。这在处理自定义数据类型时非常有用。

注册adapter callable以将Python类型type适配为一个SQLite类型。该适配器在调用时会传入一个type类型的Python对象作为其唯一参数，并且必须返回一个SQLite原生支持的类型的值。

参数

type：类型type，要注册适配器的Python数据类型。例如，可以是datetime.datetime或自定义类。

adapter：类型callable，一个函数或可调用对象，用于将指定类型的Python对象转换为SQLite支持的类型（如字符串、整数等）。该适配器函数接受一个参数（要转换的对象）并返回转换后的值。

示例：

import sqlite3

import datetime

# 定义适配器函数，将datetime对象转换为字符串

def adapt_datetime(dt):

return dt.isoformat() # 转换为ISO格式的字符串

# 注册适配器

sqlite3.register_adapter(datetime.datetime, adapt_datetime)

# 创建一个数据库连接

connection = sqlite3.connect(':memory:')

# 创建一个游标

cursor = connection.cursor()

# 创建一个表，包含datetime类型的字段

cursor.execute('CREATE TABLE events (id INTEGER PRIMARY KEY, event_time TEXT)')

# 插入当前时间

now = datetime.datetime.now()

cursor.execute('INSERT INTO events (event_time) VALUES (?)', (now,))

# 查询数据

cursor.execute('SELECT * FROM events')

rows = cursor.fetchall()

# 打印查询结果

for row in rows:

print(row) # (1, '2024-10-28T15:03:03.832984')

# 关闭游标和连接

cursor.close()

connection.close()

5、sqlite3.register_converter(typename, converter, /)

用于注册自定义转换器，以便将SQLite数据库中的特定类型的值转换为Python对象。这在处理自定义数据类型时非常有用。

注册converter callable以将typename类型的SQLite对象转换为一个特定类型的Python对象。转换器会针对所有类型为typename的SQLite值发起调用；它会传递一个bytes对象并且应该返回一个所需的Python类型的对象。请参阅connect()的detect_types形参了解有关类型检测工作方式的详情。

注：typename以及您在查询中使用的类型名是不大小写敏感的。

参数

typename：类型str，要注册转换器的SQLite数据类型名称。例如，可以是'INTEGER'、'TEXT'、'BLOB'等。

converter：类型callable，一个函数或可调用对象，用于将SQLite中的值转换为Python对象。该转换器函数接受一个参数（要转换的值）并返回转换后的Python对象。

示例：

import sqlite3

# 定义一个简单的自定义类

class CustomData:

def __init__(self, value):

self.value = value

def __repr__(self):

return f"CustomData(value={self.value})"

# 定义转换器函数，将字符串转换为CustomData对象

def convert_custom_data(value):

return CustomData(value.decode('utf-8')) # 存储为UTF-8编码的字符串

# 注册转换器

sqlite3.register_converter("custom_data", convert_custom_data)

# 创建一个数据库连接，启用转换器

connection = sqlite3.connect(':memory:', detect_types=sqlite3.PARSE_DECLTYPES)

# 创建一个游标

cursor = connection.cursor()

# 创建一个表，包含custom_data类型的字段

cursor.execute('CREATE TABLE items (id INTEGER PRIMARY KEY, data custom_data)')

# 插入数据

cursor.execute('INSERT INTO items (data) VALUES (?)', (sqlite3.Binary(b'Hello, World!'),))

# 查询数据

cursor.execute('SELECT * FROM items')

rows = cursor.fetchall()

# 打印查询结果

for row in rows:

print(row) # (1, CustomData(value=Hello, World!))

# 关闭游标和连接

cursor.close()

connection.close()

模块常量（13个）

——事务提交方式（1个）

1、sqlite3.LEGACY_TRANSACTION_CONTROL

将autocommit设为该常量以选择旧式（Python3.12之前）事务控制行为。

在这种模式下，SQLite会在每个SQL语句执行时自动开始和提交事务，不需要手动管理事务（即可以省略con.commit()方法，但使用的话也不会报错）。

注意：使用此模式，可能会影响性能和并发性。

示例：

# 设置 autocommit 模式为 LEGACY_TRANSACTION_CONTROL

conn.execute('PRAGMA autocommit = LEGACY_TRANSACTION_CONTROL')

——自定义转换器（2个）

1、sqlite3.PARSE_COLNAMES

用作connect()方法的detect_types参数，以便在查询中解析列名，并根据列名查找相应的转换器。

将这个旗标传递给connect()的detect_types形参，以使用从查询列名解析的类型名作为转换器字典键来查找转换器函数。类型名称必须用方括号([])括起来。

SELECT p as "p [point]" FROM test; ! will look up converter "point"

此旗标可以使用|（位或）运算符与PARSE_DECLTYPES组合。

示例：

import sqlite3

# 定义转换器函数

def point_converter(value):

# 将字节对象解码为字符串

value = value.decode('utf-8') # 假设使用 UTF-8 编码

# 假设 value 是一个字符串，格式为 "x,y"

x, y = map(float, value.split(','))

return (x, y) # 返回一个元组表示点

# 注册转换器

sqlite3.register_converter("point", point_converter)

# 创建数据库连接，使用 PARSE_COLNAMES 解析列名

conn = sqlite3.connect(':memory:', detect_types=sqlite3.PARSE_COLNAMES)

# 创建表

conn.execute('CREATE TABLE IF NOT EXISTS test (p point)')

# 插入数据

conn.execute('INSERT INTO test (p) VALUES (?)', ('1.0,2.0',))

# 查询数据，使用列名解析

query = 'SELECT p AS "p [point]" FROM test'

cursor = conn.execute(query)

# 获取结果

for row in cursor:

print(row[0]) # 输出转换后的点 (1.0, 2.0)

# 关闭连接

conn.close()

2、sqlite3.PARSE_DECLTYPES

用于根据表中声明的列类型查找转换器。

将这个旗标值传递给connect()的detect_types形参，以使用创建数据库表时为每列声明的类型的查找转换器函数。sqlite3将使用声明类型的第一个单词作为转换字典键来查找转换函数。例如：

CREATE TABLE test(

i integer primary key, -- will look up a converter named "integer"

p point, -- will look up a converter named "point"

n number(10) -- will look up a converter named "number"

)

此旗标可以使用|（位或）运算符与PARSE_COLNAMES组合

示例：

# 这两个常量可以组合使用，以便同时解析列名和声明类型

conn = sqlite3.connect(':memory:', sqlite3.PARSE_COLNAMES | sqlite3.PARSE_DECLTYPES)

——SQL语句操作状态（3个）

1、sqlite3.SQLITE_OK

表示SQL语句操作成功的状态码

2、sqlite3.SQLITE_DENY

表示SQL语句操作被拒绝的状态码

3、sqlite3.SQLITE_IGNORE

应当由传给Connection.set_authorizer()的authorizer_callback callable返回的旗标，用于指明是否：

访问被允许（SQLITE_OK）
SQL语句伴异常的执行失败（SQLITE_DENY）
该列应被视NULL（SQLITE_IGNORE）

综合示例：

import sqlite3

# 定义授权回调函数

def authorizer_function(action, table, column, sql_location, ignore):

# 如果尝试访问名为'secret_column'的列

if column == 'secret_column':

# 返回SQLITE_IGNORE，将其视为NULL

return sqlite3.SQLITE_IGNORE

# 对于其他列，允许访问

return sqlite3.SQLITE_OK

# 连接到SQLite数据库（这里使用内存数据库）

conn = sqlite3.connect(':memory:')

# 设置授权回调函数

conn.set_authorizer(authorizer_function)

# 创建一个示例表

conn.execute('CREATE TABLE example (id INTEGER PRIMARY KEY, public_data TEXT, secret_column TEXT)')

# 插入一些数据

conn.execute('INSERT INTO example (public_data, secret_column) VALUES (?, ?)', ('public info', 'secret info'))

# 尝试查询secret_column，但由于授权回调，它将被视为NULL

cursor = conn.execute('SELECT id, public_data, secret_column FROM example')

# 获取查询结果

row = cursor.fetchone()

print(row) # 输出将显示(id, public_data, None)因为secret_column被视为NULL

# 关闭数据库连接

conn.close()

——其他（2个）

1、sqlite3.apilevel

用于让开发者了解当前使用的数据库接口版本。对于SQLite3模块，通常返回值是'2.0'，这表明它遵循PEP 249中定义的DB-API 2.0规范。

指明所支持的DB-API级别的字符串常量。根据DB-API的需要设置。硬编码为“2.0”。

2、sqlite3.paramstyle

用于指示该模块支持的参数样式。

通常返回值是'qmark'，表示使用问号（？）作为参数的占位符。这是SQLite中最常用的参数样式。

示例：

cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))

——显示SQLite版本（4个）

1、sqlite3.sqlite_version

以字符串表示的运行时SQLite库版本号（如：3.43.1）

2、sqlite3.sqlite_version_info

以整数tuple表示的运行时.SQLite库版本号（如：(3, 43, 1)）

3、sqlite3.version

表示当前Python的sqlite3模块的版本号（此版本号是与Python版本绑定的，实际运行时是以实际使用的sqlite3版本号为准，即sqlite3.sqlite_version）

此模块字符串形式的版本号。这不是SQLite库的版本号（当前值：2.6.0）。

在3.12版本弃用，将会在3.14版本移除：这个常量原来是用于反映pysqlite包的版本号，它是一个用于对sqlite3进行上游修改的第三方库，如今已不具任何意义或实用价值。

4、sqlite3.version_info

此模块整数tuple形式的版本号。这是SQLite库的版本号。

sqlite3 --- SQLite 数据库的 DB-API 2.0 接口 — Python 3.13.1 文档

——显示线程安全级别（1个）

1、sqlite3.threadsafety

用于指示该模块的线程安全级别（当前值为3，代表线程安全）。

DB-API2.0所要求的整数常量，指明sqlite3模块支持的线程安全级别。该属性将基于编译下层SQLite库所使用的默认线程模式来设置。SQLite的线程模式有：

Single-thread：在此模式下，所有的互斥都被禁用并且SQLite同时在多个线程中使用将是不安全的。
Multi-thread：在此模式下，只要单个数据库连接没有被同时用于两个或多个线程之中SQLite就可以安全地被多个线程所使用。
Seralized：在序列化模式下，SQLite可以安全地被多个线程所使用而没有额外的限制。

从SQLite线程模式到DB-API2.0线程安全级别的映射关系如下：

SQLite 线程模式	threadsafety	SQLITE_THREADSAFE	DB-API 2.0 含义
single-thread	0	0	各个线程不能共享模块
multi-thread	1	2	线程可以共享模块，但不能共享连接
serialized	3	1	线程可以共享模块、连接和游标Threads may share the module, connections and cursors

在3.11版本发生变更：动态设置threadsafety而不是将其硬编码为1.

连接对象

class sqlite3.Connection

Connection类代表一个连接的数据库对象，用于执行SQL语句，进行事务管理。

每个打开的SQLite数据库均以Connection对象来表示，这种对象是使用SQLite3.connect()创建的。它们的主要目的是创建Cursor对象，以及事务控制。

在3.13版本发生变更：如果未在Connection对象被删除前调用close()则会发出ResourceWarning

SQLite数据库连接对象有如下的属性和方法：

——Connection类对象方法（21个）

1、cursor(factory=Cursor)

创建并返回Cursor对象。cursor方法接受一个可选参数factory。如果提供了这个参数，它必须是一个callable并且返回Cursor或其子类的实例。

用于创建一个游标对象，游标是执行SQL语句和获取结果的主要工具。

示例：

con = sqlite3.connect('tutorial.db') # 连接到数据库

cursor = con.cursor() # 创建游标

cursor.execute('''......''') # 执行SQL语句

cursor.close() # 关闭游标

con.commit() # 提交事务

con.close() # 关闭数据库连接

**2、blobopen(table, column, row, /, *, readonly=False, name='main')**

打开一个已有的BLOB（Binary Large Object，二进制大型对象）Blob句柄。

参数

table(str)：二进制大对象blob所在表的名称

column(str)：二进制大对象blob所在表的列名

row(str)：二进制大对象blob所在的行名

readonly(bool)：如果blob应当不带写入权限打开则设为True，默认为False。

name(str)：二进制大对象blob所在的数据库名。默认为'main'。

抛出：OperationalError：当尝试打开WITHOUT ROWID的表中的某个blob时。

返回类型：Blob

备注：blob的大小无法使用Blob类来修改。可使用SQL函数zeroblob来创建固定大小的blob。

Added in version 3.11

说明：在SQLite中。BLOB类型用于存储大量的二进制数据。

如：图像文件（JPEG/PNG/GIF等）、音频文件（如MP3/WAV/AAC）、视频文件（如MP4/AVI/MOV）、文档文件（如PDF/WORD/EXCEL）、其他（如ZIP/二进制数据流）

示例：

import sqlite3

# 连接到数据库

conn = sqlite3.connect('tutorial.db')

# 创建表以存储BLOB数据

conn.execute('''

CREATE TABLE IF NOT EXISTS images (

id INTEGER PRIMARY KEY,

name TEXT,

data BLOB

)

''')

# 插入BLOB数据

with open('example_image.png', 'rb') as file:

image_data = file.read()

conn.execute("INSERT INTO images (name, data) VALUES (?, ?)", ('example_image', image_data))

# 提交更改

conn.commit()

# 读取BLOB数据

cursor = conn.cursor()

cursor.execute("SELECT rowid, data FROM images WHERE name = 'example_image'")

row = cursor.fetchone()

if row:

rowid, blob_data = row

# 使用blobopen读取BLOB数据

with conn.blobopen('images', 'data', rowid, readonly=True) as blob:

with open('output_image.png', 'wb') as output_file:

output_file.write(blob.read())

# 关闭连接

cursor.close()

conn.close()

3、commit()

向数据库提交任何待处理事务。如果autocommit为True，或者没有已开启的事务，则此方法不会做任何操作。如果autocommit为False，则如果有一个待处理事务被此方法提交则会隐匿地开启一个新事务。

4、rollback()

用于撤销数据库事务的函数，通常与数据库连接对象一起使用。它的主要作用是将数据库的状态恢复到上一个提交点，通常在发生错误或异常时使用，以确保数据一一致性和完整性。

如果：attr:!autocommit为False，则如果此方法回滚了一个待处理事务则会隐匿地开启一个新事务。

5、close()

关闭数据库连接。如果autocommit为False，则任何待处理事务都会被隐式地回滚。如果autocommit为True或LEGACY_TRANSACTION_CONTROL，则不会执行隐式的事务控制。请确保在关闭之前commit()以避免丢失待处理的更改。

**6、create_function(name, num_args, func, *, deterministic=False)**

创建或移除用户定义的SQL函数。

参数

name(str)：要注册的函数名称（字符串）。在SQL查询中使用时，必须使用这个名称。

num_args(int)：该函数可接受的参数数量，如果是-1，则该函数可以接受任意数量的参数。

func(callback|None)：实际的Python函数，定义了函数的逻辑。该函数接受与num_params相同数量的参数，并返回一个值。该可调用对象必须返回一个SQLite原生支持的类型。设为None将移除现有的SQL函数。

deterministic(bool)：如为True，创建的SQL函数将标记为deterministic，这允许SQLite执行额外的优化。

在3.8版本发生变更：增加了deterministic形参。

在3.13版本发生变更：将name，num_arg和func作为关键字参数传入的做法已被弃用。这些形叁将在Python3.15中成为仅限位置形叁。

示例：

# 定义一个Python函数

def max_value(a, b):

return max(a, b)

...

# 注册自定义函数

connection.create_function("max_value", 2, max_value)

# 查询并使用自定义函数

cursor = connection.cursor()

cursor.execute("SELECT id, num1, num2, max_value(num1, num2) AS max_num FROM numbers")

rows = cursor.fetchall()

7、create_aggregate(name, num_arg, aggregate_class)

创建或移除用户自定义的SQL聚合函数。

用于注册用户自定义聚合函数，用于对一组值进行计算并返回单个值，常见的聚合函数包括SUM/AVG/COUNT等。

参数

name(str)：要注册的聚合函数名称（字符串）。在SQL查询中使用时，必须使用这个名称。

num_arg(int)：该聚合函数接受的参数数量（整数）。如为-1，则接受任意数量参数。

aggregate_class(class|None)：一个类，定义了聚合函数的逻辑。该类必须实现两个方法：

step(self,*args)：向聚合添加一行。在每次调用聚合函数时执行，接收当前行的参数。

finalize(self)：将聚合的最终结果作为一个SQLite原生支持的类型返回。在聚合函数完全时执行，返回最终结果。*step()方法需要接受的参数数量是由num_arg控制的。设为None将移除现有的SQL聚合函数。

在3.13版本发生变更：将name，num_arg和aggregate_class作为关键字参数传入的做法已被弃用。这些形叁将在Python 3.15中成为仅限位置形叁。

示例：

import sqlite3

# 定义聚合函数

class Average:

def __init__(self):

self.total = 0

self.count = 0

def step(self, value):

if value is not None:

self.total += value

self.count += 1

def finalize(self):

return self.total / self.count if self.count > 0 else None

# 连接到数据库

con = sqlite3.connect('tutorial.db')

# 注册自定义聚合函数

con.create_aggregate("average", 1, Average)

# 创建表

con.execute('''

CREATE TABLE IF NOT EXISTS numbers (

id INTEGER PRIMARY KEY,

value INTEGER

)

''')

# 插入数据

con.execute("INSERT INTO numbers (value) VALUES (10)")

con.execute("INSERT INTO numbers (value) VALUES (20)")

con.execute("INSERT INTO numbers (value) VALUES (30)")

# 查询并使用自定义聚合函数

cursor = con.cursor()

cursor.execute("SELECT average(value) AS avg_value FROM numbers")

row = cursor.fetchone()

# 打印结果

if row:

print("Average value:", row[0]) # 输出：Average value：20.0

# 关闭连接

cursor.close()

con.close()

8、create_window_function(name,num_params,aggregate_class,/)

创建或移除用户定义的聚合窗口函数。

用于注册用户自定义窗口函数，窗口函数允许你在查询结果的每一行上执行计算，而不需要将结果聚合到单个行中。这使得窗口函数在分析和报告中非常有用。

参数：

name(str)：要创建或移除的SQL聚合窗口函数的名称。

num_params(int)：SQL聚合窗口函数可接受的参数数量。如为-1，则可以接受任意数量的参数。

aggregate_class(class|None)：一个必须实现下列方法的类：

*step()：向当前窗口添加一行。

*value()：返回聚合的当前值。

*inverse()：从当前窗口移除一行。

*finalize()：将聚合的最终结果作为一个SQLite原生支持的类型返回。step()和value()方法需要接受的参数数量是由num_params控制的。设为None将移除现有的SQL聚合窗口函数。

抛出：NotSupportedError：如果在早于SQLite3.25.0，不支持聚合窗口函数的版本上使用。

Added in version 3.11.

示例：

# 来自 https://www.sqlite.org/windowfunctions.html#udfwinfunc 的示例

import sqlite3

class WindowSumInt:

def __init__(self):

self.count = 0

def step(self, value):

"""添加一行到当前窗口。"""

self.count += value

def value(self):

"""返回聚合的当前值。"""

return self.count

def inverse(self, value):

"""从当前窗口移除一行。"""

self.count -= value

def finalize(self):

"""返回聚合的最终值。

任何清理动作都应放在此处。

"""

return self.count

con = sqlite3.connect(":memory:")

cur = con.execute("CREATE TABLE test(x, y)")

values = [

("a", 4),

("b", 5),

("c", 3),

("d", 8),

("e", 1),

]

cur.executemany("INSERT INTO test VALUES(?, ?)", values)

con.create_window_function("sumint", 1, WindowSumInt)

cur.execute("""

SELECT x, sumint(y) OVER (

ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING

) AS sum_y

FROM test ORDER BY x

""")

print(cur.fetchall())

con.close()

输出：[('a', 9), ('b', 12), ('c', 16), ('d', 12), ('e', 9)]

9、interrupt()

用于中断一个长时间运行的查询操作。

这个方法可以在一个线程中调用，用于终止在另一个线程中执行的查询。

从其他的线程调用此方法以中止可能正在连接上执行的任何查询。被中止的查询将引发OperationalError。

用于中断正在执行的数据库操作。这个方法在需要取消长时间运行的查询或操作时非常有用。

示例：

import sqlite3

import time

import threading

# 创建数据库连接

conn = sqlite3.connect('example.db')

cursor = conn.cursor()

# 创建表（如果不存在）

cursor.execute('''

CREATE TABLE IF NOT EXISTS large_table (

id INTEGER PRIMARY KEY,

name TEXT

)

''')

conn.commit()

# 创建一个长时间运行的查询

def long_running_query():

# 在每个线程中创建独立的游标

cursor = conn.cursor()

try:

cursor.execute("SELECT * FROM large_table") # 假设large_table是一个大表

while True:

time.sleep(1) # 模拟长时间运行的查询

except sqlite3.OperationalError as e:

print("查询被中断:", e)

finally:

cursor.close()

# 启动查询线程

query_thread = threading.Thread(target=long_running_query)

query_thread.start()

# 等待一段时间后中断查询

time.sleep(5)

print("准备中断查询...")

conn.interrupt() # 中断查询

# 等待查询线程结束

query_thread.join()

# 关闭连接

conn.close()

10、set_authorizer(authorizer_callback)

用于设置一个授权回调函数，该函数用于控制对数据库的访问权限。当SQLite尝试执行某些操作时，如读取或修改数据，它会调用这个回调函数来决定是否允许该操作。

参数：

authorizer_callback：一个回调函数，SQLite在执行SQL语句时会调用该函数来检查是否允许特定的操作。

回调函数的参数

autorizer_callback需要接受以下参数：

action_code：一个整数，表示SQLite请求执行的操作类型。SQLite定义了一系列的常量来表示不同的操作，如：

SQLITE_SELECT: 1，表示SELECT操作。

SQLITE_INSERT: 2，表示INSERT操作。

SQLITE_UPDATE: 3，表示UPDATE操作。

SQLITE_DELETE: 4，表示DELETE操作。

SQLITE_CREATE_INDEX: 5，表示CREATE INDEX操作。

SQLITE_CREATE_TABLE: 6，表示CREATE TABLE操作。

SQLITE_CREATE_TEMP_INDEX: 7，表示CREATE TEMP INDEX操作。

SQLITE_CREATE_TEMP_TABLE: 8，表示CREATE TEMP TABLE操作。

SQLITE_CREATE_TEMP_TRIGGER: 9，表示CREATE TEMP TRIGGER操作。

SQLITE_CREATE_TEMP_VIEW: 10，表示CREATE TEMP VIEW操作。

SQLITE_CREATE_TRIGGER: 11，表示CREATE TRIGGER操作。

SQLITE_CREATE_VIEW: 12，表示CREATE VIEW操作。

SQLITE_DROP_INDEX: 13，表示DROP INDEX操作。

SQLITE_DROP_TABLE: 14，表示DROP TABLE操作。

SQLITE_DROP_TEMP_INDEX: 15，表示DROP TEMP INDEX操作。

SQLITE_DROP_TEMP_TABLE: 16，表示DROP TEMP TABLE操作。

SQLITE_DROP_TEMP_TRIGGER: 17，表示DROP TEMP TRIGGER操作。

SQLITE_DROP_TEMP_VIEW: 18，表示DROP TEMP VIEW操作。

SQLITE_DROP_TRIGGER: 19，表示DROP TRIGGER操作。

SQLITE_DROP_VIEW: 20，表示DROP VIEW操作。

SQLITE_ALTER_TABLE: 21，表示ALTER TABLE操作。

SQLITE_RENAME_TABLE: 22，表示RENAME TABLE操作。

SQLITE_RENAME_COLUMN: 23，表示RENAME COLUMN操作。

arg1: 依赖于action_code的值，通常表示数据库的名称。

arg2: 依赖于action_code的值，通常表示表名。

arg3: 依赖于action_code的值，通常表示列名或者触发器名称。

回调函数的返回值

SQLITE_OK: 允许操作。

SQLITE_IGNORE: 忽略操作，但不会返回错误。

SQLITE_DENY: 拒绝操作，并返回错误。

示例：

import sqlite3

def authorizer_cb(action, arg1, arg2, arg3, arg4):

if action == sqlite3.SQLITE_SELECT:

if arg2 == 'sensitive_data':

return sqlite3.SQLITE_DENY # 不允许查询敏感数据表

return sqlite3.SQLITE_OK # 允许其他所有操作

conn = sqlite3.connect(':memory:')

conn.set_authorizer(authorizer_cb)

# 尝试查询敏感数据表

try:

conn.execute("SELECT * FROM sensitive_data")

except sqlite3.OperationalError as e:

print("Access denied:", e)

conn.close()

输出：Access denied: no such table: sensitive_data

注册callable authorizer_callback用于在每次尝试访问数据库中表的某一列时发起调用。该回调应当返回SQLITE_OK/SQLITE_DENY或SQLITE_IGNORE中的一个以提示下层SQLite库应当如何处理对该列的访问。

该回调的第一个参数指明哪种操作将被授权。第二个和第三个参数根据第一个参数的具体值将为传给操作的参数或为None。第四个参数如果适用则为数据库名称（'main','temp'等）。第五个参数是负责尝试访问的最内层触发器或视图的名称或者如果该尝试访问是直接来自输入的SQL代码的话则为None。

请参阅 SQLite 文档了解第一个参数可能的值以及依赖于第一个参数的第二个和第三个参数的含义。所有必需的常量均在 sqlite3 模块中可用。

将 None 作为 authorizer_callback 传入将禁用授权回调。

在 3.11 版本发生变更: 增加对使用 None 禁用授权回调的支持。

在 3.13 版本发生变更: 将 authorizer_callback 作为关键字参数传入的做法已被弃用。该形参将在 Python 3.15 中成为仅限位置形参

11、set_progress_handler(progress_handler, n)

用于设置一个进度处理回调函数，该函数会在SQLite处理某些操作时被周期性地调用。这个方法对于长时间运行的操作特别有用，因为它允许你监视操作的进度。

参数：

progress_handler：这是一个回调函数，它将在SQLite执行操作期间被周期性地调用。

n：一个整数，表示SQLite虚拟机执行的指令数。每当SQLite虚拟机执行了n条指令后，progress_handler将被调用。

回调函数

进度处理回调函数应该接受以下参数：

n：一个整数，表示自上次调用进度处理回调以来SQLite虚拟机执行的指令数。

回调函数可以返回非零值来中断当前的操作。

如果你想清除任何先前安装的进度处理器，可在调用该方法时传入 None 作为 progress_handler。

从处理函数返回非零值将终止当前正在执行的查询并导致它引发 DatabaseError 异常。

在 3.13 版本发生变更: 将 progress_handler 作为关键字参数传入的做法已被弃用。该形参将在 Python 3.15 中成为仅限位置形参。

示例：

import sqlite3

def progress_handler(n):

print(f"Progress: {n} steps executed")

return 0

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 设置进度处理回调函数，每执行1000条指令调用一次

conn.set_progress_handler(progress_handler, 1)

# 创建一个表并插入大量数据，以演示进度处理

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (col1 int)")

# 插入大量数据

for i in range(10):

cursor.execute("INSERT INTO test (col1) VALUES (?)", (i,))

# 关闭游标和连接

cursor.close()

conn.close()

报错：sqlite3.OperationalError: interrupte

12、set_trace_callback(trace_callback)

用于设置一个跟踪回调函数，该函数会在SQLite执行每一条SQL语句之前被调用。这个方法对于调试和监控数据库操作非常有用。

参数：

trace_callback：这是一个回调函数，它将在每次SQLite执行SQL语句之前被调用。

回调函数

跟踪回调函数应该接受以下参数：

sql：一个字符串，表示即将被执行的SQL语句。

示例：

import sqlite3

def trace_callback(sql):

print("Executing:", sql)

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 设置跟踪回调函数

conn.set_trace_callback(trace_callback)

# 创建一个表并插入一些数据

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (col1 int)")

cursor.execute("INSERT INTO test (col1) VALUES (1)")

cursor.execute("INSERT INTO test (col1) VALUES (2)")

# 查询数据

cursor.execute("SELECT * FROM test")

print(cursor.fetchall())

# 关闭游标和连接

cursor.close()

conn.close()

控制台输出：

Executing: CREATE TABLE test (col1 int)

Executing: BEGIN

Executing: INSERT INTO test (col1) VALUES (1)

Executing: INSERT INTO test (col1) VALUES (2)

Executing: SELECT * FROM test

[(1,), (2,)]

注意：

1、跟踪回调函数主要用于调试目的，不应该在生产环境中使用，因为它可能会影响性能。

2、当启用跟踪回调时，所有通过SQLite3模块执行的SQL语句都会被传递给回调函数，包括内部操作和准备语句。

3、如果跟踪回调函数执行耗时操作，它可能会显著减慢数据库操作的速度。

4、在回调函数内部抛出异常可能会导致数据库操作失败。

传给该回调的唯一参数是被执行的语句 (作为 str)。回调的返回值将被忽略。请注意后端不仅会运行传给 Cursor.execute() 方法的语句。其他来源还包括 sqlite3 模块的事务管理以及在当前数据库中定义的触发器的执行。

传入 None 作为 trace_callback 将禁用追踪回调。

备注：在跟踪回调中产生的异常不会被传播。作为开发和调试的辅助手段，使用 enable_callback_tracebacks() 来启用打印跟踪回调中产生的异常的回调。

Added in version 3.3.

在 3.13 版本发生变更: 将 trace_callback 作为关键字参数传入的做法已被弃用。该形参将在 Python 3.15 中成为仅限位置形参。

13、enable_load_extension(enabled, /)

如果 enabled 为 True 则允许 SQLite 从共享库加载 SQLite 扩展；否则，不允许加载 SQLite 扩展。 SQLite 扩展可以定义新的函数、聚合或全新的虚拟表实现。一个知名的扩展是与随同 SQLite 一起分发的全文搜索扩展。

备注：在默认情况下 sqlite3 模块的构建没有附带可加载扩展支持，因为某些平台（主要是 macOS）上的 SQLite 库在编译时未启用此特性。要获得可加载扩展支持，你必须将 --enable-loadable-sqlite-extensions 选项传给 configure。

引发一个审计事件 sqlite3.enable_load_extension 并附带参数 connection, enabled。

Added in version 3.2.

在 3.10 版本发生变更: 增加了 sqlite3.enable_load_extension 审计事件。

示例：

con.enable_load_extension(True)

# 加载 fts (fulltext search) 扩展

con.execute("select load_extension('./fts3.so')")

# 你也可以使用 API 调用来加载该扩展：

# con.load_extension("./fts3.so")

# 禁止扩展再次加载

con.enable_load_extension(False)

# 来自 SQLite wiki 的示例

con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")

con.executescript("""

INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');

INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');

INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');

INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');

""")

for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):

print(row)

**14、load_extension(path, /, *, entrypoint=None)**

从共享库加载 SQLite 扩展。请在调用此方法前通过 enable_load_extension() 来启用扩展加载。

参数:

path (str) -- SQLite 扩展的路径。

entrypoint (str | None) -- 入口点名称。如果为 None (默认值)，SQLite 将自行生成入口点名称；请参阅 SQLite 文档 Loading an Extension 了解详情。

引发一个审计事件 sqlite3.load_extension 并附带参数 connection, path。

Added in version 3.2.

在 3.10 版本发生变更: 增加了 sqlite3.load_extension 审计事件。

在 3.12 版本发生变更: 增加了 entrypoint 形参。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect('example.db')

# 加载SQLite扩展

try:

conn.enable_load_extension(True) # 允许加载扩展

conn.load_extension('path/to/your/extension.so') # 替换为你的扩展路径

print("Extension loaded successfully.")

except sqlite3.Error as e:

print(f"An error occurred: {e}")

# 关闭连接

conn.close()

**15、iterdump(*, filter=None)**

返回一个 iterator 用来将数据库转储为 SQL 源代码。在保存内存数据库以便将来恢复时很有用处。类似于 sqlite3 shell 中的 .dump 命令。

用于将数据库的内容以SQL语句的形式转储出来，以便可以将这些SQL语句用于重建数据库。这个方法在sqlite3模块的Connection对象上调用。

参数:

filter (str | None) -- 可选的 LIKE 模式用于确定要转储的数据库对象，例如 prefix_%。如为 None (默认值)，则将包括所有数据库对象。

参见

如何处理非 UTF-8 文本编码格式

在 3.13 版本发生变更: 添加了 filter 形参。

示例:

# 将文件 example.db 转换为 SQL 转储文件 dump.sql

con = sqlite3.connect('example.db')

with open('dump.sql', 'w') as f:

for line in con.iterdump():

f.write('%s\n' % line)

con.close()

**16、backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)**

创建 SQLite 数据库的备份。

即使数据库是通过其他客户端访问或通过同一连接并发访问也是有效的。

参数:

target (Connection) -- 用于保存备份的数据库连接。

pages (int) -- 每次要拷贝的页数。如果小于等于 0，则一次性拷贝整个数据库。默认为 -1。

progress (callback | None) -- 如果设为一个 callable，它将针对每次备份迭代附带三个整数参数被发起调用：上次迭代的状态 status，待拷贝的剩余页数 remaining，以及总页数 total。默认值为 None。

name (str) -- 要备份的数据库名称。可能为代表主数据库的 "main" (默认值)，代表临时数据库的 "temp"，或者使用 ATTACH DATABASE SQL 语句所附加的自定义数据库名称。

sleep (float) -- 连续尝试备份剩余页所要间隔的休眠秒数。

示例 1，

将现有数据库拷贝至另一个数据库:

def progress(status, remaining, total):

print(f'已复制 {total-remaining} 到 {total} 页……')

src = sqlite3.connect('example.db')

dst = sqlite3.connect('backup.db')

with dst:

src.backup(dst, pages=1, progress=progress)

dst.close()

src.close()

示例 2，

将现有数据库拷贝至一个临时副本:

src = sqlite3.connect('example.db')

dst = sqlite3.connect(':memory:')

src.backup(dst)

dst.close()

src.close()

Added in version 3.7.

17、getlimit(category, /)

获取一个连接的运行时限制。

用于查询SQLite数据库引擎的某个资源使用限制的当前值。

参数:

category: 一个整数，代表要查询的资源使用限制的类型。SQLite定义了几种资源限制类别，例如：sqlite3.LIMIT_ATTACHED: 附加数据库的数量限制。

sqlite3.LIMIT_COLUMN: 表中列的数量限制。

sqlite3.LIMIT_COMPOUND_SELECT: 复合SELECT语句中SELECT子句的数量限制。

sqlite3.LIMIT_EXPR_DEPTH: 表达式深度的限制。

sqlite3.LIMIT_FUNCTION_ARG: 函数参数的数量限制。

sqlite3.LIMIT_LENGTH: 字符串/二进制 blob的最大长度限制。

sqlite3.LIMIT_LIKE_PATTERN_LENGTH: LIKE/REGEXP模式的最大长度限制。

sqlite3.LIMIT_SQL_LENGTH: SQL语句的最大长度限制。

sqlite3.LIMIT_TRIGGER_DEPTH: 触发器递归深度的限制。

返回类型:int

返回值：返回一个整数，表示当前资源使用限制的值。

抛出:ProgrammingError -- 如果 category 不能被下层的 SQLite 库所识别。

示例，

import sqlite3

# 创建一个 SQLite 连接

conn = sqlite3.connect(':memory:')

# 获取当前的列限制

column_limit = conn.getlimit(sqlite3.SQLITE_LIMIT_COLUMN)

print(f"当前的列限制为: {column_limit}")

# 关闭连接

conn.close()

输出：当前的列限制为: 2000

Added in version 3.11.

18、setlimit(category, limit, /)

设置连接运行时限制。如果试图将限制提高到超出强制上界则会静默地截短到强制上界。无论限制值是否被修改，都将返回之前的限制值。

参数:

category (int) -- 要设置的 SQLite limit category。

limit (int) -- 新的限制值。如为负值，当前限制将保持不变。

返回类型:int

抛出:ProgrammingError -- 如果 category 不能被下层的 SQLite 库所识别。

示例，将 Connection con 上附加的数据库数量限制为 1（默认限制为 10）:

>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)

>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)

Added in version 3.11.

19、getconfig(op, /)

查询一个布尔类型的连接配置选项。

参数:

op (int) -- 一个 SQLITE_DBCONFIG 代码。

返回类型:bool

Added in version 3.12.

示例：

import sqlite3

# 连接到 SQLite 数据库

conn = sqlite3.connect('tutorial.db')

# 查询是否启用了加载扩展

# SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 是一个 SQLITE_DBCONFIG 常量

enable_load_extension = conn.getconfig(sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION)

print(f"Load extension enabled: {enable_load_extension}")

# 关闭数据库连接

conn.close()

20、setconfig(op, enable=True, /)

设置一个布尔类型的连接配置选项。

参数:

op (int) -- 一个 SQLITE_DBCONFIG 代码。

enable (bool) -- 如果该配置选项应当启用则为 True (默认值)；如果应当禁用则为 False。

Added in version 3.12.

**21、serialize(*, name='main')**

将一个数据库序列化为 bytes 对象。对于普通的磁盘数据库文件，序列化就是磁盘文件的一个副本。对于内存数据库或“临时”数据库，序列化就是当数据库备份到磁盘时要写入到磁盘的相同字节序列。

参数:

name (str) -- 要序列化的数据库名称。默认为 "main"。

返回类型:bytes

备注：此方法仅在下层 SQLite 库具有序列化 API 时可用。

Added in version 3.11.

示例：

import sqlite3

# 连接到 SQLite 数据库

conn = sqlite3.connect('tutorial.db')

# 序列化数据库

serialized_db = conn.serialize(name='main')

# 可以将序列化后的数据写入文件或进行其他操作

with open('example.db.backup', 'wb') as f:

f.write(serialized_db)

# 关闭数据库连接

conn.close()

**22、deserialize(data, /, *, name='main')**

将一个已序列化的数据库反序列化至 Connection。此方法将导致数据库连接从 name 数据库断开，并基于包含在 data 中的序列化数据将 name 作为内存数据库重新打开。

参数:

data (bytes) -- 已序列化的数据库。

name (str) -- 反序列化的目标数据库名称。默认为 "main"。

抛出:OperationalError -- 如果当前数据库连接正在执行读取事务或备份操作。

DatabaseError -- 如果 data 不包含有效的 SQLite 数据库。

OverflowError -- 如果 len(data) 大于 2**63 - 1。

备注： 此方法仅在下层的 SQLite 库具有反序列化 API 时可用。

Added in version 3.11.

——Connection类对象属性（6个）

1、autocommit

该属性控制符合 PEP 249 的事务行为。

autocommit属性是一个布尔值，用于指示是否自动提交事务。在SQLite中，默认情况下，事务是手动管理的，这意味着你需要显式地开始一个事务，并在更改完成后提交它。如果autocommit设置为True，则每个SQL语句的执行都会自动提交，而不需要显式调用commit()方法。

autocommit 有三个可用的值:

False: 选择符合 PEP 249 的事务行为，即 sqlite3 将保证总是开启一个事务。使用 commit() 和 rollback() 来关闭事务。这是 autocommit 推荐的取值。

True: 使用 SQLite 的 autocommit mode。在此模式下 commit() 和 rollback() 将没有任何效果。

LEGACY_TRANSACTION_CONTROL: Python 3.12 之前 (不符合 PEP 249) 的事务控制。请参阅 isolation_level 了解详情。这是 autocommit 当前的默认值。

将 autocommit 更改为 False 将开启一个新事务，而将其更改为 True 将提交任何待处理事务。

详情参见通过 autocommit 属性进行事务控制。

备注：除非 autocommit 为 LEGACY_TRANSACTION_CONTROL 否则 isolation_level 属性将不起作用。

Added in version 3.12.

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect('example.db')

# 启用自动提交

conn.autocommit = True

# 现在执行的每个SQL语句都会自动提交

conn.execute("CREATE TABLE IF NOT EXISTS test (id INTEGER)")

# 禁用自动提交

conn.autocommit = False

# 现在需要显式提交事务

conn.execute("INSERT INTO test (id) VALUES (1)")

conn.commit()

# 关闭数据库连接

conn.close()

2、in_transaction

这个只读属性对应于低层级的 SQLite autocommit mode。

如果一个事务处于活动状态（有未提交的更改）则为 True，否则为 False。

Added in version 3.2.

3、isolation_level

控制 sqlite3 的旧式事务处理模式。

如果设为 None，则绝不会隐式地开启事务。

如果设为 "DEFERRED"、"IMMEDIATE" 或 "EXCLUSIVE" 中的一个，对应于下层的 SQLite transaction behaviour，会执行隐式事务管理。

如果未被 connect() 的 isolation_level 形参覆盖，则默认为 ""，这是 "DEFERRED" 的一个别名。

备注

建议使用 autocommit 来控制事务处理而不是使用 isolation_level。除非 autocommit 设为 LEGACY_TRANSACTION_CONTROL (默认值) 否则 isolation_level 将不起作用。

4、row_factory

自定义查询结果的返回格式。

可以是一个类或，通常是一个返回行对象的工厂函数。

针对从该连接创建的 Cursor 对象的初始 row_factory。为该属性赋值不会影响属于该连接的现有游标的 row_factory，只影响新的游标。

默认为 None，表示将每一行作为 tuple 返回。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect('tutorial.db')

# 设置row_factory为sqlite3.Row

conn.row_factory = sqlite3.Row

# 创建一个游标对象

cursor = conn.cursor()

# 创建一个表

cursor.execute('''

CREATE TABLE IF NOT EXISTS users (

id INTEGER PRIMARY KEY AUTOINCREMENT,

name TEXT NOT NULL,

age INTEGER NOT NULL

)

''')

# 插入数据

cursor.execute("INSERT INTO users (name, age) VALUES (?, ?)", ('Alice', 30))

cursor.execute("INSERT INTO users (name, age) VALUES (?, ?)", ('Bob', 25))

conn.commit()

# 查询数据

cursor.execute("SELECT * FROM users")

rows = cursor.fetchall()

# 打印查询结果，使用列名访问

for row in rows:

print(f"ID: {row['id']}, Name: {row['name']}, Age: {row['age']}")

# 关闭游标和连接

cursor.close()

conn.close()

5、text_factory

用于控制从数据库中读取text类型数据时返回的对象类型（如普通字符串、Unicode字符串或字节对象）

一个接受 bytes 形参并返回其文本表示形式的 callable。该可调用对象将针对数据类型为 TEXT 的 SQLite 值发起调用。在默认情况下，该属性将被设为 str。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect('tutorial.db')

# 设置text_factory为bytes

conn.text_factory = bytes

# 创建一个游标对象

cursor = conn.cursor()

# 创建一个表

cursor.execute('''

CREATE TABLE IF NOT EXISTS messages (

id INTEGER PRIMARY KEY AUTOINCREMENT,

content TEXT NOT NULL

)

''')

# 插入数据

cursor.execute("INSERT INTO messages (content) VALUES (?)", ('Hello, World!',))

cursor.execute("INSERT INTO messages (content) VALUES (?)", ('SQLite is great!',))

conn.commit()

# 查询数据

cursor.execute("SELECT * FROM messages")

rows = cursor.fetchall()

# 打印查询结果，内容将以字节对象的形式返回

for row in rows:

print(f"ID: {row[0]}, Content: {row[1]} (Type: {type(row[1])})")

# 关闭游标和连接

cursor.close()

conn.close()

6、total_changes

返回自打开数据库连接以来已修改、插入或删除的数据库行的总数。

游标对象

一个指向数据库查询结果集的指针。它允许开发者逐行访问查询结果，而不是一次性将所有数据加载到内存中。游标可以被视为一个控制结构，帮助程序在结果集中进行遍历和操作。

一个代表被用于执行SQL语句，并管理获取操作的上下文的database_cursor的Cursor对象。游标对象是使用Connection.cursor()，或者是通过使用任何连接快捷方法来创建的。

Cursor对象属于迭代器，这意味着如果你通过execute()来执行SELECT查询，你可以简单地迭代游标来获取结果行：

for row in cur.execute("SELECT t FROM data"):

print(row)

class sqlite3.Cursor

Cursor游标实例具有以下属性和方法。

——cursor对象方法（9个）

1、execute(sql,parameters=(),/)

用于执行单条SQL语句。

这个方法可以执行任何类型的SQL命令，包括查询、更新和删除操作。

执行一条 SQL 语句，可以选择使用占位符来绑定 Python 值。

参数:

sql (str) -- 一条 SQL 语句。

parameters (dict | sequence) -- 要绑定到 sql 中占位符的 Python 值。如果使用命名占位符则会使用 dict。如果使用非命名占位符则会使用 sequence。参见如何在 SQL 查询中使用占位符来绑定值。

抛出:ProgrammingError -- 如果 sql 包含多条 SQL 语句。

如果 autocommit 为 LEGACY_TRANSACTION_CONTROL，isolation_level 不为 None，sql 为一条 INSERT, UPDATE, DELETE 或 REPLACE 语句，并且没有开启事务，则会在执行 sql 之前隐式地开启事务。

Deprecated since version 3.12, will be removed in version 3.14: 如果使用了命名占位符并且 parameters 是一个序列而非 dict 则会发出 DeprecationWarning。从 Python 3.14 起，将改为引发 ProgrammingError。

使用 executescript() 来执行多条 SQL 语句。statements.

2、executemany(sql, parameters, /)

对于 parameters 中的每一项，重复执行参数化的 DML SQL 语句 sql。

使用与 execute() 相同的隐式事务处理。

参数:

sql (str) -- 一条 SQL DML 语句。

parameters (iterable) -- 一个用来绑定到 sql 中的占位符的形参的 iterable。参见如何在 SQL 查询中使用占位符来绑定值。

抛出:ProgrammingError -- 如果 sql 包含多条 SQL 语句，或者不属于 DML 语句。

示例:

rows = [

("row1",),

("row2",),

]

# cur 是一个 sqlite3.Cursor 对象

cur.executemany("INSERT INTO data VALUES(?)", rows)

备注：任何结果行都将被丢弃，包括带有 RETURNING 子句的 DML 语句。

Deprecated since version 3.12, will be removed in version 3.14: 如果使用了命名占位符并且 parameters 中的每个条目都是序列而非 dict 则会发出 DeprecationWarning。从 Python 3.14 起，将改为引发 ProgrammingError。

execute()和executemany()区别示例：

# 插入单条记录

cursor.execute("INSERT INTO table_name (name,age) VALUES (?,?)", ('Alice',30))

# 插入多条记录

users = [

('小飞',32),

('大飞',40),

('老飞',60)

]

cursor.executemany("INSERT INTO table_name (name,age) VALUES (?,?)", users)

3、executescript(sql_script, /)

executescript()可以一次性执行多个SQL语句，适用于需要批量执行的场景。

执行 sql_script 中的 SQL 语句。如果 autocommit 为 LEGACY_TRANSACTION_CONTROL 并且存在待处理的事务，则首先隐式执行一条 COMMIT 语句。不会执行其他隐式事务控制；任何事务控制都必须添加至 sql_script。

sql_script 必须为字符串。

示例:

# cur 是一个 sqlite3.Cursor 对象

cur.executescript("""

BEGIN;

CREATE TABLE person(firstname, lastname, age);

CREATE TABLE book(title, author, published);

CREATE TABLE publisher(name, address);

COMMIT;

""")

4、fetchone()

用于从当前查询的结果集中获取下一行。如果结果集有更多的行，fetchone()会返回一个表示该行的元组；如果没有更多的行，它将返回None。

如果row_factory为None，则将下一行查询结果集作为tuple返回。否则，将其传给指定的行工厂函数并返回函数结果。如果没有更多可用数据则返回None。

注意

1、调用fetchone()之前，必须先执行一个查询。

2、如查询没有任何结果，将返回None。

3、fetchone()在内部维护一个指针，所以连续调用fetchone()将按顺序返回结果集中的每一行。

4、如果在一个多线程环境中使用游标，确保不会同时从多个线程调用fetchone()，因为这可能会导致不可预测的结果。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect('tutorial.db')

cursor = conn.cursor()

# 执行一个查询

cursor.execute("SELECT * FROM users")

# 使用fetchone()获取第一行数据

row = cursor.fetchone()

print(row) # 输出：例如 (1, 'john_doe', 'john@example.com')

# 继续使用fetchone()获取后续的行，直到没有更多行

while row is not None:

print(row) # 输出每行的数据

row = cursor.fetchone()

# 关闭游标和连接

cursor.close()

conn.close()

输出：

(1, 'Bob', 25)

(2, 'Charlie', 35)

(3, 'David', 40)

[Finished in 155ms]

5、fetchmany(size=cursor.arraysize)

用于从查询结果中获取多行数据。

这个方法是Cursor对象的一部分，允许你一次性获取指定数量的行，适用于处理大量数据时的性能优化。

每次调用要获取的行数是由 size 形参指定的。如果未指定 size，则由 arraysize 确定要获取的行数。如果可用的行少于 size，则返回可用的行数。

请注意 size 形参会涉及到性能方面的考虑。为了获得优化的性能，通常最好是使用 arraysize 属性。如果使用 size 形参，则最好在从一个 fetchmany() 调用到下一个调用之间保持相同的值。

参数：

size：一个整数，表示要获取的行数。如果size为负数，则返回所有剩余的行。

返回值：

返回一个列表（list），其中包含多个元组，每个元组代表一行数据。如果没有更多的行可供返回，则返回一个空列表。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 创建一个表并插入数据

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)")

# 插入一些示例数据

for i in range(1, 21):

cursor.execute("INSERT INTO test (value) VALUES (?)", (f"Value {i}",))

# 执行查询

cursor.execute("SELECT * FROM test")

# 使用fetchmany获取数据

while True:

rows = cursor.fetchmany(5) # 每次获取5行

if not rows:

break

for row in rows:

print(row)

# 关闭游标和连接

cursor.close()

conn.close()

输出：

(1, 'Value 1')

(2, 'Value 2')

......

6、fetchall()

将全部（剩余的）查询结果行作为 list 返回。

如果没有可用的行则返回空列表。

请注意 arraysize 属性可能会影响此操作的性能。

7、close()

立即关闭 cursor（而不是在当 __del__ 被调用的时候）。

从这一时刻起该 cursor 将不再可用，如果再尝试用该 cursor 执行任何操作将引发 ProgrammingError 异常。

8、setinputsizes(sizes, /)

用于设置输入参数的大小，通常用于处理大数据类型。

DB-API 要求的方法。在 sqlite3 不做任何事情。

9、setoutputsize(size, column=None, /)

用于设置输出参数的大小，通常用于处理大数据类型。

DB-API 要求的方法。在 sqlite3 不做任何事情。

——cursor对象属性（6个）

1、arraysize

默认值为1，即每次返回1行。

用于控制fetchmany()方法每次获取的默认行数。它可以帮助你在处理查询结果时优化内存使用和性能。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 创建一个表并插入数据

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)")

# 插入一些示例数据

for i in range(1, 21):

cursor.execute("INSERT INTO test (value) VALUES (?)", (f"Value {i}",))

# 执行查询

cursor.execute("SELECT * FROM test")

# 设置arraysize属性

cursor.arraysize = 5 # 设置每次fetchmany获取5行

# 使用fetchmany获取数据

rows = cursor.fetchmany() # 不传递参数，使用arraysize的值

for row in rows:

print(row)

# 关闭游标和连接

cursor.close()

conn.close()

输出：

(1, 'Value 1')

(2, 'Value 2')

(3, 'Value 3')

(4, 'Value 4')

(5, 'Value 5')

2、connection

返回与当前游标关联的连接对象。

提供属于该游标的 SQLite Connection 的只读属性。通过调用 con.cursor() 创建的 Cursor 对象将具有一个指向 con 的 connection 属性:

>>>>>> con = sqlite3.connect(":memory:")

>>> cur = con.cursor()

>>> cur.connection == con

True

>>> con.close()

3、description

只读。用于获取最近执行的查询结果集的列元数据。

提供关于查询结果的元数据。在执行查询后，可以帮助你了解结果集的结构。

返回值：返回一个列表，其中每个元素是一个元组，描述结果集中的一列。如果没有执行查询则返回None。

提供上一次查询的列名称的只读属性。为了与 Python DB API 保持兼容，它会为每个列返回一个 7 元组，每个元组的最后六个条目均为 None。

对于没有任何匹配行的 SELECT 语句同样会设置该属性。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 创建一个表并插入数据

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)")

# 插入一些示例数据

for i in range(1, 6):

cursor.execute("INSERT INTO test (value) VALUES (?)", (f"Value {i}",))

# 执行查询

cursor.execute("SELECT * FROM test")

# 获取列的描述信息

columns = cursor.description

# 打印列的信息

for column in columns:

print(column)

# 关闭游标和连接

cursor.close()

conn.close()

输出：

('id', None, None, None, None, None, None)

('value', None, None, None, None, None, None)

4、lastrowid

只读。返回最后一行插入操作所生成的行的主键键值。如果没有执行插入操作，则返回None。

当你插入一行数据并希望获取该行的主键时，可以使用此属性。

它只会在使用 execute() 方法的 INSERT 或 REPLACE 语句成功后被更新。对于其他语句，则在 executemany() 或 executescript()，或者如果插入失败，lastrowid 的值将保持不变。 lastrowid 的初始值为 None。

备注：对 WITHOUT ROWID 表的插入不被记录。

在 3.6 版本发生变更: 增加了 REPLACE 语句的支持。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 创建一个表

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (id INTEGER, value TEXT, age INTEGER PRIMARY KEY)")

# 插入一行数据

cursor.execute("INSERT INTO test (age) VALUES (?)", (22,))

# 获取最近插入的行的ID

last_id = cursor.lastrowid

print(f"最近插入的行ID: {last_id}") # 输出：22（因为age被设为了主键，并且值为22）

# 关闭游标和连接

cursor.close()

conn.close()

5、rowcount

只读。返回最近执行的操作影响的行数。

对于INSERT/UPDATE/DELETE操作，它返回受影响的行数；对于SELECT操作，它返回结果集中的行数。

提供 INSERT, UPDATE, DELETE 和 REPLACE 语句所修改行数的只读属性；

对于其他语句则为 -1，包括 CTE 查询。

只有 execute() 和 executemany() 方法会在语句运行完成后更新此属性。这意味着任何结果行都必须按顺序被提取以使 rowcount 获得更新。

示例：

import sqlite3

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 创建一个表

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)")

# 插入多行数据

cursor.execute("INSERT INTO test (value) VALUES (?)", ("Value 1",))

cursor.execute("INSERT INTO test (value) VALUES (?)", ("Value 2",))

cursor.execute("INSERT INTO test (value) VALUES (?)", ("Value 3",))

cursor.execute("UPDATE test SET value = 888") # 将value列所有值设为888

# 获取受影响的行数

affected_rows = cursor.rowcount

print(f"受影响的行数: {affected_rows}") # 输出：3（因为value列共有3行）

# 关闭游标和连接

cursor.close()

conn.close()

6、row_factory

允许你自定义游标返回的行的类型。你可以将其设置为一个可调用对象（如函数或类），以便在获取行时返回自定义类型（如字典或其他对象）。

当你希望以特定格式（如字典）访问查询结果时，可以使用此属性。

控制从该 Cursor 获取的行的表示形式。

如为 None，一行将表示为一个 tuple。可设置形式包括 sqlite3.Row；或者接受两个参数的 callable，一个 Cursor 对象和由行内所有值组成的 tuple，以及返回代表一个 SQLite 行的自定义对象。

默认为当 Cursor 被创建时设置的 Connection.row_factory。对该属性赋值不会影响父连接的 Connection.row_factory。

详情参见如何创建并使用行工厂对象。

示例：

import sqlite3

# 自定义行工厂函数

def dict_factory(cursor, row):

return {col[0]: row[idx] for idx, col in enumerate(cursor.description)}

# 连接到SQLite数据库

conn = sqlite3.connect(':memory:')

# 设置行工厂

conn.row_factory = dict_factory

# 创建一个表

cursor = conn.cursor()

cursor.execute("CREATE TABLE test (id INTEGER PRIMARY KEY, value TEXT)")

# 插入数据

cursor.execute("INSERT INTO test (value) VALUES (?)", ("Value 1",))

cursor.execute("INSERT INTO test (value) VALUES (?)", ("Value 2",))

# 执行查询

cursor.execute("SELECT * FROM test")

# 获取结果

rows = cursor.fetchall()

for row in rows:

print(row) # 每行将以字典形式输出

# 关闭游标和连接

cursor.close()

conn.close()

输出： {'id': 1, 'value': 'Value 1'}

{'id': 2, 'value': 'Value 2'}

Row对象

class sqlite3.Row

一个被用作Connection对象的高度优化的row_factory的row实例。它支持迭代、相等性检测、len() 以及基于列名称的mapping访问和数字序列。

两个Row对象如果具有相同的列名称和值则比较结果相等。

详情参见如何创建并使用行工厂对象。

——Row对象方法（1个）

1、keys()

返回值

返回一个包含当前行所有列名的列表。这些列名对应于查询结果中的列。

使用场景

当你使用Row对象并希望以列名访问数据时，keys()方法非常有用。它可以帮助你动态地获取列名，尤其是在处理不确定列数或列名的查询结果时。

在一次查询之后，立即将由列名称组成的 list 作为字符串返回，它是 Cursor.description 中每个元组的第一个成员。

在 3.5 版本发生变更: 添加了对切片操作的支持。

示例：

import sqlite3

# 连接到数据库（数据库文件是 tutorial.db）

conn = sqlite3.connect('tutorial.db')

# 设置行工厂为 sqlite3.Row，以便使用 keys() 方法

conn.row_factory = sqlite3.Row

cursor = conn.cursor()

# 执行查询

cursor.execute("SELECT * FROM users")

# 获取所有查询结果

rows = cursor.fetchall()

# 输出列名

column_names = rows[0].keys() if rows else []

print("列名:", column_names)

# 输出每一行的数据

for row in rows:

print({key: row[key] for key in column_names}) # 使用字典推导式输出每一行的数据

# 关闭游标和连接

cursor.close()

conn.close()

输出：

列名: ['id', 'name', 'age']

{'id': 1, 'name': 'Bob', 'age': 25}

{'id': 2, 'name': 'Charlie', 'age': 35}

{'id': 3, 'name': 'David', 'age': 40}

Blob对象

class sqlite3.Blob

Added in version 3.11.

Blob实例是可以读写SQLite BLOB数据的file-like object。调用len(blob)可得到blob的大小（字节数）。请使用索引和切片来直接访问blob数据。

将Blob作为context manager使用以确保使用结束后blob句柄自动关闭。

con = sqlite3.connect(":memory:")

con.execute("CREATE TABLE test(blob_col blob)")

con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# 写入到我们的 blob，使用两次 write 操作：

with con.blobopen("test", "blob_col", 1) as blob:

blob.write(b"hello, ")

blob.write(b"world.")

# 修改我们的 blob 的开头和末尾字节

blob[0] = ord("H")

blob[-1] = ord("!")

# 读取我们的 blob 的内容

with con.blobopen("test", "blob_col", 1) as blob:

greeting = blob.read()

print(greeting) # 输出 "b'Hello, world!'"

con.close()

——Blob对象方法（5个）

1、close()

关闭 blob对象，释放与该对象相关的资源。

从这一时刻起该 blob 将不再可用。如果再尝试用该 blob 执行任何操作将引发 Error (或其子类) 异常。

例：blob.close()

2、read(length=-1, /)

用于从BLOB对象中读取数据。size参数指定要读取的字节数。如果size为负值（默认值），则读取所有剩余的数据。

从 blob 的当前偏移位置读取 length 个字节的数据。如果到达了 blob 的末尾，则将返回 EOF 之前的数据。当未指定 length，或指定负值时，read() 将读取至 blob 的末尾。

示例：

data = blob.read(1024) # 读取前1024个字节

3、write(data, /)

用于将数据写入BLOB对象。data参数可以是字节串（bytes）或字节数组（bytearray）。

返回值：返回写入的字节数

在 blob 的当前偏移位置上写入 data。此函数不能改变 blob 的长度。写入数据超出 blob 的末尾将引发 ValueError。

示例：blobl.write(b'Hello, World!') # 写入字节数据

4、tell()

返回 blob 的当前访问位置。

5、seek(offset, origin=os.SEEK_SET, /)

用于移动BLOB对象的当前读写位置。

参数：

offset：移动的字节数

origin：指定从哪个位置开始移动，取值可以是：

0：SEEK_SET从文件开头开始（默认值）

1：SEEK_CUR从当前位置开始

2：SEEK_END从文件末尾开始

将 Blob 的当前访问位置设为 offset。 origin 参数默认为 os.SEEK_SET (blob 的绝对位置)。 origin 的其他值包括 os.SEEK_CUR （相对于当前位置寻址) 和 os.SEEK_END (相对于 blob 末尾寻址)。

示例：

blob.seek(0) # 移动到开头

blob.seek(10, 0) # 从开头移动10个字节

综合示例：

import sqlite3

con = sqlite3.connect(":memory:")

con.execute("CREATE TABLE test(blob_col blob)")

con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# 写入到我们的 blob，使用两次 write 操作：

with con.blobopen("test", "blob_col", 1) as blob:

blob.write(b"hello, ")

blob.write(b"world.")

# 修改我们的 blob 的开头和末尾字节

blob[0] = ord("H")

blob[-1] = ord("!")

# 写入数据

blob.seek(3,0) # 从开头移动5个位置

print(blob.tell()) # 打印blob当前位置：3

# print(blob.read()) # 读取当前blob数据

blob.write(b' New Data') # 写入新数据（不能超过原blob数据长度）

# 读取我们的 blob 的内容

with con.blobopen("test", "blob_col", 1) as blob:

greeting = blob.read()

print(greeting) # 输出：b'Hel New Data!'

blob.close()

con.close()

PrepareProtocol 对象

class sqlite3.PrepareProtocol

PrepareProtocol类型的唯一目的是作为 PEP 246 风格的适配协议让对象能够将自身适配为原生 SQLite 类型。

异常（10个）

异常层次是由 DB-API 2.0 (PEP 249) 定义的。

——用户操作错误（2个）

1、exception sqlite3.OperationalError

与数据库操作有关的错误而引发的异常，不一定在程序员的控制之下。例如，数据库路径没有找到，或者一个事务无法被处理。 OperationalError 是 DatabaseError 的子类。

2、exception sqlite3.IntegrityError

当数据库的关系一致性受到影响时引发的异常。例如外键检查失败等。它是 DatabaseError 的子类。

——编程错误（2个）

1、exception sqlite3.DataError

由于处理的数据有问题而产生的异常，比如数字值超出范围，字符串太长。 DataError 是 DatabaseError 的子类。

2、exception sqlite3.ProgrammingError

针对 sqlite3 API 编程错误引发的异常，例如向查询提供错误数量的绑定，或试图在已关闭的 Connection 上执行操作。 ProgrammingError 是 DatabaseError 的一个子类。

——模块错误（3个）

1、exception sqlite3.InterfaceError

因错误使用低层级 SQLite C API 而引发的异常，换句话说，如果此异常被引发，则可能表明 sqlite3 模块中存在错误。 InterfaceError 是 Error 的一个子类。

2、exception sqlite3.NotSupportedError

在下层的 SQLite 库不支持某个方法或数据库 API 的情况下引发的异常。例如，在 create_function() 中把 deterministic 设为 True，而下层的 SQLite 库不支持确定性函数的时候。 NotSupportedError 是 DatabaseError 的一个子类。

3、exception sqlite3.InternalError

当 SQLite 遇到一个内部错误时引发的异常。如果它被引发，可能表明运行中的 SQLite 库有问题。 InternalError 是 DatabaseError 的子类。

——数据库错误（1个）

1、exception sqlite3.DatabaseError

对与数据库有关的错误引发的异常。它作为几种数据库错误的基础异常。它只通过专门的子类隐式引发。 DatabaseError 是 Error 的一个子类。

——其他错误（2个）

1、exception sqlite3.Warning

目前此异常不会被 sqlite3 模块引发，但可能会被使用 sqlite3 的应用程序引发，例如当一个用户自定义的函数在插入操作中截断了数据时。 Warning 是 Exception 的一个子类。

2、exception sqlite3.Error

本模块是其他异常的基类。使用它来捕捉所有的错误，只需一条 except 语句。 Error 是 Exception 的子类。

如果异常是产生于 SQLite 库的内部，则以下两个属性将被添加到该异常:

sqlite_errorcode

来自 SQLite API 的数字错误代码

Added in version 3.11.

sqlite_errorname

来自 SQLite API 的数字错误代码符号名称

Added in version 3.11.

SQLite 与 Python 类型

SQLite 原生支持如下的类型： NULL，INTEGER，REAL，TEXT，BLOB。

因此可以将以下Python类型发送到SQLite而不会出现任何问题：

Python类型 SQLite 类型

None NULL

int INTEGER

float REAL

str TEXT

bytes BLOB

这是SQLite类型默认转换为Python类型的方式：

SQLite类型 Python 类型

NULL None

INTEGER int

REAL float

TEXT 取决于 text_factory , 默认为 str

BLOB bytes

sqlite3 模块的类型系统可通过两种方式来扩展：你可以通过对象适配器将额外的 Python 类型保存在 SQLite 数据库中，你也可以让 sqlite3 模块通过转换器将 SQLite 类型转换为不同的 Python 类型。types via.

默认适配器和转换器（已弃用）

备注：自 Python 3.12 起，默认适配器和转换器已被弃用。取而代之的是使用适配器和转换器范例程序，并根据您的需要定制它们。

弃用的默认适配器和转换器包括：

将 datetime.date 对象转换为 ISO 8601 格式字符串的适配器。
将 datetime.datetime 对象转换为 ISO 8601 格式字符串的适配器。
从已声明的 "date" 类型到 datetime.date 对象的转换器。
将已声明的 "timestamp" 类型转成 datetime.datetime 对象的转换器。小数部分将截断至 6 位（微秒精度）。

备注：默认的 "时间戳" 转换器忽略了数据库中的 UTC 偏移，总是返回一个原生的 datetime.datetime 对象。要在时间戳中保留 UTC 偏移，可以不使用转换器，或者用 register_converter() 注册一个偏移感知的转换器。

|自 3.12 版本弃用.

命令行接口

sqlite3 模块可以作为脚本发起调用，使用解释器的 -m 开关选项，以提供一个简单的 SQLite shell。

参数签名如下:

python -m sqlite3 [-h] [-v] [filename] [sql]

输入 .quit 或 CTRL-D 退出 shell。

-h, --help

打印 CLI 帮助。

-v, --version

打印下层 SQLite 库版本。

|Added in version 3.12.

示例：

在CMD命令提示符中输入sqlite3即可进入shell。

C:\Users\Administrator>sqlite3

SQLite version 3.8.7.2 2014-11-18 20:57:56

sqlite>

常用方案指引

如何在 SQL 查询中使用占位符来绑定值

SQL 操作通常会需要使用来自 Python 变量的值。不过，请谨慎使用 Python 的字符串操作来拼装查询，因为这样易受 SQL injection attacks。例如，攻击者可以简单地添加结束单引号并注入 OR TRUE 来选择所有的行:

# 绝不要这样做 -- 很不安全！

>>> symbol = input()

' OR TRUE; --

>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol

>>> print(sql)

SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'

>>> cur.execute(sql)

请改用 DB-API 的形参替换。要将变量插入到查询字符串中，可在字符串中使用占位符，并通过将实际值作为游标的 execute() 方法的第二个参数以由多个值组成的 tuple 形式提供给查询来替换它们。

SQL 语句可以使用两种占位符之一：问号占位符（问号风格）或命名占位符（命名风格）。对于问号风格，parameters 要是一个长度必须与占位符的数量相匹配的 sequence，否则将引发 ProgrammingError。对于命名风格，parameters 必须是 dict （或其子类）的实例，它必须包含与所有命名参数相对应的键；任何额外的条目都将被忽略。下面是一个同时使用这两种风格的示例：

import sqlite3

con = sqlite3.connect(":memory:")

cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# 这是用于 executemany() 的名称风格：

data = (

{"name": "C", "year": 1972},

{"name": "Fortran", "year": 1957},

{"name": "Python", "year": 1991},

{"name": "Go", "year": 2009},

)

cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# 这是用于 SELECT 查询的问号风格：

params = (1972,)

cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)

print(cur.fetchall()) # 输出：[('C', 1972)]

con.close()

备注：PEP 249 数字占位符已经不再被支持。如果使用，它们将被解读为命名占位符。

如何将自定义 Python 类型适配到 SQLite 值

SQLite 仅支持一个原生数据类型的有限集。要在 SQLite 数据库中存储自定义 Python 类型，请将它们适配到 SQLite 原生可识别的 Python 类型之一。

有两种方式可将 Python 对象适配到 SQLite 类型：让你的对象自行适配，或是使用适配器可调用对象。后者将优先于前者发挥作用。对于导出自定义类型的库，启用该类型的自行适配可能更为合理。而作为一名应用程序开发者，通过注册自定义适配器函数进行直接控制可能更为合理。

如何编写可适配对象

假设我们有一个代表笛卡尔坐标系中的坐标值对 Point，x 和 y 的类，该坐标值在数据库中将存储为一个文本字符串。这可以通过添加一个返回已适配值的 __conform__(self, protocol) 方法来实现。传给 protocol 的对象将为 PrepareProtocol 类型。

import sqlite3

class Point:

def __init__(self, x, y):

self.x, self.y = x, y

def __conform__(self, protocol):

if protocol is sqlite3.PrepareProtocol:

return f"{self.x};{self.y}"

con = sqlite3.connect(":memory:")

cur = con.cursor()

cur.execute("SELECT ?", (Point(4.0, -3.2),))

print(cur.fetchone()[0]) # 输出：4.0;-3.2

con.close()

如何注册适配器可调用对象

另一种可能的方式是创建一个将 Python 对象转换为 SQLite 兼容类型的函数。随后可使用 register_adapter() 来注册该函数。

import sqlite3

class Point:

def __init__(self, x, y):

self.x, self.y = x, y

def adapt_point(point):

return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")

cur = con.cursor()

cur.execute("SELECT ?", (Point(1.0, 2.5),))

print(cur.fetchone()[0]) # 输出：1.0;2.5

con.close()

如何将 SQLite 值转换为自定义 Python 类型

编写适配器使你可以将 from 自定义 Python 类型转换为 to SQLite 值。为了能将 from SQLite 值转换为 to 自定义 Python 类型，我们可使用 converters。

让我们回到 Point 类。我们以以分号分隔的字符串形式在 SQLite 中存储了 x 和 y 坐标值。

首先，我们将定义一个转换器函数，它接受这样的字符串作为形参并根据该参数构造一个 Point 对象。

备注：转换器函数总是接受传入一个 bytes 对象，无论下层的 SQLite 数据类型是什么。

def convert_point(s):

x, y = map(float, s.split(b";"))

return Point(x, y)

我们现在需要告诉 sqlite3 何时应当转换一个给定的 SQLite 值。这是在连接到一个数据库时完成的，使用 connect() 的 detect_types 形参。有三个选项:

隐式: 将 detect_types 设为 PARSE_DECLTYPES
显式: 将 detect_types 设为 PARSE_COLNAMES
同时: 将 detect_types 设为 sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES。列名的优先级高于声明的类型。

下面的示例演示了隐式和显式的方法:

import sqlite3

class Point:

def __init__(self, x, y):

self.x, self.y = x, y

def __repr__(self):

return f"Point({self.x}, {self.y})"

def adapt_point(point):

return f"{point.x};{point.y}"

def convert_point(s):

x, y = list(map(float, s.split(b";")))

return Point(x, y)

# 注册适配器和转换器

sqlite3.register_adapter(Point, adapt_point)

sqlite3.register_converter("point", convert_point)

# 1) 使用声明的类型来解析

p = Point(4.0, -3.2)

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)

cur = con.execute("CREATE TABLE test(p point)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))

cur.execute("SELECT p FROM test")

print("with declared types:", cur.fetchone()[0])

cur.close()

con.close()

# 2) 使用列名称来解析

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)

cur = con.execute("CREATE TABLE test(p)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))

cur.execute('SELECT p AS "p [point]" FROM test')

print("with column names:", cur.fetchone()[0])

cur.close()

con.close()

输出：

with declared types: Point(4.0, -3.2)

with column names: Point(4.0, -3.2)

适配器和转换器范例程序

本小节显示了通用适配器和转换器的范例程序。

import datetime

import sqlite3

def adapt_date_iso(val):

"""将 datetime.date 适配为 ISO 8601 日期。"""

return val.isoformat()

def adapt_datetime_iso(val):

"""将 datetime.datetime 适配为不带时区的 ISO 8601 日期。"""

return val.isoformat()

def adapt_datetime_epoch(val):

"""将 datetime.datetime 适配为 Unix 时间戳。"""

return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)

sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)

sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

def convert_date(val):

"""将 ISO 8601 日期转换为 datetime.date 对象。"""

return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):

"""将 ISO 8601 日期时间转换为 datetime.datetime 对象。"""

return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):

"""将 Unix 纪元时间戳转换为 datetime.datetime 对象。"""

return datetime.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)

sqlite3.register_converter("datetime", convert_datetime)

sqlite3.register_converter("timestamp", convert_timestamp)

如何使用连接快捷方法

通过使用 Connection 类的 execute(), executemany() 与 executescript() 方法，您可以简化您的代码，因为无需再显式创建（通常是多余的） Cursor 对象。

此时 Cursor 对象会被隐式创建并且由这些快捷方法返回。这样一来，您仅需在 Connection 对象上调用一次方法就可以执行 SELECT 语句，并对其进行迭代。

import sqlite3

# 创建并填充表。

con = sqlite3.connect(":memory:")

con.execute("CREATE TABLE lang(name, first_appeared)")

data = [

("C++", 1985),

("Objective-C", 1984),

]

con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

# 打印表内容

for row in con.execute("SELECT name, first_appeared FROM lang"):

print(row) # 输出：('C++', 1985)

('Objective-C', 1984)

print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")

# 输出：I just deleted 2 rows

# close() 不是一个快捷方法也不会被自动调用；

# 连接对象应当被手动关闭

con.close()

如何使用连接上下文管理器

Connection 对象可被用作上下文管理器以便在离开上下文管理器代码块时自动提交或回滚开启的事务。如果 with 语句体无异常地结束，事务将被提交。如果提交失败，或者如果 with 语句体引发了未捕获的异常，则事务将被回滚。如果 autocommit 为 False，则会在提交或回滚后隐式地开启一个新事务。

如果在离开 with 语句体时没有开启的事务，或者如果 autocommit 为 True，则上下文管理器将不做任何操作。

备注：上下文管理器既不会隐式开启新事务也不会关闭连接。如果你需要关闭上下文管理器，请考虑使用 contextlib.closing()。

import sqlite3

con = sqlite3.connect(":memory:")

con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

# 成功，con.commit() 将在此后被自动调用

with con:

con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() 会在 with 代码块结束时被自动调用并附带一个异常；

# 该异常仍会被引发并且必须被捕获

try:

with con:

con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

except sqlite3.IntegrityError:

print("couldn't add Python twice") # 输出：couldn't add Python twice

# 被用作上下文管理器的连接对象只能提交或回滚事务，

# 因此连接对象必须被手动关闭

con.close()

如何使用 SQLite URI

一些有用的 URI （统一资源标识符）技巧包括:

以只读模式打开一个数据库:

# 指定数据库文件位置，并以只读模式打开文件

con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)

>>> con.execute("CREATE TABLE readonly(data)")

Traceback (most recent call last):

OperationalError: attempt to write a readonly database

>>> con.close()

如果一个数据库尚不存在则不会隐式地新建数据库；如果无法新建数据库则将引发 OperationalError:

con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)

Traceback (most recent call last):

OperationalError: unable to open database file

创建一个名为 shared 的内存数据库:

db = "file:mem1?mode=memory&cache=shared"

con1 = sqlite3.connect(db, uri=True)

con2 = sqlite3.connect(db, uri=True)

with con1:

con1.execute("CREATE TABLE shared(data)")

con1.execute("INSERT INTO shared VALUES(28)")

res = con2.execute("SELECT data FROM shared")

assert res.fetchone() == (28,)

con1.close()

con2.close()

关于此特性的更多信息，包括可用的形参列表，可以在 SQLite URI documentation 中找到。

如何创建并使用行工厂对象

在默认情况下，sqlite3 会以 tuple 来表示每一行。如果 tuple 不适合你的需求，你可以使用 sqlite3.Row 类或自定义的 row_factory。

虽然 row_factory 同时作为 Cursor 和 Connection 的属性存在，但推荐设置 Connection.row_factory，这样在该连接上创建的所有游标都将使用同一个行工厂对象。

Row 提供了针对列的序列方式和大小写不敏感的名称方式访问，具有优于 tuple 的最小化内存开销和性能影响。要使用 Row 作为行工厂对象，请将其赋值给 row_factory 属性:

con = sqlite3.connect(":memory:")

con.row_factory = sqlite3.Row

现在查询将返回Row对象：

res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")

>>> row = res.fetchone()

>>> row.keys()

['name', 'radius']

>>> row[0] # 通过索引访问。

'Earth'

>>> row["name"] # 通过名称访问。

'Earth'

>>> row["RADIUS"] # 列名不区分大小写。

6378

>>> con.close()

备注：FROM 子句可以在 SELECT 语句中省略，像在上面的示例中那样。在这种情况下，SQLite 将返回单独的行，其中的列由表达式来定义，例如使用字面量并给出相应的别名 expr AS alias。

你可以创建自定义 row_factory 用来返回 dict 形式的行，将列名映射到相应的值。

def dict_factory(cursor, row):

fields = [column[0] for column in cursor.description]

return {key: value for key, value in zip(fields, row)}

使用它，现在查询将返回 dict 而不是 tuple:

con = sqlite3.connect(":memory:")

>>> con.row_factory = dict_factory

>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):

... print(row)

{'a': 1, 'b': 2}

>>> con.close()

以下行工厂函数将返回一个 named tuple:

from collections import namedtuple

def namedtuple_factory(cursor, row):

fields = [column[0] for column in cursor.description]

cls = namedtuple("Row", fields)

return cls._make(row)

namedtuple_factory() 可以像下面这样使用:

con = sqlite3.connect(":memory:")

>>> con.row_factory = namedtuple_factory

>>> cur = con.execute("SELECT 1 AS a, 2 AS b")

>>> row = cur.fetchone()

>>> row

Row(a=1, b=2)

>>> row[0] # 索引访问。

>>> row.b # 属性访问。

>>> con.close()

经过一些调整，上面的范例程序可以被适配为使用 dataclass，或任何其他自定义类，而不是 namedtuple。

如何处理非 UTF-8 文本编码格式

在默认情况下，sqlite3 使用 str 来适配 TEXT 数据类型的 SQLite 值。这对 UTF-8 编码的文本来说很适用，但对于其他编码格式和无效的 UTF-8 来说则可能出错。你可以使用自定义的 text_factory 来处理这种情况。

由于 SQLite 的 flexible typing，遇到包含非 UTF-8 编码格式的 TEXT 数据类型甚至任意数据的表字段的情况并不少见。作为演示，让我们假定有一个使用 ISO-8859-2 (Latin-2) 编码的文本的数据库，例如一个捷克语-英语字典条目的表。假定我们现在有一个 Connection 实例 con 已连接到这个数据库，我们将可以使用这个 text_factory 来解码使用 Latin-2 编码的文本：

con.text_factory = lambda data: str(data, encoding="latin2")

对于存储在 TEXT 表字段中的无效 UTF-8 或任意数据，你可以使用以下技巧，借用自 Unicode 指南:

con.text_factory = lambda data: str(data, errors="surrogateescape")

备注：sqlite3 模块 API 不支持包含替代符的字符串。

参见：Unicode 指南

说明

事务控制

sqlite3 提供了多个方法来控制在何时以及怎样控制数据库事务的开启和关闭。推荐使用通过 autocommit 属性进行事务控制，而通过 isolation_level 属性进行事务控制则保留了 Python 3.12 之前的行为。

通过 autocommit 属性进行事务控制

控制事务行为的推荐方式是通过 Connection.autocommit 属性，最好是使用 connect() 的 autocommit 形参来设置该属性。

建议将 autocommit 设为 False，表示使用兼容 PEP 249 的事务控制。这意味着：

sqlite3 会确保事务始终处于开启状态，因此 connect() 、Connection.commit() 和 Connection.rollback() 将隐式地开启一个新事务（对于后两者，在关闭待处理事务后会立即执行）。开启事务时 sqlite3 会使用 BEGIN DEFERRED 语句。
事务应当显式地使用 commit() 执行提交。
事务应当显式地使用 rollback() 执行回滚。
如果数据库执行 close() 时有待处理的更改则会隐式地执行回滚。

将 autocommit 设为 True 以启用 SQLite 的 autocommit mode。在此模式下，Connection.commit() 和 Connection.rollback() 将没有任何作用。请注意 SQLite 的自动提交模式与兼容 PEP 249 的 Connection.autocommit 属性不同；请使用 Connection.in_transaction 查询底层的 SQLite 自动提交模式。

将 autocommit 设为 LEGACY_TRANSACTION_CONTROL 以将事务控制行为保留给 Connection.isolation_level 属性。