?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 方言的語法和可用的數據類型。

SQL Tutorial

學習 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 數據庫，并且學會了以多種方式往其中插入數據與檢索值。

參見

閱讀?常用方案指引?以獲取更多信息：
- 如何在 SQL 查詢中使用占位符來綁定值
- 如何將自定義 Python 類型適配到 SQLite 值
- 如何將 SQLite 值轉換為自定義 Python 類型
- 如何使用連接上下文管理器
- 如何創建并使用行工廠對象
參閱?說明?以獲取關于事務控制的更深一步的背景。

參考

模塊函數

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)

打開一個與 SQLite 數據庫的連接。

參數

database?(path-like object) -- 要撕開的數據庫文件的路徑。你可以傳入?":memory:"?來創建一個?僅存在于內存中的 SQLite 數據庫，并打開它的一個連接。
timeout?(float) -- 當一個表被鎖定時連接在最終引發?OperationalError?之前應該等待多少秒。如果另一個鏈接開啟了一個事務來修改一個表，該表將被鎖定直到該事務完成提交。默認值為五秒。
detect_types?(int) -- 控制是否以及如何使用由?register_converter()?注冊的轉換器將并非由?SQLite 原生支持的?數據類型轉換為 Python 類型。將它設置為?PARSE_DECLTYPES?和?PARSE_COLNAMES?的任意組合 (使用?|，即按位或) 來啟動它。如果兩個旗標都被設置則列名將優先于聲明的類型。即使設置了?detect_types，依然無法對生成的字段 (例如?max(data)) 進行類型檢測；此時它將改為返回?str。當使用默認值 (0) 時，類型檢測將被禁用。
isolation_level?(str?|?None) -- 控制舊式的事務處理行為。更多信息請參閱?Connection.isolation_level?和?通過 isolation_level 屬性進行事務控制。可以為?"DEFERRED"?(默認值)、"EXCLUSIVE"?或?"IMMEDIATE"；或者為?None?表示禁止隱式地開啟事務。除非?Connection.autocommit?設為?LEGACY_TRANSACTION_CONTROL?(默認值) 否則沒有任何影響。
check_same_thread?(bool) -- 如果為?True?(默認)，則?ProgrammingError?將在數據庫連接被它的創建者以外的線程使用時被引發。如果為?False，則連接可以在多個線程中被訪問；寫入操作需要由用戶者進行序列化以避免數據損壞。請參閱?threadsafety?了解詳情。
factory?(Connection) -- 如果您不想使用默認的?Connection?類創建連接，那么您可以通過傳入一個自定義的?Connection?類的子類給該參數以創建連接。
cached_statements?(int) -- 該參數指明?sqlite3?模塊應該為該連接進行內部緩存的語句 (statements) 數量。默認情況下，它的值為128。
uri?(bool) -- 如果將該參數的值設置為?True，參數?database?將會被解釋為一個由文件路徑與可選的查詢字符串組成的?URI?鏈接。鏈接的前綴協議部分 (schema part)?必需?是?"file:"?，后面的文件路徑可以是相對路徑或絕對路徑。查詢字符串允許向 SQLite 傳遞參數，以實現不同的?如何使用 SQLite URI。
autocommit?(bool) -- 控制?PEP 249?事務處理行為。更多信息參見?Connection.autocommit?和?通過 autocommit 屬性進行事務控制。?autocommit?目前默認值為?LEGACY_TRANSACTION_CONTROL。在未來的 Python 版本中默認值將變為?False。

返回類型

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?。

3.12 新版功能:?autocommit?形參。

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()?前是否還需要額外的輸入。

請參閱?Lib/sqlite3/__main__.py?中的?runsource()?了解實際使用情況。

sqlite3.enable_callback_tracebacks(flag,?/)

是否啟用回調回溯 (callback tracebacks) 。默認情況下，在 SQLite 中，您不會在用戶定義的函數、聚合函數 (aggregates) 、轉換函數 (converters) 、驗證回調函數 (authorizer callbacks) 等中得到任何回溯信息。如果您想調試它們，您可以在將形式參數?flag?設置為?True?的情況下調用該函數。之后您便可以從?sys.stderr?的回調中得到回溯信息。使用?False?將再次禁用該功能。

同樣，您可以注冊一個?unraisable?hook?handler?以改善您的調試體驗：

>>>

