`sqlite3` --- SQLite 数据库 DB-API 2.0 接口模块¶

原始碼：Lib/sqlite3/

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

sqlite3 模块由Gerhard Häring编写。它提供了 PEP 249 所描述的符合 DB-API 2.0 规范的 SQL 接口，并要求使用 SQLite 3.7.15 或更新的版本。

本文档包括了四个主要部分：

教程将教你如何使用 sqlite3 模块。
参考描述了该模块定义的类与函数。
常用方案指引详细介绍了如何处理一些特定的任务。
解釋提供了关于事务控制（transaction control）的更深一步的背景。

也參考

https://www.sqlite.org: SQLite的主页；它的文档详细描述了它所支持的 SQL 方言的语法和可用的数据类型。
https://www.w3schools.com/sql/: 学习 SQL 语法的教程、参考和例子。
PEP 249 - DB-API 2.0 规范: PEP 由 Marc-André Lemburg 撰寫。

教程¶

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

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

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

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

为了执行 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_matser 表以验证新表是否已经创建，本例中，此时该表应该已经包括了一条 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")
>>> 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()  # Remember to commit the transaction after executing INSERT.

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

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

>>> for row in cur.execute("SELECT year, title 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}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975

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

也參考

阅读常用方案指引以获取更多信息：
参阅解釋以获取关于事务控制的更深一步的背景。

参考¶

模块函数¶

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=100, uri=False)¶

打开一个与 SQLite 数据库的连接。

參數

database (path-like object) -- 数据库文件所在的路径。传入 ":memory:" 将会打开一个与在计算机内存 (RAM) 中的数据库连接，而不是打开与在本地磁盘 (disk) 上储存的数据库的连接。
timeout (float) -- 当一个表被锁定时连接在最终引发 OperationalError 之前应该等待多少秒。如果另一个链接开启了一个事务来修改一个表，该表将被锁定直到该事务完成提交。默认值为五秒。
detect_types (int) -- 控制是否以及如何使用由 register_converter() 注册的转换器将并非由 SQLite 原生支持的数据类型转换为 Python 类型。将它设置为 PARSE_DECLTYPES 和 PARSE_COLNAMES 的任意组合 (使用 |，即按位或) 来启动它。如果两个旗标都被设置则列名将优先于声明的类型。即使设置了 detect_types，依然无法对生成的字段 (例如 max(data)) 进行类型检测；此时它将改为返回 str。当使用默认值 (0) 时，类型检测将被禁用。
isolation_level (str | None) -- 该参数代表数据库连接的事务控制级别 (isolation_level)，它将控制数据库事务 (transactions) 是否以及如何隐式创建。它的可取值为 "DEFERRED" （默认值），"EXCLUSIVE"，"IMMEDIATE" 或 None （取用该值将禁止事务的隐式创建）。请参阅事务控制以获取更多信息。
check_same_thread (bool) -- 如果为 True (默认)，则 ProgrammingError 将在数据库连接被它的创建者以外的线程使用时被引发。如果为 False，则连接可以在多个线程中被访问；写入操作需要由用户者进行序列化以避免数据损坏。请参阅 threadsafety 了解详情。
factory (Connection) -- 如果您不想使用默认的 Connection 类创建连接，那么您可以通过传入一个自定义的 Connection 类的子类给该参数以创建连接。
cached_statements (int) -- sqlite3 应当为该连接进行内部缓存以避免解析开销的语句数量。在默认情况下为 100 条语句。
uri (bool) -- 如果将该参数的值设置为 True，参数 database 将会被解释为一个由文件路径与可选的查询字符串组成的 URI 链接。链接的前缀协议部分 (schema part) 必需是 "file:" ，后面的文件路径可以是相对路径或绝对路径。查询字符串允许向 SQLite 传递参数，以实现不同的如何使用 SQLite URI。

傳回型態

Connection

使用它将引发一个附带参数 database 的审计事件 (auditing event) sqlite3.connect 。

使用它将引发一个附带参数 connection_handle 的审计事件 sqlite3.connect/handle 。

3.4 版新加入: uri 參數。

