`sqlite3` --- Giao diện DB-API 2.0 cho cơ sở dữ liệu SQLite¶

Source code: Lib/sqlite3/

SQLite là thư viện C cung cấp cơ sở dữ liệu dựa trên đĩa nhẹ, không yêu cầu quy trình máy chủ riêng và cho phép truy cập cơ sở dữ liệu bằng biến thể không chuẩn của ngôn ngữ truy vấn SQL. Một số ứng dụng có thể sử dụng SQLite để lưu trữ dữ liệu nội bộ. Cũng có thể tạo nguyên mẫu một ứng dụng bằng SQLite và sau đó chuyển mã sang cơ sở dữ liệu lớn hơn như PostgreSQL hoặc Oracle.

Mô-đun sqlite3 được viết bởi Gerhard Häring. Nó cung cấp giao diện SQL tuân thủ thông số kỹ thuật DB-API 2.0 được mô tả bởi PEP 249 và yêu cầu thư viện SQLite của bên thứ ba.

Đây là một optional module. Nếu nó bị thiếu trong bản sao CPython của bạn, hãy tìm tài liệu từ nhà phân phối của bạn (nghĩa là bất kỳ ai đã cung cấp Python cho bạn). Nếu bạn là nhà phân phối, hãy xem Yêu cầu đối với các mô-đun tùy chọn.

Tài liệu này bao gồm bốn phần chính:

Hướng dẫn dạy cách sử dụng mô-đun sqlite3.
Tài liệu tham khảo mô tả các lớp và chức năng mà mô-đun này xác định.
Hướng dẫn cách thực hiện trình bày chi tiết cách xử lý các tác vụ cụ thể.
Giải thích cung cấp kiến thức chuyên sâu về kiểm soát giao dịch.

Xem thêm

https://www.sqlite.org: Trang web SQLite; tài liệu mô tả cú pháp và các kiểu dữ liệu có sẵn cho phương ngữ SQL được hỗ trợ.
https://www.w3schools.com/sql/: Hướng dẫn, tham khảo và ví dụ để học cú pháp SQL.
PEP 249 - Cơ sở dữ liệu API Đặc tả 2.0: PEP được viết bởi Marc-André Lemburg.

Hướng dẫn¶

Trong hướng dẫn này, bạn sẽ tạo cơ sở dữ liệu về phim Monty Python bằng chức năng sqlite3 cơ bản. Nó giả định sự hiểu biết cơ bản về các khái niệm cơ sở dữ liệu, bao gồm cursors và transactions.

Đầu tiên, chúng ta cần tạo cơ sở dữ liệu mới và mở kết nối cơ sở dữ liệu để cho phép sqlite3 hoạt động với nó. Gọi sqlite3.connect() để tạo kết nối tới cơ sở dữ liệu tutorial.db trong thư mục làm việc hiện tại, ngầm tạo nó nếu nó không tồn tại:

nhập sqlite3
con = sqlite3.connect("tutorial.db")

Đối tượng Connection được trả về con thể hiện kết nối tới cơ sở dữ liệu trên đĩa.

Để thực thi các câu lệnh SQL và tìm nạp kết quả từ các truy vấn SQL, chúng ta sẽ cần sử dụng con trỏ cơ sở dữ liệu. Gọi con.cursor() để tạo Cursor:

cur = con.cursor()

Bây giờ chúng ta đã có kết nối cơ sở dữ liệu và con trỏ, chúng ta có thể tạo bảng cơ sở dữ liệu movie với các cột cho tiêu đề, năm phát hành và điểm đánh giá. Để đơn giản, chúng ta chỉ có thể sử dụng tên cột trong phần khai báo bảng -- nhờ tính năng flexible typing của SQLite, việc chỉ định các kiểu dữ liệu là tùy chọn. Thực thi câu lệnh CREATE TABLE bằng cách gọi cur.execute(...):

cur.execute("phim CREATE TABLE (tiêu đề, năm, điểm)")

Chúng tôi có thể xác minh rằng bảng mới đã được tạo bằng cách truy vấn bảng sqlite_master được tích hợp sẵn trong SQLite. Bảng này hiện sẽ chứa mục nhập cho định nghĩa bảng movie (xem The Schema Table để biết chi tiết). Thực hiện truy vấn đó bằng cách gọi cur.execute(...), gán kết quả cho res và gọi res.fetchone() để tìm nạp hàng kết quả:

>>> res = cur.execute("tên SELECT FROM sqlite_master")
>>> res.fetchone()
('phim',)

Chúng ta có thể thấy rằng bảng đã được tạo, khi truy vấn trả về tuple chứa tên của bảng. Nếu chúng ta truy vấn sqlite_master để tìm bảng spam không tồn tại, res.fetchone() sẽ trả về None:

