sqlite3
— DB-API 2.0 интерфейс для баз данных SQLite¶
Источник: Lib/sqlite3/
SQLite - это библиотека на языке C, которая предоставляет легкую дисковую базу данных, не требующую отдельного серверного процесса и позволяющую обращаться к базе данных с помощью нестандартного варианта языка запросов SQL. Некоторые приложения могут использовать SQLite для внутреннего хранения данных. Также можно создать прототип приложения с использованием SQLite, а затем перенести код на более крупную базу данных, такую как PostgreSQL или Oracle.
Модуль sqlite3
был написан Герхардом Херингом. Он предоставляет SQL-интерфейс, соответствующий спецификации DB-API 2.0, описанной в PEP 249, и требует SQLite 3.15.2 или более новой версии.
Этот документ включает в себя четыре основных раздела:
Учебное пособие учит, как использовать модуль
sqlite3
.Ссылка описывает классы и функции, определяемые этим модулем.
Руководства по эксплуатации подробно описывает, как справиться с конкретными задачами.
Пояснение содержит подробную информацию об управлении транзакциями.
См.также
- https://www.sqlite.org
Веб-страница SQLite; документация описывает синтаксис и доступные типы данных для поддерживаемого диалекта SQL.
- https://www.w3schools.com/sql/
Учебник, справочник и примеры для изучения синтаксиса SQL.
- PEP 249 - Спецификация API баз данных 2.0
PEP написан Марком-Андре Лембургом.
Учебное пособие¶
В этом уроке вы создадите базу данных фильмов о Монти Пайтоне, используя базовую функциональность sqlite3
. Оно предполагает фундаментальное понимание концепций баз данных, включая cursors и transactions.
Сначала нам нужно создать новую базу данных и открыть соединение с ней, чтобы sqlite3
мог с ней работать. Вызовите sqlite3.connect()
для создания соединения с базой данных tutorial.db
в текущем рабочем каталоге, неявно создавая ее, если она не существует:
import sqlite3
con = sqlite3.connect("tutorial.db")
Возвращаемый Connection
объект con
представляет собой соединение с базой данных на диске.
Для выполнения SQL-запросов и получения результатов из SQL-запросов нам понадобится курсор базы данных. Вызовите con.cursor()
, чтобы создать Cursor
:
cur = con.cursor()
Теперь, когда у нас есть подключение к базе данных и курсор, мы можем создать таблицу базы данных movie
со столбцами для названия, года выпуска и оценки рецензии. Для простоты мы можем просто использовать имена столбцов в объявлении таблицы - благодаря функции flexible typing в SQLite указание типов данных необязательно. Выполните оператор CREATE TABLE
, вызвав команду cur.execute(...)
:
cur.execute("CREATE TABLE movie(title, year, score)")
Мы можем убедиться, что новая таблица создана, запросив встроенную в SQLite таблицу sqlite_master
, которая теперь должна содержать запись для определения таблицы movie
(подробности см. в разделе The Schema Table). Выполните этот запрос, вызвав cur.execute(...)
, присвойте результат 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
Теперь добавьте две строки данных, представленных в виде SQL-литералей, выполнив оператор INSERT
, а затем снова вызвав cur.execute(...)
:
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
неявно открывает транзакцию, которая должна быть зафиксирована до сохранения изменений в базе данных (подробнее см. Контроль транзакций). Вызовите con.commit()
на объекте соединения, чтобы зафиксировать транзакцию:
con.commit()
Мы можем убедиться, что данные были вставлены правильно, выполнив запрос SELECT
. Используйте уже знакомый нам cur.execute(...)
, чтобы присвоить результат res
, и вызовите res.fetchall()
, чтобы вернуть все результирующие строки:
>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]
В результате получается list
из двух tuple
, по одному на ряд, каждый из которых содержит значение 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.
Обратите внимание, что для привязки data
к запросу используются ?
. Всегда используйте местодержатели вместо string formatting для привязки значений Python к SQL-запросам, чтобы избежать SQL injection attacks (см. Как использовать заполнители для привязки значений в 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")
Каждая строка представляет собой два элемента tuple
из (year, title)
, соответствующих столбцам, выбранным в запросе.
Наконец, проверьте, что база данных была записана на диск, вызвав 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
>>> new_con.close()
Теперь вы создали базу данных SQLite с помощью модуля sqlite3
, вставили в нее данные и извлекли из нее значения несколькими способами.
См.также
Руководства по эксплуатации для дальнейшего чтения:
Пояснение для получения подробной информации об управлении транзакциями.
Ссылка¶
Функции модуля¶
- 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 database existing only in memory и открыть соединение с ним.timeout (float) – Сколько секунд соединение должно ждать, прежде чем поднять
OperationalError
, если таблица заблокирована. Если другое соединение открывает транзакцию для изменения таблицы, эта таблица будет заблокирована до тех пор, пока транзакция не будет зафиксирована. По умолчанию 5 секунд.detect_types (int) – Контролирует, будут ли и как типы данных не natively supported by SQLite искаться для преобразования в типы Python, используя конвертеры, зарегистрированные в
register_converter()
. Установите любое сочетание (с помощью|
, побитового или)PARSE_DECLTYPES
иPARSE_COLNAMES
, чтобы включить это. Имена столбцов имеют приоритет над объявленными типами, если установлены оба флага. Типы не могут быть определены для сгенерированных полей (например,max(data)
), даже если установлен параметр detect_types; вместо него будет возвращено значение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
должен внутренне кэшировать для этого соединения, чтобы избежать накладных расходов на разбор. По умолчанию 128 утверждений.uri (bool) – Если установлено значение
True
, database интерпретируется как URI с путем к файлу и необязательной строкой запроса. Часть схемы обязательно должна быть"file:"
, а путь может быть относительным или абсолютным. Строка запроса позволяет передавать SQLite параметры, позволяющие использовать различные Как работать с URI SQLite.autocommit (bool) – Управление поведением PEP 249 при обработке транзакций. Дополнительные сведения см. в разделах
Connection.autocommit
и Управление транзакциями с помощью атрибута autocommit. autocommit в настоящее время имеет значение по умолчаниюLEGACY_TRANSACTION_CONTROL
. Значение по умолчанию будет изменено наFalse
в одном из будущих выпусков Python.
- Тип результата:
Поднимает auditing event
sqlite3.connect
с аргументомdatabase
.Поднимает auditing event
sqlite3.connect/handle
с аргументомconnection_handle
.Изменено в версии 3.4: Добавлен параметр uri.
Изменено в версии 3.7: Теперь база данных может быть не только строкой, но и path-like object.
Изменено в версии 3.10: Добавлено событие аудита
sqlite3.connect/handle
.Изменено в версии 3.12: Добавлен параметр autocommit.
Изменено в версии 3.13: Позиционное использование параметров timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements и uri устарело. В Python 3.15 они станут параметрами только для ключевых слов.
- sqlite3.complete_statement(statement)¶
Возвращает
True
, если строка statement содержит один или несколько полных операторов SQL. Никакой синтаксической проверки или синтаксического разбора не выполняется, кроме проверки отсутствия незакрытых строковых литералов и завершения утверждения точкой с запятой.Например:
>>> sqlite3.complete_statement("SELECT foo FROM bar;") True >>> sqlite3.complete_statement("SELECT foo") False
Эта функция может быть полезна при вводе командной строки, чтобы определить, кажется ли введенный текст полным SQL-оператором, или если требуется дополнительный ввод перед вызовом
execute()
.Смотрите
runsource()
в Lib/sqlite3/__main__.py для реального использования.
- sqlite3.enable_callback_tracebacks(flag, /)¶
Включите или отключите отслеживание обратных вызовов. По умолчанию вы не получите никаких обратных трассировок в пользовательских функциях, агрегатах, конвертерах, обратных вызовах авторизаторов и т. д. Если вы хотите отладить их, вы можете вызвать эту функцию с flag, установленным в
True
. После этого вы получите трассировку обратных вызовов наsys.stderr
. ИспользуйтеFalse
, чтобы снова отключить эту функцию.Примечание
Ошибки в обратных вызовах пользовательских функций регистрируются как невыводимые исключения. Используйте
unraisable hook handler
для интроспекции неудачного обратного вызова.
- sqlite3.register_adapter(type, adapter, /)¶
Зарегистрируйте адаптер callable для адаптации типа Python type в тип SQLite. Адаптер вызывается с объектом Python типа type в качестве единственного аргумента и должен возвращать значение type that SQLite natively understands.
- sqlite3.register_converter(typename, converter, /)¶
Зарегистрируйте конвертер callable для преобразования объектов SQLite типа typename в объект Python определенного типа. Конвертер вызывается для всех значений SQLite типа typename; ему передается объект
bytes
, и он должен вернуть объект нужного типа Python. Обратитесь к параметру detect_types изconnect()
для получения информации о том, как работает определение типов.Примечание: typename и имя типа в вашем запросе сопоставляются без учета регистра.
Константы модуля¶
- sqlite3.LEGACY_TRANSACTION_CONTROL¶
Установите значение
autocommit
для этой константы, чтобы выбрать старый стиль (до Python 3.12) поведения управления транзакциями. Более подробную информацию см. в разделе Управление транзакциями с помощью атрибута isolation_level.
- sqlite3.PARSE_COLNAMES¶
Передайте это значение флага параметру detect_types из
connect()
, чтобы найти функцию конвертера, используя имя типа, разобранное из имени столбца запроса, в качестве ключа словаря конвертеров. Имя типа должно быть заключено в квадратные скобки ([]
).SELECT p as "p [point]" FROM test; ! will look up converter "point"
Этот флаг может быть объединен с
PARSE_DECLTYPES
с помощью оператора|
(побитовое или).
- sqlite3.PARSE_DECLTYPES¶
Передайте значение этого флага параметру detect_types из
connect()
, чтобы найти функцию преобразования, используя объявленные типы для каждого столбца. Типы объявляются при создании таблицы базы данных.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¶
Флаги, которые должны быть возвращены authorizer_callback callable, переданным в
Connection.set_authorizer()
, чтобы указать, является ли:Доступ разрешен (
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.threadsafety¶
Целочисленная константа, требуемая DB-API 2.0 и указывающая уровень безопасности потоков, поддерживаемый модулем
sqlite3
. Этот атрибут устанавливается на основе threading mode, с которым по умолчанию скомпилирована базовая библиотека SQLite. Режимы потокобезопасности SQLite следующие:Однопоточный: В этом режиме все мьютексы отключены, и SQLite небезопасно использовать более чем в одном потоке одновременно.
Многопоточный: В этом режиме SQLite может безопасно использоваться несколькими потоками при условии, что ни одно соединение с базой данных не используется одновременно в двух или более потоках.
Сериализованный: В режиме сериализации SQLite может безопасно использоваться несколькими потоками без каких-либо ограничений.
Сопоставление потоковых режимов SQLite с уровнями потокобезопасности DB-API 2.0 выглядит следующим образом:
Потоковый режим работы SQLite
Значение DB-API 2.0
однопоточный
0
0
Нити не могут совместно использовать модуль
многопоточный
1
2
Нити могут совместно использовать модуль, но не соединения
сериализованный
3
1
Потоки могут совместно использовать модуль, соединения и курсоры
Изменено в версии 3.11: Установите threadsafety динамически, вместо того чтобы жестко кодировать его в
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¶
Эти константы используются для методов
Connection.setconfig()
иgetconfig()
.Наличие этих констант зависит от версии SQLite, с которой был скомпилирован Python.
Added in version 3.12.
См.также
- https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
Документация по SQLite: Параметры конфигурации подключения к базе данных
Утратил актуальность с версии 3.12, удален в версии 3.14: Константы version
и version_info
.
Объекты подключения¶
- class sqlite3.Connection¶
Каждая открытая база данных SQLite представлена объектом
Connection
, который создается с помощьюsqlite3.connect()
. Их основное назначение - создание объектовCursor
и Контроль транзакций.См.также
Изменено в версии 3.13: Если
close()
не вызывается до удаления объектаConnection
, выдается сообщениеResourceWarning
.Соединение с базой данных SQLite имеет следующие атрибуты и методы:
- cursor(factory=Cursor)¶
Создает и возвращает объект
Cursor
. Метод cursor принимает один необязательный параметр factory. Если он задан, то это должен быть callable, возвращающий экземплярCursor
или его подклассов.
- blobopen(table, column, row, /, *, readonly=False, name='main')¶
Откройте хэндл
Blob
для существующего BLOB.- Параметры:
table (str) – Имя таблицы, в которой находится шарик.
column (str) – Имя столбца, в котором находится шарик.
row (str) – Имя строки, в которой находится шарик.
readonly (bool) – Установите значение
True
, если блоб должен быть открыт без прав на запись. По умолчанию установлено значениеFalse
.name (str) – Имя базы данных, в которой находится блоб. По умолчанию
"main"
.
- Исключение:
OperationalError – При попытке открыть шарик в таблице
WITHOUT ROWID
.- Тип результата:
Примечание
Размер блоба нельзя изменить с помощью класса
Blob
. Для создания блоба с фиксированным размером используйте SQL-функциюzeroblob
.Added in version 3.11.
- commit()¶
Зафиксируйте любую ожидающую транзакцию в базе данных. Если
autocommit
равноTrue
, или нет открытой транзакции, этот метод ничего не делает. Еслиautocommit
равноFalse
, то неявно открывается новая транзакция, если отложенная транзакция была зафиксирована этим методом.
- rollback()¶
Откат к началу любой отложенной транзакции. Если
autocommit
равноTrue
, или нет открытой транзакции, этот метод ничего не делает. Еслиautocommit
равноFalse
, то неявно открывается новая транзакция, если отложенная транзакция была откачена этим методом.
- close()¶
Закрыть соединение с базой данных. Если
autocommit
равноFalse
, любая ожидающая транзакция неявно откатывается. Еслиautocommit
равноTrue
илиLEGACY_TRANSACTION_CONTROL
, неявное управление транзакциями не выполняется. Убедитесь, чтоcommit()
установлен перед закрытием, чтобы избежать потери ожидающих изменений.
- execute(sql, parameters=(), /)¶
Создайте новый объект
Cursor
и вызовите на немexecute()
с заданными sql и параметрами. Верните новый объект курсора.
- executemany(sql, parameters, /)¶
Создайте новый объект
Cursor
и вызовите на немexecutemany()
с заданными sql и параметрами. Верните новый объект курсора.
- executescript(sql_script, /)¶
Создайте новый объект
Cursor
и вызовите на немexecutescript()
с заданным sql_script. Верните новый объект курсора.
- create_function(name, narg, func, *, deterministic=False)¶
Создайте или удалите пользовательскую функцию SQL.
- Параметры:
name (str) – Имя функции SQL.
narg (int) – Количество аргументов, которые может принимать функция SQL. Если
-1
, то она может принимать любое количество аргументов.func (callback | None) – Вызываемый callable, который вызывается при вызове функции SQL. Вызываемая функция должна возвращать a type natively supported by SQLite. Установите значение
None
, чтобы удалить существующую SQL-функцию.deterministic (bool) – Если
True
, то созданная SQL-функция помечается как deterministic, что позволяет SQLite выполнять дополнительные оптимизации.
Изменено в версии 3.8: Добавлен параметр детерминированный.
Пример:
>>> 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',) >>> con.close()
Изменено в версии 3.13: Передача name, narg и func в качестве аргументов ключевых слов устарела. В Python 3.15 эти параметры станут только позиционными.
- create_aggregate(name, n_arg, aggregate_class)¶
Создайте или удалите пользовательскую агрегатную функцию SQL.
- Параметры:
name (str) – Имя агрегатной функции SQL.
n_arg (int) – Количество аргументов, которые может принимать агрегатная функция SQL. Если
-1
, то она может принимать любое количество аргументов.aggregate_class (class | None) – Класс должен реализовывать следующие методы: *
step()
: Добавить строку в агрегат. *finalize()
: Возвращает конечный результат агрегата в виде a type natively supported by SQLite. Количество аргументов, которые должен принимать методstep()
, контролируется параметром n_arg. Установите значениеNone
, чтобы удалить существующую агрегатную функцию SQL.
Пример:
class MySum: def __init__(self): self.count = 0 def step(self, value): self.count += value def finalize(self): return self.count con = sqlite3.connect(":memory:") con.create_aggregate("mysum", 1, MySum) cur = con.execute("CREATE TABLE test(i)") cur.execute("INSERT INTO test(i) VALUES(1)") cur.execute("INSERT INTO test(i) VALUES(2)") cur.execute("SELECT mysum(i) FROM test") print(cur.fetchone()[0]) con.close()
Изменено в версии 3.13: Передача name, n_arg и aggregate_class в качестве аргументов ключевых слов устарела. В Python 3.15 эти параметры станут только позиционными.
- create_window_function(name, num_params, aggregate_class, /)¶
Создайте или удалите пользовательскую функцию агрегатного окна.
- Параметры:
name (str) – Имя функции окна агрегата SQL для создания или удаления.
num_params (int) – Количество аргументов, которые может принимать функция окна агрегата SQL. Если
-1
, то она может принимать любое количество аргументов.aggregate_class (class | None) – Класс, который должен реализовывать следующие методы: *
step()
: Добавить строку в текущее окно. *value()
: Возвращает текущее значение агрегата. *inverse()
: Удалить строку из текущего окна. *finalize()
: Возвращает конечный результат агрегата в виде a type natively supported by SQLite. Количество аргументов, которые должны принимать методыstep()
иvalue()
, контролируется параметром num_params. Установите значениеNone
, чтобы удалить существующую оконную функцию агрегата SQL.
- Исключение:
NotSupportedError – Если используется с версией SQLite старше 3.25.0, которая не поддерживает агрегатные оконные функции.
Added in version 3.11.
Пример:
# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc class WindowSumInt: def __init__(self): self.count = 0 def step(self, value): """Add a row to the current window.""" self.count += value def value(self): """Return the current value of the aggregate.""" return self.count def inverse(self, value): """Remove a row from the current window.""" self.count -= value def finalize(self): """Return the final value of the aggregate. Any clean-up actions should be placed here. """ return self.count con = sqlite3.connect(":memory:") cur = con.execute("CREATE TABLE test(x, y)") values = [ ("a", 4), ("b", 5), ("c", 3), ("d", 8), ("e", 1), ] cur.executemany("INSERT INTO test VALUES(?, ?)", values) con.create_window_function("sumint", 1, WindowSumInt) cur.execute(""" SELECT x, sumint(y) OVER ( ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING ) AS sum_y FROM test ORDER BY x """) print(cur.fetchall()) con.close()
- create_collation(name, callable, /)¶
Создайте коллацию с именем name с помощью функции коллации callable. callable передается два аргумента
string
, и она должна вернутьinteger
:1
, если первое упорядочено выше, чем второе-1
, если первое упорядочено ниже, чем второе0
, если они упорядочены поровну.
В следующем примере показана сортировка с обратной сортировкой:
def collate_reverse(string1, string2): if string1 == string2: return 0 elif string1 < string2: return 1 else: return -1 con = sqlite3.connect(":memory:") con.create_collation("reverse", collate_reverse) cur = con.execute("CREATE TABLE test(x)") cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)]) cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse") for row in cur: print(row) con.close()
Удалите функцию collation, установив значение callable в
None
.Изменено в версии 3.11: Имя collation может содержать любой символ Unicode. Ранее допускались только символы ASCII.
- interrupt()¶
Вызовите этот метод из другого потока, чтобы прервать все запросы, которые могут выполняться на соединении. Прерванные запросы вызовут сообщение
OperationalError
.
- set_authorizer(authorizer_callback)¶
Зарегистрируйте callable authorizer_callback, который будет вызываться при каждой попытке доступа к столбцу таблицы в базе данных. Обратный вызов должен возвращать одно из
SQLITE_OK
,SQLITE_DENY
илиSQLITE_IGNORE
, чтобы сигнализировать о том, как доступ к столбцу должен обрабатываться базовой библиотекой SQLite.Первый аргумент обратного вызова указывает, какая операция должна быть авторизована. Второй и третий аргументы будут аргументами или
None
в зависимости от первого аргумента. Четвертый аргумент - это имя базы данных («main», «temp» и т. д.), если это применимо. 5-й аргумент - это имя внутреннего триггера или представления, которое отвечает за попытку доступа, илиNone
, если попытка доступа происходит непосредственно из входного SQL-кода.О возможных значениях первого аргумента, а также о значении второго и третьего аргументов в зависимости от первого читайте в документации SQLite. Все необходимые константы доступны в модуле
sqlite3
.Передача
None
в качестве authorizer_callback отключит авторизатор.Изменено в версии 3.11: Добавлена поддержка отключения авторизатора с помощью
None
.Изменено в версии 3.13: Передача authorizer_callback в качестве аргумента ключевого слова устарела. В Python 3.15 этот параметр станет только позиционным.
- set_progress_handler(progress_handler, n)¶
Зарегистрируйте callable progress_handler, который будет вызываться для каждой n инструкции виртуальной машины SQLite. Это полезно, если вы хотите получать вызовы от SQLite во время длительных операций, например, для обновления графического интерфейса.
Если вы хотите очистить любой ранее установленный обработчик выполнения, вызовите метод с
None
для progress_handler.Возврат ненулевого значения из функции-обработчика прервет текущий выполняющийся запрос и вызовет исключение
DatabaseError
.Изменено в версии 3.13: Передача progress_handler в качестве аргумента ключевого слова устарела. В Python 3.15 этот параметр станет только позиционным.
- set_trace_callback(trace_callback)¶
Зарегистрируйте callable trace_callback, который будет вызываться для каждого SQL-оператора, фактически выполняемого бэкендом SQLite.
Единственным аргументом, передаваемым обратному вызову, является выполняемый оператор (как
str
). Возвращаемое значение обратного вызова игнорируется. Обратите внимание, что бэкэнд выполняет не только утверждения, переданные методамCursor.execute()
. К другим источникам относятся transaction management модуляsqlite3
и выполнение триггеров, определенных в текущей базе данных.Передача
None
в качестве trace_callback отключит обратный вызов трассировки.Примечание
Исключения, вызванные в обратном вызове трассировки, не распространяются. В качестве помощи при разработке и отладке используйте
enable_callback_tracebacks()
, чтобы включить печать трассировки исключений, поднятых в обратном вызове трассировки.Added in version 3.3.
Изменено в версии 3.13: Передача trace_callback в качестве аргумента ключевого слова устарела. В Python 3.15 этот параметр станет только позиционным.
- enable_load_extension(enabled, /)¶
Разрешите движку SQLite загружать расширения SQLite из общих библиотек, если значение enabled равно
True
; в противном случае запретите загрузку расширений SQLite. Расширения SQLite могут определять новые функции, агрегаты или совершенно новые реализации виртуальных таблиц. Одним из известных расширений является расширение полнотекстового поиска, распространяемое вместе с SQLite.Примечание
Модуль
sqlite3
по умолчанию не собирается с поддержкой загружаемых расширений, поскольку на некоторых платформах (в частности, на macOS) библиотеки SQLite компилируются без этой функции. Чтобы получить поддержку загружаемых расширений, вы должны передать опцию--enable-loadable-sqlite-extensions
в configure.Поднимает auditing event
sqlite3.enable_load_extension
с аргументамиconnection
,enabled
.Added in version 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)
- load_extension(path, /, *, entrypoint=None)¶
Загрузка расширения SQLite из общей библиотеки. Включите загрузку расширения с помощью
enable_load_extension()
перед вызовом этого метода.- Параметры:
path (str) – Путь к расширению SQLite.
entrypoint (str | None) – Имя точки входа. Если
None
(по умолчанию), SQLite придумает собственное имя точки входа; подробности см. в документации SQLite Loading an Extension.
Поднимает auditing event
sqlite3.load_extension
с аргументамиconnection
,path
.Added in version 3.2.
Изменено в версии 3.10: Добавлено событие аудита
sqlite3.load_extension
.Изменено в версии 3.12: Добавлен параметр entrypoint.
- iterdump(*, filter=None)¶
Возвращает значение iterator для дампа базы данных в виде исходного кода SQL. Полезно при сохранении базы данных в памяти для последующего восстановления. Аналогично команде
.dump
в оболочке sqlite3.- Параметры:
filter (str | None) – Необязательный шаблон
LIKE
для объектов базы данных для дампа, напримерprefix_%
. ЕслиNone
(по умолчанию), то будут включены все объекты базы данных.
Пример:
# 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()
Изменено в версии 3.13: Добавлен параметр фильтр.
- backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)¶
Создайте резервную копию базы данных SQLite.
Работает, даже если к базе данных обращаются другие клиенты или одновременно по одному и тому же соединению.
- Параметры:
target (Connection) – Соединение с базой данных для сохранения резервной копии.
pages (int) – Количество страниц, копируемых за один раз. Если оно равно или меньше
0
, вся база данных копируется за один шаг. По умолчанию-1
.progress (callback | None) – Если установлено значение callable, то для каждой итерации резервного копирования вызывается с тремя целочисленными аргументами: статус последней итерации, оставшееся количество страниц, которые еще предстоит скопировать, и общее количество страниц. По умолчанию
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) dst.close() src.close()
Added in version 3.7.
- getlimit(category, /)¶
Получение ограничения времени выполнения соединения.
- Параметры:
category (int) – Запрашиваемый SQLite limit category.
- Тип результата:
- Исключение:
ProgrammingError – Если category не распознается базовой библиотекой SQLite.
Пример, запрос максимальной длины SQL-оператора для
Connection
con
(по умолчанию 1000000000):>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH) 1000000000
Added in version 3.11.
- setlimit(category, limit, /)¶
Устанавливает ограничение времени выполнения соединения. Попытки увеличить лимит выше его жесткой верхней границы молча обрезаются до жесткой верхней границы. Независимо от того, был ли изменен лимит, возвращается предыдущее значение лимита.
- Параметры:
category (int) – Устанавливаемое значение SQLite limit category.
limit (int) – Значение нового предела. Если отрицательно, то текущий предел не изменяется.
- Тип результата:
- Исключение:
ProgrammingError – Если category не распознается базовой библиотекой SQLite.
Например, ограничьте количество подключенных баз данных до 1 для
Connection
con
(по умолчанию ограничение равно 10):>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1) 10 >>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED) 1
Added in version 3.11.
- getconfig(op, /)¶
Запрос булевого параметра конфигурации соединения.
- Параметры:
op (int) – A SQLITE_DBCONFIG code.
- Тип результата:
Added in version 3.12.
- setconfig(op, enable=True, /)¶
Установка булевого параметра конфигурации соединения.
- Параметры:
op (int) – A SQLITE_DBCONFIG code.
enable (bool) –
True
, если опция конфигурации должна быть включена (по умолчанию);False
, если она должна быть отключена.
Added in version 3.12.
- serialize(*, name='main')¶
Сериализация базы данных в объект
bytes
. Для обычного файла базы данных на диске сериализация - это просто копия дискового файла. Для базы данных в памяти или «временной» базы данных сериализация представляет собой ту же последовательность байтов, которая была бы записана на диск при резервном копировании этой базы данных на диск.- Параметры:
name (str) – Имя базы данных, подлежащее сериализации. По умолчанию
"main"
.- Тип результата:
Примечание
Этот метод доступен только в том случае, если базовая библиотека SQLite имеет API serialize.
Added in version 3.11.
- deserialize(data, /, *, name='main')¶
Десериализация базы данных
serialized
в базу данныхConnection
. Этот метод заставляет соединение базы данных отсоединиться от базы данных name и снова открыть name как базу данных в памяти на основе сериализации, содержащейся в data.- Параметры:
- Исключение:
OperationalError – Если соединение с базой данных в данный момент участвует в транзакции чтения или операции резервного копирования.
DatabaseError – Если data не содержит действительной базы данных SQLite.
OverflowError – Если
len(data)
больше, чем2**63 - 1
.
Примечание
Этот метод доступен только в том случае, если базовая библиотека SQLite имеет API десериализации.
Added in version 3.11.
- autocommit¶
Этот атрибут управляет поведением транзакций, соответствующих стандарту PEP 249.
autocommit
имеет три допустимых значения:False
: Выберите поведение транзакции, соответствующее PEP 249, подразумевая, чтоsqlite3
гарантирует, что транзакция всегда открыта. Для закрытия транзакций используйтеcommit()
иrollback()
.Рекомендуемое значение
autocommit
.True
: Используйте autocommit mode SQLite.commit()
иrollback()
в этом режиме не действуют.LEGACY_TRANSACTION_CONTROL
: Управление транзакциями в версии до Python 3.12 (не:pep:249-совместимой). Более подробную информацию см. в разделеisolation_level
.В настоящее время по умолчанию это значение
autocommit
.
Изменение
autocommit
наFalse
откроет новую транзакцию, а изменение наTrue
зафиксирует любую ожидающую транзакцию.Более подробную информацию см. в разделе Управление транзакциями с помощью атрибута autocommit.
Примечание
Атрибут
isolation_level
не влияет, еслиautocommit
не равенLEGACY_TRANSACTION_CONTROL
.Added in version 3.12.
- in_transaction¶
Этот атрибут, доступный только для чтения, соответствует низкоуровневому атрибуту SQLite autocommit mode.
True
, если транзакция активна (есть незафиксированные изменения),False
в противном случае.Added in version 3.2.
- isolation_level¶
Управляет legacy transaction handling mode из
sqlite3
. Если установлено значениеNone
, транзакции никогда не открываются неявно. Если установлено одно из"DEFERRED"
,"IMMEDIATE"
или"EXCLUSIVE"
, то выполняются транзакции, соответствующие базовым SQLite transaction behaviour, implicit transaction management.Если параметр isolation_level не переопределен параметром
connect()
, по умолчанию используется значение""
, которое является псевдонимом для"DEFERRED"
.Примечание
Использование
autocommit
для управления обработкой транзакций рекомендуется вместо использованияisolation_level
.isolation_level
не имеет никакого эффекта, если дляautocommit
не установлено значениеLEGACY_TRANSACTION_CONTROL
(по умолчанию).
- row_factory¶
Начальный
row_factory
дляCursor
объектов, созданных на основе этого соединения. Присвоение этого атрибута не влияет наrow_factory
существующих курсоров, принадлежащих этому соединению, только на новые. По умолчанию имеет значениеNone
, что означает, что каждая строка возвращается в видеtuple
.Более подробную информацию см. в разделе Как создавать и использовать фабрики рядов.
- text_factory¶
Вызываемый модуль callable, который принимает параметр
bytes
и возвращает его текстовое представление. Вызывается для значений SQLite с типом данныхTEXT
. По умолчанию этот атрибут имеет значениеstr
.Более подробную информацию см. в разделе Как работать с текстовыми кодировками, отличными отUTF-8.
- total_changes¶
Возвращает общее количество строк базы данных, которые были изменены, вставлены или удалены с момента открытия соединения с базой данных.
Объекты курсора¶
Объект
Cursor
представляет собой database cursor, который используется для выполнения SQL-запросов и управления контекстом операции выборки. Курсоры создаются с помощьюConnection.cursor()
или с помощью любого из connection shortcut methods.Объекты курсора являются iterators, что означает, что если вы
execute()
сделаетеSELECT
запрос, вы можете просто выполнить итерацию над курсором, чтобы получить результирующие строки:for row in cur.execute("SELECT t FROM data"): print(row)
- class sqlite3.Cursor¶
Экземпляр
Cursor
имеет следующие атрибуты и методы.- execute(sql, parameters=(), /)¶
Выполните один SQL-оператор, по желанию связав значения Python с помощью placeholders.
- Параметры:
sql (str) – Один оператор SQL.
parameters (
dict
| sequence) – Значения Python для привязки к плейсхолдерам в sql. Символdict
, если используются именованные плейсхолдеры. Значение sequence, если используются неименованные плейсхолдеры. См. Как использовать заполнители для привязки значений в SQL-запросах.
- Исключение:
ProgrammingError – Если sql содержит более одного оператора SQL.
Если
autocommit
равноLEGACY_TRANSACTION_CONTROL
,isolation_level
не равноNone
, sql - это операторINSERT
,UPDATE
,DELETE
илиREPLACE
, и нет открытой транзакции, то перед выполнением sql транзакция неявно открывается.Утратил актуальность с версии 3.12, удален в версии 3.14:
DeprecationWarning
выдается, если используется named placeholders и параметры являются последовательностью, а неdict
. Начиная с Python 3.14, вместо этого будет выдаватьсяProgrammingError
.Используйте
executescript()
для выполнения нескольких операторов SQL.
- executemany(sql, parameters, /)¶
Для каждого элемента в параметрах повторно выполните команду parameterized DML SQL-оператор sql.
Использует ту же неявную обработку транзакций, что и
execute()
.- Параметры:
sql (str) – Один оператор SQL DML.
parameters (iterable) – iterable параметров для связывания с плейсхолдерами в sql. См. Как использовать заполнители для привязки значений в SQL-запросах.
- Исключение:
ProgrammingError – Если sql содержит более одного оператора SQL или не является оператором DML.
Пример:
rows = [ ("row1",), ("row2",), ] # cur is an sqlite3.Cursor object cur.executemany("INSERT INTO data VALUES(?)", rows)
Примечание
Все результирующие строки отбрасываются, включая операторы DML с RETURNING clauses.
Утратил актуальность с версии 3.12, удален в версии 3.14:
DeprecationWarning
выдается, если используется named placeholders и элементы в параметрах являются последовательностями, а неdict
s. Начиная с Python 3.14, вместо этого будет выдаватьсяProgrammingError
.
- executescript(sql_script, /)¶
Выполните операторы SQL в sql_script. Если значение
autocommit
равноLEGACY_TRANSACTION_CONTROL
и существует ожидающая транзакция, сначала выполняется неявный операторCOMMIT
. Никакого другого неявного управления транзакциями не выполняется; любое управление транзакциями должно быть добавлено в sql_script.sql_script должен быть
string
.Пример:
# 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()¶
Закрывайте курсор сейчас (а не всякий раз, когда вызывается
__del__
).С этого момента курсор становится непригодным для использования; при попытке выполнить любую операцию с курсором будет вызвано исключение
ProgrammingError
.
- setinputsizes(sizes, /)¶
Требуется DB-API. Ничего не делает в
sqlite3
.
- setoutputsize(size, column=None, /)¶
Требуется DB-API. Ничего не делает в
sqlite3
.
- arraysize¶
Атрибут чтения/записи, который управляет количеством строк, возвращаемых
fetchmany()
. Значение по умолчанию равно 1, что означает, что за один вызов будет получен один ряд.
- connection¶
Атрибут, доступный только для чтения, который предоставляет базу данных SQLite
Connection
, принадлежащую курсору. ОбъектCursor
, созданный вызовомcon.cursor()
, будет иметь атрибутconnection
, который ссылается на con:>>> con = sqlite3.connect(":memory:") >>> cur = con.cursor() >>> cur.connection == con True >>> con.close()
- description¶
Атрибут, доступный только для чтения, который предоставляет имена столбцов последнего запроса. Чтобы сохранить совместимость с Python DB API, он возвращает 7 кортежей для каждого столбца, где последние шесть элементов каждого кортежа -
None
.Он устанавливается и для утверждений
SELECT
без совпадающих строк.
- lastrowid¶
Атрибут, доступный только для чтения, который предоставляет идентификатор последнего вставленного ряда. Он обновляется только после успешных операций
INSERT
илиREPLACE
с использованием методаexecute()
. Для других операторов, после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.По умолчанию принимает значение
Connection.row_factory
, установленное при созданииCursor
. Присвоение этого атрибута не влияет наConnection.row_factory
родительского соединения.Более подробную информацию см. в разделе Как создавать и использовать фабрики рядов.
Строковые объекты¶
- class sqlite3.Row¶
Экземпляр
Row
служит высокооптимизированнымrow_factory
для объектовConnection
. Он поддерживает итерацию, проверку на равенство,len()
и mapping доступ по имени и индексу столбца.Два объекта
Row
сравниваются между собой, если у них одинаковые имена столбцов и значения.Более подробную информацию см. в разделе Как создавать и использовать фабрики рядов.
- keys()¶
Верните
list
имен столбцов в видеstrings
. Сразу после запроса это первый член каждого кортежа вCursor.description
.
Изменено в версии 3.5: Добавлена поддержка нарезки.
Объекты-шарики¶
- class sqlite3.Blob¶
Added in version 3.11.
Экземпляр
Blob
- это file-like object, который может читать и записывать данные в SQLite BLOB. Вызовитеlen(blob)
, чтобы получить размер (количество байт) блоба. Используйте индексы и slices для прямого доступа к данным блоба.Используйте
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 blob blob[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!'" con.close()
- close()¶
Закройте шарик.
С этого момента блоб становится непригодным для использования. При попытке дальнейшей работы с блобом будет поднято исключение
Error
(или подкласс).
- read(length=-1, /)¶
Считывает length байт данных из блоба в текущей позиции смещения. Если достигнут конец блоба, будут возвращены данные до EOF. Если length не задано или отрицательно,
read()
будет считывать данные до конца блоба.
- write(data, /)¶
Запись данных в блоб по текущему смещению. Эта функция не может изменить длину блоба. Запись за конец блоба приведет к появлению
ValueError
.
- tell()¶
Возвращает текущую позицию доступа к блобу.
- seek(offset, origin=os.SEEK_SET, /)¶
Устанавливает текущую позицию доступа к блобу на offset. Аргумент origin по умолчанию принимает значение
os.SEEK_SET
(абсолютное позиционирование блоба). Другие значения для origin -os.SEEK_CUR
(поиск относительно текущей позиции) иos.SEEK_END
(поиск относительно конца блоба).
Объекты PrepareProtocol¶
- class sqlite3.PrepareProtocol¶
Единственное назначение типа PrepareProtocol - выступать в качестве протокола адаптации в стиле PEP 246 для объектов, которые могут adapt themselves превращаться в native SQLite types.
Исключения¶
Иерархия исключений определена DB-API 2.0 (PEP 249).
- exception sqlite3.Warning¶
В настоящее время это исключение не вызывается модулем
sqlite3
, но может быть вызвано приложениями, использующимиsqlite3
, например, если пользовательская функция усекает данные при вставке.Warning
является подклассомException
.
- exception sqlite3.Error¶
Базовый класс остальных исключений в этом модуле. Используйте его, чтобы перехватывать все ошибки одним единственным оператором
except
.Error
является подклассомException
.Если исключение возникло из библиотеки SQLite, к нему добавляются следующие два атрибута:
- sqlite_errorcode¶
Цифровой код ошибки из SQLite API
Added in version 3.11.
- sqlite_errorname¶
Символьное имя числового кода ошибки из SQLite API
Added in version 3.11.
- exception sqlite3.InterfaceError¶
Исключение, вызванное неправильным использованием низкоуровневого API SQLite C. Другими словами, если это исключение возникло, то это, вероятно, указывает на ошибку в модуле
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¶
Исключение, возникающее в случае, если метод или API базы данных не поддерживается базовой библиотекой SQLite. Например, установка deterministic в
True
вcreate_function()
, если базовая библиотека SQLite не поддерживает детерминированные функции.NotSupportedError
является подклассомDatabaseError
.
Типы SQLite и Python¶
SQLite нативно поддерживает следующие типы: NULL
, INTEGER
, REAL
, TEXT
, BLOB
.
Таким образом, следующие типы Python могут быть переданы в SQLite без каких-либо проблем:
Тип Python |
Тип SQLite |
---|---|
|
|
|
|
|
|
|
|
|
Так типы SQLite преобразуются в типы Python по умолчанию:
Тип SQLite |
Тип Python |
---|---|
|
|
|
|
|
|
|
зависит от |
|
Система типов модуля sqlite3
расширяема двумя способами: вы можете хранить дополнительные типы Python в базе данных SQLite с помощью object adapters, и вы можете позволить модулю sqlite3
преобразовывать типы SQLite в типы Python с помощью converters.
Адаптеры и конвертеры по умолчанию (устаревшие)¶
Примечание
Адаптеры и конвертеры по умолчанию устарели начиная с Python 3.12. Вместо этого используйте Рецепты адаптеров и преобразователей и подстраивайте их под свои нужды.
Устаревшие адаптеры и конвертеры по умолчанию состоят из:
Адаптер для передачи объектов
datetime.date
вstrings
в формате ISO 8601.Адаптер для преобразования объектов
datetime.datetime
в строки в формате ISO 8601.Конвертер для преобразования declared типов «дата» в объекты
datetime.date
.Конвертер объявленных типов «timestamp» в объекты
datetime.datetime
. Дробные части будут обрезаны до 6 цифр (точность микросекунды).
Примечание
Конвертер «timestamp» по умолчанию игнорирует смещения UTC в базе данных и всегда возвращает наивный объект datetime.datetime
. Чтобы сохранить смещения UTC в метках времени, либо оставьте конвертеры отключенными, либо зарегистрируйте конвертер с поддержкой смещений с помощью register_converter()
.
Не рекомендуется, начиная с версии 3.12.
Интерфейс командной строки¶
Модуль sqlite3
можно вызвать как скрипт, используя переключатель -m
интерпретатора, чтобы создать простую оболочку SQLite. Подпись аргументов выглядит следующим образом:
python -m sqlite3 [-h] [-v] [filename] [sql]
Введите .quit
или CTRL-D, чтобы выйти из оболочки.
- -h, --help¶
Печать справки CLI.
- -v, --version¶
Выведите версию базовой библиотеки SQLite.
Added in version 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. Чтобы вставить переменную в строку запроса, используйте в ней заполнитель, а фактические значения подставьте в запрос, предоставив их в виде tuple
значений второму аргументу метода execute()
курсора.
В операторе SQL может использоваться один из двух видов заполнителей: вопросительные знаки (стиль qmark) или именованные заполнители (стиль named). Для стиля qmark, параметры должны быть элементом 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())
con.close()
Примечание
PEP 249 числовые заполнители не поддерживаются. Если они используются, то интерпретируются как именованные.
Как адаптировать пользовательские типы Python к значениям SQLite¶
SQLite поддерживает только ограниченный набор типов данных. Чтобы хранить пользовательские типы Python в базах данных SQLite, адаптируйте их к одному из Python types SQLite natively understands.
Есть два способа адаптировать объекты Python к типам SQLite: позволить объекту адаптироваться самому или использовать адаптер, вызываемый. Последний вариант будет иметь приоритет над первым. Для библиотеки, экспортирующей пользовательский тип, может иметь смысл позволить этому типу адаптироваться самостоятельно. Разработчику приложения, возможно, имеет смысл взять управление в свои руки, зарегистрировав пользовательские функции адаптера.
Как писать адаптируемые объекты¶
Предположим, у нас есть класс Point
, который представляет пару координат, x
и y
, в декартовой системе координат. Пара координат будет храниться в базе данных в виде текстовой строки с использованием точки с запятой для разделения координат. Это можно реализовать, добавив метод __conform__(self, protocol)
, который возвращает адаптированное значение. Объект, передаваемый в protocol, будет иметь тип PrepareProtocol
.
class Point:
def __init__(self, x, y):
self.x, self.y = x, y
def __conform__(self, protocol):
if protocol is sqlite3.PrepareProtocol:
return f"{self.x};{self.y}"
con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()
Как зарегистрировать адаптер callables¶
Другая возможность - создать функцию, которая преобразует объект Python к типу, совместимому с SQLite. Эту функцию можно зарегистрировать с помощью register_adapter()
.
class Point:
def __init__(self, x, y):
self.x, self.y = x, y
def adapt_point(point):
return f"{point.x};{point.y}"
sqlite3.register_adapter(Point, adapt_point)
con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()
Как преобразовать значения SQLite в пользовательские типы Python¶
Написание адаптера позволяет конвертировать из пользовательских типов Python в значения SQLite. Чтобы иметь возможность конвертировать из значений SQLite в пользовательские типы Python, мы используем конвертеры.
Давайте вернемся к классу Point
. Мы сохранили координаты x и y, разделенные точками с запятой, в виде строк в SQLite.
Сначала мы определим функцию-конвертер, которая принимает строку в качестве параметра и строит из нее объект Point
.
Примечание
Функции конвертера всегда передается объект bytes
, независимо от типа данных, лежащих в основе SQLite.
def convert_point(s):
x, y = map(float, s.split(b";"))
return Point(x, y)
Теперь нам нужно указать sqlite3
, когда он должен преобразовать заданное значение SQLite. Это делается при подключении к базе данных с помощью параметра detect_types в connect()
. Есть три варианта:
Неявно: установите detect_types в
PARSE_DECLTYPES
.Явное: установить detect_types в
PARSE_COLNAMES
.Оба: установите detect_types в
sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES
. Имена столбцов имеют приоритет над объявленными типами.
Следующий пример иллюстрирует неявный и явный подходы:
class Point:
def __init__(self, x, y):
self.x, self.y = x, y
def __repr__(self):
return f"Point({self.x}, {self.y})"
def adapt_point(point):
return f"{point.x};{point.y}"
def convert_point(s):
x, y = list(map(float, s.split(b";")))
return Point(x, y)
# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)
# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")
cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()
# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")
cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()
Рецепты адаптеров и преобразователей¶
В этом разделе приведены рецепты для распространенных адаптеров и конвертеров.
import datetime
import sqlite3
def adapt_date_iso(val):
"""Adapt datetime.date to ISO 8601 date."""
return val.isoformat()
def adapt_datetime_iso(val):
"""Adapt datetime.datetime to timezone-naive ISO 8601 date."""
return val.isoformat()
def adapt_datetime_epoch(val):
"""Adapt datetime.datetime to Unix timestamp."""
return int(val.timestamp())
sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)
def convert_date(val):
"""Convert ISO 8601 date to datetime.date object."""
return datetime.date.fromisoformat(val.decode())
def convert_datetime(val):
"""Convert ISO 8601 datetime to datetime.datetime object."""
return datetime.datetime.fromisoformat(val.decode())
def convert_timestamp(val):
"""Convert Unix epoch timestamp to datetime.datetime object."""
return datetime.datetime.fromtimestamp(int(val))
sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)
Как использовать методы быстрого подключения¶
Используя методы execute()
, executemany()
и executescript()
класса Connection
, ваш код можно написать более лаконично, поскольку вам не нужно явно создавать (часто лишние) объекты Cursor
. Вместо этого объекты Cursor
создаются неявно, а эти методы быстрого доступа возвращают объекты курсора. Таким образом, вы можете выполнить оператор SELECT
и выполнить итерацию по нему напрямую, используя только один вызов объекта Connection
.
# 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()
Как работать с URI SQLite¶
Некоторые полезные трюки с 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
Создайте общую именованную базу данных in-memory:
db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
con1.execute("CREATE TABLE shared(data)")
con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)
con1.close()
con2.close()
Более подробную информацию об этой функции, включая список параметров, можно найти в разделе SQLite URI documentation.
Как создавать и использовать фабрики рядов¶
По умолчанию sqlite3
представляет каждую строку как tuple
. Если tuple
не подходит для ваших нужд, вы можете использовать класс sqlite3.Row
или собственный row_factory
.
Хотя row_factory
существует как атрибут и для Cursor
, и для Connection
, рекомендуется установить Connection.row_factory
, чтобы все курсоры, созданные на основе соединения, использовали одну и ту же фабрику строк.
Row
обеспечивает именованный доступ к столбцам с индексацией и без учета регистра, с минимальными затратами памяти и производительностью по сравнению с tuple
. Чтобы использовать Row
в качестве фабрики строк, присвойте его атрибуту row_factory
:
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row
Запросы теперь возвращают объекты Row
:
>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0] # Access by index.
'Earth'
>>> row["name"] # Access by name.
'Earth'
>>> row["RADIUS"] # Column names are case-insensitive.
6378
>>> con.close()
Примечание
Клаузулу FROM
можно опустить в операторе SELECT
, как в примере выше. В таком случае SQLite возвращает одну строку со столбцами, заданными выражениями, например литералами, с заданными псевдонимами expr AS alias
.
Вы можете создать пользовательский row_factory
, который возвращает каждую строку как dict
, с именами столбцов, сопоставленными со значениями:
def dict_factory(cursor, row):
fields = [column[0] for column in cursor.description]
return {key: value for key, value in zip(fields, row)}
Используя его, запросы теперь возвращают dict
вместо tuple
:
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
... print(row)
{'a': 1, 'b': 2}
>>> con.close()
Следующая фабрика строк возвращает named tuple:
from collections import namedtuple
def namedtuple_factory(cursor, row):
fields = [column[0] for column in cursor.description]
cls = namedtuple("Row", fields)
return cls._make(row)
namedtuple_factory()
можно использовать следующим образом:
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0] # Indexed access.
1
>>> row.b # Attribute access.
2
>>> con.close()
С некоторыми изменениями приведенный выше рецепт может быть адаптирован для использования dataclass
или любого другого пользовательского класса вместо namedtuple
.
Как работать с текстовыми кодировками, отличными отUTF-8¶
По умолчанию sqlite3
использует str
для адаптации значений SQLite с типом данных TEXT
. Это хорошо работает для текста в кодировке UTF-8, но может привести к ошибке для других кодировок и недействительного UTF-8. Для обработки таких случаев можно использовать собственный text_factory
.
Из-за того, что в SQLite используется flexible typing, нередко можно встретить столбцы таблицы с типом данных TEXT
, содержащие кодировки, отличные отUTF-8, или даже произвольные данные. Чтобы продемонстрировать это, предположим, что у нас есть база данных с текстом в кодировке ISO-8859-2 (Latin-2), например, таблица чешско-английских словарных статей. Предполагая, что теперь у нас есть экземпляр Connection
con
, подключенный к этой базе данных, мы можем декодировать текст в кодировке Latin-2 с помощью этого text_factory
:
con.text_factory = lambda data: str(data, encoding="latin2")
Для недопустимых данных UTF-8 или произвольных данных, хранящихся в столбцах таблицы TEXT
, можно использовать следующую технику, заимствованную из Unicode HOWTO:
con.text_factory = lambda data: str(data, errors="surrogateescape")
Примечание
API модуля sqlite3
не поддерживает строки, содержащие суррогаты.
См.также
Пояснение¶
Контроль транзакций¶
sqlite3
предлагает несколько способов управления тем, как, когда и когда открываются и закрываются транзакции базы данных. Рекомендуется использовать Управление транзакциями с помощью атрибута autocommit, в то время как Управление транзакциями с помощью атрибута isolation_level сохраняет поведение, характерное для версии до Python 3.12.
Управление транзакциями с помощью атрибута autocommit
¶
Рекомендуемый способ управления поведением транзакций - атрибут Connection.autocommit
, который предпочтительно устанавливать с помощью параметра autocommit connect()
.
Рекомендуется установить autocommit на False
, что подразумевает PEP 249-совместимый контроль транзакций. Это означает:
sqlite3
гарантирует, что транзакция всегда открыта, поэтомуconnect()
,Connection.commit()
иConnection.rollback()
будут неявно открывать новую транзакцию (для двух последних - сразу после закрытия отложенной). Вsqlite3
при открытии транзакций используются операторыBEGIN DEFERRED
.Транзакции должны фиксироваться явно с помощью
commit()
.Транзакции должны быть откачены явным образом с помощью
rollback()
.Неявный откат выполняется, если в базе данных есть
close()
-е ожидающие изменения.
Установите autocommit в True
, чтобы включить autocommit mode SQLite. В этом режиме 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()
для фиксации и отката транзакций. Вы можете выбрать базовый SQLite transaction behaviour - то есть, будет ли BEGIN
неявно выполнять sqlite3
операторы и какого типа - с помощью атрибута isolation_level
.
Если для isolation_level
установлено значение None
, то неявное открытие транзакций вообще не производится. Это оставляет базовую библиотеку SQLite в режиме autocommit mode, но при этом позволяет пользователю выполнять собственную обработку транзакций с помощью явных операторов SQL. Режим автокоммита базовой библиотеки SQLite можно запросить с помощью атрибута in_transaction
.
Метод executescript()
неявно фиксирует все незавершенные транзакции перед выполнением данного SQL-сценария, независимо от значения isolation_level
.
Изменено в версии 3.6: sqlite3
раньше неявно фиксировала открытую транзакцию перед операторами DDL. Теперь это не так.
Изменено в версии 3.12: Рекомендуемый способ управления транзакциями теперь - через атрибут autocommit
.