3.7 版更變: database 现在可以是一个 path-like object 对象了，而不仅仅是字符串。

3.10 版新加入: 审计事件 sqlite3.connect/handle 。

sqlite3.complete_statement(statement)¶

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

範例：

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

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

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

sqlite3.register_adapter(type, adapter, /)¶: 注册一个可调用的适配器 (adapter) 以将一个 Python 类型适配为一个 SQLite 类型。适配器应该以一个类型为 type 的 Python 对象作为它的唯一参数传入调用，并且必需返回能被 SQLite 原生支持的类型的一个值。

sqlite3.register_converter(typename, converter, /)¶

注册一个可调用的转换器 (converter) ，它能够将 SQLite 对象转换为一个特定类型的 Python 对象。转换器将会对所有类型为 typename 的 SQLite 值进行调用；它会被传递给一个 bytes 对象并且应该返回一个所需的 Python 类型的对象。您可以参考函数 connect() 的形式参数 detect_types 的文档，以了解关于类型检测 (detection works) 是如何工作的详细信息。

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

模块常量¶

sqlite3.PARSE_COLNAMES¶

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

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

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

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 组合。

sqlite3.SQLITE_OK¶

sqlite3.SQLITE_DENY¶

sqlite3.SQLITE_IGNORE¶

作为传递给函数 Connection.set_authorizer() 的形式参数 authorizer_callback 的回调函数应该返回的标志 (flags) ，以表明是否：

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

sqlite3.apilevel¶: 指明所支持的 DB-API 级别的字符串常量。根据 DB-API 的需要设置。硬编码为 "2.0"。

sqlite3.paramstyle¶: 指明 sqlite3 模块所预期的形参标记格式化类型。根据 DB-API 的需要设置。硬编码为 "qmark"。

備註

named DB-API 形参风格也受到支持。

sqlite3.sqlite_version¶: 以 字符串 表示的运行时 SQLite 库版本号。

sqlite3.sqlite_version_info¶: 以 整数 tuple 表示的运行时. SQLite 库版本号。

sqlite3.threadsafety¶

由 DB-API 所需要的整数常量，指明 sqlite3 模块支持的线程安全 (thread safety) 等级。目前硬编码为 1，表示 线程可能会分享模块 (module) ，但不会分享连接 (connections) 。然而，这可能不会总是正确的，即它无法完全确保它所指明的情况总是为真。您可以通过使用以下查询以检查底层的 SQLite 库在编译时的线程模式 (threaded mode) ：

import sqlite3
con = sqlite3.connect(":memory:")
con.execute("""
    select * from pragma_compile_options
    where compile_options like 'THREADSAFE=%'
""").fetchall()

注意 SQLITE_THREADSAFE 级别与 DB-API 2.0 threadsafety 级别不一致。

sqlite3.version¶: 此模块 字符串 形式的版本号。这不是 SQLite 库的版本号。

sqlite3.version_info¶: 此模块 整数 tuple 形式的版本号。这不是 SQLite 库的版本号。library.

连接对象¶

class sqlite3.Connection¶

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

也參考

如何使用连接快捷方法
如何使用连接上下文管理器

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

cursor(factory=Cursor)¶: 创建并返回一个 Cursor 对象。该方法接受一个可选的形式参数 factory 。如果要提供该参数，请确保该参数是一个能够返回从属于 Cursor 类或其子类的实例的可调用参数。

commit()¶: 向数据库提交任何未决事务 (pending transaction) 。如果不存在打开的事务，那么该方法便没有作用。

rollback()¶: 回滚到任何未决事务 (pending transaction) 的起点处。如果不存在打开的事务，那么该方法便没有作用。

close()¶: 关闭数据库连接。任何未决事务 (pending transaction) 都不会被隐式提交，即所有未提交的事务都会丢失。请确保您在关闭数据库连接前调用方法 commit() ，以避免丢失任何挂起 (pending) 的更改。

execute(sql, parameters=(), /)¶: 创建一个新的 Cursor 对象，并在其上使用给出的 sql 和 parameters 调用 execute()。返回新的游标对象。