>>> res = cur.execute("SELECT tên FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() là Không có
đúng

Bây giờ, hãy thêm hai hàng dữ liệu được cung cấp dưới dạng chữ SQL bằng cách thực thi câu lệnh INSERT, một lần nữa bằng cách gọi cur.execute(...):

cur.execute("""
    phim INSERT INTO VALUES
        ("Monty Python và Chén Thánh", 1975, 8.2),
        ('Và bây giờ là điều gì đó hoàn toàn khác', 1971, 7.5)
""")

Câu lệnh INSERT ngầm mở một giao dịch cần được thực hiện trước khi các thay đổi được lưu vào cơ sở dữ liệu (xem Kiểm soát giao dịch để biết chi tiết). Gọi con.commit() trên đối tượng kết nối để thực hiện giao dịch:

con.commit()

Chúng tôi có thể xác minh rằng dữ liệu đã được chèn chính xác bằng cách thực hiện truy vấn SELECT. Sử dụng cur.execute(...) quen thuộc để gán kết quả cho res và gọi res.fetchall() để trả về tất cả các hàng kết quả:

>>> res = cur.execute("SELECT điểm FROM phim")
>>> res.fetchall()
[(8.2,), (7.5,)]

Kết quả là một list gồm hai tuples, mỗi hàng một hàng, mỗi hàng chứa giá trị score của hàng đó.

Bây giờ, chèn thêm ba hàng bằng cách gọi cur.executemany(...):

dữ liệu = [
    ("Monty Python Trực tiếp tại Hollywood Bowl", 1982, 7.9),
    ("Ý nghĩa cuộc sống của Monty Python", 1983, 7.5),
    ("Cuộc đời Brian của Monty Python", 1979, 8.0),
]
cur.executemany("INSERT INTO phim VALUES(?, ?, ?)", data)
con.commit() # Remember để thực hiện giao dịch sau khi thực hiện INSERT.

Lưu ý rằng phần giữ chỗ ? được sử dụng để liên kết data với truy vấn. Luôn sử dụng trình giữ chỗ thay vì string formatting để liên kết các giá trị Python với câu lệnh SQL, để tránh SQL injection attacks (xem Cách sử dụng trình giữ chỗ để liên kết các giá trị trong truy vấn SQL để biết thêm chi tiết).

Chúng tôi có thể xác minh rằng các hàng mới đã được chèn bằng cách thực hiện truy vấn SELECT, lần này lặp lại kết quả của truy vấn:

>>> cho hàng trong cur.execute("SELECT năm, tiêu đề phim FROM ORDER THEO năm"):
... in(hàng)
(1971, 'Và bây giờ là một điều gì đó hoàn toàn khác')
(1975, 'Monty Python và Chén Thánh')
(1979, "Cuộc đời Brian của Monty Python")
(1982, 'Monty Python trực tiếp tại Hollywood Bowl')
(1983, "Ý nghĩa cuộc sống của Monty Python")

Mỗi hàng là một tuple gồm hai mục trong số (year, title), khớp với các cột được chọn trong truy vấn.

Cuối cùng, xác minh rằng cơ sở dữ liệu đã được ghi vào đĩa bằng cách gọi con.close() để đóng kết nối hiện có, mở kết nối mới, tạo con trỏ mới, sau đó truy vấn cơ sở dữ liệu:

>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("tiêu đề SELECT, phim FROM năm ORDER THEO điểm DESC")
>>> tiêu đề, năm = res.fetchone()
>>> print(f'Phim Monty Python có điểm cao nhất là {title!r}, phát hành vào {year}')
Phim Monty Python đạt điểm cao nhất là 'Monty Python and the Holy Grail', phát hành năm 1975
>>> new_con.close()

Bây giờ bạn đã tạo cơ sở dữ liệu SQLite bằng mô-đun sqlite3, chèn dữ liệu và truy xuất các giá trị từ đó theo nhiều cách.

Xem thêm

Hướng dẫn cách thực hiện để đọc thêm:
Giải thích để có kiến thức chuyên sâu về kiểm soát giao dịch.

Tài liệu tham khảo¶

Chức năng mô-đun¶

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

Mở kết nối tới cơ sở dữ liệu SQLite.

Tham số:

database (path-like object) -- Đường dẫn tới file cơ sở dữ liệu cần mở. Bạn có thể chuyển ":memory:" để tạo SQLite database existing only in memory và mở kết nối với nó.
timeout (float) -- Kết nối phải đợi bao nhiêu giây trước khi tăng OperationalError khi bảng bị khóa. Nếu một kết nối khác mở một giao dịch để sửa đổi bảng, bảng đó sẽ bị khóa cho đến khi giao dịch được thực hiện. Mặc định là năm giây.
detect_types (int) -- Kiểm soát xem các loại dữ liệu không phải natively supported by SQLite có được tra cứu để chuyển đổi sang loại Python hay không và bằng cách nào bằng cách sử dụng các trình chuyển đổi đã đăng ký với register_converter(). Đặt nó thành bất kỳ kết hợp nào (sử dụng |, bitwise hoặc) của PARSE_DECLTYPES và PARSE_COLNAMES để kích hoạt tính năng này. Tên cột được ưu tiên hơn các loại được khai báo nếu cả hai cờ được đặt. Theo mặc định (0), tính năng phát hiện loại bị tắt.
isolation_level (str | None) -- Kiểm soát hành vi xử lý giao dịch kế thừa. Xem Connection.isolation_level và Kiểm soát giao dịch thông qua thuộc tính isolation_level để biết thêm thông tin. Có thể là "DEFERRED" (mặc định), "EXCLUSIVE" hoặc "IMMEDIATE"; hoặc None để vô hiệu hóa việc mở giao dịch một cách ngầm định. Không có hiệu lực trừ khi Connection.autocommit được đặt thành LEGACY_TRANSACTION_CONTROL (mặc định).
check_same_thread (bool) -- Nếu True (mặc định), ProgrammingError sẽ được nâng lên nếu kết nối cơ sở dữ liệu được sử dụng bởi một luồng không phải là luồng đã tạo ra nó. Nếu False, kết nối có thể được truy cập trong nhiều luồng; Người dùng có thể cần phải tuần tự hóa các thao tác ghi để tránh hỏng dữ liệu. Xem threadsafety để biết thêm thông tin.
factory (Connection) -- Một lớp con tùy chỉnh của Connection để tạo kết nối, nếu không phải là lớp Connection mặc định.
cached_statements (int) -- Số lượng câu lệnh mà sqlite3 nên lưu vào bộ nhớ đệm nội bộ cho kết nối này để tránh phân tích cú pháp quá mức. Theo mặc định, 128 câu lệnh.
uri (bool) -- Nếu được đặt thành True, database được hiểu là URI với đường dẫn tệp và chuỗi truy vấn tùy chọn. Phần sơ đồ must là "file:" và đường dẫn có thể là tương đối hoặc tuyệt đối. Chuỗi truy vấn cho phép truyền tham số tới SQLite, cho phép nhiều Cách làm việc với URI SQLite khác nhau.
autocommit (bool) -- Kiểm soát hành vi xử lý giao dịch PEP 249. Xem Connection.autocommit và Kiểm soát giao dịch thông qua thuộc tính autocommit để biết thêm thông tin. autocommit hiện được mặc định là LEGACY_TRANSACTION_CONTROL. Mặc định sẽ thay đổi thành False trong bản phát hành Python trong tương lai.

Kiểu trả về:

Connection

Tăng một auditing event sqlite3.connect với đối số database.

Tăng một auditing event sqlite3.connect/handle với đối số connection_handle.

Thay đổi trong phiên bản 3.4: Đã thêm tham số uri.

Thay đổi trong phiên bản 3.7: database bây giờ cũng có thể là path-like object chứ không chỉ là một chuỗi.

Thay đổi trong phiên bản 3.10: Đã thêm sự kiện kiểm tra sqlite3.connect/handle.

Thay đổi trong phiên bản 3.12: Đã thêm tham số autocommit.

Thay đổi trong phiên bản 3.13: Việc sử dụng theo vị trí của các tham số timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements và uri không được dùng nữa. Chúng sẽ trở thành tham số chỉ có từ khóa trong Python 3.15.

sqlite3.complete_statement(statement)¶

Trả về True nếu chuỗi statement dường như chứa một hoặc nhiều câu lệnh SQL hoàn chỉnh. Không có xác minh cú pháp hoặc phân tích cú pháp nào được thực hiện, ngoài việc kiểm tra xem không có chuỗi ký tự nào không được tiết lộ và câu lệnh được kết thúc bằng dấu chấm phẩy.

Ví dụ:

>>> sqlite3.complete_statement("SELECT foo FROM bar;")
đúng
>>> sqlite3.complete_statement("SELECT foo")
sai

Hàm này có thể hữu ích trong quá trình nhập dòng lệnh để xác định xem văn bản đã nhập có tạo thành một câu lệnh SQL hoàn chỉnh hay không hoặc liệu có cần nhập thêm dữ liệu trước khi gọi execute() hay không.

Xem runsource() trong Lib/sqlite3/__main__.py để sử dụng trong thế giới thực.

sqlite3.enable_callback_tracebacks(flag, /)¶: Bật hoặc tắt tính năng theo dõi cuộc gọi lại. Theo mặc định, bạn sẽ không nhận được bất kỳ dấu vết nào trong các hàm do người dùng xác định, tổng hợp, bộ chuyển đổi, lệnh gọi lại của người ủy quyền, v.v. Nếu muốn gỡ lỗi chúng, bạn có thể gọi hàm này bằng flag được đặt thành True. Sau đó, bạn sẽ nhận được dấu vết từ các lệnh gọi lại trên sys.stderr. Sử dụng False để tắt lại tính năng này.

Ghi chú

Lỗi trong lệnh gọi lại hàm do người dùng xác định được ghi lại dưới dạng ngoại lệ không thể xử lý được. Sử dụng unraisable hook handler để xem xét cuộc gọi lại không thành công.

sqlite3.register_adapter(type, adapter, /)¶: Đăng ký adapter callable để điều chỉnh loại type của Python thành loại SQLite. Bộ điều hợp được gọi với đối tượng Python thuộc loại type làm đối số duy nhất và phải trả về giá trị type that SQLite natively understands.

sqlite3.register_converter(typename, converter, /)¶

Đăng ký converter callable để chuyển đổi các đối tượng SQLite thuộc loại typename thành đối tượng Python thuộc một loại cụ thể. Trình chuyển đổi được gọi cho tất cả các giá trị SQLite thuộc loại typename; nó được truyền một đối tượng bytes và sẽ trả về một đối tượng thuộc loại Python mong muốn. Tham khảo tham số detect_types của connect() để biết thông tin về cách hoạt động của tính năng phát hiện loại.

Lưu ý: typename và tên loại trong truy vấn của bạn được khớp không phân biệt chữ hoa chữ thường.

Hằng số mô-đun¶

sqlite3.LEGACY_TRANSACTION_CONTROL¶: Đặt autocommit thành hằng số này để chọn hành vi kiểm soát giao dịch kiểu cũ (tiền Python 3.12). Xem Kiểm soát giao dịch thông qua thuộc tính isolation_level để biết thêm thông tin.

sqlite3.PARSE_DECLTYPES¶

Chuyển giá trị cờ này cho tham số detect_types của connect() để tra cứu hàm chuyển đổi bằng cách sử dụng các kiểu được khai báo cho mỗi cột. Các loại được khai báo khi bảng cơ sở dữ liệu được tạo. sqlite3 sẽ tra cứu hàm chuyển đổi bằng cách sử dụng từ đầu tiên của loại được khai báo làm khóa từ điển của trình chuyển đổi. Ví dụ:

kiểm tra CREATE TABLE(
   i khóa chính là số nguyên, ! sẽ tra cứu một công cụ chuyển đổi có tên là "số nguyên"
   điểm p, ! sẽ tra cứu một công cụ chuyển đổi có tên là "điểm"
   n số(10) ! sẽ tra cứu một công cụ chuyển đổi có tên "number"
 )

Cờ này có thể được kết hợp với PARSE_COLNAMES bằng toán tử | (bitwise hoặc).

Ghi chú

Các trường đã tạo (ví dụ MAX(p)) được trả về dưới dạng str. Sử dụng PARSE_COLNAMES để thực thi các loại cho các truy vấn như vậy.

sqlite3.PARSE_COLNAMES¶

Chuyển giá trị cờ này cho tham số detect_types của connect() để tra cứu hàm chuyển đổi bằng cách sử dụng tên loại, được phân tích cú pháp từ tên cột truy vấn, làm khóa từ điển trình chuyển đổi. Tên cột truy vấn phải được đặt trong dấu ngoặc kép (") và tên loại phải được đặt trong dấu ngoặc vuông ([]).

SELECT MAX(p) dưới dạng kiểm tra "p [điểm]" FROM;  ! sẽ tra cứu "điểm" chuyển đổi

Cờ này có thể được kết hợp với PARSE_DECLTYPES bằng toán tử | (bitwise hoặc).

sqlite3.SQLITE_OK¶

sqlite3.SQLITE_DENY¶

sqlite3.SQLITE_IGNORE¶

Các cờ cần được trả về bởi authorizer_callback callable sẽ được chuyển tới Connection.set_authorizer() để cho biết liệu:

Được phép truy cập (SQLITE_OK),
Câu lệnh SQL sẽ bị hủy do có lỗi (SQLITE_DENY)
Cột phải được coi là giá trị NULL (SQLITE_IGNORE)

sqlite3.apilevel¶: Hằng chuỗi cho biết mức DB-API được hỗ trợ. Được yêu cầu bởi DB-API. Mã hóa cứng thành "2.0".

sqlite3.paramstyle¶: Hằng chuỗi cho biết loại định dạng điểm đánh dấu tham số mà mô-đun sqlite3 mong đợi. Được yêu cầu bởi DB-API. Mã hóa cứng thành "qmark".

Ghi chú

Kiểu tham số named DB-API cũng được hỗ trợ.

sqlite3.sqlite_version¶: Số phiên bản của thư viện SQLite thời gian chạy dưới dạng string.

sqlite3.sqlite_version_info¶: Số phiên bản của thư viện SQLite thời gian chạy dưới dạng tuple của integers.

sqlite3.threadsafety¶

Hằng số nguyên mà DB-API 2.0 yêu cầu, cho biết mức độ an toàn của luồng mà mô-đun sqlite3 hỗ trợ. Thuộc tính này được đặt dựa trên threading mode mặc định mà thư viện SQLite cơ bản được biên dịch. Các chế độ phân luồng SQLite là:

Single-thread: Trong chế độ này, tất cả các mutex đều bị tắt và SQLite không an toàn khi sử dụng trong nhiều luồng cùng một lúc.
Multi-thread: Trong chế độ này, SQLite có thể được sử dụng một cách an toàn bởi nhiều luồng với điều kiện là không có kết nối cơ sở dữ liệu nào được sử dụng đồng thời trong hai hoặc nhiều luồng.
Serialized: Ở chế độ tuần tự hóa, SQLite có thể được nhiều luồng sử dụng một cách an toàn mà không bị hạn chế.

Ánh xạ từ chế độ phân luồng SQLite đến mức an toàn luồng DB-API 2.0 như sau:

Chế độ phân luồng SQLite	threadsafety	SQLITE_THREADSAFE	Ý nghĩa của DB-API 2.0
sợi đơn	0	0	Chủ đề có thể không chia sẻ mô-đun
đa luồng	1	2	Chủ đề có thể chia sẻ mô-đun, nhưng không chia sẻ kết nối
được đăng nhiều kỳ	3	1	Chủ đề có thể chia sẻ mô-đun, kết nối và con trỏ

Thay đổi trong phiên bản 3.11: Đặt threadsafety một cách linh hoạt thay vì mã hóa cứng thành 1.

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¶

Các hằng số này được sử dụng cho các phương thức Connection.setconfig() và getconfig().

Tính khả dụng của các hằng số này khác nhau tùy thuộc vào phiên bản SQLite Python được biên dịch.

Added in version 3.12.

Xem thêm

https://www.sqlite.org/c3ref/c_dbconfig_defensive.html: Tài liệu SQLite: Tùy chọn cấu hình kết nối cơ sở dữ liệu

Không được dùng nữa kể từ phiên bản 3.12, đã bị xóa trong phiên bản 3.14: Các hằng số version và version_info.

Đối tượng kết nối¶

class sqlite3.Connection¶

Mỗi cơ sở dữ liệu SQLite mở được biểu thị bằng một đối tượng Connection, được tạo bằng sqlite3.connect(). Mục đích chính của họ là tạo ra các đối tượng Cursor và Kiểm soát giao dịch.

Xem thêm

Cách sử dụng các phương pháp phím tắt kết nối
Cách sử dụng trình quản lý bối cảnh kết nối

Thay đổi trong phiên bản 3.13: Một ResourceWarning được phát ra nếu close() không được gọi trước khi đối tượng Connection bị xóa.

Kết nối cơ sở dữ liệu SQLite có các thuộc tính và phương thức sau:

cursor(factory=Cursor)¶: Tạo và trả về một đối tượng Cursor. Phương thức con trỏ chấp nhận một tham số tùy chọn duy nhất factory. Nếu được cung cấp, đây phải là callable trả về một phiên bản của Cursor hoặc các lớp con của nó.

blobopen(table, column, rowid, /, *, readonly=False, name='main')¶

Mở bộ điều khiển Blob cho BLOB hiện có.

Tham số:

table (str) -- Tên của bảng nơi đặt blob.
column (str) -- Tên của cột nơi blob nằm.
rowid (int) -- Id hàng nơi đặt blob.
readonly (bool) -- Đặt thành True nếu blob được mở mà không có quyền ghi. Mặc định là False.
name (str) -- Tên của cơ sở dữ liệu nơi đặt blob. Mặc định là "main".

Đưa ra:

OperationalError -- Khi cố gắng mở một đốm màu trong bảng WITHOUT ROWID.

Kiểu trả về:

Blob

Ghi chú

Không thể thay đổi kích thước blob bằng lớp Blob. Sử dụng hàm SQL zeroblob để tạo một đốm màu có kích thước cố định.

Added in version 3.11.

commit()¶: Cam kết mọi giao dịch đang chờ xử lý vào cơ sở dữ liệu. Nếu autocommit là True hoặc không có giao dịch mở nào thì phương thức này không có tác dụng gì. Nếu autocommit là False, một giao dịch mới sẽ được mở ngầm nếu giao dịch đang chờ xử lý được thực hiện bằng phương thức này.

rollback()¶: Quay trở lại điểm bắt đầu của bất kỳ giao dịch đang chờ xử lý nào. Nếu autocommit là True hoặc không có giao dịch mở nào thì phương thức này không có tác dụng gì. Nếu autocommit là False, một giao dịch mới sẽ được mở hoàn toàn nếu giao dịch đang chờ xử lý được khôi phục bằng phương pháp này.

close()¶: Đóng kết nối cơ sở dữ liệu. Nếu autocommit là False thì mọi giao dịch đang chờ xử lý sẽ được hoàn nguyên ngầm. Nếu autocommit là True hoặc LEGACY_TRANSACTION_CONTROL thì không có kiểm soát giao dịch ngầm nào được thực thi. Đảm bảo commit() trước khi đóng để tránh mất các thay đổi đang chờ xử lý.

execute(sql, parameters=(), /)¶: Tạo một đối tượng Cursor mới và gọi execute() trên đó với sql và parameters đã cho. Trả về đối tượng con trỏ mới.

executemany(sql, parameters, /)¶: Tạo một đối tượng Cursor mới và gọi executemany() trên đó với sql và parameters đã cho. Trả về đối tượng con trỏ mới.

executescript(sql_script, /)¶: Tạo một đối tượng Cursor mới và gọi executescript() trên đó với sql_script đã cho. Trả về đối tượng con trỏ mới.

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

Tạo hoặc xóa hàm SQL do người dùng xác định.

Tham số:

name (str) -- Tên của hàm SQL.
narg (int) -- Số lượng đối số mà hàm SQL có thể chấp nhận. Nếu là -1, nó có thể nhận bất kỳ số lượng đối số nào.
func (callback | None) -- Một callable được gọi khi hàm SQL được gọi. Người có thể gọi phải trả về a type natively supported by SQLite. Đặt thành None để xóa chức năng SQL hiện có.
deterministic (bool) -- Nếu True, hàm SQL đã tạo sẽ được đánh dấu là deterministic, cho phép SQLite thực hiện các tối ưu hóa bổ sung.

Thay đổi trong phiên bản 3.8: Đã thêm tham số deterministic.

Ví dụ:

>>> nhập hashlib
>>> def md5sum(t):
... trả về hashlib.md5(t).hexdigest()
>>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> cho hàng trong con.execute("SELECT md5(?)", (b"foo",)):
... in(hàng)
('acbd18db4cc2f85cedef654fccc4a4d8',)
>>> con.close()

Thay đổi trong phiên bản 3.13: Việc chuyển name, narg và func làm đối số từ khóa không được dùng nữa. Các tham số này sẽ chỉ có vị trí trong Python 3.15.

create_aggregate(name, n_arg, aggregate_class)¶

Tạo hoặc xóa hàm tổng hợp SQL do người dùng xác định.

Tham số:

name (str) -- Tên của hàm tổng hợp SQL.
n_arg (int) -- Số lượng đối số mà hàm tổng hợp SQL có thể chấp nhận. Nếu là -1, nó có thể nhận bất kỳ số lượng đối số nào.
aggregate_class (class | None) -- Một lớp phải triển khai các phương thức sau: * step(): Thêm một hàng vào tổng hợp. * finalize(): Trả về kết quả cuối cùng của tổng hợp là a type natively supported by SQLite. Số lượng đối số mà phương thức step() phải chấp nhận được kiểm soát bởi n_arg. Đặt thành None để xóa hàm tổng hợp SQL hiện có.

Ví dụ:

lớp MySum:
    định nghĩa __init__(tự):
        self.count = 0

    bước def (tự, giá trị):
        self.count += giá trị

    def hoàn thiện (tự):
        trở về 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()

Thay đổi trong phiên bản 3.13: Việc chuyển name, n_arg và aggregate_class làm đối số từ khóa không được dùng nữa. Các tham số này sẽ chỉ có vị trí trong Python 3.15.

create_window_function(name, num_params, aggregate_class, /)¶

Tạo hoặc xóa chức năng cửa sổ tổng hợp do người dùng xác định.

Tham số:

name (str) -- Tên của hàm cửa sổ tổng hợp SQL để tạo hoặc xóa.
num_params (int) -- Số lượng đối số mà hàm cửa sổ tổng hợp SQL có thể chấp nhận. Nếu là -1, nó có thể nhận bất kỳ số lượng đối số nào.
aggregate_class (class | None) -- Một lớp phải triển khai các phương thức sau: * step(): Thêm một hàng vào cửa sổ hiện tại. * value(): Trả về giá trị hiện tại của tổng hợp. * inverse(): Xóa một hàng khỏi cửa sổ hiện tại. * finalize(): Trả về kết quả cuối cùng của tổng hợp là a type natively supported by SQLite. Số lượng đối số mà phương thức step() và value() phải chấp nhận được kiểm soát bởi num_params. Đặt thành None để xóa chức năng cửa sổ tổng hợp SQL hiện có.

Đưa ra:

NotSupportedError -- Nếu được sử dụng với phiên bản SQLite cũ hơn 3.25.0, phiên bản này không hỗ trợ các chức năng cửa sổ tổng hợp.

Added in version 3.11.

Ví dụ:

# Example lấy từ https://www.sqlite.org/windowfunctions.html#udfwinfunc
lớp WindowSumInt:
    định nghĩa __init__(tự):
        self.count = 0

    bước def (tự, giá trị):
        """Thêm một hàng vào cửa sổ hiện tại."""
        self.count += giá trị

    giá trị def (tự):
        """Trả về giá trị hiện tại của tổng hợp."""
        trở về self.count

    def nghịch đảo (tự, giá trị):
        """Xóa một hàng khỏi cửa sổ hiện tại."""
        self.count -= giá trị

    def hoàn thiện (tự):
        """Trả về giá trị cuối cùng của tổng hợp.

        Mọi hành động dọn dẹp nên được đặt ở đây.
        """
        trở về self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
giá trị = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", các giá trị)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BỞI x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) NHƯ tổng_y
    kiểm tra FROM ORDER BỞI x
""")
print(cur.fetchall())
con.close()

create_collation(name, callable, /)¶

Tạo đối chiếu có tên name bằng cách sử dụng chức năng đối chiếu callable. callable được truyền hai đối số string và nó sẽ trả về integer:

1 nếu cái đầu tiên được đặt hàng cao hơn cái thứ hai
-1 nếu cái đầu tiên được đặt hàng thấp hơn cái thứ hai
0 nếu chúng được sắp xếp bằng nhau

Ví dụ sau đây cho thấy đối chiếu sắp xếp ngược:

def collate_reverse(string1, string2):
    nếu chuỗi1 == chuỗi2:
        trở về 0
    chuỗi Elif1 < chuỗi2:
        trở lại 1
    khác:
        trở lại -1

con = sqlite3.connect(":memory:")
con.create_collation("đảo ngược", collate_reverse)

cur = con.execute("CREATE TABLE test(x)")
cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",,"b",)])
cur.execute("SELECT x FROM kiểm tra ORDER BY x COLLATE đảo ngược")
cho hàng trong cur:
    in (hàng)
con.close()

Xóa chức năng đối chiếu bằng cách đặt callable thành None.

Thay đổi trong phiên bản 3.11: Tên đối chiếu có thể chứa bất kỳ ký tự Unicode nào. Trước đó, chỉ cho phép các ký tự ASCII.

interrupt()¶: Gọi phương thức này từ một luồng khác để hủy bỏ mọi truy vấn có thể đang thực thi trên kết nối. Các truy vấn bị hủy sẽ tăng OperationalError.

set_authorizer(authorizer_callback)¶

Đăng ký callable authorizer_callback để được gọi cho mỗi lần thử truy cập vào một cột của bảng trong cơ sở dữ liệu. Lệnh gọi lại sẽ trả về một trong các SQLITE_OK, SQLITE_DENY hoặc SQLITE_IGNORE để báo hiệu cách thư viện SQLite cơ bản xử lý quyền truy cập vào cột.

Đối số đầu tiên của lệnh gọi lại biểu thị loại hoạt động nào được ủy quyền. Đối số thứ hai và thứ ba sẽ là đối số hoặc None tùy thuộc vào đối số đầu tiên. Đối số thứ 4 là tên của cơ sở dữ liệu ("chính", "tạm thời", v.v.) nếu có. Đối số thứ 5 là tên của trình kích hoạt hoặc chế độ xem trong cùng chịu trách nhiệm về nỗ lực truy cập hoặc None nếu nỗ lực truy cập này trực tiếp từ mã SQL đầu vào.

Vui lòng tham khảo tài liệu SQLite về các giá trị có thể có cho đối số thứ nhất cũng như ý nghĩa của đối số thứ hai và thứ ba tùy thuộc vào đối số thứ nhất. Tất cả các hằng số cần thiết đều có sẵn trong mô-đun sqlite3.

Chuyển None là authorizer_callback sẽ vô hiệu hóa người ủy quyền.

Thay đổi trong phiên bản 3.11: Đã thêm hỗ trợ để vô hiệu hóa trình ủy quyền bằng None.

Thay đổi trong phiên bản 3.13: Việc chuyển authorizer_callback làm đối số từ khóa không được dùng nữa. Tham số sẽ chỉ có vị trí trong Python 3.15.

set_progress_handler(progress_handler, n)¶

Đăng ký callable progress_handler để được gọi cho mọi lệnh n của máy ảo SQLite. Điều này hữu ích nếu bạn muốn nhận được lệnh gọi từ SQLite trong các hoạt động chạy dài, chẳng hạn như để cập nhật GUI.

Nếu bạn muốn xóa bất kỳ trình xử lý tiến trình nào đã cài đặt trước đó, hãy gọi phương thức bằng None cho progress_handler.

Việc trả về giá trị khác 0 từ hàm xử lý sẽ chấm dứt truy vấn hiện đang thực thi và khiến nó đưa ra ngoại lệ DatabaseError.

Thay đổi trong phiên bản 3.13: Việc chuyển progress_handler làm đối số từ khóa không được dùng nữa. Tham số sẽ chỉ có vị trí trong Python 3.15.

set_trace_callback(trace_callback)¶

Đăng ký callable trace_callback để được gọi cho mỗi câu lệnh SQL thực sự được thực thi bởi phần phụ trợ SQLite.

Đối số duy nhất được truyền cho lệnh gọi lại là câu lệnh (dưới dạng str) đang được thực thi. Giá trị trả về của cuộc gọi lại bị bỏ qua. Lưu ý rằng phần phụ trợ không chỉ chạy các câu lệnh được truyền cho các phương thức Cursor.execute(). Các nguồn khác bao gồm transaction management của mô-đun sqlite3 và việc thực thi các trình kích hoạt được xác định trong cơ sở dữ liệu hiện tại.

Chuyển None thành trace_callback sẽ vô hiệu hóa lệnh gọi lại theo dõi.

Ghi chú

Các ngoại lệ được nêu ra trong cuộc gọi lại theo dõi không được truyền bá. Là một công cụ hỗ trợ phát triển và gỡ lỗi, hãy sử dụng enable_callback_tracebacks() để cho phép in dấu vết từ các ngoại lệ được đưa ra trong lệnh gọi lại dấu vết.

Added in version 3.3.

Thay đổi trong phiên bản 3.13: Việc chuyển trace_callback làm đối số từ khóa không được dùng nữa. Tham số sẽ chỉ có vị trí trong Python 3.15.

enable_load_extension(enabled, /)¶

Cho phép công cụ SQLite tải các phần mở rộng SQLite từ các thư viện dùng chung nếu enabled là True; nếu không, không cho phép tải các phần mở rộng SQLite. Các tiện ích mở rộng SQLite có thể xác định các hàm mới, tổng hợp hoặc triển khai bảng ảo hoàn toàn mới. Một tiện ích mở rộng nổi tiếng là tiện ích mở rộng tìm kiếm toàn văn bản được phân phối bằng SQLite.

Ghi chú

Theo mặc định, mô-đun sqlite3 không được xây dựng với hỗ trợ tiện ích mở rộng có thể tải được vì một số nền tảng (đặc biệt là macOS) có thư viện SQLite được biên dịch mà không có tính năng này. Để nhận được hỗ trợ tiện ích mở rộng có thể tải, bạn phải chuyển tùy chọn --enable-loadable-sqlite-extensions cho configure.

Tăng một auditing event sqlite3.enable_load_extension với các đối số connection, enabled.

Added in version 3.2.

Thay đổi trong phiên bản 3.10: Đã thêm sự kiện kiểm tra sqlite3.enable_load_extension.

con.enable_load_extension(Đúng)

# Load tiện ích mở rộng tìm kiếm toàn văn
con.execute("select Load_extension('./fts3.so')")

# alternatively bạn có thể tải tiện ích mở rộng bằng lệnh gọi API:
# con.load_extension("./fts3.so")

Đang tải lại tiện ích mở rộng # disable
con.enable_load_extension(Sai)

# example từ wiki SQLite
con.execute("CREATE VIRTUAL TABLE công thức USING fts3(tên, thành phần)")
con.executescript("""
    INSERT INTO công thức (tên, nguyên liệu) VALUES('bông cải xanh hầm', 'bông cải xanh ớt phô mai cà chua');
    INSERT INTO công thức (tên, nguyên liệu) VALUES('bí ngô hầm', 'bí ngô hành tỏi cần tây');
    INSERT INTO công thức (tên, nguyên liệu) VALUES('bánh bông cải xanh', 'bột hành tây phô mai bông cải xanh');
    INSERT INTO công thức (tên, nguyên liệu) VALUES('bánh bí ngô', 'bơ bột đường bí ngô');
    """)
cho hàng trong con.execute("SELECT rowid, tên, thành phần FROM công thức WHERE tên MATCH 'pie'"):
    in (hàng)

load_extension(path, /, *, entrypoint=None)¶

Tải tiện ích mở rộng SQLite từ thư viện dùng chung. Cho phép tải tiện ích mở rộng bằng enable_load_extension() trước khi gọi phương thức này.

Tham số:

path (str) -- Đường dẫn đến phần mở rộng SQLite.
entrypoint (str | None) -- Tên điểm vào. Nếu None (mặc định), SQLite sẽ đưa ra tên điểm vào của riêng nó; xem tài liệu SQLite Loading an Extension để biết chi tiết.

Tăng một auditing event sqlite3.load_extension với các đối số connection, path.

Added in version 3.2.

Thay đổi trong phiên bản 3.10: Đã thêm sự kiện kiểm tra sqlite3.load_extension.

Thay đổi trong phiên bản 3.12: Đã thêm tham số entrypoint.

iterdump(*, filter=None)¶

Trả về iterator để kết xuất cơ sở dữ liệu dưới dạng mã nguồn SQL. Hữu ích khi lưu cơ sở dữ liệu trong bộ nhớ để khôi phục sau này. Tương tự như lệnh .dump trong shell sqlite3.

Tham số:: filter (str | None) -- Mẫu LIKE tùy chọn để kết xuất các đối tượng cơ sở dữ liệu, ví dụ: prefix_%. Nếu None (mặc định), tất cả các đối tượng cơ sở dữ liệu sẽ được đưa vào.

Ví dụ:

tệp # Convert example.db sang tệp kết xuất SQL dump.sql
con = sqlite3.connect('example.db')
với open('dump.sql', 'w') là f:
    cho dòng trong con.iterdump():
        f.write('%s\n' % dòng)
con.close()

Xem thêm

Cách xử lý mã hóa văn bản không phải UTF-8

Thay đổi trong phiên bản 3.13: Đã thêm tham số filter.

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

Tạo bản sao lưu của cơ sở dữ liệu SQLite.

Hoạt động ngay cả khi cơ sở dữ liệu đang được truy cập bởi các máy khách khác hoặc đồng thời bằng cùng một kết nối.

Tham số:

target (Connection) -- Kết nối cơ sở dữ liệu để lưu bản sao lưu vào.
pages (int) -- Số lượng trang cần sao chép cùng một lúc. Nếu bằng hoặc nhỏ hơn 0, toàn bộ cơ sở dữ liệu sẽ được sao chép chỉ trong một bước. Mặc định là -1.
progress (callback | None) -- Nếu được đặt thành callable, nó sẽ được gọi với ba đối số nguyên cho mỗi lần lặp dự phòng: status của lần lặp cuối cùng, số trang remaining vẫn được sao chép và số trang total. Mặc định là None.
name (str) -- Tên cơ sở dữ liệu cần sao lưu. "main" (mặc định) cho cơ sở dữ liệu chính, "temp" cho cơ sở dữ liệu tạm thời hoặc tên của cơ sở dữ liệu tùy chỉnh được đính kèm bằng câu lệnh ATTACH DATABASE SQL.
sleep (float) -- Số giây nghỉ giữa các lần thử liên tiếp để sao lưu các trang còn lại.

Ví dụ 1, sao chép cơ sở dữ liệu hiện có sang cơ sở dữ liệu khác:

tiến trình def (trạng thái, còn lại, tổng số):
    print(f'Đã sao chép {total-remaining} của {total} trang...')

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
với dst:
    src.backup(dst, pages=1, Progress=progress)
dst.close()
src.close()

Ví dụ 2, sao chép cơ sở dữ liệu hiện có thành bản sao tạm thời:

src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)
dst.close()
src.close()

Added in version 3.7.

Xem thêm

Cách xử lý mã hóa văn bản không phải UTF-8

getlimit(category, /)¶

Nhận giới hạn thời gian chạy kết nối.

Tham số:: category (int) -- SQLite limit category được truy vấn.
Kiểu trả về:: int
Đưa ra:: ProgrammingError -- Nếu category không được thư viện SQLite cơ bản nhận ra.

Ví dụ: truy vấn độ dài tối đa của câu lệnh SQL cho Connection con (mặc định là 1000000000):

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

Added in version 3.11.

setlimit(category, limit, /)¶

Đặt giới hạn thời gian chạy kết nối. Các nỗ lực tăng giới hạn lên trên giới hạn trên cứng của nó sẽ bị cắt ngắn một cách âm thầm thành giới hạn trên cứng. Bất kể giới hạn có được thay đổi hay không, giá trị trước đó của giới hạn sẽ được trả về.

Tham số:

category (int) -- SQLite limit category sẽ được thiết lập.
limit (int) -- Giá trị của giới hạn mới. Nếu âm, giới hạn hiện tại không thay đổi.

Kiểu trả về:

int

Đưa ra:

ProgrammingError -- Nếu category không được thư viện SQLite cơ bản nhận ra.

Ví dụ: giới hạn số lượng cơ sở dữ liệu đính kèm ở mức 1 cho Connection con (giới hạn mặc định là 10):

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

Added in version 3.11.

getconfig(op, /)¶

Truy vấn tùy chọn cấu hình kết nối boolean.

Tham số:: op (int) -- Một SQLITE_DBCONFIG code.
Kiểu trả về:: bool

Added in version 3.12.

setconfig(op, enable=True, /)¶

Đặt tùy chọn cấu hình kết nối boolean.

Tham số:

op (int) -- Một SQLITE_DBCONFIG code.
enable (bool) -- True nếu tùy chọn cấu hình được bật (mặc định); False nếu nó bị vô hiệu hóa.

Added in version 3.12.

serialize(*, name='main')¶

Tuần tự hóa cơ sở dữ liệu thành đối tượng bytes. Đối với tệp cơ sở dữ liệu trên đĩa thông thường, việc tuần tự hóa chỉ là bản sao của tệp đĩa. Đối với cơ sở dữ liệu trong bộ nhớ hoặc cơ sở dữ liệu "tạm thời", việc tuần tự hóa là cùng một chuỗi byte sẽ được ghi vào đĩa nếu cơ sở dữ liệu đó được sao lưu vào đĩa.

Tham số:: name (str) -- Tên cơ sở dữ liệu sẽ được tuần tự hóa. Mặc định là "main".
Kiểu trả về:: bytes

Ghi chú

Phương pháp này chỉ khả dụng nếu thư viện SQLite cơ bản có API tuần tự hóa.

Added in version 3.11.

deserialize(data, /, *, name='main')¶

Giải tuần tự hóa cơ sở dữ liệu serialized thành Connection. Phương pháp này khiến kết nối cơ sở dữ liệu bị ngắt kết nối khỏi cơ sở dữ liệu name và mở lại name dưới dạng cơ sở dữ liệu trong bộ nhớ dựa trên tuần tự hóa có trong data.

Tham số:

data (bytes) -- Một cơ sở dữ liệu được tuần tự hóa.
name (str) -- Tên cơ sở dữ liệu để giải tuần tự hóa thành. Mặc định là "main".

Đưa ra:

OperationalError -- Nếu kết nối cơ sở dữ liệu hiện đang tham gia vào giao dịch đọc hoặc hoạt động sao lưu.
DatabaseError -- Nếu data không chứa cơ sở dữ liệu SQLite hợp lệ.
OverflowError -- Nếu len(data) lớn hơn 2**63 - 1.

Ghi chú

Phương pháp này chỉ khả dụng nếu thư viện SQLite cơ bản có API giải tuần tự hóa.

Added in version 3.11.

autocommit¶

Thuộc tính này kiểm soát hành vi giao dịch tuân thủ PEP 249. autocommit có ba giá trị được phép:

False: Chọn hành vi giao dịch tuân thủ PEP 249, ngụ ý rằng sqlite3 đảm bảo giao dịch luôn mở. Sử dụng commit() và rollback() để đóng giao dịch.

Đây là giá trị được đề xuất của autocommit.
True: Sử dụng autocommit mode của SQLite. commit() và rollback() không có tác dụng ở chế độ này.
LEGACY_TRANSACTION_CONTROL: Kiểm soát giao dịch Pre-Python 3.12 (không tuân thủ PEP 249). Xem isolation_level để biết thêm chi tiết.

Đây hiện là giá trị mặc định của autocommit.

Thay đổi autocommit thành False sẽ mở một giao dịch mới và thay đổi thành True sẽ thực hiện mọi giao dịch đang chờ xử lý.

Xem Kiểm soát giao dịch thông qua thuộc tính autocommit để biết thêm chi tiết.

Ghi chú

Thuộc tính isolation_level không có hiệu lực trừ khi autocommit là LEGACY_TRANSACTION_CONTROL.

Added in version 3.12.

in_transaction¶

Thuộc tính chỉ đọc này tương ứng với autocommit mode SQLite cấp thấp.

True nếu giao dịch đang hoạt động (có những thay đổi không được cam kết), nếu không thì False.

Added in version 3.2.

isolation_level¶

Kiểm soát legacy transaction handling mode của sqlite3. Nếu được đặt thành None, các giao dịch sẽ không bao giờ được mở ngầm. Nếu được đặt thành một trong các "DEFERRED", "IMMEDIATE" hoặc "EXCLUSIVE", tương ứng với SQLite transaction behaviour cơ bản, implicit transaction management sẽ được thực hiện.

Nếu không bị ghi đè bởi tham số isolation_level của connect(), mặc định là "", đây là bí danh của "DEFERRED".

Ghi chú

Nên sử dụng autocommit để kiểm soát việc xử lý giao dịch hơn là sử dụng isolation_level. isolation_level không có hiệu lực trừ khi autocommit được đặt thành LEGACY_TRANSACTION_CONTROL (mặc định).

row_factory¶

row_factory ban đầu cho các đối tượng Cursor được tạo từ kết nối này. Việc gán cho thuộc tính này không ảnh hưởng đến row_factory của các con trỏ hiện có thuộc kết nối này, chỉ những con trỏ mới. Theo mặc định là None, nghĩa là mỗi hàng được trả về dưới dạng tuple.

Xem Cách tạo và sử dụng Row Factory để biết thêm chi tiết.

text_factory¶

Một callable chấp nhận tham số bytes và trả về dạng văn bản của tham số đó. Hàm có thể gọi được được gọi cho các giá trị SQLite với kiểu dữ liệu TEXT. Theo mặc định, thuộc tính này được đặt thành str.

Xem Cách xử lý mã hóa văn bản không phải UTF-8 để biết thêm chi tiết.

total_changes¶: Trả về tổng số hàng cơ sở dữ liệu đã được sửa đổi, chèn hoặc xóa kể từ khi kết nối cơ sở dữ liệu được mở.

Đối tượng con trỏ¶

Đối tượng Cursor đại diện cho database cursor được sử dụng để thực thi các câu lệnh SQL và quản lý ngữ cảnh của thao tác tìm nạp. Con trỏ được tạo bằng Connection.cursor() hoặc bằng bất kỳ connection shortcut methods nào.

Đối tượng con trỏ là iterators, nghĩa là nếu bạn execute() một truy vấn SELECT, bạn có thể chỉ cần lặp lại con trỏ để tìm nạp các hàng kết quả:
cho hàng trong cur.execute("SELECT t FROM data"):
    in (hàng)

class sqlite3.Cursor¶

Một phiên bản Cursor có các thuộc tính và phương thức sau.

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

Thực thi một câu lệnh SQL, tùy chọn liên kết các giá trị Python bằng placeholders.

Tham số:

sql (str) -- Một câu lệnh SQL duy nhất.
parameters (dict | sequence) -- Các giá trị Python để liên kết với phần giữ chỗ trong sql. Một dict nếu phần giữ chỗ có tên được sử dụng. Một sequence nếu sử dụng phần giữ chỗ không tên. Xem Cách sử dụng trình giữ chỗ để liên kết các giá trị trong truy vấn SQL.

Đưa ra:

ProgrammingError -- Khi sql chứa nhiều hơn một câu lệnh SQL. Khi named placeholders được sử dụng và parameters là một chuỗi thay vì dict.

Nếu autocommit là LEGACY_TRANSACTION_CONTROL, isolation_level không phải là None, sql là một câu lệnh INSERT, UPDATE, DELETE hoặc REPLACE và không có giao dịch mở thì giao dịch sẽ được mở ngầm trước khi thực hiện sql.

Thay đổi trong phiên bản 3.14: ProgrammingError được phát ra nếu named placeholders được sử dụng và parameters là một chuỗi thay vì dict.

Sử dụng executescript() để thực thi nhiều câu lệnh SQL.

executemany(sql, parameters, /)¶

Đối với mọi mục trong parameters, hãy thực hiện liên tục câu lệnh parameterized DML SQL sql.

Sử dụng cách xử lý giao dịch ngầm tương tự như execute().

Tham số:

sql (str) -- Một câu lệnh SQL DML duy nhất.
parameters (iterable) -- Một tham số iterable để liên kết với phần giữ chỗ trong sql. Xem Cách sử dụng trình giữ chỗ để liên kết các giá trị trong truy vấn SQL.

Đưa ra:

ProgrammingError -- Khi sql chứa nhiều hơn một câu lệnh SQL hoặc không phải là câu lệnh DML, Khi named placeholders được sử dụng và các mục trong parameters là các chuỗi thay vì dicts.

Ví dụ:

hàng = [
    ("hàng1",),
    ("hàng2",),
]
# cur là một đối tượng sqlite3.Cursor
cur.executemany("INSERT INTO dữ liệu VALUES(?)", hàng)

Ghi chú

Mọi hàng kết quả đều bị loại bỏ, bao gồm các câu lệnh DML có RETURNING clauses.

Thay đổi trong phiên bản 3.14: ProgrammingError được phát ra nếu named placeholders được sử dụng và các mục trong parameters là các chuỗi thay vì dicts.

executescript(sql_script, /)¶

Thực thi các câu lệnh SQL trong sql_script. Nếu autocommit là LEGACY_TRANSACTION_CONTROL và có một giao dịch đang chờ xử lý thì câu lệnh COMMIT ẩn sẽ được thực thi trước tiên. Không có kiểm soát giao dịch ngầm nào khác được thực hiện; mọi kiểm soát giao dịch phải được thêm vào sql_script.

sql_script phải là string.

Ví dụ:

# cur là một đối tượng sqlite3.Cursor
cur.executescript("""
    BEGIN;
    CREATE TABLE người(tên, họ, tuổi);
    cuốn sách CREATE TABLE (tiêu đề, tác giả, đã xuất bản);
    nhà xuất bản CREATE TABLE(tên, địa chỉ);
    COMMIT;
""")

fetchone()¶: Nếu row_factory là None, trả về tập kết quả truy vấn hàng tiếp theo là tuple. Ngược lại, chuyển nó đến nhà máy sản xuất hàng và trả về kết quả của nó. Trả về None nếu không còn dữ liệu.

fetchmany(size=cursor.arraysize)¶

Trả về tập hợp hàng tiếp theo của kết quả truy vấn dưới dạng list. Trả về một danh sách trống nếu không còn hàng nào nữa.

Số lượng hàng cần tìm nạp cho mỗi cuộc gọi được chỉ định bởi tham số size. Nếu size không được cung cấp, arraysize sẽ xác định số hàng cần tìm nạp. Nếu có ít hơn hàng size thì số hàng có sẵn sẽ được trả về.

Lưu ý rằng có những cân nhắc về hiệu suất liên quan đến tham số size. Để có hiệu suất tối ưu, tốt nhất nên sử dụng thuộc tính arraysize. Nếu tham số size được sử dụng thì tốt nhất là nó nên giữ nguyên giá trị từ lệnh gọi fetchmany() này đến lệnh gọi tiếp theo.

Thay đổi trong phiên bản 3.14.1: Các giá trị size âm bị từ chối bằng cách tăng ValueError.

fetchall()¶: Trả về tất cả các hàng (còn lại) của kết quả truy vấn dưới dạng list. Trả về một danh sách trống nếu không có hàng nào có sẵn. Lưu ý rằng thuộc tính arraysize có thể ảnh hưởng đến hiệu suất của thao tác này.

close()¶

Đóng con trỏ ngay bây giờ (thay vì bất cứ khi nào __del__ được gọi).

Con trỏ sẽ không sử dụng được từ thời điểm này trở đi; một ngoại lệ ProgrammingError sẽ xuất hiện nếu thực hiện bất kỳ thao tác nào với con trỏ.

setinputsizes(sizes, /)¶: Được yêu cầu bởi DB-API. Không có gì trong sqlite3.

setoutputsize(size, column=None, /)¶: Được yêu cầu bởi DB-API. Không có gì trong sqlite3.

arraysize¶: Thuộc tính đọc/ghi kiểm soát số hàng được trả về bởi fetchmany(). Giá trị mặc định là 1 có nghĩa là một hàng sẽ được tìm nạp cho mỗi lệnh gọi.

Thay đổi trong phiên bản 3.14.1: Các giá trị âm bị từ chối bằng cách tăng ValueError.

connection¶

Thuộc tính chỉ đọc cung cấp cơ sở dữ liệu SQLite Connection thuộc về con trỏ. Một đối tượng Cursor được tạo bằng cách gọi con.cursor() sẽ có thuộc tính connection đề cập đến con:

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
đúng
>>> con.close()

description¶

Thuộc tính chỉ đọc cung cấp tên cột của truy vấn cuối cùng. Để duy trì khả năng tương thích với Python DB API, nó trả về 7 bộ dữ liệu cho mỗi cột trong đó sáu mục cuối cùng của mỗi bộ dữ liệu là None.

Nó được đặt cho các câu lệnh SELECT mà không có bất kỳ hàng nào phù hợp.

lastrowid¶: Thuộc tính chỉ đọc cung cấp id hàng của hàng được chèn cuối cùng. Nó chỉ được cập nhật sau khi các câu lệnh INSERT hoặc REPLACE thành công bằng phương thức execute(). Đối với các câu lệnh khác, sau executemany() hoặc executescript() hoặc nếu việc chèn không thành công thì giá trị của lastrowid sẽ không thay đổi. Giá trị ban đầu của lastrowid là None.

Ghi chú

Việc chèn vào bảng WITHOUT ROWID không được ghi lại.

Thay đổi trong phiên bản 3.6: Đã thêm hỗ trợ cho câu lệnh REPLACE.

rowcount¶: Thuộc tính chỉ đọc cung cấp số hàng được sửa đổi cho các câu lệnh INSERT, UPDATE, DELETE và REPLACE; là -1 cho các câu lệnh khác, bao gồm cả truy vấn CTE. Nó chỉ được cập nhật bằng các phương thức execute() và executemany() sau khi câu lệnh chạy đến khi hoàn thành. Điều này có nghĩa là mọi hàng kết quả phải được tìm nạp để rowcount được cập nhật.

row_factory¶

Kiểm soát cách trình bày một hàng được tìm nạp từ Cursor này. Nếu None, một hàng được biểu diễn dưới dạng tuple. Có thể được đặt thành sqlite3.Row đi kèm; hoặc callable chấp nhận hai đối số, một đối tượng Cursor và tuple của các giá trị hàng và trả về một đối tượng tùy chỉnh đại diện cho một hàng SQLite.

Mặc định là Connection.row_factory được đặt khi Cursor được tạo. Việc gán cho thuộc tính này không ảnh hưởng đến Connection.row_factory của kết nối chính.

Xem Cách tạo và sử dụng Row Factory để biết thêm chi tiết.

Hàng đối tượng¶

class sqlite3.Row¶

Phiên bản Row đóng vai trò là row_factory được tối ưu hóa cao cho các đối tượng Connection. Nó hỗ trợ lặp lại, kiểm tra đẳng thức, truy cập len() và mapping theo tên cột và chỉ mục.

Hai đối tượng Row so sánh bằng nhau nếu chúng có tên và giá trị cột giống hệt nhau.

Xem Cách tạo và sử dụng Row Factory để biết thêm chi tiết.

keys()¶: Trả về list tên cột là strings. Ngay sau một truy vấn, nó là thành viên đầu tiên của mỗi bộ trong Cursor.description.

Thay đổi trong phiên bản 3.5: Đã thêm hỗ trợ cắt lát.

Đối tượng đốm màu¶

class sqlite3.Blob¶

Added in version 3.11.

Phiên bản Blob là file-like object có thể đọc và ghi dữ liệu trong SQLite BLOB. Gọi len(blob) để lấy kích thước (số byte) của blob. Sử dụng các chỉ mục và slices để truy cập trực tiếp vào dữ liệu blob.

Sử dụng Blob làm context manager để đảm bảo rằng tay cầm blob được đóng lại sau khi sử dụng.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE test(blob_col blob)")
con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# Write vào blob của chúng tôi, sử dụng hai thao tác ghi:
với con.blobopen("test", "blob_col", 1) là blob:
    blob.write(b"xin chào, ")
    blob.write(b"thế giới.")
    # Modify byte đầu tiên và cuối cùng của blob của chúng tôi
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Read nội dung của blob của chúng tôi
với con.blobopen("test", "blob_col", 1) là blob:
    lời chào = blob.read()

print(lời chào) # outputs "b'Xin chào thế giới!'"
con.close()

close()¶

Đóng đốm màu.

Các đốm màu sẽ không thể sử dụng được từ thời điểm này trở đi. Một ngoại lệ Error (hoặc lớp con) sẽ được đưa ra nếu thực hiện thêm bất kỳ thao tác nào với blob.

read(length=-1, /)¶: Đọc byte dữ liệu length từ blob ở vị trí offset hiện tại. Nếu đạt đến cuối blob, dữ liệu lên tới EOF sẽ được trả về. Khi length không được chỉ định hoặc âm, read() sẽ đọc cho đến hết đốm màu.

write(data, /)¶: Viết data vào blob ở offset hiện tại. Chức năng này không thể thay đổi độ dài blob. Viết quá cuối đốm màu sẽ tăng ValueError.

tell()¶: Trả về vị trí truy cập hiện tại của blob.

seek(offset, origin=os.SEEK_SET, /)¶: Đặt vị trí truy cập hiện tại của blob thành offset. Đối số origin mặc định là os.SEEK_SET (định vị blob tuyệt đối). Các giá trị khác cho origin là os.SEEK_CUR (tìm kiếm tương đối với vị trí hiện tại) và os.SEEK_END (tìm kiếm tương đối với phần cuối của đốm màu).

Đối tượng Chuẩn bị Giao thức¶

class sqlite3.PrepareProtocol¶: Mục đích duy nhất của loại Chuẩn bị giao thức là hoạt động như một giao thức thích ứng kiểu PEP 246 cho các đối tượng có thể adapt themselves đến native SQLite types.

Ngoại lệ¶

Hệ thống phân cấp ngoại lệ được xác định bởi DB-API 2.0 (PEP 249).

exception sqlite3.Warning¶: Ngoại lệ này hiện không được mô-đun sqlite3 đưa ra nhưng có thể được đưa ra bởi các ứng dụng sử dụng sqlite3, chẳng hạn như nếu một hàm do người dùng xác định sẽ cắt bớt dữ liệu trong khi chèn. Warning là một lớp con của Exception.

exception sqlite3.Error¶

Lớp cơ sở của các ngoại lệ khác trong mô-đun này. Sử dụng tính năng này để phát hiện tất cả lỗi chỉ bằng một câu lệnh except. Error là một lớp con của Exception.

Nếu ngoại lệ bắt nguồn từ bên trong thư viện SQLite, hai thuộc tính sau sẽ được thêm vào ngoại lệ đó:

sqlite_errorcode¶: Mã lỗi số từ SQLite API

Added in version 3.11.

sqlite_errorname¶: Tên tượng trưng của mã lỗi số từ SQLite API

Added in version 3.11.

exception sqlite3.InterfaceError¶: Ngoại lệ được đưa ra do sử dụng sai SQLite C API cấp thấp. Nói cách khác, nếu ngoại lệ này được nêu ra, nó có thể chỉ ra lỗi trong mô-đun sqlite3. InterfaceError là một lớp con của Error.

exception sqlite3.DatabaseError¶: Ngoại lệ nảy sinh do lỗi liên quan đến cơ sở dữ liệu. Điều này đóng vai trò là ngoại lệ cơ bản cho một số loại lỗi cơ sở dữ liệu. Nó chỉ được ngầm nâng lên thông qua các lớp con chuyên biệt. DatabaseError là một lớp con của Error.

exception sqlite3.DataError¶: Ngoại lệ nảy sinh đối với các lỗi do sự cố xảy ra với dữ liệu đã xử lý, như giá trị số nằm ngoài phạm vi và chuỗi quá dài. DataError là một lớp con của DatabaseError.

exception sqlite3.OperationalError¶: Ngoại lệ được đưa ra đối với các lỗi liên quan đến hoạt động của cơ sở dữ liệu và không nhất thiết nằm dưới sự kiểm soát của người lập trình. Ví dụ: không tìm thấy đường dẫn cơ sở dữ liệu hoặc không thể xử lý giao dịch. OperationalError là một lớp con của DatabaseError.

exception sqlite3.IntegrityError¶: Ngoại lệ nảy sinh khi tính toàn vẹn quan hệ của cơ sở dữ liệu bị ảnh hưởng, ví dụ: kiểm tra khóa ngoại không thành công. Nó là một lớp con của DatabaseError.

exception sqlite3.InternalError¶: Ngoại lệ nảy sinh khi SQLite gặp lỗi nội bộ. Nếu điều này được nêu ra, nó có thể chỉ ra rằng có vấn đề với thư viện SQLite thời gian chạy. InternalError là một lớp con của DatabaseError.

exception sqlite3.ProgrammingError¶: Ngoại lệ được đưa ra đối với các lỗi lập trình sqlite3 API, ví dụ như cung cấp sai số lượng liên kết cho một truy vấn hoặc cố gắng thao tác trên Connection đã đóng. ProgrammingError là một lớp con của DatabaseError.

exception sqlite3.NotSupportedError¶: Ngoại lệ được đưa ra trong trường hợp phương thức hoặc cơ sở dữ liệu API không được thư viện SQLite cơ bản hỗ trợ. Ví dụ: đặt deterministic thành True trong create_function(), nếu thư viện SQLite cơ bản không hỗ trợ các hàm xác định. NotSupportedError là một lớp con của DatabaseError.

Các loại SQLite và Python¶

SQLite vốn hỗ trợ các loại sau: NULL, INTEGER, REAL, TEXT, BLOB.

Do đó, các loại Python sau có thể được gửi tới SQLite mà không gặp vấn đề gì:

loại Python	Kiểu SQLite
`None`	`NULL`
`int`	`INTEGER`
`float`	`REAL`
`str`	`TEXT`
`bytes`	`BLOB`

Đây là cách các kiểu SQLite được chuyển đổi thành các kiểu Python theo mặc định:

Kiểu SQLite	loại Python
`NULL`	`None`
`INTEGER`	`int`
`REAL`	`float`
`TEXT`	phụ thuộc vào `text_factory`, `str` theo mặc định
`BLOB`	`bytes`

Hệ thống loại của mô-đun sqlite3 có thể mở rộng theo hai cách: bạn có thể lưu trữ các loại Python bổ sung trong cơ sở dữ liệu SQLite thông qua object adapters và bạn có thể cho phép mô-đun sqlite3 chuyển đổi các loại SQLite thành các loại Python thông qua converters.

Bộ điều hợp và bộ chuyển đổi mặc định (không dùng nữa)¶

Ghi chú

Các bộ điều hợp và bộ chuyển đổi mặc định không được dùng nữa kể từ Python 3.12. Thay vào đó, hãy sử dụng Công thức chuyển đổi và chuyển đổi và điều chỉnh chúng theo nhu cầu của bạn.

Các bộ điều hợp và bộ chuyển đổi mặc định không được dùng nữa bao gồm:

Một bộ chuyển đổi cho các đối tượng datetime.date sang strings ở định dạng ISO 8601.
Bộ chuyển đổi cho các đối tượng datetime.datetime thành chuỗi ở định dạng ISO 8601.
Bộ chuyển đổi cho các loại "ngày" declared thành các đối tượng datetime.date.
Trình chuyển đổi cho các loại "dấu thời gian" được khai báo thành đối tượng datetime.datetime. Các phần phân số sẽ được cắt ngắn thành 6 chữ số (độ chính xác micro giây).

Ghi chú

Trình chuyển đổi "dấu thời gian" mặc định bỏ qua các giá trị bù UTC trong cơ sở dữ liệu và luôn trả về một đối tượng datetime.datetime ngây thơ. Để duy trì độ lệch UTC trong dấu thời gian, hãy tắt bộ chuyển đổi hoặc đăng ký bộ chuyển đổi nhận biết độ lệch với register_converter().

Sắp loại bỏ từ phiên bản 3.12.

Giao diện dòng lệnh¶

Mô-đun sqlite3 có thể được gọi dưới dạng tập lệnh, sử dụng khóa chuyển -m của trình thông dịch để cung cấp một trình bao SQLite đơn giản. Chữ ký đối số như sau:

python -m sqlite3 [-h] [-v] [tên tệp] [sql]

Gõ .quit hoặc CTRL-D để thoát khỏi shell.

-h, --help¶: Trợ giúp in CLI.

-v, --version¶: In phiên bản thư viện SQLite cơ bản.

Added in version 3.12.

Hướng dẫn cách thực hiện¶

Cách sử dụng trình giữ chỗ để liên kết các giá trị trong truy vấn SQL¶

Các thao tác SQL thường cần sử dụng các giá trị từ các biến Python. Tuy nhiên, hãy cẩn thận khi sử dụng các thao tác chuỗi của Python để tập hợp các truy vấn vì chúng dễ bị tấn công bởi SQL injection attacks. Ví dụ: kẻ tấn công có thể chỉ cần đóng một trích dẫn và tiêm OR TRUE để chọn tất cả các hàng

>>> # Never làm điều này -- không an toàn!
>>> ký hiệu = đầu vào()
' HOẶC TRUE; --
>>> sql = "SELECT * FROM cổ phiếu ký hiệu WHERE = '%s'" % ký hiệu
>>> in (sql)
SELECT * FROM cổ phiếu biểu tượng WHERE = '' HOẶC TRUE; --'
>>> cur.execute(sql)

Thay vào đó, hãy sử dụng thay thế tham số của DB-API. Để chèn một biến vào chuỗi truy vấn, hãy sử dụng trình giữ chỗ trong chuỗi và thay thế các giá trị thực tế vào truy vấn bằng cách cung cấp chúng dưới dạng tuple giá trị cho đối số thứ hai của phương thức execute() của con trỏ.

Câu lệnh SQL có thể sử dụng một trong hai loại phần giữ chỗ: dấu chấm hỏi (kiểu qmark) hoặc phần giữ chỗ có tên (kiểu được đặt tên). Đối với kiểu qmark, parameters phải là sequence có độ dài phải khớp với số lượng phần giữ chỗ hoặc ProgrammingError được nâng lên. Đối với kiểu được đặt tên, parameters phải là một phiên bản của dict (hoặc một lớp con), phải chứa các khóa cho tất cả các tham số được đặt tên; bất kỳ mục bổ sung nào đều bị bỏ qua. Đây là một ví dụ về cả hai phong cách:

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

# This là kiểu được đặt tên được sử dụng với execmany():
dữ liệu = (
    {"tên": "C", "năm": 1972},
    {"tên": "Fortran", "năm": 1957},
    {"tên": "Python", "năm": 1991},
    {"tên": "Đi", "năm": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# This là kiểu qmark được sử dụng trong truy vấn SELECT:
thông số = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

Ghi chú

Phần giữ chỗ số PEP 249 được hỗ trợ not. Nếu được sử dụng, chúng sẽ được hiểu là phần giữ chỗ được đặt tên.

Cách điều chỉnh các loại Python tùy chỉnh cho phù hợp với giá trị SQLite¶

SQLite chỉ hỗ trợ một tập hợp giới hạn các kiểu dữ liệu nguyên bản. Để lưu trữ các loại Python tùy chỉnh trong cơ sở dữ liệu SQLite, hãy adapt chúng vào một trong các tệp Python types SQLite natively understands.

Có hai cách để điều chỉnh các đối tượng Python theo các kiểu SQLite: để đối tượng của bạn tự điều chỉnh hoặc sử dụng adapter callable. Cái sau sẽ được ưu tiên hơn cái trước. Đối với thư viện xuất loại tùy chỉnh, việc cho phép loại đó tự điều chỉnh có thể hợp lý. Với tư cách là nhà phát triển ứng dụng, việc kiểm soát trực tiếp bằng cách đăng ký các chức năng bộ điều hợp tùy chỉnh có thể sẽ hợp lý hơn.

Cách viết các đối tượng có thể thích ứng¶

Giả sử chúng ta có một lớp Point đại diện cho một cặp tọa độ, x và y, trong hệ tọa độ Descartes. Cặp tọa độ sẽ được lưu dưới dạng chuỗi văn bản trong cơ sở dữ liệu, sử dụng dấu chấm phẩy để phân tách tọa độ. Điều này có thể được thực hiện bằng cách thêm phương thức __conform__(self, protocol) trả về giá trị được điều chỉnh. Đối tượng được truyền tới protocol sẽ có kiểu PrepareProtocol.

Điểm lớp:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(tự, giao thức):
        nếu giao thức là sqlite3.PrepareProtocol:
            trả về f"{self.x};{self.y}"

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

cur.execute("SELECT ?", (Điểm(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()

Cách đăng ký bộ điều hợp có thể gọi được¶

Khả năng khác là tạo một hàm chuyển đổi đối tượng Python thành loại tương thích với SQLite. Chức năng này sau đó có thể được đăng ký bằng register_adapter().

Điểm lớp:
    def __init__(self, x, y):
        self.x, self.y = x, y

def Adapt_point(điểm):
    trả về f"{point.x};{point.y}"

sqlite3.register_adapter(Điểm, Adapt_point)

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

cur.execute("SELECT ?", (Điểm(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()

Cách chuyển đổi giá trị SQLite thành loại Python tùy chỉnh¶

Viết một bộ điều hợp cho phép bạn chuyển đổi các giá trị SQLite to kiểu Python tùy chỉnh from. Để có thể chuyển đổi các giá trị SQLite from to các loại Python tùy chỉnh, chúng tôi sử dụng converters.

Hãy quay trở lại lớp Point. Chúng tôi đã lưu trữ tọa độ x và y được phân tách bằng dấu chấm phẩy dưới dạng chuỗi trong SQLite.

Đầu tiên, chúng ta sẽ xác định một hàm chuyển đổi chấp nhận chuỗi làm tham số và xây dựng đối tượng Point từ chuỗi đó.

Ghi chú

Các hàm chuyển đổi là always đã chuyển một đối tượng bytes, bất kể kiểu dữ liệu SQLite cơ bản.

def chuyển đổi_point(s):
    x, y = map(float, s.split(b";"))
    Điểm trả về(x, y)

Bây giờ chúng ta cần cho sqlite3 biết khi nào nó nên chuyển đổi một giá trị SQLite nhất định. Điều này được thực hiện khi kết nối với cơ sở dữ liệu, sử dụng tham số detect_types của connect(). Có ba lựa chọn:

Ngụ ý: đặt detect_types thành PARSE_DECLTYPES
Rõ ràng: đặt detect_types thành PARSE_COLNAMES
Cả hai: đặt detect_types thành sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES. Tên cột được ưu tiên hơn các loại được khai báo.

Ví dụ sau minh họa các cách tiếp cận ngầm và rõ ràng:

Điểm lớp:
    def __init__(self, x, y):
        self.x, self.y = x, y

    chắc chắn __repr__(tự):
        trả về f"Điểm({self.x}, {self.y})"

def Adapt_point(điểm):
    trả về f"{point.x};{point.y}"

def chuyển đổi_point(s):
    x, y = list(map(float, s.split(b";")))
    Điểm trả về(x, y)

# Register bộ chuyển đổi và bộ chuyển đổi
sqlite3.register_adapter(Điểm, Adapt_point)
sqlite3.register_converter("điểm", Convert_point)

# 1) Phân tích cú pháp bằng cách sử dụng các loại đã khai báo
p = Điểm(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("với các kiểu đã khai báo:", cur.fetchone()[0])
cur.close()
con.close()

# 2) Phân tích cú pháp bằng tên cột
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 [điểm]" FROM test')
print("với tên cột:", cur.fetchone()[0])
cur.close()
con.close()

Công thức chuyển đổi và chuyển đổi¶

Phần này hiển thị các công thức cho các bộ điều hợp và bộ chuyển đổi phổ biến.

nhập ngày giờ dưới dạng dt
nhập sqlite3

chắc chắn Adapt_date_iso(val):
    """Điều chỉnh datetime.date thành ngày ISO 8601."""
    trả về val.isoformat()

chắc chắn Adapt_datetime_iso(val):
    """Điều chỉnh datetime.datetime thành ngày ISO 8601 theo múi giờ."""
    trả về val.replace(tzinfo=None).isoformat()

def Adapt_datetime_epoch(val):
    """Điều chỉnh datetime.datetime theo dấu thời gian Unix."""
    trả về int(val.timestamp())

sqlite3.register_adapter(dt.date, Adapt_date_iso)
sqlite3.register_adapter(dt.datetime, Adapt_datetime_iso)
sqlite3.register_adapter(dt.datetime, Adapt_datetime_epoch)

chắc chắn chuyển đổi_date(val):
    """Chuyển đổi ngày ISO 8601 thành đối tượng datetime.date."""
    trả về dt.date.fromisoformat(val.decode())

def chuyển đổi_datetime(val):
    """Chuyển đổi datetime ISO 8601 thành đối tượng datetime.datetime."""
    trả về dt.datetime.fromisoformat(val.decode())

chắc chắn chuyển đổi_timestamp(val):
    """Chuyển đổi dấu thời gian kỷ nguyên Unix thành đối tượng datetime.datetime."""
    trả về dt.datetime.fromtimestamp(int(val))

sqlite3.register_converter("ngày", Convert_date)
sqlite3.register_converter("datetime", Convert_datetime)
sqlite3.register_converter("dấu thời gian", Convert_timestamp)

Cách sử dụng các phương pháp phím tắt kết nối¶

Sử dụng các phương thức execute(), executemany() và executescript() của lớp Connection, mã của bạn có thể được viết chính xác hơn vì bạn không phải tạo các đối tượng Cursor (thường là không cần thiết) một cách rõ ràng. Thay vào đó, các đối tượng Cursor được tạo ngầm và các phương thức phím tắt này trả về các đối tượng con trỏ. Bằng cách này, bạn có thể thực thi câu lệnh SELECT và lặp lại trực tiếp nó chỉ bằng một lệnh gọi duy nhất trên đối tượng Connection.

# Create và điền vào bảng.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(tên, first_appeared)")
dữ liệu = [
    ("C++", 1985),
    ("Mục tiêu-C", 1984),
]
con.executemany("INSERT INTO lang(tên, first_appeared) VALUES(?, ?)", data)

# Print nội dung bảng
cho hàng trong con.execute("SELECT name, first_appeared FROM lang"):
    in (hàng)

print("Tôi vừa xóa", con.execute("DELETE FROM lang").rowcount, "rows")

# close() không phải là một phương thức phím tắt và nó không được gọi tự động;
Đối tượng kết nối # the phải được đóng bằng tay
con.close()

Cách sử dụng trình quản lý bối cảnh kết nối¶

Đối tượng Connection có thể được sử dụng làm trình quản lý bối cảnh tự động cam kết hoặc khôi phục các giao dịch đang mở khi rời khỏi phần thân của trình quản lý bối cảnh. Nếu phần thân của câu lệnh with kết thúc mà không có ngoại lệ thì giao dịch được thực hiện. Nếu cam kết này không thành công hoặc nếu phần nội dung của câu lệnh with đưa ra một ngoại lệ chưa được phát hiện thì giao dịch sẽ được khôi phục. Nếu autocommit là False, một giao dịch mới sẽ được mở ngầm sau khi cam kết hoặc quay lại.

Nếu không có giao dịch mở nào khi rời khỏi phần nội dung của câu lệnh with hoặc nếu autocommit là True thì trình quản lý bối cảnh sẽ không làm gì cả.

Ghi chú

Trình quản lý bối cảnh không ngầm mở một giao dịch mới cũng như không đóng kết nối. Nếu bạn cần trình quản lý bối cảnh đóng, hãy cân nhắc sử dụng contextlib.closing().

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

# Successful, con.commit() được gọi tự động sau đó
với con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() được gọi sau khi khối with kết thúc với một ngoại lệ,
Ngoại lệ # the vẫn được nêu ra và phải bị bắt
thử:
    với con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
ngoại trừ sqlite3.IntegrityError:
    print("không thể thêm Python hai lần")

Đối tượng # Connection được sử dụng làm trình quản lý bối cảnh chỉ thực hiện hoặc hoàn tác các giao dịch,
# so đối tượng kết nối phải được đóng bằng tay
con.close()

Cách làm việc với URI SQLite¶

Một số thủ thuật URI hữu ích bao gồm:

Mở cơ sở dữ liệu ở chế độ chỉ đọc:

>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE chỉ đọc(dữ liệu)")
Traceback (cuộc gọi gần đây nhất):
OperationalError: cố gắng viết cơ sở dữ liệu chỉ đọc
>>> con.close()

Không ngầm tạo một tệp cơ sở dữ liệu mới nếu nó chưa tồn tại; sẽ tăng OperationalError nếu không thể tạo tệp mới:

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (cuộc gọi gần đây nhất):
OperationalError: không thể mở tệp cơ sở dữ liệu

Tạo cơ sở dữ liệu trong bộ nhớ có tên được chia sẻ:

db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
với con1:
    con1.execute("CREATE TABLE đã chia sẻ (dữ liệu)")
    con1.execute("INSERT INTO chia sẻ VALUES(28)")
res = con2.execute("dữ liệu SELECT FROM được chia sẻ")
khẳng định res.fetchone() == (28,)

con1.close()
con2.close()

Bạn có thể tìm thêm thông tin về tính năng này, bao gồm danh sách các tham số, trong SQLite URI documentation.

Cách tạo và sử dụng Row Factory¶

Theo mặc định, sqlite3 đại diện cho mỗi hàng dưới dạng tuple. Nếu tuple không phù hợp với nhu cầu của bạn, bạn có thể sử dụng lớp sqlite3.Row hoặc row_factory tùy chỉnh.

Mặc dù row_factory tồn tại như một thuộc tính trên cả Cursor và Connection, nhưng bạn nên đặt Connection.row_factory để tất cả các con trỏ được tạo từ kết nối sẽ sử dụng cùng một nhà máy hàng.

Row cung cấp quyền truy cập được đặt tên theo chỉ mục và không phân biệt chữ hoa chữ thường vào các cột, với mức tiêu hao bộ nhớ tối thiểu và tác động đến hiệu suất so với tuple. Để sử dụng Row làm nhà máy sản xuất hàng, hãy gán nó cho thuộc tính row_factory:

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

Các truy vấn hiện trả về các đối tượng Row:

>>> res = con.execute("Tên AS SELECT 'Trái Đất', bán kính 6378 AS")
>>> hàng = res.fetchone()
>>> row.keys()
['tên', 'bán kính']
>>> hàng[0] # Access theo chỉ mục.
'Trái đất'
>>> row["name"] # Access theo tên.
'Trái đất'
>>> row["RADIUS"] # Column tên không phân biệt chữ hoa chữ thường.
6378
>>> con.close()

Ghi chú

Mệnh đề FROM có thể được bỏ qua trong câu lệnh SELECT, như trong ví dụ trên. Trong những trường hợp như vậy, SQLite trả về một hàng có các cột được xác định bởi các biểu thức, ví dụ: nghĩa đen, với các bí danh đã cho expr AS alias.

Bạn có thể tạo một row_factory tùy chỉnh trả về mỗi hàng dưới dạng dict, với tên cột được ánh xạ tới các giá trị:

def dict_factory(con trỏ, hàng):
    các trường = [cột[0] cho cột trong con trỏ.description]
    trả về {key: giá trị cho khóa, giá trị trong zip(fields, row)}

Khi sử dụng nó, các truy vấn hiện trả về dict thay vì tuple:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> cho hàng trong con.execute("SELECT 1 AS a, 2 AS b"):
... in(hàng)
{'a': 1, 'b': 2}
>>> con.close()

Nhà máy hàng sau trả về named tuple:

từ bộ sưu tập nhập têntuple

def có têntuple_factory(con trỏ, hàng):
    các trường = [cột[0] cho cột trong con trỏ.description]
    cls = nametuple("Hàng", trường)
    trả về cls._make(hàng)

namedtuple_factory() có thể được sử dụng như sau:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = nametuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> hàng
Hàng(a=1, b=2)
>>> row[0] truy cập # Indexed.
1
>>> truy cập row.b # Attribute.
2
>>> con.close()

Với một số điều chỉnh, công thức trên có thể được điều chỉnh để sử dụng dataclass hoặc bất kỳ lớp tùy chỉnh nào khác thay vì namedtuple.

Cách xử lý mã hóa văn bản không phải UTF-8¶

Theo mặc định, sqlite3 sử dụng str để điều chỉnh các giá trị SQLite với kiểu dữ liệu TEXT. Điều này hoạt động tốt đối với văn bản được mã hóa UTF-8, nhưng nó có thể không thành công đối với các mã hóa khác và UTF-8 không hợp lệ. Bạn có thể sử dụng text_factory tùy chỉnh để xử lý những trường hợp như vậy.

Do flexible typing của SQLite, không có gì lạ khi bắt gặp các cột trong bảng có kiểu dữ liệu TEXT chứa các mã hóa không phải UTF-8 hoặc thậm chí là dữ liệu tùy ý. Để chứng minh, giả sử chúng ta có một cơ sở dữ liệu với văn bản được mã hóa ISO-8859-2 (Latin-2), ví dụ: một bảng các mục từ điển tiếng Séc-Anh. Giả sử bây giờ chúng ta có một phiên bản Connection con được kết nối với cơ sở dữ liệu này, chúng ta có thể giải mã văn bản được mã hóa Latin-2 bằng cách sử dụng text_factory này:

con.text_factory = dữ liệu lambda: str(data, Encoding="latin2")

Đối với UTF-8 không hợp lệ hoặc dữ liệu tùy ý được lưu trữ trong các cột của bảng TEXT, bạn có thể sử dụng kỹ thuật sau, mượn từ Unicode HOWTO:

con.text_factory = dữ liệu lambda: str(data,errors="surrogateescape")

Ghi chú

Mô-đun sqlite3 API không hỗ trợ các chuỗi chứa đại diện thay thế.

Xem thêm

Unicode HOWTO

Giải thích¶

Kiểm soát giao dịch¶

sqlite3 cung cấp nhiều phương pháp kiểm soát xem các giao dịch cơ sở dữ liệu có được mở và đóng hay không, khi nào và như thế nào. Kiểm soát giao dịch thông qua thuộc tính autocommit được khuyến nghị, trong khi Kiểm soát giao dịch thông qua thuộc tính isolation_level vẫn giữ nguyên hành vi trước Python 3.12.

Kiểm soát giao dịch thông qua thuộc tính `autocommit`¶

Cách kiểm soát hành vi giao dịch được khuyến nghị là thông qua thuộc tính Connection.autocommit, tốt nhất nên đặt thuộc tính này bằng tham số autocommit của connect().

Bạn nên đặt autocommit thành False, ngụ ý kiểm soát giao dịch tuân thủ PEP 249. Điều này có nghĩa là:

sqlite3 đảm bảo rằng một giao dịch luôn mở, vì vậy connect(), Connection.commit() và Connection.rollback() sẽ ngầm mở một giao dịch mới (ngay sau khi đóng giao dịch đang chờ xử lý, đối với hai giao dịch sau). sqlite3 sử dụng câu lệnh BEGIN DEFERRED khi mở giao dịch.
Các giao dịch phải được cam kết rõ ràng bằng cách sử dụng commit().
Các giao dịch phải được khôi phục một cách rõ ràng bằng cách sử dụng rollback().
Việc khôi phục ngầm được thực hiện nếu cơ sở dữ liệu được close()-ed với các thay đổi đang chờ xử lý.

Đặt autocommit thành True để bật autocommit mode của SQLite. Ở chế độ này, Connection.commit() và Connection.rollback() không có hiệu lực. Lưu ý rằng chế độ tự động cam kết của SQLite khác với thuộc tính Connection.autocommit tuân thủ PEP 249; sử dụng Connection.in_transaction để truy vấn chế độ tự động xác nhận SQLite cấp thấp.

Đặt autocommit thành LEGACY_TRANSACTION_CONTROL để để lại hành vi kiểm soát giao dịch cho thuộc tính Connection.isolation_level. Xem Kiểm soát giao dịch thông qua thuộc tính isolation_level để biết thêm thông tin.

Kiểm soát giao dịch thông qua thuộc tính `isolation_level`¶

Ghi chú

Cách kiểm soát giao dịch được khuyến nghị là thông qua thuộc tính autocommit. Xem Kiểm soát giao dịch thông qua thuộc tính autocommit.

Nếu Connection.autocommit được đặt thành LEGACY_TRANSACTION_CONTROL (mặc định), hành vi giao dịch được kiểm soát bằng thuộc tính Connection.isolation_level. Ngược lại, isolation_level không có tác dụng.

Nếu thuộc tính kết nối isolation_level không phải là None, thì các giao dịch mới sẽ được mở ngầm trước khi execute() và executemany() thực thi các câu lệnh INSERT, UPDATE, DELETE hoặc REPLACE; đối với các câu lệnh khác, không có xử lý giao dịch ngầm nào được thực hiện. Sử dụng các phương thức commit() và rollback() để cam kết và khôi phục các giao dịch đang chờ xử lý tương ứng. Bạn có thể chọn SQLite transaction behaviour cơ bản — tức là xem loại câu lệnh BEGIN nào mà sqlite3 có thực thi ngầm hay không — thông qua thuộc tính isolation_level.

Nếu isolation_level được đặt thành None thì không có giao dịch nào được mở ngầm cả. Điều này để lại thư viện SQLite cơ bản ở autocommit mode, nhưng cũng cho phép người dùng thực hiện xử lý giao dịch của riêng họ bằng cách sử dụng các câu lệnh SQL rõ ràng. Chế độ tự động cam kết của thư viện SQLite cơ bản có thể được truy vấn bằng thuộc tính in_transaction.

Phương thức executescript() hoàn toàn cam kết mọi giao dịch đang chờ xử lý trước khi thực thi tập lệnh SQL đã cho, bất kể giá trị của isolation_level.

Thay đổi trong phiên bản 3.6: sqlite3 được sử dụng để thực hiện ngầm một giao dịch mở trước các câu lệnh DDL. Đây không còn là trường hợp nữa.

Thay đổi trong phiên bản 3.12: Cách kiểm soát giao dịch được khuyến nghị hiện nay là thông qua thuộc tính autocommit.

`sqlite3` --- Giao diện DB-API 2.0 cho cơ sở dữ liệu SQLite¶

Hướng dẫn¶

Tài liệu tham khảo¶

Chức năng mô-đun¶

Hằng số mô-đun¶

Đối tượng kết nối¶

Đối tượng con trỏ¶

Hàng đối tượng¶

Đối tượng đốm màu¶

Đối tượng Chuẩn bị Giao thức¶

Ngoại lệ¶

Các loại SQLite và Python¶

Bộ điều hợp và bộ chuyển đổi mặc định (không dùng nữa)¶

Giao diện dòng lệnh¶

Hướng dẫn cách thực hiện¶

Cách sử dụng trình giữ chỗ để liên kết các giá trị trong truy vấn SQL¶

Cách điều chỉnh các loại Python tùy chỉnh cho phù hợp với giá trị SQLite¶

Cách viết các đối tượng có thể thích ứng¶

Cách đăng ký bộ điều hợp có thể gọi được¶

Cách chuyển đổi giá trị SQLite thành loại Python tùy chỉnh¶

Công thức chuyển đổi và chuyển đổi¶

Cách sử dụng các phương pháp phím tắt kết nối¶

Cách sử dụng trình quản lý bối cảnh kết nối¶

Cách làm việc với URI SQLite¶

Cách tạo và sử dụng Row Factory¶

Cách xử lý mã hóa văn bản không phải UTF-8¶

Giải thích¶

Kiểm soát giao dịch¶

Kiểm soát giao dịch thông qua thuộc tính `autocommit`¶

Kiểm soát giao dịch thông qua thuộc tính `isolation_level`¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

sqlite3 --- Giao diện DB-API 2.0 cho cơ sở dữ liệu SQLite¶

Hướng dẫn¶

Tài liệu tham khảo¶

Chức năng mô-đun¶

Hằng số mô-đun¶

Đối tượng kết nối¶

Đối tượng con trỏ¶

Hàng đối tượng¶

Đối tượng đốm màu¶

Đối tượng Chuẩn bị Giao thức¶

Ngoại lệ¶

Các loại SQLite và Python¶

Bộ điều hợp và bộ chuyển đổi mặc định (không dùng nữa)¶

Giao diện dòng lệnh¶

Hướng dẫn cách thực hiện¶

Cách sử dụng trình giữ chỗ để liên kết các giá trị trong truy vấn SQL¶

Cách điều chỉnh các loại Python tùy chỉnh cho phù hợp với giá trị SQLite¶

Cách viết các đối tượng có thể thích ứng¶

Cách đăng ký bộ điều hợp có thể gọi được¶

Cách chuyển đổi giá trị SQLite thành loại Python tùy chỉnh¶

Công thức chuyển đổi và chuyển đổi¶

Cách sử dụng các phương pháp phím tắt kết nối¶

Cách sử dụng trình quản lý bối cảnh kết nối¶

Cách làm việc với URI SQLite¶

Cách tạo và sử dụng Row Factory¶

Cách xử lý mã hóa văn bản không phải UTF-8¶

Giải thích¶

Kiểm soát giao dịch¶

Kiểm soát giao dịch thông qua thuộc tính autocommit¶

Kiểm soát giao dịch thông qua thuộc tính isolation_level¶

`sqlite3` --- Giao diện DB-API 2.0 cho cơ sở dữ liệu SQLite¶

Kiểm soát giao dịch thông qua thuộc tính `autocommit`¶

Kiểm soát giao dịch thông qua thuộc tính `isolation_level`¶