>>> sqlite3.enable_callback_tracebacks(True)
>>> con = sqlite3.connect(":memory:")
>>> def evil_trace(stmt):
...     5/0
...
>>> con.set_trace_callback(evil_trace)
>>> def debug(unraisable):
...     print(f"{unraisable.exc_value!r} in callback {unraisable.object.__name__}")
...     print(f"Error message: {unraisable.err_msg}")
>>> import sys
>>> sys.unraisablehook = debug
>>> cur = con.execute("SELECT 1")
ZeroDivisionError('division by zero') in callback evil_trace
Error message: None

sqlite3.register_adapter(type,?adapter,?/)

注冊?adapter?callable?以將 Python 類型?type?適配為一個 SQLite 類型。該適配器在調用時會傳入一個?type?類型的 Python 對象作為其唯一參數，并且必須返回一個?SQLite 原生支持的類型?的值。

sqlite3.register_converter(typename,?converter,?/)

注冊?converter?callable?以將?typename?類型的 SQLite 對象轉換為一個特定類型的 Python 對象。轉換器會針對所有類型為?typename?的 SQLite 值發起調用；它會傳遞一個?bytes?對象并且應該返回一個所需的 Python 類型的對象。請參閱?connect()?的?detect_types?形參了解有關類型檢測工作方式的詳情。

注：typename?以及您在查詢中使用的類型名是不大小寫敏感的。

模塊常量

sqlite3.LEGACY_TRANSACTION_CONTROL

將?autocommit?設為該常量以選擇舊式（Python 3.12 之前）事務控制行為。更多信息請參閱?通過 isolation_level 屬性進行事務控制。

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?callable?返回的旗標，用于指明是否:

訪問被允許（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 2.0 所要求的整數常量，指明?sqlite3?模塊支持的線程安全級別。該屬性將基于編譯下層 SQLite 庫所使用的默認?線程模式?來設置。 SQLite 的線程模式有:

Single-thread: 在此模式下，所有的互斥都被禁用并且 SQLite 同時在多個線程中使用將是不安全的。
Multi-thread: 在此模式下，只要單個數據庫連接沒有被同時用于兩個或多個線程之中 SQLite 就可以安全地被多個線程所使用。
Serialized: 在序列化模式下，SQLite 可以安全地被多個線程所使用而沒有額外的限制。

從 SQLite 線程模式到 DB-API 2.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。

sqlite3.version

此模塊?字符串?形式的版本號。這不是 SQLite 庫的版本號。

從 3.12 版起不建議使用，將在 3.14 版中移除:?這個常量原本是用于反映?pysqlite?包的版本號，它是一個用于對?sqlite3?進行上游修改的第三方庫。如今它已不具任何意義或實用價值。

sqlite3.version_info

此模塊?整數?tuple?形式的版本號。這不是 SQLite 庫的版本號。library.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE

sqlite3.SQLITE_DBCONFIG_DQS_DDL

sqlite3.SQLITE_DBCONFIG_DQS_DML

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP

sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

這些常量被用于?Connection.setconfig()?和?getconfig()?方法。

這些常量的可用性會根據 Python 編譯時使用的 SQLite 版本而發生變化。

3.12 新版功能.

參見

Database Connection Configuration Options

SQLite 文檔：數據庫連接配置選項

連接對象

class?sqlite3.Connection

每個打開的 SQLite 數據庫均以?Connection?對象來表示，這種對象是使用?sqlite3.connect()?創建的。它們的主要目的是創建?Cursor?對象，以及?事務控制。

參見

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

SQLite 數據庫連接對象有如下的屬性和方法：

cursor(factory=Cursor)

創建并返回?Cursor?對象。 cursor 方法接受一個可選參數?factory。如果提供了這個參數，它必須是一個?callable?并且返回?Cursor?或其子類的實例。

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

打開一個已有的?BLOB（二進制大型對象）?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。

3.11 新版功能.

commit()

向數據庫提交任何待處理事務。如果?autocommit?為?True，或者沒有已開啟的事務，則此方法不會做任何操作。如果?autocommit?為?False，則如果有一個待處理事務被此方法提交則會隱式地開啟一個新事務。

rollback()

回滾到任何待處理事務的起始位置。如果?autocommit?為?True，或者沒有已開啟的事務，則此方法不會做任何操作。如果:attr:!autocommit?為?False，則如果此方法回滾了一個待處理事務則會隱式地開啟一個新事務。

close()