executemany(sql, parameters, /)¶: 创建一个新的 Cursor 对象，并在其上使用给出的 sql 和 parameters 调用 executemany()。返回新的游标对象。

executescript(sql_script, /)¶: 创建一个新的 Cursor 对象，并在其上使用给出的 sql_script 调用 executescript()。返回新的游标对象。

create_function(name, narg, func, *, deterministic=False)¶

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

參數

name (str) -- SQL 函数的名称。
narg (int) -- SQL 函数可接受的参数数量，如果是 -1，则该函数可以接受任意数量的参数。
func (callback | None) -- 当 SQL 函数被调用时，所唤起的一个可调用对象 (callable) 。该可调用对象应该返回一个 SQLite 原生支持的类型。如果将它设置为 None ，那么将会移除一个现存的 SQL 函数。
deterministic (bool) -- 如为 True，创建的 SQL 函数将被标记为 deterministic，这允许 SQLite 执行额外的优化。

丟出

NotSupportedError -- 如果 deterministic 在早于 SQLite 3.8.3 的版本上使用。

3.8 版新加入: 新增 deterministic 參數。

範例：

>>> import hashlib
>>> def md5sum(t):
...     return hashlib.md5(t).hexdigest()
>>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> for row in con.execute("SELECT md5(?)", (b"foo",)):
...     print(row)
('acbd18db4cc2f85cedef654fccc4a4d8',)

create_aggregate(name, /, n_arg, aggregate_class)¶

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

參數

name (str) -- SQL 聚合函数的名称。
n_arg (int) -- SQL 聚合函数可接受的参数数量。如为 -1，则可以接受任意数量的参数。
aggregate_class (class | None) -- 一个类必须实现下列方法: * step(): 向聚合添加一行。 * finalize(): 将聚合的最终结果作为一个 SQLite 原生支持的类型返回。 step() 方法需要接受的参数数量是由 n_arg 控制的。设为 None 将移除现有的 SQL 聚合函数。

範例：

class MySum:
    def __init__(self):
        self.count = 0

    def step(self, value):
        self.count += value

    def finalize(self):
        return self.count

con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.execute("CREATE TABLE test(i)")
cur.execute("INSERT INTO test(i) VALUES(1)")
cur.execute("INSERT INTO test(i) VALUES(2)")
cur.execute("SELECT mysum(i) FROM test")
print(cur.fetchone()[0])

con.close()

create_collation(name, callable)¶

使用排序函数 callable 创建一个名为 name 的排序规则。 callable 被传递给两个 字符串 参数，并且它应该返回一个 整数。

如果前者的排序高于后者则为 1
如果前者的排序低于于后者则为 -1
如果它们的顺序相同则为 0

下面的例子显示了一个反向排序的排序方法:

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.execute("CREATE TABLE test(x)")
cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])
cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")
for row in cur:
    print(row)
con.close()

通过将 callable 设为 None 来移除一个排序规则函数。

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

set_authorizer(authorizer_callback)¶

注册可调用的 authorizer_callback 回调函数，它将在每次试图访问数据库中的表的某一列被调用。回调函数应该返回常量 SQLITE_OK、SQLITE_DENY、SQLITE_IGNORE 中的任意一个，以表明对该列的访问应该由底层 SQLite 库进行怎样的处理。

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

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

set_progress_handler(progress_handler, n)¶

注册可调用的 progress_handler 函数，它将在 SQLite 虚拟机 (SQLite virtual machine) 的每 n 条指令中被调用。如果您向在长期运行的操作中得到 SQLite 的调用，例如更新GUI，那么这个函数将非常有用。

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

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

set_trace_callback(trace_callback)¶

注册可调用的 trace_callback 追踪回调函数，它将在 SQLite后端 (SQLite backend) 执行每一条 SQL 语句时被调用。

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

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

備註

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

3.3 版新加入.

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。

3.2 版新加入.

3.10 版更變: 增加了 sqlite3.enable_load_extension 审计事件。

con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from 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)

con.close()

load_extension(path, /)¶

