sqlite3.md
1> **Источник:** https://python-all.ru/3.14/library/sqlite3.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `sqlite3` – интерфейс DB-API 2.0 для баз данных SQLite89**Исходный код:** [Lib/sqlite3/](https://python-all.ru/src/3.14/Lib/sqlite3)1011SQLite – это библиотека на C, которая предоставляет легковесную дисковую базу данных, не требующую отдельного серверного процесса, и позволяет обращаться к базе данных с помощью нестандартного варианта языка SQL. Некоторые приложения могут использовать SQLite для внутреннего хранения данных. Также можно создать прототип приложения на SQLite, а затем перенести код на более крупную базу данных, например PostgreSQL или Oracle.1213Модуль `sqlite3` написан Герхардом Хэрингом. Он предоставляет SQL-интерфейс, соответствующий спецификации DB-API 2.0, описанной в [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html), и требует стороннюю библиотеку [SQLite](https://python-all.ru/3.14/library/sqlite3.html).1415Это [опциональный модуль](https://python-all.ru/3.14/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3.14/using/configure.html#optional-module-requirements).1617Этот документ включает четыре основных раздела:1819- [Руководство](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-tutorial) рассказывает, как использовать модуль `sqlite3`.20- [Справочник](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-reference) описывает классы и функции, которые определяет этот модуль.21- [Практические руководства](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howtos) подробно описывают выполнение конкретных задач.22- [Пояснение](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-explanation) содержит углубленные сведения об управлении транзакциями.2324> **См. также**25>26> **[https://www.sqlite.org](https://python-all.ru/3.14/library/sqlite3.html)**27>28> Веб-страница SQLite; документация описывает синтаксис и доступные типы данных поддерживаемого диалекта SQL.29>30> **[https://www.w3schools.com/sql/](https://python-all.ru/3.14/library/sqlite3.html)**31>32> Учебные материалы, справочник и примеры для изучения синтаксиса SQL.33>34> **[**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html) – спецификация API баз данных 2.0**35>36> PEP написан Марком-Андре Лембургом.3738## Учебное руководство3940В этом руководстве вы создадите базу данных фильмов Монти Пайтона, используя базовые возможности `sqlite3`. Предполагается базовое понимание концепций баз данных, включая [курсоры](https://python-all.ru/3.14/library/sqlite3.html) и [транзакции](https://python-all.ru/3.14/library/sqlite3.html).4142Сначала нужно создать новую базу данных и открыть соединение с базой данных, чтобы `sqlite3` мог с ней работать. Вызовите [`sqlite3.connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect), чтобы создать соединение с базой данных `tutorial.db` в текущем рабочем каталоге; если она не существует, она будет неявно создана:4344```python45import sqlite346con = sqlite3.connect("tutorial.db")47```4849Возвращаемый объект [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection) `con` представляет соединение с базой данных на диске.5051Для выполнения SQL-запросов и получения результатов нужно использовать курсор базы данных. Вызовите [`con.cursor()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.cursor), чтобы создать [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor):5253```python54cur = con.cursor()55```5657Теперь, когда у нас есть соединение с базой данных и курсор, можно создать таблицу базы данных `movie` со столбцами для названия, года выпуска и оценки. Для простоты в объявлении таблицы можно использовать только имена столбцов – благодаря функции [гибкой типизации](https://python-all.ru/3.14/library/sqlite3.html) в SQLite указание типов данных необязательно. Выполните оператор `CREATE TABLE`, вызвав [`cur.execute(...)`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute):5859```python60cur.execute("CREATE TABLE movie(title, year, score)")61```6263Можно проверить, что новая таблица создана, запросив встроенную таблицу SQLite `sqlite_master`, в которой теперь должна быть запись для определения таблицы `movie` (подробнее см. [Схема таблицы](https://python-all.ru/3.14/library/sqlite3.html)). Выполните этот запрос, вызвав [`cur.execute(...)`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute), присвойте результат `res` и вызовите [`res.fetchone()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.fetchone) для получения строки результата:6465```pycon66>>> res = cur.execute("SELECT name FROM sqlite_master")67>>> res.fetchone()68('movie',)69```7071Мы видим, что таблица создана, так как запрос возвращает [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple), содержащий имя таблицы. Если запросить `sqlite_master` для несуществующей таблицы `spam`, `res.fetchone()` вернёт `None`:7273```pycon74>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")75>>> res.fetchone() is None76True77```7879Теперь добавьте две строки данных, заданные как SQL-литералы, выполнив оператор `INSERT`, снова вызвав [`cur.execute(...)`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute):8081```python82cur.execute("""83 INSERT INTO movie VALUES84 ('Monty Python and the Holy Grail', 1975, 8.2),85 ('And Now for Something Completely Different', 1971, 7.5)86""")87```8889Оператор `INSERT` неявно открывает транзакцию, которую нужно зафиксировать, прежде чем изменения будут сохранены в базе данных (подробнее см. [Управление транзакциями](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-controlling-transactions)). Вызовите [`con.commit()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.commit) у объекта соединения, чтобы зафиксировать транзакцию:9091```python92con.commit()93```9495Можно проверить, что данные вставлены правильно, выполнив запрос `SELECT`. Используйте уже знакомый [`cur.execute(...)`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute), чтобы присвоить результат `res`, и вызовите [`res.fetchall()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.fetchall), чтобы вернуть все строки результата:9697```pycon98>>> res = cur.execute("SELECT score FROM movie")99>>> res.fetchall()100[(8.2,), (7.5,)]101```102103Результат – это [`list`](https://python-all.ru/3.14/library/stdtypes.html#list) из двух `tuple`, по одному на строку, каждый содержит значение `score` этой строки.104105Теперь вставьте ещё три строки, вызвав [`cur.executemany(...)`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executemany):106107```python108data = [109 ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),110 ("Monty Python's The Meaning of Life", 1983, 7.5),111 ("Monty Python's Life of Brian", 1979, 8.0),112]113cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)114con.commit() # Необходимо зафиксировать транзакцию после выполнения INSERT.115```116117Обратите внимание, что используются местозаполнители `?` для привязки `data` к запросу. Всегда используйте местозаполнители вместо [форматирования строк](https://python-all.ru/3.14/tutorial/inputoutput.html#tut-formatting) для привязки значений Python к SQL-запросам, чтобы избежать [SQL-инъекций](https://python-all.ru/3.14/library/sqlite3.html) (подробнее см. [Как использовать местозаполнители для привязки значений в SQL-запросах](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders)).118119Можно проверить, что новые строки вставлены, выполнив запрос `SELECT`, на этот раз итерируя по результатам запроса:120121```pycon122>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):123... print(row)124(1971, 'And Now for Something Completely Different')125(1975, 'Monty Python and the Holy Grail')126(1979, "Monty Python's Life of Brian")127(1982, 'Monty Python Live at the Hollywood Bowl')128(1983, "Monty Python's The Meaning of Life")129```130131Каждая строка представляет собой [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple) из двух элементов `(year, title)`, соответствующих столбцам, выбранным в запросе.132133Наконец, проверьте, что база данных записана на диск, вызвав [`con.close()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.close), чтобы закрыть существующее соединение, открыть новое, создать новый курсор, а затем выполнить запрос к базе данных:134135```pycon136>>> con.close()137>>> new_con = sqlite3.connect("tutorial.db")138>>> new_cur = new_con.cursor()139>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")140>>> title, year = res.fetchone()141>>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')142The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975143>>> new_con.close()144```145146С помощью модуля `sqlite3` создана база данных SQLite, вставлены данные и извлечены из неё значения несколькими способами.147148> **См. также**149>150> - [Практические руководства](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howtos) для дальнейшего изучения:151>152> - [Как использовать плейсхолдеры для привязки значений в SQL-запросах](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders)153> - [Как адаптировать пользовательские типы Python к значениям SQLite](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-adapters)154> - [Как преобразовывать значения SQLite в пользовательские типы Python](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-converters)155> - [Как использовать контекстный менеджер соединения](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-connection-context-manager)156> - [Как создавать и использовать фабрики строк](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howto-row-factory)157> - [Объяснение](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-explanation) для углублённого изучения управления транзакциями.158159## Ссылка160161### Функции модуля162163#### `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)`164165Открывает соединение с базой данных SQLite.166167**Параметры:**168169- **database** ([объект, подобный пути](https://python-all.ru/3.14/glossary.html#term-path-like-object)) – путь к файлу базы данных, который нужно открыть. Можно передать `":memory:"` для создания [базы данных SQLite, существующей только в памяти](https://python-all.ru/3.14/library/sqlite3.html), и открыть соединение с ней.170- **timeout** ([*float*](https://python-all.ru/3.14/library/functions.html#float)) – сколько секунд соединение должно ждать перед возбуждением исключения [`OperationalError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.OperationalError), когда таблица заблокирована. Если другое соединение открывает транзакцию для изменения таблицы, эта таблица будет заблокирована до фиксации транзакции. По умолчанию пять секунд.171- **detect\_types** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – управляет тем, как типы данных, не [поддерживаемые SQLite изначально](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-types), ищутся для преобразования в типы Python с помощью преобразователей, зарегистрированных через [`register_converter()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.register_converter). Установите любое сочетание (используя `|`, побитовое ИЛИ) из [`PARSE_DECLTYPES`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.PARSE_DECLTYPES) и [`PARSE_COLNAMES`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.PARSE_COLNAMES), чтобы включить эту функцию. Имена столбцов имеют приоритет над объявленными типами, если установлены оба флага. По умолчанию (`0`) определение типов отключено.172- **isolation\_level** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str) *|* *None*) – управляет устаревшим поведением обработки транзакций. См. [`Connection.isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level) и [Управление транзакциями через атрибут isolation\_level](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-isolation-level) для получения дополнительной информации. Может быть `"DEFERRED"` (по умолчанию), `"EXCLUSIVE"` или `"IMMEDIATE"`; или `None` для отключения неявного открытия транзакций. Не действует, если [`Connection.autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) не установлено в [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL) (по умолчанию).173- **check\_same\_thread** ([*bool*](https://python-all.ru/3.14/library/functions.html#bool)) – Если `True` (по умолчанию), будет возбуждено [`ProgrammingError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError), если соединение с базой данных используется потоком, отличным от того, который его создал. Если `False`, к соединению можно обращаться из нескольких потоков; пользователю может потребоваться сериализовать операции записи во избежание повреждения данных. См. [`threadsafety`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.threadsafety) для получения дополнительной информации.174- **factory** ([*Connection*](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection)) – пользовательский подкласс [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection) для создания соединения, если не используется стандартный класс `Connection`.175- **cached\_statements** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – количество операторов, которые `sqlite3` должен кэшировать для этого соединения, чтобы избежать накладных расходов на разбор. По умолчанию 128 операторов.176- **uri** ([*bool*](https://python-all.ru/3.14/library/functions.html#bool)) – Если установлено в `True`, *database* интерпретируется как URI с путём к файлу и необязательной строкой запроса. Часть схемы *должна* быть `"file:"`, а путь может быть относительным или абсолютным. Строка запроса позволяет передавать параметры SQLite, открывая возможности, описанные в [Работа с URI SQLite](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-uri-tricks).177- **autocommit** ([*bool*](https://python-all.ru/3.14/library/functions.html#bool)) – управляет поведением обработки транзакций [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html). См. [`Connection.autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) и [Управление транзакциями через атрибут autocommit](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-autocommit) для получения дополнительной информации. *autocommit* в настоящее время по умолчанию равен [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL). Значение по умолчанию будет изменено на `False` в одном из будущих выпусков Python.178179**Тип возвращаемого значения :**180181[*Connection*](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection)182183Вызывает [событие аудита](https://python-all.ru/3.14/library/sys.html#auditing) `sqlite3.connect` с аргументом `database`.184185Вызывает [событие аудита](https://python-all.ru/3.14/library/sys.html#auditing) `sqlite3.connect/handle` с аргументом `connection_handle`.186187Изменено в версии 3.4: Добавлен параметр *uri*.188189Изменено в версии 3.7: *database* теперь также может быть [объектом, подобным пути](https://python-all.ru/3.14/glossary.html#term-path-like-object), а не только строкой.190191Изменено в версии 3.10: Добавлено событие аудита `sqlite3.connect/handle`.192193Изменено в версии 3.12: Добавлен параметр *autocommit*.194195Изменено в версии 3.13: Позиционное использование параметров *timeout*, *detect\_types*, *isolation\_level*, *check\_same\_thread*, *factory*, *cached\_statements* и *uri* устарело. Они станут только ключевыми параметрами в Python 3.15.196197#### `sqlite3.complete_statement(statement)`198199Возвращает `True`, если строка *statement* содержит один или несколько полных SQL-операторов. Никакая синтаксическая проверка или разбор не выполняются, кроме проверки отсутствия незакрытых строковых литералов и завершения оператора точкой с запятой.200201Например:202203```pycon204>>> sqlite3.complete_statement("SELECT foo FROM bar;")205True206>>> sqlite3.complete_statement("SELECT foo")207False208```209210Эта функция может быть полезна при вводе с командной строки для определения, является ли введённый текст полным SQL-оператором, или требуется дополнительный ввод перед вызовом [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute).211212См. `runsource()` в [Lib/sqlite3/\_\_main\_\_.py](https://python-all.ru/src/3.14/Lib/sqlite3/__main__.py) для практического использования.213214#### `sqlite3.enable_callback_tracebacks(flag, /)`215216Включить или отключить трассировку колбэков. По умолчанию трассировка в пользовательских функциях, агрегатах, конвертерах, колбэках авторизатора и т.д. не отображается. Чтобы отладить их, можно вызвать эту функцию, установив для *flag* значение `True`. После этого трассировка колбэков будет выводиться на [`sys.stderr`](https://python-all.ru/3.14/library/sys.html#sys.stderr). Используйте `False`, чтобы снова отключить эту возможность.217218> **Примечание**219>220> Ошибки в колбэках пользовательских функций логируются как неподнимаемые исключения. Используйте [`unraisable hook handler`](https://python-all.ru/3.14/library/sys.html#sys.unraisablehook) для анализа неисправного колбэка.221222#### `sqlite3.register_adapter(type, adapter, /)`223224Регистрирует *адаптер* – [вызываемый объект](https://python-all.ru/3.14/glossary.html#term-callable), который адаптирует тип Python *type* в тип SQLite. Адаптер вызывается с объектом Python типа *type* в качестве единственного аргумента и должен возвращать значение [типа, который SQLite понимает изначально](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-types).225226#### `sqlite3.register_converter(typename, converter, /)`227228Регистрирует *конвертер* – [вызываемый объект](https://python-all.ru/3.14/glossary.html#term-callable), который преобразует объекты SQLite типа *typename* в объект Python определённого типа. Конвертер вызывается для всех значений SQLite типа *typename*; ему передаётся объект [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) и он должен вернуть объект желаемого типа Python. Обратитесь к параметру *detect\_types* функции [`connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect) для получения информации о том, как работает определение типа.229230Примечание: *typename* и имя типа в запросе сравниваются без учёта регистра.231232### Константы модуля233234#### `sqlite3.LEGACY_TRANSACTION_CONTROL`235236Установите [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) в эту константу, чтобы выбрать старый стиль управления транзакциями (до Python 3.12). Дополнительную информацию см. в разделе [Управление транзакциями через атрибут isolation\_level](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-isolation-level).237238#### `sqlite3.PARSE_DECLTYPES`239240Передайте это значение флага параметру *detect\_types* функции [`connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect) для поиска функции конвертера по объявленным типам каждого столбца. Типы объявляются при создании таблицы базы данных. `sqlite3` будет искать функцию конвертера, используя первое слово объявленного типа в качестве ключа словаря конвертеров. Например:241242```sql243CREATE TABLE test(244 i integer primary key, ! will look up a converter named "integer"245 p point, ! will look up a converter named "point"246 n number(10) ! will look up a converter named "number"247 )248```249250Этот флаг можно комбинировать с [`PARSE_COLNAMES`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.PARSE_COLNAMES) с помощью оператора `|` (побитовое ИЛИ).251252> **Примечание**253>254> Сгенерированные поля (например, `MAX(p)`) возвращаются как [`str`](https://python-all.ru/3.14/library/stdtypes.html#str). Используйте `PARSE_COLNAMES`, чтобы принудительно задать типы для таких запросов.255256#### `sqlite3.PARSE_COLNAMES`257258Передайте это значение флага параметру *detect\_types* функции [`connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect) для поиска функции конвертера по имени типа, извлечённому из имени столбца запроса, в качестве ключа словаря конвертеров. Имя столбца запроса должно быть заключено в двойные кавычки (`"`), а имя типа – в квадратные скобки (`[]`).259260```sql261SELECT MAX(p) as "p [point]" FROM test; ! will look up converter "point"262```263264Этот флаг можно комбинировать с [`PARSE_DECLTYPES`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.PARSE_DECLTYPES) с помощью оператора `|` (побитовое ИЛИ).265266#### `sqlite3.SQLITE_OK`267268#### `sqlite3.SQLITE_DENY`269270#### `sqlite3.SQLITE_IGNORE`271272Флаги, которые должны возвращаться *authorizer\_callback* – [вызываемым объектом](https://python-all.ru/3.14/glossary.html#term-callable), переданным в [`Connection.set_authorizer()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.set_authorizer), чтобы указать следующее:273274- Доступ разрешён (`SQLITE_OK`),275- Выполнение SQL-оператора должно быть прервано с ошибкой (`SQLITE_DENY`)276- Столбец должен обрабатываться как значение `NULL` (`SQLITE_IGNORE`)277278#### `sqlite3.apilevel`279280Строковая константа, указывающая поддерживаемый уровень DB-API. Требуется спецификацией DB-API. Жёстко закодирована как `"2.0"`.281282#### `sqlite3.paramstyle`283284Строковая константа, указывающая тип форматирования маркеров параметров, ожидаемый модулем `sqlite3`. Требуется спецификацией DB-API. Жёстко закодирована как `"qmark"`.285286> **Примечание**287>288> Также поддерживается стиль параметров DB-API `named`.289290#### `sqlite3.sqlite_version`291292Номер версии библиотеки SQLite во время выполнения в виде [`string`](https://python-all.ru/3.14/library/stdtypes.html#str).293294#### `sqlite3.sqlite_version_info`295296Номер версии библиотеки SQLite времени выполнения как [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple) из [`integers`](https://python-all.ru/3.14/library/functions.html#int).297298#### `sqlite3.threadsafety`299300Целочисленная константа, требуемая DB-API 2.0, указывающая уровень потоковой безопасности, поддерживаемый модулем `sqlite3`. Значение этого атрибута определяется [режимом многопоточности](https://python-all.ru/3.14/library/sqlite3.html), с которым скомпилирована библиотека SQLite. Режимы многопоточности SQLite:3013021. **Однопоточный**: в этом режиме все мьютексы отключены, и SQLite небезопасен при использовании в более чем одном потоке одновременно.3032. **Многопоточный**: в этом режиме SQLite можно безопасно использовать из нескольких потоков при условии, что ни одно соединение с базой данных не используется одновременно двумя или более потоками.3043. **Сериализованный**: в сериализованном режиме SQLite можно безопасно использовать из нескольких потоков без ограничений.305306Соответствие режимов многопоточности SQLite уровням потоковой безопасности DB-API 2.0 выглядит следующим образом:307308| Режим многопоточности SQLite | [**threadsafety**](https://python-all.ru/3.14/library/sqlite3.html) | [SQLITE\_THREADSAFE](https://python-all.ru/3.14/library/sqlite3.html) | Значение DB-API 2.0 |309| --- | --- | --- | --- |310| однопоточный | 0 | 0 | Потоки не могут совместно использовать модуль |311| многопоточный | 1 | 2 | Потоки могут совместно использовать модуль, но не соединения |312| сериализованный | 3 | 1 | Потоки могут совместно использовать модуль, соединения и курсоры |313314Изменено в версии 3.11: Атрибут *threadsafety* теперь устанавливается динамически, а не жёстко задаётся равным `1`.315316#### `sqlite3.SQLITE_DBCONFIG_DEFENSIVE`317318#### `sqlite3.SQLITE_DBCONFIG_DQS_DDL`319320#### `sqlite3.SQLITE_DBCONFIG_DQS_DML`321322#### `sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY`323324#### `sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER`325326#### `sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION`327328#### `sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG`329330#### `sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER`331332#### `sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW`333334#### `sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE`335336#### `sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT`337338#### `sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE`339340#### `sqlite3.SQLITE_DBCONFIG_RESET_DATABASE`341342#### `sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP`343344#### `sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA`345346#### `sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA`347348Эти константы используются для методов [`Connection.setconfig()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.setconfig) и [`getconfig()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.getconfig).349350Доступность этих констант зависит от версии SQLite, с которой был скомпилирован Python.351352Добавлено в версии 3.12.353354> **См. также**355>356> **[https://www.sqlite.org/c3ref/c\_dbconfig\_defensive.html](https://python-all.ru/3.14/library/sqlite3.html)**357>358> Документация SQLite: параметры конфигурации соединения с базой данных359360Устарело с версии 3.12, удалено в версии 3.14: Константы `version` и `version_info`.361362### Объекты Connection363364#### `class sqlite3.Connection`365366Каждая открытая база данных SQLite представлена объектом `Connection`, который создается с помощью [`sqlite3.connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect). Их основное назначение – создание объектов [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor) и [управление транзакциями](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-controlling-transactions).367368> **См. также**369>370> - [Как использовать сокращенные методы соединения](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-connection-shortcuts)371> - [Как использовать контекстный менеджер соединения](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-connection-context-manager)372373Изменено в версии 3.13: Если [`close()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.close) не вызывается до yдаления объекта `Connection`, выдается [`ResourceWarning`](https://python-all.ru/3.14/library/exceptions.html#ResourceWarning).374375Соединение с базой данных SQLite имеет следующие атрибуты и методы:376377#### `cursor(factory=Cursor)`378379Создает и возвращает объект [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor). Метод cursor принимает один необязательный параметр *factory*. Если он указан, это должен быть [вызываемый объект](https://python-all.ru/3.14/glossary.html#term-callable), возвращающий экземпляр `Cursor` или его подклассов.380381#### `blobopen(table, column, rowid, /, *, readonly=False, name='main')`382383Открывает дескриптор [`Blob`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Blob) для существующего BLOB.384385**Параметры:**386387- **table** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Имя таблицы, в которой находится blob.388- **column** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Имя столбца, в котором находится blob.389- **rowid** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – Идентификатор строки, в которой находится blob.390- **readonly** ([*bool*](https://python-all.ru/3.14/library/functions.html#bool)) – Установите в `True`, если blob должен открываться без прав на запись. По умолчанию `False`.391- **name** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Имя базы данных, в которой находится blob. По умолчанию `"main"`.392393**Возбуждает:**394395[**OperationalError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.OperationalError) – Возникает при попытке открыть blob в таблице `WITHOUT ROWID`.396397**Тип возвращаемого значения :**398399[Blob](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Blob)400401> **Примечание**402>403> Размер blob нельзя изменить с помощью класса [`Blob`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Blob). Используйте SQL-функцию `zeroblob` для создания blob фиксированного размера.404405Добавлено в версии 3.12.406407#### `commit()`408409Фиксирует любую ожидающую транзакцию в базе данных. Если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) равно `True` или нет открытой транзакции, этот метод ничего не делает. Если `autocommit` равно `False`, неявно открывается новая транзакция, если этим методом была зафиксирована ожидающая транзакция.410411#### `rollback()`412413Откатывает любую ожидающую транзакцию к началу. Если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) равно `True` или нет открытой транзакции, этот метод ничего не делает. Если `autocommit` равно `False`, неявно открывается новая транзакция, если этим методом была откачена ожидающая транзакция.414415#### `close()`416417Закрывает соединение с базой данных. Если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) равно `False`, любая ожидающая транзакция неявно откатывается. Если `autocommit` равно `True` или [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL), неявное управление транзакциями не выполняется. Перед закрытием обязательно [`commit()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.commit), чтобы не потерять ожидающие изменения.418419#### `execute(sql, parameters=(), /)`420421Создать новый объект [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor) и вызвать для него [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute) с заданными *sql* и *parameters*. Вернуть новый объект курсора.422423#### `executemany(sql, parameters, /)`424425Создать новый объект [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor) и вызвать для него [`executemany()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executemany) с заданными *sql* и *parameters*. Вернуть новый объект курсора.426427#### `executescript(sql_script, /)`428429Создать новый объект [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor) и вызвать для него [`executescript()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executescript) с заданным *sql\_script*. Вернуть новый объект курсора.430431#### `create_function(name, narg, func, *, deterministic=False)`432433Создать или удалить пользовательскую SQL-функцию.434435**Параметры:**436437- **name** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Имя SQL-функции.438- **narg** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – Количество аргументов, которое может принимать SQL-функция. Если `-1`, может принимать любое количество аргументов.439- **func** ([колбэк](https://python-all.ru/3.14/glossary.html#term-callback) | None) – [Вызываемый объект](https://python-all.ru/3.14/glossary.html#term-callable), который вызывается при вызове SQL-функции. Вызываемый объект должен возвращать [тип, нативно поддерживаемый SQLite](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-types). Установите `None`, чтобы удалить существующую SQL-функцию.440- **deterministic** ([*bool*](https://python-all.ru/3.14/library/functions.html#bool)) – Если `True`, созданная SQL-функция помечается как [детерминированная](https://python-all.ru/3.14/library/sqlite3.html), что позволяет SQLite выполнять дополнительные оптимизации.441442Изменено в версии 3.8: Добавлен параметр *deterministic*.443444Пример:445446```pycon447>>> import hashlib448>>> def md5sum(t):449... return hashlib.md5(t).hexdigest()450>>> con = sqlite3.connect(":memory:")451>>> con.create_function("md5", 1, md5sum)452>>> for row in con.execute("SELECT md5(?)", (b"foo",)):453... print(row)454('acbd18db4cc2f85cedef654fccc4a4d8',)455>>> con.close()456```457458Изменено в версии 3.13: Передача *name*, *narg* и *func* в качестве именованных аргументов устарела. Эти параметры станут только позиционными в Python 3.15.459460#### `create_aggregate(name, n_arg, aggregate_class)`461462Создать или удалить пользовательскую агрегатную SQL-функцию.463464**Параметры:**465466- **name** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Имя агрегатной SQL-функции.467- **n\_arg** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – Количество аргументов, которое может принимать агрегатная SQL-функция. Если `-1`, может принимать любое количество аргументов.468- **aggregate\_class** ([class](https://python-all.ru/3.14/glossary.html#term-class) | None) –469470 Класс должен реализовывать следующие методы:471472 - `step()`: Добавить строку в агрегат.473 - `finalize()`: Возвращает окончательный результат агрегата в виде [типа, поддерживаемого SQLite нативно](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-types).474475 Количество аргументов, которое должен принимать метод `step()`, определяется параметром *n\_arg*.476477 Установите `None` для удаления существующей агрегатной SQL-функции.478479Пример:480481```python482class MySum:483 def __init__(self):484 self.count = 0485486 def step(self, value):487 self.count += value488489 def finalize(self):490 return self.count491492con = sqlite3.connect(":memory:")493con.create_aggregate("mysum", 1, MySum)494cur = con.execute("CREATE TABLE test(i)")495cur.execute("INSERT INTO test(i) VALUES(1)")496cur.execute("INSERT INTO test(i) VALUES(2)")497cur.execute("SELECT mysum(i) FROM test")498print(cur.fetchone()[0])499500con.close()501```502503Изменено в версии 3.13: Передача *name*, *n\_arg* и *aggregate\_class* в качестве именованных аргументов устарела. Эти параметры станут только позиционными в Python 3.15.504505#### `create_window_function(name, num_params, aggregate_class, /)`506507Создать или удалить пользовательскую агрегатную оконную функцию.508509**Параметры:**510511- **name** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Имя агрегатной оконной SQL-функции для создания или удаления.512- **num\_params** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – Количество аргументов, которое может принимать агрегатная оконная SQL-функция. Если `-1`, может принимать любое количество аргументов.513- **aggregate\_class** ([class](https://python-all.ru/3.14/glossary.html#term-class) | None) –514515 Класс, который должен реализовывать следующие методы:516517 - `step()`: Добавить строку в текущее окно.518 - `value()`: Возвращает текущее значение агрегата.519 - `inverse()`: Удаляет строку из текущего окна.520 - `finalize()`: Возвращает окончательный результат агрегата в виде [типа, поддерживаемого SQLite нативно](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-types).521522 Количество аргументов, которые должны принимать методы `step()` и `value()`, определяется параметром *num\_params*.523524 Установка `None` удаляет существующую агрегатную оконную функцию SQL.525526**Возбуждает:**527528[**NotSupportedError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.NotSupportedError) – возбуждается при использовании с версией SQLite старше 3.25.0, которая не поддерживает агрегатные оконные функции.529530Добавлено в версии 3.12.531532Пример:533534```python535# Пример взят с https://www.sqlite.org/windowfunctions.html#udfwinfunc536class WindowSumInt:537 def __init__(self):538 self.count = 0539540 def step(self, value):541 """Добавить строку в текущее окно."""542 self.count += value543544 def value(self):545 """Возвращает текущее значение агрегата."""546 return self.count547548 def inverse(self, value):549 """Удалить строку из текущего окна."""550 self.count -= value551552 def finalize(self):553 """Возвращает окончательное значение агрегата.554555 Здесь следует разместить любые операции очистки.556 """557 return self.count558559con = sqlite3.connect(":memory:")560cur = con.execute("CREATE TABLE test(x, y)")561values = [562 ("a", 4),563 ("b", 5),564 ("c", 3),565 ("d", 8),566 ("e", 1),567]568cur.executemany("INSERT INTO test VALUES(?, ?)", values)569con.create_window_function("sumint", 1, WindowSumInt)570cur.execute("""571 SELECT x, sumint(y) OVER (572 ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING573 ) AS sum_y574 FROM test ORDER BY x575""")576print(cur.fetchall())577con.close()578```579580#### `create_collation(name, callable, /)`581582Создаёт collation с именем *name*, используя функцию сравнения *callable*. *callable* передаётся два аргумента [`string`](https://python-all.ru/3.14/library/stdtypes.html#str), и она должна возвращать [`integer`](https://python-all.ru/3.14/library/functions.html#int):583584- `1`, если первый больше второго585- `-1`, если первый меньше второго586- `0`, если они равны587588Следующий пример демонстрирует collation с обратной сортировкой:589590```python591def collate_reverse(string1, string2):592 if string1 == string2:593 return 0594 elif string1 < string2:595 return 1596 else:597 return -1598599con = sqlite3.connect(":memory:")600con.create_collation("reverse", collate_reverse)601602cur = con.execute("CREATE TABLE test(x)")603cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])604cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")605for row in cur:606 print(row)607con.close()608```609610Удаляет функцию collation, устанавливая *callable* в `None`.611612Изменено в версии 3.11: Имя collation может содержать любые символы Unicode. Ранее допускались только символы ASCII.613614#### `interrupt()`615616Вызовите этот метод из другого потока, чтобы прервать любые запросы, которые могут выполняться на соединении. Прерванные запросы возбудят исключение [`OperationalError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.OperationalError).617618#### `set_authorizer(authorizer_callback)`619620Регистрирует [callable](https://python-all.ru/3.14/glossary.html#term-callable) *authorizer\_callback*, который будет вызываться при каждой попытке доступа к столбцу таблицы в базе данных. Колбэк должен возвращать одно из значений [`SQLITE_OK`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.SQLITE_OK), [`SQLITE_DENY`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.SQLITE_DENY) или [`SQLITE_IGNORE`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.SQLITE_IGNORE), чтобы указать, как библиотека SQLite должна обрабатывать доступ к столбцу.621622Первый аргумент колбэка указывает, какой тип операции требуется авторизовать. Второй и третий аргументы будут аргументами или `None` в зависимости от первого аргумента. Четвёртый аргумент – имя базы данных («main», «temp» и т.д.), если применимо. Пятый аргумент – имя самого внутреннего триггера или представления, ответственного за попытку доступа, или `None`, если эта попытка доступа происходит непосредственно из входного SQL-кода.623624Обратитесь к документации SQLite за возможными значениями первого аргумента и значением второго и третьего аргументов в зависимости от первого. Все необходимые константы доступны в модуле `sqlite3`.625626Передача `None` в качестве *authorizer\_callback* отключает авторизатор.627628Изменено в версии 3.11: Добавлена поддержка отключения авторизатора с помощью `None`.629630Изменено в версии 3.13: Передача *authorizer\_callback* в качестве именованного аргумента устарела. Параметр станет только позиционным в Python 3.15.631632#### `set_progress_handler(progress_handler, n)`633634Регистрирует [callable](https://python-all.ru/3.14/glossary.html#term-callable) *progress\_handler*, который будет вызываться каждые *n* инструкций виртуальной машины SQLite. Это полезно, если нужно получать вызовы от SQLite во время длительных операций, например для обновления графического интерфейса.635636Чтобы удалить ранее установленный обработчик прогресса, вызовите метод с `None` в качестве *progress\_handler*.637638Возврат ненулевого значения из функции-обработчика завершит текущий выполняющийся запрос и приведёт к возбуждению исключения [`DatabaseError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError).639640Изменено в версии 3.13: Передача *progress\_handler* в качестве именованного аргумента устарела. Параметр станет только позиционным в Python 3.15.641642#### `set_trace_callback(trace_callback)`643644Регистрирует [callable](https://python-all.ru/3.14/glossary.html#term-callable) *trace\_callback*, который будет вызываться для каждого SQL-выражения, фактически выполняемого внутренним движком SQLite.645646Единственный аргумент, передаваемый колбэку – это выполняемое выражение (в виде [`str`](https://python-all.ru/3.14/library/stdtypes.html#str)). Возвращаемое значение колбэка игнорируется. Обратите внимание, что внутренний движок выполняет не только выражения, переданные методам [`Cursor.execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute). Другие источники включают [управление транзакциями](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-controlling-transactions) модуля `sqlite3` и выполнение триггеров, определённых в текущей базе данных.647648Передача `None` в качестве *trace\_callback* отключает трассировочный колбэк.649650> **Примечание**651>652> Исключения, возникающие в колбэке трассировки, не распространяются. В качестве средства отладки и разработки используйте [`enable_callback_tracebacks()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.enable_callback_tracebacks), чтобы включить печать трассировок для исключений, возникающих в колбэке трассировки.653654Добавлено в версии 3.3.655656Изменено в версии 3.13: Передача *trace\_callback* в качестве именованного аргумента устарела. Начиная с Python 3.15 этот параметр станет позиционным.657658#### `enable_load_extension(enabled, /)`659660Включает загрузку расширений SQLite из разделяемых библиотек, если *enabled* равен `True`; иначе отключает эту возможность. Расширения SQLite могут определять новые функции, агрегаты или целые новые реализации виртуальных таблиц. Известным расширением является расширение полнотекстового поиска, распространяемое вместе с SQLite.661662> **Примечание**663>664> Модуль `sqlite3` по умолчанию собирается без поддержки загружаемых расширений, поскольку на некоторых платформах (в частности, macOS) библиотеки SQLite скомпилированы без этой возможности. Чтобы получить поддержку загружаемых расширений, необходимо передать параметр [`--enable-loadable-sqlite-extensions`](https://python-all.ru/3.14/using/configure.html#cmdoption-enable-loadable-sqlite-extensions) в **configure**.665666Возбуждает [событие аудита](https://python-all.ru/3.14/library/sys.html#auditing) `sqlite3.enable_load_extension` с аргументами `connection`, `enabled`.667668Добавлено в версии 3.2.669670Изменено в версии 3.10: Добавлено событие аудита `sqlite3.enable_load_extension`.671672```python673con.enable_load_extension(True)674675# Загрузить расширение полнотекстового поиска.676con.execute("select load_extension('./fts3.so')")677678# в качестве альтернативы можно загрузить расширение с помощью вызова API:679# con.load_extension("./fts3.so")680681# отключить загрузку расширения снова682con.enable_load_extension(False)683684# пример из вики SQLite685con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")686con.executescript("""687 INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');688 INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');689 INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');690 INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');691 """)692for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):693 print(row)694```695696#### `load_extension(path, /, *, entrypoint=None)`697698Загружает расширение SQLite из разделяемой библиотеки. Включите загрузку расширений с помощью [`enable_load_extension()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.enable_load_extension) перед вызовом этого метода.699700**Параметры:**701702- **path** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – путь к расширению SQLite.703- **entrypoint** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str) *|* *None*) – имя точки входа. Если `None` (по умолчанию), SQLite сам найдёт имя точки входа; подробнее см. в документации SQLite [Loading an Extension](https://python-all.ru/3.14/library/sqlite3.html).704705Возбуждает [событие аудита](https://python-all.ru/3.14/library/sys.html#auditing) `sqlite3.load_extension` с аргументами `connection`, `path`.706707Добавлено в версии 3.2.708709Изменено в версии 3.10: Добавлено событие аудита `sqlite3.load_extension`.710711Изменено в версии 3.12: Добавлен параметр *entrypoint*.712713#### `iterdump(*, filter=None)`714715Возвращает [итератор](https://python-all.ru/3.14/glossary.html#term-iterator) для дампа базы данных в виде SQL-кода. Полезно при сохранении базы данных в памяти для последующего восстановления. Аналог команды `.dump` в оболочке **sqlite3**.716717**Параметры:**718719**filter** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str) *|* *None*) – необязательный шаблон `LIKE` для объектов базы данных, которые нужно выгрузить, например `prefix_%`. Если `None` (по умолчанию), будут включены все объекты базы данных.720721Пример:722723```python724# Преобразовать файл example.db в дамп SQL dump.sql725con = sqlite3.connect('example.db')726with open('dump.sql', 'w') as f:727 for line in con.iterdump():728 f.write('%s\n' % line)729con.close()730```731732> **См. также**733>734> [Как работать с не-UTF-8 текстовыми кодировками](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howto-encoding)735736Изменено в версии 3.13: Добавлен параметр *filter*.737738#### `backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)`739740Создаёт резервную копию базы данных SQLite.741742Работает даже при доступе к базе данных другими клиентами или при одновременной работе через то же подключение.743744**Параметры:**745746- **target** ([*Connection*](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection)) – подключение к базе данных, в которое будет сохранена резервная копия.747- **pages** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – количество страниц, копируемых за один раз. Если значение равно или меньше `0`, вся база данных копируется за один шаг. По умолчанию `-1`.748- **progress** ([колбэк](https://python-all.ru/3.14/glossary.html#term-callback) | None) – если задан [вызываемый объект](https://python-all.ru/3.14/glossary.html#term-callable), он вызывается с тремя целочисленными аргументами на каждой итерации резервного копирования: *status* последней итерации, *remaining* – количество страниц, которые ещё нужно скопировать, и *total* – общее количество страниц. По умолчанию `None`.749- **name** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – имя базы данных для резервного копирования. Это может быть `"main"` (по умолчанию) для основной базы данных, `"temp"` для временной базы данных или имя пользовательской базы данных, добавленной с помощью SQL-выражения `ATTACH DATABASE`.750- **sleep** ([*float*](https://python-all.ru/3.14/library/functions.html#float)) – количество секунд ожидания между последовательными попытками резервного копирования оставшихся страниц.751752Пример 1: копирование существующей базы данных в другую:753754```python755def progress(status, remaining, total):756 print(f'Copied {total-remaining} of {total} pages...')757758src = sqlite3.connect('example.db')759dst = sqlite3.connect('backup.db')760with dst:761 src.backup(dst, pages=1, progress=progress)762dst.close()763src.close()764```765766Пример 2: копирование существующей базы данных во временную копию:767768```python769src = sqlite3.connect('example.db')770dst = sqlite3.connect(':memory:')771src.backup(dst)772dst.close()773src.close()774```775776Добавлено в версии 3.7.777778> **См. также**779>780> [Как работать с не-UTF-8 текстовыми кодировками](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howto-encoding)781782#### `getlimit(category, /)`783784Возвращает ограничение времени выполнения подключения.785786**Параметры:**787788**category** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – [категория ограничения SQLite](https://python-all.ru/3.14/library/sqlite3.html), которую нужно запросить.789790**Тип возвращаемого значения :**791792[int](https://python-all.ru/3.14/library/functions.html#int)793794**Возбуждает:**795796[**ProgrammingError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError) – если *category* не распознаётся базовой библиотекой SQLite.797798Пример: запрос максимальной длины SQL-запроса для `Connection` `con` (значение по умолчанию – 1000000000):799800```pycon801>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)8021000000000803```804805Добавлено в версии 3.12.806807#### `setlimit(category, limit, /)`808809Устанавливает ограничение времени выполнения соединения. Попытки увеличить лимит выше его жёсткого верхнего предела молча ограничиваются этим пределом. Независимо от того, был ли изменён лимит, возвращается предыдущее значение лимита.810811**Параметры:**812813- **category** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – [категория лимита SQLite](https://python-all.ru/3.14/library/sqlite3.html), которую нужно установить.814- **limit** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – значение нового лимита. Если значение отрицательное, текущий лимит не изменяется.815816**Тип возвращаемого значения :**817818[int](https://python-all.ru/3.14/library/functions.html#int)819820**Возбуждает:**821822[**ProgrammingError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError) – если *category* не распознаётся базовой библиотекой SQLite.823824Пример: ограничить количество присоединённых баз данных до 1 для `Connection` `con` (лимит по умолчанию – 10):825826```pycon827>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)82810829>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)8301831```832833Добавлено в версии 3.12.834835#### `getconfig(op, /)`836837Запрашивает логическую опцию конфигурации соединения.838839**Параметры:**840841**op** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – [код SQLITE\_DBCONFIG](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-dbconfig-constants).842843**Тип возвращаемого значения :**844845[bool](https://python-all.ru/3.14/library/functions.html#bool)846847Добавлено в версии 3.12.848849#### `setconfig(op, enable=True, /)`850851Устанавливает логическую опцию конфигурации соединения.852853**Параметры:**854855- **op** ([*int*](https://python-all.ru/3.14/library/functions.html#int)) – [код SQLITE\_DBCONFIG](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-dbconfig-constants).856- **enable** ([*bool*](https://python-all.ru/3.14/library/functions.html#bool)) – `True`, если опция конфигурации должна быть включена (по умолчанию); `False`, если она должна быть отключена.857858Добавлено в версии 3.12.859860#### `serialize(*, name='main')`861862Сериализует базу данных в объект [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes). Для обычного файла базы данных на диске сериализация представляет собой просто копию дискового файла. Для базы данных в памяти или временной базы данных сериализация – это та же последовательность байтов, которая была бы записана на диск, если бы эта база данных была скопирована на диск.863864**Параметры:**865866**name** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – имя базы данных для сериализации. По умолчанию `"main"`.867868**Тип возвращаемого значения :**869870[bytes](https://python-all.ru/3.14/library/stdtypes.html#bytes)871872> **Примечание**873>874> Этот метод доступен, только если базовая библиотека SQLite поддерживает API сериализации.875876Добавлено в версии 3.12.877878#### `deserialize(data, /, *, name='main')`879880Десериализует базу данных [`serialized`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.serialize) в `Connection`. Этот метод приводит к отключению соединения с базой данных *name* и повторному открытию *name* как базы данных в памяти на основе сериализации, содержащейся в *data*.881882**Параметры:**883884- **data** ([*bytes*](https://python-all.ru/3.14/library/stdtypes.html#bytes)) – сериализованная база данных.885- **name** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – имя базы данных, в которую выполняется десериализация. По умолчанию `"main"`.886887**Возбуждает:**888889- [**OperationalError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.OperationalError) – если соединение с базой данных в настоящее время участвует в транзакции чтения или операции резервного копирования.890- [**DatabaseError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError) – если *data* не содержит корректную базу данных SQLite.891- [**OverflowError**](https://python-all.ru/3.14/library/exceptions.html#OverflowError) – если [`len(data)`](https://python-all.ru/3.14/library/functions.html#len) больше `2**63 - 1`.892893> **Примечание**894>895> Этот метод доступен, только если используемая библиотека SQLite содержит deserialize API.896897Добавлено в версии 3.12.898899#### `autocommit`900901Этот атрибут управляет поведением транзакций, совместимым с [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html). `autocommit` имеет три допустимых значения:902903- `False`: выбирает [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html)-совместимое поведение транзакций, подразумевающее, что `sqlite3` гарантирует, что транзакция всегда открыта. Используйте [`commit()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.commit) и [`rollback()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.rollback) для закрытия транзакций.904905 Это рекомендуемое значение `autocommit`.906- `True`: использует [режим автоматической фиксации SQLite](https://python-all.ru/3.14/library/sqlite3.html). [`commit()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.commit) и [`rollback()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.rollback) в этом режиме не действуют.907- [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL): управление транзакциями до Python 3.12 (несовместимое с [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html)). Подробнее см. [`isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level).908909 В настоящее время это значение по умолчанию для `autocommit`.910911Изменение `autocommit` на `False` открывает новую транзакцию, а изменение на `True` фиксирует любую ожидающую транзакцию.912913Подробнее см. [управление транзакциями через атрибут autocommit](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-autocommit).914915> **Примечание**916>917> Атрибут [`isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level) не действует, если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) не установлен в [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL).918919Добавлено в версии 3.12.920921#### `in_transaction`922923Этот атрибут, доступный только для чтения, соответствует низкоуровневому [режиму автоматической фиксации SQLite](https://python-all.ru/3.14/library/sqlite3.html).924925`True`, если транзакция активна (есть незафиксированные изменения), `False` в противном случае.926927Добавлено в версии 3.2.928929#### `isolation_level`930931Управляет [устаревшим режимом обработки транзакций](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-isolation-level) для `sqlite3`. Если установлено `None`, транзакции никогда не открываются неявно. Если установлено одно из `"DEFERRED"`, `"IMMEDIATE"` или `"EXCLUSIVE"`, что соответствует базовому [поведению транзакций SQLite](https://python-all.ru/3.14/library/sqlite3.html), выполняется [неявное управление транзакциями](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-isolation-level).932933Если параметр *isolation\_level* в [`connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect) не переопределяет его, то по умолчанию используется `""`, что является псевдонимом для `"DEFERRED"`.934935> **Примечание**936>937> Использовать [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) для управления транзакциями рекомендуется вместо `isolation_level`. `isolation_level` не действует, пока `autocommit` не установлен в [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL) (по умолчанию).938939#### `row_factory`940941Начальный [`row_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.row_factory) для объектов [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor), созданных из этого соединения. Присвоение этому атрибуту не влияет на `row_factory` существующих курсоров, принадлежащих этому соединению, только новых. По умолчанию установлено `None`, то есть каждая строка возвращается как [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple).942943См. [Как создавать и использовать фабрики строк](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howto-row-factory) для получения дополнительных сведений.944945Изменено в версии 3.14.6: Удаление атрибута `row_factory` больше не допускается.946947#### `text_factory`948949[Вызываемый объект](https://python-all.ru/3.14/glossary.html#term-callable), который принимает параметр [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) и возвращает его текстовое представление. Вызываемый объект вызывается для значений SQLite с типом данных `TEXT`. По умолчанию для этого атрибута установлено значение [`str`](https://python-all.ru/3.14/library/stdtypes.html#str).950951Подробнее см. [как обрабатывать текстовые кодировки, отличные от UTF-8](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howto-encoding).952953Изменено в версии 3.14.6: Удаление атрибута `text_factory` больше не допускается.954955#### `total_changes`956957Возвращает общее количество строк базы данных, которые были изменены, вставлены или удалены с момента открытия соединения с базой данных.958959### Объекты курсора960961> Объект `Cursor` представляет собой [курсор базы данных](https://python-all.ru/3.14/library/sqlite3.html), который используется для выполнения SQL-запросов и управления контекстом операции выборки. Курсоры создаются с помощью [`Connection.cursor()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.cursor) или с помощью любого из [сокращённых методов соединения](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-connection-shortcuts).962>963> Объекты курсора являются [итераторами](https://python-all.ru/3.14/glossary.html#term-iterator), то есть если выполнить [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute) запрос `SELECT`, можно просто перебирать курсор для получения результирующих строк:964>965> ```python966> for row in cur.execute("SELECT t FROM data"):967> print(row)968> ```969970#### `class sqlite3.Cursor`971972Экземпляр `Cursor` имеет следующие атрибуты и методы.973974#### `execute(sql, parameters=(), /)`975976Выполняет один SQL-запрос, с возможностью привязки значений Python с помощью [плейсхолдеров](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders).977978**Параметры:**979980- **sql** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Один SQL-запрос.981- **parameters** ([`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict) | [sequence](https://python-all.ru/3.14/glossary.html#term-sequence)) – Значения Python для привязки к плейсхолдерам в *sql*. `dict`, если используются именованные плейсхолдеры. последовательность, если используются безымянные плейсхолдеры. См. [Как использовать плейсхолдеры для привязки значений в SQL-запросах](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders).982983**Возбуждает:**984985[**ProgrammingError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError) – Когда *sql* содержит более одного SQL-запроса. Когда используются [именованные плейсхолдеры](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders) и *parameters* является последовательностью вместо [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict).986987Если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) равно [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL), [`isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level) не равно `None`, *sql* является `INSERT`, `UPDATE`, `DELETE` или `REPLACE`-запросом, и нет открытой транзакции, то транзакция неявно открывается перед выполнением *sql*.988989Изменено в версии 3.14: [`ProgrammingError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError) выбрасывается, если используются [именованные плейсхолдеры](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders) и *parameters* является последовательностью вместо [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict).990991Используйте [`executescript()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executescript) для выполнения нескольких SQL-запросов.992993#### `executemany(sql, parameters, /)`994995Для каждого элемента в *parameters* повторно выполнить [параметризованный](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders) DML SQL-запрос *sql*.996997Использует ту же неявную обработку транзакций, что и [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute).998999**Параметры:**10001001- **sql** ([*str*](https://python-all.ru/3.14/library/stdtypes.html#str)) – Один SQL-запрос DML.1002- **parameters** ([iterable](https://python-all.ru/3.14/glossary.html#term-iterable)) – итерируемый объект с параметрами для привязки к плейсхолдерам в *sql*. См. [Как использовать плейсхолдеры для привязки значений в SQL-запросах](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders).10031004**Возбуждает:**10051006[**ProgrammingError**](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError) – Когда *sql* содержит более одного SQL-запроса или не является запросом DML, Когда используются [именованные плейсхолдеры](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders) и элементы в *parameters* являются последовательностями вместо [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict).10071008Пример:10091010```python1011rows = [1012 ("row1",),1013 ("row2",),1014]1015# cur – объект sqlite3.Cursor1016cur.executemany("INSERT INTO data VALUES(?)", rows)1017```10181019> **Примечание**1020>1021> Все результирующие строки отбрасываются, включая запросы DML с [предложениями RETURNING](https://python-all.ru/3.14/library/sqlite3.html).10221023Изменено в версии 3.14: [`ProgrammingError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError) выбрасывается, если используются [именованные плейсхолдеры](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-placeholders) и элементы в *parameters* являются последовательностями вместо [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict).10241025#### `executescript(sql_script, /)`10261027Выполняет SQL-запросы из *sql\_script*. Если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) равно [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL) и есть незавершённая транзакция, сначала выполняется неявный `COMMIT`-запрос. Другой неявный контроль транзакций не выполняется; весь контроль транзакций должен быть добавлен в *sql\_script*.10281029*sql\_script* должен быть [`string`](https://python-all.ru/3.14/library/stdtypes.html#str).10301031Пример:10321033```python1034# cur – объект sqlite3.Cursor1035cur.executescript("""1036 BEGIN;1037 CREATE TABLE person(firstname, lastname, age);1038 CREATE TABLE book(title, author, published);1039 CREATE TABLE publisher(name, address);1040 COMMIT;1041""")1042```10431044#### `fetchone()`10451046Если [`row_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.row_factory) равен `None`, возвращает следующую строку результирующего набора как [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple). Иначе передаёт её фабрике строк и возвращает результат. Возвращает `None`, если данные закончились.10471048#### `fetchmany(size=cursor.arraysize)`10491050Возвращает следующий набор строк результата запроса как [`list`](https://python-all.ru/3.14/library/stdtypes.html#list). Возвращает пустой список, если строк больше нет.10511052Количество строк, извлекаемых за один вызов, задаётся параметром *size*. Если *size* не указан, количество извлекаемых строк определяется [`arraysize`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.arraysize). Если доступно меньше строк, чем *size*, возвращается столько строк, сколько есть.10531054Обратите внимание, что параметр *size* связан с производительностью. Для оптимальной производительности обычно лучше использовать атрибут arraysize. Если используется параметр *size*, рекомендуется сохранять одно и то же значение от одного вызова `fetchmany()` к следующему.10551056Изменено в версии 3.14.1: Отрицательные значения *size* отклоняются с выбрасыванием [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError).10571058#### `fetchall()`10591060Возвращает все (оставшиеся) строки результата запроса как [`list`](https://python-all.ru/3.14/library/stdtypes.html#list). Возвращает пустой список, если строк нет. Обратите внимание, что атрибут [`arraysize`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.arraysize) может влиять на производительность этой операции.10611062#### `close()`10631064Закрывает курсор сейчас (а не при вызове `__del__`).10651066Курсор станет непригодным к использованию; будет выброшено исключение [`ProgrammingError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError) при любой попытке выполнить операцию с курсором.10671068#### `setinputsizes(sizes, /)`10691070Требуется DB-API. Ничего не делает в `sqlite3`.10711072#### `setoutputsize(size, column=None, /)`10731074Требуется DB-API. Ничего не делает в `sqlite3`.10751076#### `arraysize`10771078Атрибут чтения/записи, управляющий количеством строк, возвращаемых [`fetchmany()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.fetchmany). Значение по умолчанию – 1, то есть при каждом вызове будет извлечена одна строка.10791080Изменено в версии 3.14.1: Отрицательные значения отклоняются с возбуждением [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError).10811082#### `connection`10831084Атрибут только для чтения, предоставляющий соединение с базой данных SQLite [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection), принадлежащее курсору. Объект `Cursor`, созданный вызовом [`con.cursor()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.cursor), будет иметь атрибут [`connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.connection), который ссылается на *con*:10851086```pycon1087>>> con = sqlite3.connect(":memory:")1088>>> cur = con.cursor()1089>>> cur.connection == con1090True1091>>> con.close()1092```10931094#### `description`10951096Атрибут только для чтения, предоставляющий имена столбцов последнего запроса. Для сохранения совместимости с Python DB API он возвращает кортеж из 7 элементов для каждого столбца, где последние шесть элементов каждого кортежа равны `None`.10971098Он также устанавливается для операторов `SELECT`, не имеющих подходящих строк.10991100#### `lastrowid`11011102Атрибут только для чтения, предоставляющий идентификатор строки последней вставленной строки. Он обновляется только после успешного выполнения операторов `INSERT` или `REPLACE` с использованием метода [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute). Для других операторов, после [`executemany()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executemany) или [`executescript()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executescript), или если вставка не удалась, значение `lastrowid` остаётся без изменений. Начальное значение `lastrowid` равно `None`.11031104> **Примечание**1105>1106> Вставки в таблицы `WITHOUT ROWID` не записываются.11071108Изменено в версии 3.6: Добавлена поддержка оператора `REPLACE`.11091110#### `rowcount`11111112Атрибут только для чтения, предоставляющий количество изменённых строк для операторов `INSERT`, `UPDATE`, `DELETE` и `REPLACE`; для других операторов, включая запросы CTE, равно `-1`. Он обновляется только методами [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute) и [`executemany()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executemany) после завершения выполнения оператора. Это означает, что для обновления `rowcount` необходимо извлечь все результирующие строки.11131114#### `row_factory`11151116Управляет представлением строки, извлечённой из этого `Cursor`. Если `None`, строка представляется как [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple). Может быть установлен во встроенный [`sqlite3.Row`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Row); или в [вызываемый объект](https://python-all.ru/3.14/glossary.html#term-callable), который принимает два аргумента: объект `Cursor` и `tuple` значений строки, и возвращает пользовательский объект, представляющий строку SQLite.11171118По умолчанию равно тому, на что был установлен [`Connection.row_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.row_factory) при создании `Cursor`. Присваивание этому атрибуту не влияет на `Connection.row_factory` родительского соединения.11191120См. [Как создавать и использовать фабрики строк](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howto-row-factory) для получения дополнительных сведений.11211122Изменено в версии 3.14.6: Удаление атрибута `row_factory` больше не допускается.11231124### Объекты Row11251126#### `class sqlite3.Row`11271128Экземпляр `Row` служит высокооптимизированным [`row_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.row_factory) для объектов [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection). Он поддерживает итерацию, проверку равенства, [`len()`](https://python-all.ru/3.14/library/functions.html#len) и доступ через [отображение](https://python-all.ru/3.14/glossary.html#term-mapping) по имени столбца и индексу.11291130Два объекта `Row` считаются равными, если они имеют одинаковые имена столбцов и значения.11311132См. [Как создавать и использовать фабрики строк](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-howto-row-factory) для получения дополнительных сведений.11331134#### `keys()`11351136Возвращает [`list`](https://python-all.ru/3.14/library/stdtypes.html#list) имен столбцов в виде [`strings`](https://python-all.ru/3.14/library/stdtypes.html#str). Сразу после запроса это первый элемент каждого кортежа в [`Cursor.description`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.description).11371138Изменено в версии 3.5: Добавлена поддержка срезов.11391140### Объекты Blob11411142#### `class sqlite3.Blob`11431144Добавлено в версии 3.12.11451146Экземпляр `Blob` – это [объект, похожий на файл](https://python-all.ru/3.14/glossary.html#term-file-like-object), который может читать и записывать данные в BLOB SQLite. Вызывайте [`len(blob)`](https://python-all.ru/3.14/library/functions.html#len), чтобы получить размер (количество байт) BLOB. Используйте индексы и [срезы](https://python-all.ru/3.14/glossary.html#term-slice) для прямого доступа к данным BLOB.11471148Используйте `Blob` как [менеджер контекста](https://python-all.ru/3.14/glossary.html#term-context-manager), чтобы гарантировать закрытие дескриптора BLOB после использования.11491150```python1151con = sqlite3.connect(":memory:")1152con.execute("CREATE TABLE test(blob_col blob)")1153con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")11541155# Записать данные в blob с помощью двух операций записи:1156with con.blobopen("test", "blob_col", 1) as blob:1157 blob.write(b"hello, ")1158 blob.write(b"world.")1159 # Изменить первый и последний байты нашего blob1160 blob[0] = ord("H")1161 blob[-1] = ord("!")11621163# Прочитать содержимое нашего blob1164with con.blobopen("test", "blob_col", 1) as blob:1165 greeting = blob.read()11661167print(greeting) # выводит "b'Hello, world!'"1168con.close()1169```11701171#### `close()`11721173Закрыть BLOB.11741175После этого BLOB станет непригодным для использования. При любой дальнейшей попытке работы с BLOB будет возбуждено исключение [`Error`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Error) (или подкласса).11761177#### `read(length=-1, /)`11781179Читает *length* байт данных из BLOB с текущей позиции смещения. При достижении конца BLOB возвращаются данные до EOF. Если *length* не указан или отрицателен, `read()` читает до конца BLOB.11801181#### `write(data, /)`11821183Записывает *data* в BLOB по текущему смещению. Эта функция не может изменить длину BLOB. Запись за пределами конца BLOB вызывает [`ValueError`](https://python-all.ru/3.14/library/exceptions.html#ValueError).11841185#### `tell()`11861187Возвращает текущую позицию доступа к BLOB.11881189#### `seek(offset, origin=os.SEEK_SET, /)`11901191Устанавливает текущую позицию доступа к BLOB в *offset*. Аргумент *origin* по умолчанию равен [`os.SEEK_SET`](https://python-all.ru/3.14/library/os.html#os.SEEK_SET) (абсолютное позиционирование BLOB). Другие значения *origin*: [`os.SEEK_CUR`](https://python-all.ru/3.14/library/os.html#os.SEEK_CUR) (смещение относительно текущей позиции) и [`os.SEEK_END`](https://python-all.ru/3.14/library/os.html#os.SEEK_END) (смещение относительно конца BLOB).11921193### Объекты PrepareProtocol11941195#### `class sqlite3.PrepareProtocol`11961197Единственное назначение типа PrepareProtocol – служить протоколом адаптации в стиле [**PEP 246**](https://python-all.ru/3.14/library/sqlite3.html) для объектов, которые могут [адаптироваться](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-conform) к [встроенным типам SQLite](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-types).11981199### Исключения12001201Иерархия исключений определена в DB-API 2.0 ([**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html)).12021203#### `exception sqlite3.Warning`12041205Это исключение в настоящее время не возбуждается модулем `sqlite3`, но может быть возбуждено приложениями, использующими `sqlite3`, например, если пользовательская функция усекает данные при вставке. `Warning` является подклассом [`Exception`](https://python-all.ru/3.14/library/exceptions.html#Exception).12061207#### `exception sqlite3.Error`12081209Базовый класс для остальных исключений этого модуля. Используйте его, чтобы перехватывать все ошибки одним оператором [`except`](https://python-all.ru/3.14/reference/compound_stmts.html#except). `Error` является подклассом [`Exception`](https://python-all.ru/3.14/library/exceptions.html#Exception).12101211Если исключение возникло внутри библиотеки SQLite, к нему добавляются следующие два атрибута:12121213#### `sqlite_errorcode`12141215Числовой код ошибки из [SQLite API](https://python-all.ru/3.14/library/sqlite3.html)12161217Добавлено в версии 3.12.12181219#### `sqlite_errorname`12201221Символическое имя числового кода ошибки из [SQLite API](https://python-all.ru/3.14/library/sqlite3.html)12221223Добавлено в версии 3.12.12241225#### `exception sqlite3.InterfaceError`12261227Исключение возбуждается при неправильном использовании низкоуровневого C API SQLite. Другими словами, если это исключение возбуждено, вероятно, это указывает на ошибку в модуле `sqlite3`. `InterfaceError` является подклассом [`Error`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Error).12281229#### `exception sqlite3.DatabaseError`12301231Исключение возбуждается для ошибок, связанных с базой данных. Оно служит базовым исключением для нескольких типов ошибок базы данных. Возбуждается только неявно через специализированные подклассы. `DatabaseError` является подклассом [`Error`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Error).12321233#### `exception sqlite3.DataError`12341235Исключение возбуждается для ошибок, вызванных проблемами с обрабатываемыми данными, например, числовые значения вне допустимого диапазона или слишком длинные строки. `DataError` является подклассом [`DatabaseError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError).12361237#### `exception sqlite3.OperationalError`12381239Исключение возникает при ошибках, связанных с работой базы данных, и не обязательно подконтрольных программисту. Например, не найден путь к базе данных или не удалось выполнить транзакцию. `OperationalError` является подклассом [`DatabaseError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError).12401241#### `exception sqlite3.IntegrityError`12421243Исключение возникает при нарушении реляционной целостности базы данных, например, при неудачной проверке внешнего ключа. Оно является подклассом [`DatabaseError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError).12441245#### `exception sqlite3.InternalError`12461247Исключение возникает, когда SQLite сталкивается с внутренней ошибкой. Если оно возникло, это может указывать на проблему с используемой библиотекой SQLite. `InternalError` является подклассом [`DatabaseError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError).12481249#### `exception sqlite3.ProgrammingError`12501251Исключение возникает при ошибках программирования API `sqlite3`, например, при указании неверного количества привязок к запросу или при попытке работы с закрытым [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection). `ProgrammingError` является подклассом [`DatabaseError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError).12521253#### `exception sqlite3.NotSupportedError`12541255Исключение возникает, если метод или API базы данных не поддерживается используемой библиотекой SQLite. Например, установка *deterministic* в `True` в [`create_function()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.create_function), если базовая библиотека SQLite не поддерживает детерминированные функции. `NotSupportedError` является подклассом [`DatabaseError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.DatabaseError).12561257### Типы SQLite и Python12581259SQLite изначально поддерживает следующие типы: `NULL`, `INTEGER`, `REAL`, `TEXT`, `BLOB`.12601261Следующие типы Python можно передавать в SQLite без каких-либо проблем:12621263| Тип Python | Тип SQLite |1264| --- | --- |1265| `None` | `NULL` |1266| [`int`](https://python-all.ru/3.14/library/functions.html#int) | `INTEGER` |1267| [`float`](https://python-all.ru/3.14/library/functions.html#float) | `REAL` |1268| [`str`](https://python-all.ru/3.14/library/stdtypes.html#str) | `TEXT` |1269| [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) | `BLOB` |12701271Так по умолчанию типы SQLite преобразуются в типы Python:12721273| Тип SQLite | Тип Python |1274| --- | --- |1275| `NULL` | `None` |1276| `INTEGER` | [`int`](https://python-all.ru/3.14/library/functions.html#int) |1277| `REAL` | [`float`](https://python-all.ru/3.14/library/functions.html#float) |1278| `TEXT` | зависит от [`text_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.text_factory), по умолчанию [`str`](https://python-all.ru/3.14/library/stdtypes.html#str) |1279| `BLOB` | [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes) |12801281Система типов модуля `sqlite3` расширяема двумя способами: можно сохранять дополнительные типы Python в базе данных SQLite через [адаптеры объектов](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-adapters) и можно позволить модулю `sqlite3` преобразовывать типы SQLite в типы Python через [конвертеры](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-converters).12821283### Адаптеры и конвертеры по умолчанию (устарело)12841285> **Примечание**1286>1287> Адаптеры и конвертеры по умолчанию устарели начиная с Python 3.12. Вместо них используйте [рецепты адаптеров и конвертеров](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-adapter-converter-recipes) и настраивайте их под свои нужды.12881289Устаревшие адаптеры и конвертеры по умолчанию включают:12901291- Адаптер для объектов [`datetime.date`](https://python-all.ru/3.14/library/datetime.html#datetime.date) в [`strings`](https://python-all.ru/3.14/library/stdtypes.html#str) в формате [ISO 8601](https://python-all.ru/3.14/library/sqlite3.html).1292- Адаптер для объектов [`datetime.datetime`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime) в строки в формате ISO 8601.1293- Конвертер для [объявленных](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-converters) типов "date" в объекты [`datetime.date`](https://python-all.ru/3.14/library/datetime.html#datetime.date).1294- Конвертер для объявленных типов "timestamp" в объекты [`datetime.datetime`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime). Дробные части будут усечены до 6 цифр (точность до микросекунд).12951296> **Примечание**1297>1298> Конвертер "timestamp" по умолчанию игнорирует смещения UTC в базе данных и всегда возвращает наивный объект [`datetime.datetime`](https://python-all.ru/3.14/library/datetime.html#datetime.datetime). Чтобы сохранить смещения UTC в метках времени, либо оставьте конвертеры отключёнными, либо зарегистрируйте конвертер с учётом смещения через [`register_converter()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.register_converter).12991300Устарело с версии 3.12.13011302### Интерфейс командной строки13031304Модуль `sqlite3` можно запускать как скрипт, используя ключ [`-m`](https://python-all.ru/3.14/using/cmdline.html#cmdoption-m) интерпретатора, чтобы получить простую оболочку SQLite. Сигнатура аргументов следующая:13051306```python1307python -m sqlite3 [-h] [-v] [filename] [sql]1308```13091310Введите `.quit` или CTRL-D, чтобы выйти из оболочки.13111312#### `-h, --help`13131314Вывести справку CLI.13151316#### `-v, --version`13171318Вывести версию нижележащей библиотеки SQLite.13191320Добавлено в версии 3.12.13211322## Практические руководства13231324### Как использовать плейсхолдеры для подстановки значений в SQL-запросы13251326Обычно в SQL-операциях нужно использовать значения из переменных Python. Однако следует остерегаться использования строковых операций Python для сборки запросов, так как они уязвимы для [атак с помощью SQL-инъекций](https://python-all.ru/3.14/library/sqlite3.html). Например, злоумышленник может просто закрыть одинарную кавычку и добавить `OR TRUE` для выборки всех строк:13271328```python1329>>> # Никогда не делайте этого – это небезопасно!1330>>> symbol = input()1331' OR TRUE; --1332>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol1333>>> print(sql)1334SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'1335>>> cur.execute(sql)1336```13371338Вместо этого используйте подстановку параметров DB-API. Чтобы вставить переменную в строку запроса, используйте плейсхолдер в строке и подставьте фактические значения в запрос, передав их в виде [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple) значений вторым аргументом метода [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute) курсора.13391340SQL-выражение может использовать один из двух видов плейсхолдеров: вопросительные знаки (стиль qmark) или именованные плейсхолдеры (именованный стиль). Для стиля qmark *параметры* должны быть [последовательностью](https://python-all.ru/3.14/glossary.html#term-sequence), длина которой должна совпадать с количеством плейсхолдеров, иначе возникает [`ProgrammingError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.ProgrammingError). Для именованного стиля *параметры* должны быть экземпляром [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict) (или подкласса), который должен содержать ключи для всех именованных параметров; любые лишние элементы игнорируются. Вот пример обоих стилей:13411342```python1343con = sqlite3.connect(":memory:")1344cur = con.execute("CREATE TABLE lang(name, first_appeared)")13451346# Это стиль с именованными параметрами, используемый с executemany():1347data = (1348 {"name": "C", "year": 1972},1349 {"name": "Fortran", "year": 1957},1350 {"name": "Python", "year": 1991},1351 {"name": "Go", "year": 2009},1352)1353cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)13541355# Это стиль с вопросительными знаками, используемый в запросе SELECT:1356params = (1972,)1357cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)1358print(cur.fetchall())1359con.close()1360```13611362> **Примечание**1363>1364> Числовые плейсхолдеры [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html) *не* поддерживаются. Если их использовать, они будут интерпретироваться как именованные.13651366### Как адаптировать пользовательские типы Python к значениям SQLite13671368SQLite изначально поддерживает только ограниченный набор типов данных. Чтобы хранить пользовательские типы Python в базах данных SQLite, *адаптируйте* их к одному из [типов Python, которые SQLite понимает изначально](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-types).13691370Существует два способа адаптации объектов Python к типам SQLite: разрешить объекту адаптироваться самостоятельно или использовать *вызываемый адаптер*. Последний имеет приоритет над первым. Для библиотеки, которая предоставляет пользовательский тип, может иметь смысл разрешить этому типу адаптироваться самостоятельно. Для разработчика приложений может быть более разумным взять прямой контроль, зарегистрировав собственные функции-адаптеры.13711372#### Как создавать адаптируемые объекты13731374Предположим, у нас есть класс `Point`, представляющий пару координат `x` и `y` в декартовой системе координат. Пара координат будет храниться в базе данных в виде текстовой строки с точкой с запятой в качестве разделителя. Это можно реализовать, добавив метод `__conform__(self, protocol)`, который возвращает адаптированное значение. Объект, передаваемый в *протокол*, будет иметь тип [`PrepareProtocol`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.PrepareProtocol).13751376```python1377class Point:1378 def __init__(self, x, y):1379 self.x, self.y = x, y13801381 def __conform__(self, protocol):1382 if protocol is sqlite3.PrepareProtocol:1383 return f"{self.x};{self.y}"13841385con = sqlite3.connect(":memory:")1386cur = con.cursor()13871388cur.execute("SELECT ?", (Point(4.0, -3.2),))1389print(cur.fetchone()[0])1390con.close()1391```13921393#### Как регистрировать вызываемые адаптеры13941395Другая возможность – создать функцию, которая преобразует объект Python в тип, совместимый с SQLite. Затем эту функцию можно зарегистрировать с помощью [`register_adapter()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.register_adapter).13961397```python1398class Point:1399 def __init__(self, x, y):1400 self.x, self.y = x, y14011402def adapt_point(point):1403 return f"{point.x};{point.y}"14041405sqlite3.register_adapter(Point, adapt_point)14061407con = sqlite3.connect(":memory:")1408cur = con.cursor()14091410cur.execute("SELECT ?", (Point(1.0, 2.5),))1411print(cur.fetchone()[0])1412con.close()1413```14141415### Как преобразовывать значения SQLite в пользовательские типы Python14161417Написание адаптера позволяет преобразовывать *из* пользовательских типов Python *в* значения SQLite. Чтобы иметь возможность преобразовывать *из* значений SQLite *в* пользовательские типы Python, мы используем *конвертеры*.14181419Вернемся к классу `Point`. Мы сохраняли координаты x и y, разделенные точкой с запятой, в виде строк в SQLite.14201421Сначала определим функцию-конвертер, которая принимает строку в качестве параметра и создает из нее объект `Point`.14221423> **Примечание**1424>1425> Функции-конвертеры **всегда** получают объект [`bytes`](https://python-all.ru/3.14/library/stdtypes.html#bytes), независимо от нижележащего типа данных SQLite.14261427```python1428def convert_point(s):1429 x, y = map(float, s.split(b";"))1430 return Point(x, y)1431```14321433Теперь нужно указать `sqlite3`, когда следует преобразовывать данное значение SQLite. Это делается при подключении к базе данных с помощью параметра *detect\_types* функции [`connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect). Есть три варианта:14341435- Неявный: установите *detect\_types* в [`PARSE_DECLTYPES`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.PARSE_DECLTYPES)1436- Явный: установите *detect\_types* в [`PARSE_COLNAMES`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.PARSE_COLNAMES)1437- Оба: установите *detect\_types* в `sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES`. Имена столбцов имеют приоритет над объявленными типами.14381439Следующий пример иллюстрирует неявный и явный подходы:14401441```python1442class Point:1443 def __init__(self, x, y):1444 self.x, self.y = x, y14451446 def __repr__(self):1447 return f"Point({self.x}, {self.y})"14481449def adapt_point(point):1450 return f"{point.x};{point.y}"14511452def convert_point(s):1453 x, y = list(map(float, s.split(b";")))1454 return Point(x, y)14551456# Зарегистрировать адаптер и конвертер1457sqlite3.register_adapter(Point, adapt_point)1458sqlite3.register_converter("point", convert_point)14591460# 1) Разбор с использованием объявленных типов1461p = Point(4.0, -3.2)1462con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)1463cur = con.execute("CREATE TABLE test(p point)")14641465cur.execute("INSERT INTO test(p) VALUES(?)", (p,))1466cur.execute("SELECT p FROM test")1467print("with declared types:", cur.fetchone()[0])1468cur.close()1469con.close()14701471# 2) Разбор с использованием имён столбцов1472con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)1473cur = con.execute("CREATE TABLE test(p)")14741475cur.execute("INSERT INTO test(p) VALUES(?)", (p,))1476cur.execute('SELECT p AS "p [point]" FROM test')1477print("with column names:", cur.fetchone()[0])1478cur.close()1479con.close()1480```14811482### Рецепты адаптеров и конвертеров14831484В этом разделе приведены рецепты для распространенных адаптеров и конвертеров.14851486```python1487import datetime as dt1488import sqlite314891490def adapt_date_iso(val):1491 """Адаптировать datetime.date к дате в формате ISO 8601."""1492 return val.isoformat()14931494def adapt_datetime_iso(val):1495 """Преобразует datetime.datetime в дату ISO 8601 без часового пояса."""1496 return val.replace(tzinfo=None).isoformat()14971498def adapt_datetime_epoch(val):1499 """Преобразует datetime.datetime в метку времени Unix."""1500 return int(val.timestamp())15011502sqlite3.register_adapter(dt.date, adapt_date_iso)1503sqlite3.register_adapter(dt.datetime, adapt_datetime_iso)1504sqlite3.register_adapter(dt.datetime, adapt_datetime_epoch)15051506def convert_date(val):1507 """Преобразует дату ISO 8601 в объект datetime.date."""1508 return dt.date.fromisoformat(val.decode())15091510def convert_datetime(val):1511 """Преобразует дату и время ISO 8601 в объект datetime.datetime."""1512 return dt.datetime.fromisoformat(val.decode())15131514def convert_timestamp(val):1515 """Преобразует метку времени Unix (эпоха) в объект datetime.datetime."""1516 return dt.datetime.fromtimestamp(int(val))15171518sqlite3.register_converter("date", convert_date)1519sqlite3.register_converter("datetime", convert_datetime)1520sqlite3.register_converter("timestamp", convert_timestamp)1521```15221523### Как использовать сокращенные методы соединения15241525Используя методы [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.execute), [`executemany()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.executemany) и [`executescript()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.executescript) класса [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection), можно писать код более кратко, поскольку не нужно явно создавать (часто излишние) объекты [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor). Вместо этого объекты `Cursor` создаются неявно, и эти сокращенные методы возвращают объекты курсора. Таким образом, можно выполнить оператор `SELECT` и сразу перебирать его результаты, используя всего один вызов на объекте `Connection`.15261527```python1528# Создаёт и заполняет таблицу.1529con = sqlite3.connect(":memory:")1530con.execute("CREATE TABLE lang(name, first_appeared)")1531data = [1532 ("C++", 1985),1533 ("Objective-C", 1984),1534]1535con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)15361537# Выводит содержимое таблицы.1538for row in con.execute("SELECT name, first_appeared FROM lang"):1539 print(row)15401541print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")15421543# close() не является сокращённым методом и не вызывается автоматически.1544# Объект соединения следует закрывать вручную.1545con.close()1546```15471548### Как использовать менеджер контекста соединения15491550Объект [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection) можно использовать как менеджер контекста, который автоматически фиксирует или откатывает открытые транзакции при выходе из тела менеджера контекста. Если тело оператора [`with`](https://python-all.ru/3.14/reference/compound_stmts.html#with) завершается без исключений, транзакция фиксируется. Если фиксация не удалась или тело оператора `with` вызывает необработанное исключение, транзакция откатывается. Если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) равно `False`, после фиксации или отката неявно открывается новая транзакция.15511552Если при выходе из тела оператора `with` нет открытой транзакции или если [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) равно `True`, менеджер контекста ничего не делает.15531554> **Примечание**1555>1556> Менеджер контекста не открывает неявно новую транзакцию и не закрывает соединение. Если нужен закрывающий менеджер контекста, рассмотрите использование [`contextlib.closing()`](https://python-all.ru/3.14/library/contextlib.html#contextlib.closing).15571558```python1559con = sqlite3.connect(":memory:")1560con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")15611562# При успешном выполнении con.commit() вызывается автоматически.1563with con:1564 con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))15651566# con.rollback() вызывается после завершения блока with с исключением,1567# исключение по-прежнему возбуждается и должно быть перехвачено.1568try:1569 with con:1570 con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))1571except sqlite3.IntegrityError:1572 print("couldn't add Python twice")15731574# Объект Connection, используемый как контекстный менеджер, только фиксирует или откатывает транзакции,1575# поэтому объект соединения следует закрывать вручную.1576con.close()1577```15781579### Как работать с SQLite URI15801581Некоторые полезные приёмы работы с URI:15821583- Открыть базу данных в режиме только для чтения:15841585```pycon1586>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)1587>>> con.execute("CREATE TABLE readonly(data)")1588Traceback (most recent call last):1589OperationalError: attempt to write a readonly database1590>>> con.close()1591```15921593- Не создавать неявно новый файл базы данных, если он ещё не существует; будет вызвано исключение [`OperationalError`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.OperationalError), если не удаётся создать новый файл:15941595```pycon1596>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)1597Traceback (most recent call last):1598OperationalError: unable to open database file1599```16001601- Создать общую именованную базу данных в памяти:16021603```python1604db = "file:mem1?mode=memory&cache=shared"1605con1 = sqlite3.connect(db, uri=True)1606con2 = sqlite3.connect(db, uri=True)1607with con1:1608 con1.execute("CREATE TABLE shared(data)")1609 con1.execute("INSERT INTO shared VALUES(28)")1610res = con2.execute("SELECT data FROM shared")1611assert res.fetchone() == (28,)16121613con1.close()1614con2.close()1615```16161617Дополнительную информацию об этой возможности, включая список параметров, можно найти в [документации SQLite по URI](https://python-all.ru/3.14/library/sqlite3.html).16181619### Как создавать и использовать фабрики строк16201621По умолчанию `sqlite3` представляет каждую строку как [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple). Если `tuple` не подходит, можно использовать класс [`sqlite3.Row`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Row) или собственную [`row_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.row_factory).16221623Хотя `row_factory` существует как атрибут как у [`Cursor`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor), так и у [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection), рекомендуется устанавливать [`Connection.row_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.row_factory), чтобы все курсоры, созданные из соединения, использовали одну и ту же фабрику строк.16241625`Row` обеспечивает индексированный и регистронезависимый доступ к столбцам по имени с минимальным потреблением памяти и влиянием на производительность по сравнению с `tuple`. Чтобы использовать `Row` в качестве фабрики строк, присвойте его атрибуту `row_factory`:16261627```pycon1628>>> con = sqlite3.connect(":memory:")1629>>> con.row_factory = sqlite3.Row1630```16311632Теперь запросы возвращают объекты `Row`:16331634```pycon1635>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")1636>>> row = res.fetchone()1637>>> row.keys()1638['name', 'radius']1639>>> row[0] # Доступ по индексу.1640'Earth'1641>>> row["name"] # Доступ по имени.1642'Earth'1643>>> row["RADIUS"] # Имена столбцов нечувствительны к регистру.164463781645>>> con.close()1646```16471648> **Примечание**1649>1650> Предложение `FROM` можно опустить в операторе `SELECT`, как в примере выше. В таких случаях SQLite возвращает одну строку со столбцами, определёнными выражениями, например литералами, с заданными псевдонимами `expr AS alias`.16511652Можно создать собственную [`row_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.row_factory), которая возвращает каждую строку как [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict), с сопоставлением имён столбцов со значениями:16531654```python1655def dict_factory(cursor, row):1656 fields = [column[0] for column in cursor.description]1657 return {key: value for key, value in zip(fields, row)}1658```16591660При её использовании запросы теперь возвращают `dict` вместо `tuple`:16611662```pycon1663>>> con = sqlite3.connect(":memory:")1664>>> con.row_factory = dict_factory1665>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):1666... print(row)1667{'a': 1, 'b': 2}1668>>> con.close()1669```16701671Следующая фабрика строк возвращает [именованный кортеж](https://python-all.ru/3.14/glossary.html#term-named-tuple):16721673```python1674from collections import namedtuple16751676def namedtuple_factory(cursor, row):1677 fields = [column[0] for column in cursor.description]1678 cls = namedtuple("Row", fields)1679 return cls._make(row)1680```16811682`namedtuple_factory()` можно использовать следующим образом:16831684```pycon1685>>> con = sqlite3.connect(":memory:")1686>>> con.row_factory = namedtuple_factory1687>>> cur = con.execute("SELECT 1 AS a, 2 AS b")1688>>> row = cur.fetchone()1689>>> row1690Row(a=1, b=2)1691>>> row[0] # Индексный доступ.169211693>>> row.b # Доступ через атрибут.169421695>>> con.close()1696```16971698С некоторыми изменениями приведённый рецепт можно адаптировать для использования [`dataclass`](https://python-all.ru/3.14/library/dataclasses.html#dataclasses.dataclass) или любого другого пользовательского класса вместо [`namedtuple`](https://python-all.ru/3.14/library/collections.html#collections.namedtuple).16991700### Как работать с текстовыми кодировками, отличными от UTF-817011702По умолчанию `sqlite3` использует [`str`](https://python-all.ru/3.14/library/stdtypes.html#str) для адаптации значений SQLite с типом данных `TEXT`. Это хорошо работает для текста в кодировке UTF-8, но может давать сбой для других кодировок и некорректного UTF-8. Можно использовать собственную [`text_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.text_factory) для обработки таких случаев.17031704Из-за [гибкой типизации](https://python-all.ru/3.14/library/sqlite3.html) SQLite нередко можно встретить столбцы таблиц с типом данных `TEXT`, содержащие не-UTF-8 кодировки или даже произвольные данные. Для демонстрации предположим, что у нас есть база данных с текстом в кодировке ISO-8859-2 (Latin-2), например таблица записей чешско-английского словаря. Предположим, у нас есть экземпляр [`Connection`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection) `con`, подключённый к этой базе данных. Мы можем декодировать текст в Latin-2, используя эту [`text_factory`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.text_factory):17051706```python1707con.text_factory = lambda data: str(data, encoding="latin2")1708```17091710Для некорректного UTF-8 или произвольных данных, хранящихся в столбцах таблицы `TEXT`, можно использовать следующий приём, заимствованный из [Unicode HOWTO](https://python-all.ru/3.14/howto/unicode.html#unicode-howto):17111712```python1713con.text_factory = lambda data: str(data, errors="surrogateescape")1714```17151716> **Примечание**1717>1718> API модуля `sqlite3` не поддерживает строки, содержащие суррогаты.17191720> **См. также**1721>1722> [HOWTO по Unicode](https://python-all.ru/3.14/howto/unicode.html#unicode-howto)17231724## Пояснение17251726### Управление транзакциями17271728`sqlite3` предлагает несколько методов управления тем, открываются и закрываются ли транзакции базы данных, когда и как это происходит. [Управление транзакциями через атрибут autocommit](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-autocommit) рекомендуется, тогда как [Управление транзакциями через атрибут isolation\_level](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-isolation-level) сохраняет поведение, существовавшее до Python 3.12.17291730#### Управление транзакциями через атрибут `autocommit`17311732Рекомендуемый способ управления поведением транзакций – через атрибут [`Connection.autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit), который желательно устанавливать с помощью параметра *autocommit* функции [`connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect).17331734Рекомендуется устанавливать *autocommit* в `False`, что подразумевает управление транзакциями в соответствии с [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html). Это означает:17351736- `sqlite3` гарантирует, что транзакция всегда открыта, поэтому [`connect()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.connect), [`Connection.commit()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.commit) и [`Connection.rollback()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.rollback) неявно откроют новую транзакцию (сразу после закрытия ожидающей для последних двух). `sqlite3` использует операторы `BEGIN DEFERRED` при открытии транзакций.1737- Транзакции должны быть явно зафиксированы с помощью `commit()`.1738- Транзакции должны быть явно отменены с помощью `rollback()`.1739- Неявный откат выполняется, если база данных [`close()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.close) при наличии незафиксированных изменений.17401741Установите *autocommit* в `True`, чтобы включить [режим автокоммита SQLite](https://python-all.ru/3.14/library/sqlite3.html). В этом режиме [`Connection.commit()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.commit) и [`Connection.rollback()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.rollback) не имеют эффекта. Обратите внимание, что режим автокоммита SQLite отличается от атрибута [`Connection.autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit), совместимого с [**PEP 249**](https://python-all.ru/3.14/library/sqlite3.html); используйте [`Connection.in_transaction`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.in_transaction), чтобы запросить низкоуровневый режим автокоммита SQLite.17421743Установите *autocommit* в [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL), чтобы оставить управление транзакциями на атрибут [`Connection.isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level). См. [Управление транзакциями через атрибут isolation\_level](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-isolation-level) для получения дополнительной информации.17441745#### Управление транзакциями через атрибут `isolation_level`17461747> **Примечание**1748>1749> Рекомендуемый способ управления транзакциями – через атрибут [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit). См. [Управление транзакциями через атрибут autocommit](https://python-all.ru/3.14/library/sqlite3.html#sqlite3-transaction-control-autocommit).17501751Если [`Connection.autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit) установлен в [`LEGACY_TRANSACTION_CONTROL`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.LEGACY_TRANSACTION_CONTROL) (по умолчанию), поведение транзакций управляется с помощью атрибута [`Connection.isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level). В противном случае `isolation_level` не имеет эффекта.17521753Если атрибут соединения [`isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level) не равен `None`, новые транзакции неявно открываются перед тем, как [`execute()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.execute) и [`executemany()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executemany) выполняют `INSERT`, `UPDATE`, `DELETE` или `REPLACE` операторы; для других операторов неявная обработка транзакций не выполняется. Используйте методы [`commit()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.commit) и [`rollback()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.rollback) для фиксации и отката ожидающих транзакций соответственно. Можно выбрать базовое [поведение транзакций SQLite](https://python-all.ru/3.14/library/sqlite3.html) – то есть, будут ли и какого типа `BEGIN` операторы `sqlite3` выполняет неявно – через атрибут `isolation_level`.17541755Если [`isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level) установлен в `None`, транзакции вообще не открываются неявно. Это оставляет базовую библиотеку SQLite в [режиме автокоммита](https://python-all.ru/3.14/library/sqlite3.html), но также позволяет пользователю выполнять собственную обработку транзакций с помощью явных SQL-операторов. Режим автокоммита базовой библиотеки SQLite можно запросить с помощью атрибута [`in_transaction`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.in_transaction).17561757Метод [`executescript()`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Cursor.executescript) неявно фиксирует любую ожидающую транзакцию перед выполнением данного SQL-скрипта, независимо от значения [`isolation_level`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.isolation_level).17581759Изменено в версии 3.6: `sqlite3` ранее неявно фиксировал открытую транзакцию перед DDL операторами. Теперь это не так.17601761Изменено в версии 3.12: Рекомендуемый способ управления транзакциями теперь – через атрибут [`autocommit`](https://python-all.ru/3.14/library/sqlite3.html#sqlite3.Connection.autocommit).1762