關閉數據庫連接。如果?autocommit?為?False，則任何待處理事務都會被隱式地回滾。如果?autocommit?為?True?或?LEGACY_TRANSACTION_CONTROL，則不會執行隱式的事務控制。請確保在關閉之前?commit()?以避免丟失待處理的更改。

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 = 0def step(self, value):self.count += valuedef finalize(self):return self.countcon = 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_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?-- 如果在早于 SQLite 3.25.0，不支持聚合窗口函數的版本上使用。

3.11 新版功能.

示例:

# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:def __init__(self):self.count = 0def step(self, value):"""Add a row to the current window."""self.count += valuedef value(self):"""Return the current value of the aggregate."""return self.countdef inverse(self, value):"""Remove a row from the current window."""self.count -= valuedef finalize(self):"""Return the final value of the aggregate.Any clean-up actions should be placed here."""return self.countcon = 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_yFROM test ORDER BY x
""")
print(cur.fetchall())

create_collation(name,?callable,?/)

使用排序函數?callable?創建一個名為?name?的排序規則。?callable?被傳遞給兩個?字符串?參數，并且它應該返回一個?整數。

如果前者的排序高于后者則為?1
如果前者的排序低于于后者則為?-1
如果它們的順序相同則為?0

下面的例子顯示了一個反向排序的排序方法:

def collate_reverse(string1, string2):if string1 == string2:return 0elif string1 < string2:return 1else:return -1con = 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?來移除一個排序規則函數。

在 3.11 版更改:?排序規則的名稱可以包含任意 Unicode 字符。在之前，只允許 ASCII 字符。

interrupt()

從其他的線程調用此方法以中止可能正在連接上執行的任何查詢。被中止的查詢將引發?OperationalError。

set_authorizer(authorizer_callback)

注冊?callable?authorizer_callback?用于在每次嘗試訪問數據庫中表的某一列時發起調用。該回調應當返回?SQLITE_OK、SQLITE_DENY?或?SQLITE_IGNORE?中的一個以提示下層 SQLite 庫應當如何處理對該列的訪問。

該回調的第一個參數指明哪種操作將被授權。第二個和第三個參數根據第一個參數的具體值將為傳給操作的參數或為?None。第四個參數如果適用則為數據庫名稱（"main", "temp" 等）。第五個參數是負責嘗試訪問的最內層觸發器或視圖的名稱或者如果該嘗試訪問是直接來自輸入的 SQL 代碼的話則為?None。

請參閱 SQLite 文檔了解第一個參數可能的值以及依賴于第一個參數的第二個和第三個參數的含義。所有必需的常量均在?sqlite3?模塊中可用。

將?None?作為?authorizer_callback?傳入將禁用授權回調。

在 3.11 版更改:?增加對使用?None?禁用授權回調的支持。

set_progress_handler(progress_handler,?n)

注冊?callable?progress_handler?以針對 SQLite 虛擬機的每?n?條指令發起調用。如果你想要在長時間運行的操作，例如更新 GUI 期間獲得來自 SQLite 的調用這將很有用處。

如果你想清除任何先前安裝的進度處理句柄，可在調用該方法時傳入?None?作為?progress_handler。

從處理函數返回非零值將終止當前正在執行的查詢并導致它引發?DatabaseError?異常。

set_trace_callback(trace_callback)

注冊?callable?trace_callback?以針對 SQLite 后端實際執行的每條 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,?/,?*,?entrypoint=None)

從共享庫加載 SQLite 擴展。請在調用此方法前通過?enable_load_extension()?來啟用擴展加載。

參數

path?(str) -- SQLite 擴展的路徑。
entrypoint?(str?|?None) -- 入口點名稱。如果為?None?(默認值)，SQLite 將自行生成入口點名稱；請參閱 SQLite 文檔?Loading an Extension?了解詳情。

引發一個?審計事件?sqlite3.load_extension，附帶參數?connection,?path。

3.2 新版功能.

在 3.10 版更改:?增加了?sqlite3.load_extension?審計事件。

3.12 新版功能:?entrypoint?形參。

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

參見

如何處理非 UTF-8 文本編碼格式

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'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 新版功能.

參見

如何處理非 UTF-8 文本編碼格式

getlimit(category,?/)

獲取一個連接的運行時限制。

參數

category?(int) -- 要查詢的?SQLite limit category。

返回類型

int

引發

ProgrammingError?-- 如果?category?不能被下層的 SQLite 庫所識別。

示例，查詢?Connection?con?上一條 SQL 語句的最大長度（默認值為 1000000000）:

>>>

>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000

3.11 新版功能.

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)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1

3.11 新版功能.

getconfig(op,?/)

查詢一個布爾類型的連接配置選項。

參數

op?(int) -- 一個?SQLITE_DBCONFIG 代碼。

返回類型

bool

3.12 新版功能.

setconfig(op,?enable=True,?/)

設置一個布爾類型的連接配置選項。

參數

op?(int) -- 一個?SQLITE_DBCONFIG 代碼。
enable?(bool) -- 如果該配置選項應當啟用則為?True?(默認值)；如果應當禁用則為?False。

3.12 新版功能.

serialize(*,?name='main')

將一個數據庫序列化為?bytes?對象。對于普通的磁盤數據庫文件，序列化就是磁盤文件的一個副本。對于內存數據庫或“臨時”數據庫，序列化就是當數據庫備份到磁盤時要寫入到磁盤的相同字節序列。

參數

name?(str) -- 要序列化的數據庫名稱。默認為?"main"。

返回類型

bytes

備注

此方法僅在下層 SQLite 庫具有序列化 API 時可用。

3.11 新版功能.

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 時可用。

3.11 新版功能.

autocommit

該屬性控制符合?PEP 249?的事務行為。?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?屬性將不起作用。

3.12 新版功能.

in_transaction

這個只讀屬性對應于低層級的 SQLite?autocommit mode。

如果一個事務處于活動狀態（有未提交的更改）則為?True，否則為?False。

3.2 新版功能.

isolation_level

控制?sqlite3?的?舊式事務處理模式。如果設為?None，則絕不會隱式地開啟事務。如果設為?"DEFERRED"、"IMMEDIATE"?或?"EXCLUSIVE"?中的一個，對應于下層的?SQLite transaction behaviour，會執行?隱式事務管理。

如果未被?connect()?的?isolation_level?形參覆蓋，則默認為?""，這是?"DEFERRED"?的一個別名。

備注

建議使用?autocommit?來控制事務處理而不是使用?isolation_level。除非?autocommit?設為?LEGACY_TRANSACTION_CONTROL?(默認值) 否則?isolation_level?將不起作用。

row_factory

針對從該連接創建的?Cursor?對象的初始?row_factory。為該屬性賦值不會影響屬于該連接的現有游標的?row_factory，只影響新的游標。默認為?None，表示將每一行作為?tuple?返回。

詳情參見?如何創建并使用行工廠對象。

text_factory

一個接受?bytes?形參并返回其文本表示形式的?callable。該可調用對象將針對數據類型為?TEXT?的 SQLite 值發起調用。在默認情況下，該屬性將被設為?str。

請參閱?如何處理非 UTF-8 文本編碼格式?了解詳情。

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 查詢中使用占位符來綁定值。

引發

ProgrammingError?-- 如果?sql?包含多條 SQL 語句。

如果?autocommit?為?LEGACY_TRANSACTION_CONTROL，isolation_level?不為?None，sql?為一條?INSERT,?UPDATE,?DELETE?或?REPLACE?語句，并且沒有開啟事務，則會在執行?sql?之前隱式地開啟事務。

從 3.12 版起不建議使用，將在 3.14 版中移除:?如果使用了?命名占位符?并且?parameters?是一個序列而非?dict?則會發出?DeprecationWarning。從 Python 3.14 起，將改為引發?ProgrammingError。

使用?executescript()?來執行多條 SQL 語句。statements.

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 is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)

備注

任何結果行都將被丟棄，包括帶有?RETURNING 子句?的 DML 語句。

從 3.12 版起不建議使用，將在 3.14 版中移除:?如果使用了?命名占位符?并且?parameters?中的每個條目都是序列而非?dict?則會發出?DeprecationWarning。從 Python 3.14 起，將改為引發?ProgrammingError。

executescript(sql_script,?/)

執行?sql_script?中的 SQL 語句。如果?autocommit?為?LEGACY_TRANSACTION_CONTROL?并且存在待處理的事務，則首先隱式執行一條?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,?UPDATE,?DELETE?和?REPLACE?語句所修改行數的只讀屬性；對于其他語句則為?-1，包括?CTE?查詢。只有?execute()?和?executemany()?方法會在語句運行完成后更新此屬性。這意味著任何結果行都必須按順序被提取以使?rowcount?獲得更新。

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 版更改:?添加了對切片操作的支持。

Blob 對象

3.11 新版功能.

class?sqlite3.Blob

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))")# Write to our blob, using two write operations:
with con.blobopen("test", "blob_col", 1) as blob:blob.write(b"hello, ")blob.write(b"world.")# Modify the first and last bytes of our blobblob[0] = ord("H")blob[-1] = ord("!")# Read the contents of our blob
with con.blobopen("test", "blob_col", 1) as blob:greeting = blob.read()print(greeting)  # outputs "b'Hello, world!'"

close()

關閉 blob。

從這一時刻起該 blob 將不再可用。如果再嘗試用該 blob 執行任何操作將引發?Error?(或其子類) 異常。

read(length=-?1,?/)

從 blob 的當前偏移位置讀取?length?個字節的數據。如果到達了 blob 的末尾，則將返回?EOF?之前的數據。當未指定?length，或指定負值時，read()?將讀取至 blob 的末尾。

write(data,?/)

在 blob 的當前偏移位置上寫入?data。此函數不能改變 blob 的長度。寫入數據超出 blob 的末尾將引發?ValueError。

tell()

返回 blob 的當前訪問位置。

seek(offset,?origin=os.SEEK_SET,?/)

將 Blob 的當前訪問位置設為?offset。?origin?參數默認為?os.SEEK_SET?(blob 的絕對位置)。?origin?的其他值包括?os.SEEK_CUR?（相對于當前位置尋址) 和?os.SEEK_END?(相對于 blob 末尾尋址)。

PrepareProtocol 對象

class?sqlite3.PrepareProtocol

PrepareProtocol 類型的唯一目的是作為?PEP 246?風格的適配協議讓對象能夠?將自身適配?為?原生 SQLite 類型。

異常

異常層次是由 DB-API 2.0 (PEP 249) 定義的。

exception?sqlite3.Warning

目前此異常不會被?sqlite3?模塊引發，但可能會被使用?sqlite3?的應用程序引發，例如當一個用戶自定義的函數在插入操作中截斷了數據時。?Warning?是?Exception?的一個子類。

exception?sqlite3.Error

本模塊中其他異常的基類。使用它來捕捉所有的錯誤，只需一條?except?語句。?Error?是?Exception?的子類。

如果異常是產生于 SQLite 庫的內部，則以下兩個屬性將被添加到該異常:

sqlite_errorcode

來自?SQLite API?的數字錯誤代碼

3.11 新版功能.

sqlite_errorname

來自?SQLite API?的數字錯誤代碼符號名稱

3.11 新版功能.

exception?sqlite3.InterfaceError

因錯誤使用低層級 SQLite C API 而引發的異常，換句話說，如果此異常被引發，則可能表明?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?上執行操作。?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.

默認適配器和轉換器（已棄用）

備注

自 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 庫版本。

3.12 新版功能.

常用方案指引

如何在 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 語句可以使用兩種占位符之一：問號占位符（問號風格）或命名占位符（命名風格）。對于問號風格，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, ydef __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, ydef 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, ydef __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 sqlite3def 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?對象可被用作上下文管理器以便在離開上下文管理器代碼塊時自動提交或回滾開啟的事務。如果?with?語句體無異常地結束，事務將被提交。如果提交失敗，或者如果?with?語句體引發了未捕獲的異常，則事務將被回滾。如果?autocommit?為?False，則會在提交或回滾后隱式地開啟一個新事務。

如果在離開?with?語句體時沒有開啟的事務，或者如果?autocommit?為?True，則上下文管理器將不做任何操作。

備注

上下文管理器既不會隱式開啟新事務也不會關閉連接。如果你需要關閉上下文管理器，請考慮使用?contextlib.closing()。

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

備注

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}

以下行工廠函數將返回一個?named tuple:

from collections import namedtupledef 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。

如何處理非 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?屬性。更多信息參見?通過 isolation_level 屬性進行事務控制。

通過?`isolation_level`?屬性進行事務控制

備注

推薦的控制事務方式是通過?autocommit?屬性。參見?通過 autocommit 屬性進行事務控制。

如果?Connection.autocommit?被設為?LEGACY_TRANSACTION_CONTROL?(默認值)，則事務行為由?Connection.isolation_level?屬性控制。否則，isolation_level?將沒有任何作用。

如果連接的屬性?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 語句之前隱式地提交已開啟的事務。現存則不會再這樣做。

在 3.12 版更改:?現在推薦的控制事務方式是通過?autocommit?屬性。