从指定路径 path 的共享库中加载一个 SQLite 扩展。请您在调用该方法前，确保您已经使用 enable_load_extension() 方法启用了拓展的加载。

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

3.2 版新加入.

3.10 版更變: 增加了 sqlite3.load_extension 审计事件。

iterdump()¶

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

範例：

# Convert file example.db to SQL dump file 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()

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

创建 SQLite 数据库的备份。

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

參數

target (Connection) -- 用于保存备份的数据库连接。
pages (int) -- 每次要拷贝的页数。如果小于等于 0，则一次性拷贝整个数据库。默认为 -1。
progress (callback | None) -- 如果将它设置为一个可调用的回调函数 (callable) ，那么它会在每次备份迭代 (backup iteration) 时被调用，并且带有以下三个整数参数：最近一次迭代的的状态（形式参数 status），需要复制的剩余页数（形式参数 remaining）以及总页数（形式参数 total）。默认值为 None。
name (str) -- 要备份的数据库名称。可能为代表主数据库的 "main" (默认值)，代表临时数据库的 "temp"，或者使用 ATTACH DATABASE SQL 语句所附加的自定义数据库名称。
sleep (float) -- 连续尝试备份剩余页所要间隔的休眠秒数。

示例 1，将现有数据库拷贝至另一个数据库:

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

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)

3.7 版新加入.

in_transaction¶

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

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

3.2 版新加入.

isolation_level¶

该属性控制由 sqlite3 模块执行的事务处理。如果将该属性设置为 None ，那么事务将永远不会被隐式地打开。如果将它设置为 "DEFERRED" 、 "IMMEDIATE" 、 "EXCLUSIVE" 中的任意一个，那么事务管理 (transaction management) 将会隐式地根据其对应的 SQLite transaction behaviour 执行。

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

row_factory¶

针对从该连接创建的 Cursor 对象的初始 row_factory。为该属性赋值不会影响属于该连接的现有游标的 row_factory，只影响新的游标。默认为 None，表示将每一行作为 tuple 返回。

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

text_factory¶

一个可调用对象 (callable) ，它接受一个 bytes 作为形式参数并且返回该参数的文本表示。该调用对象将为数据类型为 TEXT 的 SQLite 值调用。默认情况下，该属性将被设置为 str ，这意味着它总是返回一个字符串。如果您想返回 bytes ，请将*text_factory*设置为`bytes`。

範例：

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

AUSTRIA = "Österreich"

# by default, rows are returned as str
cur.execute("SELECT ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

# but we can make sqlite3 always return bytestrings ...
con.text_factory = bytes
cur.execute("SELECT ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
# database ...
assert row[0] == AUSTRIA.encode("utf-8")

# we can also implement a custom text_factory ...
# here we implement one that appends "foo" to all strings
con.text_factory = lambda x: x.decode("utf-8") + "foo"
cur.execute("SELECT ?", ("bar",))
row = cur.fetchone()
assert row[0] == "barfoo"

con.close()

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 游标实例具有以下属性和方法。

execute(sql, parameters=(), /)¶

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

參數

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

丟出

Warning -- 如果 sql 包含多条 SQL 语句。

如果属性 isolation_level 的值不是 None，并且*sql* 是一个 INSERT、UPDATE、 DELETE、或 REPLACE 语句，并且现在没有打开的事务 (transaction) ，那么在执行 sql 语句前将会隐式打开一个事务。

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

executemany(sql, parameters, /)¶

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

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

參數

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

丟出

ProgrammingError -- 如果 sql 不是一条 DML 语句。
Warning -- 如果 sql 包含多条 SQL 语句。

範例：

rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)

executescript(sql_script, /)¶

执行形式参数 sql_script 中的 SQL 语句。如果在执行时仍有一个未决事务 (pending transaction) ，那么首先会隐式地执行一个 COMMIT 语句。请注意，除此之外，它不会执行任何隐式的事务控制；因此，任何关于事务控制的内容都应添加到 sql_script 中。

sql_script 必须为 字符串。

範例：

# cur is an sqlite3.Cursor object
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

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

fetchmany(size=cursor.arraysize)¶

将下一个多行查询结果集作为 list 返回。如果没有更多可用行时则返回一个空列表。

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

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

fetchall()¶: 将全部（剩余的）查询结果行作为 list 返回。如果没有可用的行则返回空列表。请注意 arraysize 属性可能会影响此操作的性能。

close()¶

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

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

setinputsizes(sizes, /)¶: DB-API 要求的方法。在 sqlite3 不做任何事情。

setoutputsize(size, column=None, /)¶: DB-API 要求的方法。在 sqlite3 不做任何事情。

arraysize¶: 用于控制 fetchmany() 返回行数的可读取/写入属性。该属性的默认值为 1，表示每次调用将获取单独一行。

connection¶

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

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True

description¶

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

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

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

備註

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

3.6 版更變: 新增 REPLACE 陳述式的支援。

rowcount¶: 这是一个只读属性。对于语句 INSERT、DELETE、REPLACE ，它将提供这些语句所修改的行数；对于其他语句，包括 CTE 查询，它的值将会是 -1。它的值只会在执行方法 execute() 与方法 executemany() 时发生更新。

row_factory¶

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

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

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

Row 对象¶

class sqlite3.Row¶

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

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

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

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

3.5 版更變: 添加了对切片操作的支持。

PrepareProtocol 对象¶

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

例外¶

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

exception sqlite3.Warning¶: 当 SQL 查询不是一个 字符串 或多个语句被传递给了方法 execute() 或方法 executemany() 时由模块 sqlite3 引发的异常。Warning 是 Exception 的子类。

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

exception sqlite3.InterfaceError¶: 当跨越回滚 (rollback) 获取数据或模块 sqlite3 无法绑定参数时引发的异常。InterfaceError 是 Error 的子类。

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

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

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

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

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

exception sqlite3.ProgrammingError¶: 由 sqlite3 API 编程错误引发的异常。例如，您尝试对一个已经关闭的 Connection 对象进行操作，或试图通过方法 executemany() 执行非DML语句 (non-DML statements) ，这些行为都会引发该异常。ProgrammingError 是 DatabaseError 的子类。

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

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.

默认适配器和转换器¶

对于 datetime 模块中的 date 和 datetime 类型已提供了默认的适配器。它们将会以 ISO 日期/ISO 时间戳的形式发给 SQLite。

默认转换器使用的注册名称是针对 datetime.date 的 "date" 和针对 datetime.datetime 的 "timestamp"。

通过这种方式，你可以在大多数情况下使用 Python 的 date/timestamp 对象而无须任何额外处理。适配器的格式还与实验性的 SQLite date/time 函数兼容。

下面的示例演示了这一点。

import sqlite3
import datetime

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(d date, ts timestamp)")

today = datetime.date.today()
now = datetime.datetime.now()

cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
cur.execute("select d, ts from test")
row = cur.fetchone()
print(today, "=>", row[0], type(row[0]))
print(now, "=>", row[1], type(row[1]))

cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
row = cur.fetchone()
print("current_date", row[0], type(row[0]))
print("current_timestamp", row[1], type(row[1]))

con.close()

如果存储在 SQLite 中的时间戳的小数位多于 6 个数字，则时间戳转换器会将该值截断至微秒精度。

備註

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

常用方案指引¶

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

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

>>> # Never do this -- insecure!
>>> 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语句可能使用这两种占位符中的一种：? 标记（或称问号标记风格 qmark style）或具名占位符（或称具名风格 named style）。对于问号标记风格，parameters 必须是一个长度与 ? 标记的数量匹配的序列 (sequence)，否则将会抛出 ProgrammingError 错误。对于具名风格，parameters 必须是一个 dict 或是其子类的实例，同时该实例必须包括所有具名占位符所对应的键。其中，该实例中不为具名占位符所对应的键将会被忽略。这里是上述两种风格的示例：

con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# This is the named style used with 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)

# This is the qmark style used in a SELECT query:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())

備註

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

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

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

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

如何编写可适配对象¶

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

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])

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

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

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])

如何将 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。列名的优先级高于声明的类型。

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

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)

# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Parse using declared types
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) Parse using column names
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])

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

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

import datetime
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    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):
    """Convert ISO 8601 date to datetime.date object."""
    return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    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 语句，并对其进行迭代。

# Create and fill the table.
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)

# Print the table contents
for row in con.execute("SELECT name, first_appeared FROM lang"):
    print(row)

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

# close() is not a shortcut method and it's not called automatically;
# the connection object should be closed manually
con.close()

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

一个 Connection 对象可以像一个上下文管理器 (context manager) 那般被使用，在这种情况下当离开上下文管理器的主体时，将会自动提交或回滚打开的事务。如果 with 语句的主体在没有异常的情况下完成，那么事务便会被提交；如果提交失败，或者 with 语句的主体引发了一个未被捕获异常，那么事务将会回滚。

如果在离开 with 语句的主体时没有打开的事务，那么上下文管理器是无用的。

備註

此上下文管理器不会隐式地开启新事务也不会关闭连接。

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() is called after the with block finishes with an exception,
# the exception is still raised and must be caught
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
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

如果一个数据库尚不存在则不会隐式地新建数据库；如果无法新建数据库则将引发 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,)

关于此特性的更多信息，包括可用的形参列表，可以在 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]         # Access by index.
'Earth'
>>> row["name"]    # Access by name.
'Earth'
>>> row["RADIUS"]  # Column names are case-insensitive.
6378

你可以创建自定义 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}

以下行工厂函数将返回一个 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]  # Indexed access.
1
>>> row.b   # Attribute access.
2

经过一些调整，上面的范例程序可以被适配为使用 dataclass，或任何其他自定义类，而不是 namedtuple。

解釋¶

事务控制¶

sqlite3 模块并不遵守 PEP 249 所推荐的事务控制规范。

如果连接的属性 isolation_level 不为 None，新的事务会在 execute() 和 executemany() 执行 INSERT, UPDATE, DELETE 或 REPLACE 语句之前隐式地开启；对于其他语句，则不会执行隐式的事务处理。可分别使用 commit() 和 rollback() 方法提交和回滚未应用的事务。你可以通过 isolation_level 属性来选择下层的 SQLite transaction behaviour — 也就是说，sqlite3 是否要隐式地执行以及执行何种类型的 BEGIN 语句

如果 isolation_level 被设为 None，则完全不会隐式地开启任何事务。这将使下层 SQLite 库处于自动提交模式，但也允许用户使用显式 SQL 语句执行他们自己的事务处理。下层 SQLite 库的自动提交模式可使用 in_transaction 属性来查询。

executescript() 方法会在执行给定的 SQL 脚本之前隐式地提交任何挂起的事务，无论 isolation_level 的值是什么。

3.6 版更變: 在以前 sqlite3 会在 DDL 语句之前隐式地提交已开启的事务。现存则不会再这样做。

`sqlite3` --- SQLite 数据库 DB-API 2.0 接口模块¶

教程¶

参考¶

模块函数¶

模块常量¶

连接对象¶

游标对象¶

Row 对象¶

PrepareProtocol 对象¶

例外¶

SQLite 与 Python 类型¶

默认适配器和转换器¶

常用方案指引¶

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

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

如何编写可适配对象¶

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

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

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

如何使用连接快捷方法¶

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

如何使用 SQLite URI¶

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

解釋¶

事务控制¶

目录

上個主題

下個主題

此頁面

sqlite3 --- SQLite 数据库 DB-API 2.0 接口模块¶

教程¶

参考¶

模块函数¶

模块常量¶

连接对象¶

游标对象¶

Row 对象¶

PrepareProtocol 对象¶

例外¶

SQLite 与 Python 类型¶

默认适配器和转换器¶

常用方案指引¶

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

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

如何编写可适配对象¶

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

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

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

如何使用连接快捷方法¶

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

如何使用 SQLite URI¶

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

解釋¶

事务控制¶

`sqlite3` --- SQLite 数据库 DB-API 2.0 接口模块¶