sqlite3 — Интерфейс DB-API 2.0 для баз данных SQLite

sqlite3 — интерфейс DB-API 2.0 для баз данных SQLite

2024-07-12

sqlite3 — Интерфейс DB-API 2.0 для баз данных SQLite — Документация Python 3.12.4

`sqlite3`— Интерфейс DB-API 2.0 для баз данных SQLite
sqlite3 — интерфейс DB-API 2.0 для баз данных SQLite.

Исходный код: Библиотека/sqlite3/ Расположение исходного кода：Lib/sqlite3/

SQLite — это библиотека C, которая предоставляет легкую дисковую базу данных, не требующую отдельного серверного процесса и позволяющую получать доступ к базе данных с помощью нестандартного варианта языка запросов SQL. Некоторые приложения могут использовать SQLite для внутреннего хранения данных. Также возможно создать прототип приложения с использованием SQLite, а затем перенести код в более крупную базу данных, например PostgreSQL или Oracle.
SQLite — это библиотека языка C, которая предоставляет облегченную дисковую базу данных, не требующую отдельного серверного процесса и позволяющую получать доступ к базе данных с использованием нестандартного варианта языка запросов SQL. Некоторые приложения могут использовать SQLite для внутреннего хранения данных. Кроме того, вы можете использовать SQLite для создания прототипа приложения, а затем перенести код в большую базу данных, например PostgreSQL или Oracle.

Thesqlite3Модуль был написан Герхардом Херингом. Он предоставляет интерфейс SQL, совместимый со спецификацией DB-API 2.0, описаннойПЭП 249и требует SQLite 3.7.15 или более поздней версии.
модуль sqlite3 Автор Герхард Херинг. Он предоставляет интерфейс SQL, соответствующий спецификации DB-API 2.0, описанной в PEP 249, и требует SQLite версии 3.7.15 или выше.

Этот документ состоит из четырех основных разделов: Этот документ в основном включает следующие четыре основных раздела.

Руководствоучит, как пользоватьсяsqlite3модуль.РуководствоЧасть учит, как использовать модуль sqlite3.
Ссылкаописывает классы и функции, которые определяет этот модуль.
Ссылаться наВ разделе описаны классы и функции, определенные этим модулем.
Руководства по использованиюподробно описывается, как выполнять конкретные задачи.
Руководство по эксплуатацииВ разделах подробно описано, как решать конкретные задачи.
Объяснениепредоставляет подробную информацию о контроле транзакций.
объяснятьВ этом разделе представлено углубленное введение в базовые знания по управлению транзакциями.

Смотрите также

https://www.sqlite.org

Веб-страница SQLite; документация описывает синтаксис и доступные типы данных для поддерживаемого диалекта SQL.
Веб-страница SQLite; ее документация описывает синтаксис поддерживаемых диалектов SQL и доступные типы данных.

Учебник SQLУчебник по SQL

Учебное пособие, справочник и примеры для изучения синтаксиса SQL.
Учебники, ссылки и примеры для изучения синтаксиса SQL.

ПЭП 249- Спецификация API базы данных 2.0 PEP 249 - Спецификация API базы данных 2.0

PEP, автор Марк-Андре Лембург. PEP, автор Марк-Андре Лембург.

РуководствоРуководство

В этом уроке вы создадите базу данных фильмы Монти Пайтон используя базовыйsqlite3функциональность. Это предполагает фундаментальное понимание концепций баз данных, включаякурсорыитранзакции.
В этом уроке вы будете использовать базовые функции sqlite3 для создания базы данных о фильмах Монти Пайтон. В этом руководстве предполагается, что у вас есть базовые знания о концепциях баз данных, включая курсоры и транзакции.

Во-первых, нам нужно создать новую базу данных и открыть соединение с базой данных, чтобы разрешитьsqlite3работать с ним. Звонитеsqlite3.подключить()для создания подключения к базе данныхtutorial.dbв текущем рабочем каталоге, неявное его создание, если он не существует:
Во-первых, нам нужно создать новую базу данных и открыть соединение с ней, чтобы sqlite3 мог с ней взаимодействовать. Вызовите sqlite3.connect(), чтобы создать соединение с базой данных Tutorial.db в текущем рабочем каталоге, неявно и аккуратно создав его автоматически, если база данных не существует:


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

ВозвращенныйСвязьобъектconпредставляет собой подключение к базе данных на диске.
Возвращенный объект Connection (в данном случае с именем con) представляет собой соединение с базой данных на диске.

Для того, чтобы выполнять операторы SQL иизвлечение результатов из SQL-запросов, нам понадобится использовать курсор базы данных. Вызовcon.курсор()чтобы создатьКурсор:
Чтобы выполнять операторы SQL и получать результаты SQL-запросов, нам нужно использовать курсоры базы данных. Вызовите con.cursor(), чтобы создать курсор:

cur = con.cursor()

Теперь, когда у нас есть подключение к базе данных и курсор, мы можем создать таблицу базы данных.movieсо столбцами для заголовка, года выпуска и оценки обзора. Для простоты мы можем просто использовать имена столбцов в объявлении таблицы – благодарягибкая типизацияособенность SQLite, указание типов данных необязательно. ВыполнитеCREATE TABLEзаявление по телефонутекущ.выполнить(...):
Теперь, когда у нас есть подключение к базе данных и курсор, мы можем создать таблицу базы данных с именем Movie с такими столбцами, как название, год выпуска и оценка по отзывам. Чтобы упростить задачу, мы можем использовать имена столбцов непосредственно в объявлении таблицы — указание типа данных не является обязательным из-за функции гибкой типизации SQLite. Выполните оператор CREATE TABLE, вызвав cur.execute(...):

cur.execute("CREATE TABLE movie(title, year, score)")

Мы можем проверить, что новая таблица была создана, запросивsqlite_masterтаблица, встроенная в SQLite, которая теперь должна содержать запись дляmovieопределение таблицы (см.Таблица схемдля получения подробной информации). Выполните этот запрос, вызвавтекущ.выполнить(...), присвоить результатres, и позвонитеres.fetchone()для извлечения результирующей строки:
Мы можем убедиться, что новая таблица создана, запросив встроенную таблицу SQLite sqlite_master, которая теперь должна содержать записи для определения таблицы фильмов (подробности см. в таблице схемы). Выполните запрос, вызвав cur.execute(...), присвойте результаты res и вызовите res.fetchone(), чтобы получить строки результатов:

>>>


>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)

Мы видим, что таблица была создана, так как запрос возвращаеткортежсодержащий имя таблицы. Если мы запросимsqlite_masterдля несуществующей таблицыspam, res.fetchone()вернетсяNone:
Мы видим, что таблица была успешно создана, поскольку запрос вернул кортеж, содержащий имя таблицы. Если мы запросим sqlite_master несуществующую таблицу (например, спам), res.fetchone() вернет None.

>>>


>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True

Теперь добавьте две строки данных, предоставленных в виде литералов SQL, выполнив командуINSERTзаявление, еще раз призвавтекущ.выполнить(...):
Теперь добавьте две строки данных, предоставленных в виде литералов SQL, выполнив оператор INSERT (снова вызвав cur.execute(...)):


cur.execute("""
    INSERT INTO movie VALUES
        ('Monty Python and the Holy Grail', 1975, 8.2),
        ('And Now for Something Completely Different', 1971, 7.5)
""")

TheINSERTоператор неявно открывает транзакцию, которую необходимо зафиксировать перед сохранением изменений в базе данных (см.Контроль транзакцийдля получения подробной информации). Вызовcon.commit()на объекте соединения для фиксации транзакции:
Оператор INSERT неявно и автоматически запускает транзакцию, которую необходимо зафиксировать перед сохранением изменений в базе данных (подробности см. в разделе «Управление транзакциями»). Вызовите con.commit() для объекта соединения, чтобы зафиксировать транзакцию:

con.commit()

Мы можем проверить, что данные были вставлены правильно, выполнивSELECTзапрос. Используйте теперь уже знакомыйтекущ.выполнить(...)чтобы присвоить результатres, и позвонитеres.fetchall()чтобы вернуть все полученные строки:
Мы можем убедиться, что данные были вставлены правильно, выполнив запрос SELECT. Назначьте результаты res, используя теперь знакомый метод cur.execute(...) и вызовите res.fetchall(), чтобы вернуть все строки результатов:

>>>


>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]

Результатом являетсясписокиз двухtuples, по одному на строку, каждый из которых содержит эту строкуscoreценить.
Результатом является список из двух кортежей, по одному для каждой строки, и каждый кортеж содержит значение оценки для этой строки.

Теперь вставьте еще три строки, вызвавcur.executemany(...):
Теперь вставьте еще три строки данных, вызвав cur.executemany(...):


data = [
    ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
    ("Monty Python's The Meaning of Life", 1983, 7.5),
    ("Monty Python's Life of Brian", 1979, 8.0),
]
cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
con.commit()  # Remember to commit the transaction after executing INSERT.

Заметить, что?заполнители используются для привязкиdataк запросу. Всегда используйте заполнители вместоформатирование строкидля привязки значений Python к операторам SQL, чтобы избежатьАтаки с использованием SQL-инъекций(видетьКак использовать заполнители для привязки значений в SQL-запросахБольше подробностей).
Обратите внимание, что заполнитель ? используется для привязки данных к запросу. Всегда используйте заполнители вместо форматирования строк для привязки значений Python к операторам SQL, чтобы избежать атак SQL-инъекций (более подробную информацию см. в разделе «Как связать значения с помощью заполнителей в запросах SQL»).

Мы можем проверить, что новые строки были вставлены, выполнивSELECTзапрос, на этот раз перебирающий результаты запроса:
Мы можем убедиться, что новая строка была вставлена, выполнив запрос SELECT, на этот раз мы будем перебирать результаты запроса:

>>>


>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
...     print(row)
(1971, 'And Now for Something Completely Different')
(1975, 'Monty Python and the Holy Grail')
(1979, "Monty Python's Life of Brian")
(1982, 'Monty Python Live at the Hollywood Bowl')
(1983, "Monty Python's The Meaning of Life")

Каждая строка состоит из двух элементов.кортежиз(year, title), соответствующие столбцам, выбранным в запросе.
Каждая строка представляет собой кортеж, содержащий два элемента (год, заголовок), соответствующий столбцу, выбранному в запросе.

Наконец, убедитесь, что база данных записана на диск, вызвавcon.закрыть()чтобы закрыть существующее соединение, открыть новое, создать новый курсор, а затем выполнить запрос к базе данных:
Наконец, позвонивcon.close() чтобы закрыть существующее соединение с базой данных и убедиться, что база данных записана на диск. Затем откройте новое соединение, создайте новый курсор и запросите базу данных, чтобы убедиться, что данные были успешно записаны.

>>>


>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
>>> title, year = res.fetchone()
>>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
>>> new_con.close()

Теперь вы создали базу данных SQLite с помощьюsqlite3модуль, вставлял данные и извлекал из них значения несколькими способами.
вы сейчас использовалиsqlite3 Модуль создает базу данных SQLite, вставляет и извлекает из нее данные различными способами [Получить? 】Значение.

Смотрите такжеСмотрите также

Руководства по использованиюдля дальнейшего чтения: Как связать значения с помощью заполнителей в SQL-запросах:
- Как использовать заполнители для привязки значений в SQL-запросах
  Как связать значения с помощью заполнителей в SQL-запросах:
- Как адаптировать пользовательские типы Python к значениям SQLite
  Как адаптировать пользовательский тип Python к значению SQLite:
- Как преобразовать значения SQLite в пользовательские типы Python
  Как преобразовать значение SQLite в пользовательский тип Python:
- Как использовать менеджер контекста подключения
  Как использовать менеджер контекста соединения:
- Как создавать и использовать фабрики строк
  Как создавать и использовать фабрики строк:
Объяснениедля получения подробной информации о контроле транзакций.
Подробное объяснение управления транзакциями:

СсылкаОписание параметра：

Функции модуля

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)

Открыть соединение с базой данных SQLite. Эта функция используется для открытия соединения с базой данных SQLite.

Параметры:

база данных (объект, похожий на путь) – Путь к файлу базы данных, который нужно открыть. Можно передать":memory:"чтобы создатьБаза данных SQLite существует только в памятии открыть к нему подключение.database (path-like object)
база данных (объект, подобный пути) — Это путь к файлу базы данных, который нужно открыть.Вы можете пройти":memory:"чтобы создать базу данных SQLite в памяти и открыть базу данных .database(объект, подобный пути), подключенный к ней.
тайм-аут (плавать) – Сколько секунд соединение должно ждать, прежде чем поднятьOperationalErrorкогда таблица заблокирована. Если другое соединение открывает транзакцию для изменения таблицы, эта таблица будет заблокирована до тех пор, пока транзакция не будет зафиксирована. По умолчанию пять секунды.timeout (float) — Соединение бросается, когда стол заблокированOperationalError Сколько секунд нужно подождать до этого. Если другое соединение открывает транзакцию для изменения таблицы, таблица будет заблокирована до тех пор, пока транзакция не будет зафиксирована. Значение по умолчанию — пять секунд.
определить_типы (инт) – Контролировать, следует ли и как типы данных нетизначально поддерживается SQLiteищутся для преобразования в типы Python с использованием преобразователей, зарегистрированных с помощьюрегистр_конвертер(). Установите его в любую комбинацию (используя|, побитовое или)PARSE_DECLTYPESиPARSE_COLNAMESчтобы это стало возможным. Названия столбцов имеет приоритет надобъявленные типы если установлены оба флага. Типы не могут быть обнаружены для сгенерированных полей (например,max(data)), даже когдаопределить_типыпараметр установлен;улбудет возвращено вместо этого. По умолчанию (0), определение типа отключено.
detect_types (int)— Определяет, будут ли и если да, то как типы данных, которые SQLite не поддерживает изначально, для использования.register_converter() Зарегистрированные преобразователи преобразуют их в типы Python.установите его наPARSE_DECLTYPESиPARSE_COLNAMESлюбая комбинация (с использованием побитового или| ), чтобы включить эту функцию.Если установлены оба флага, тоСписок будет иметь приоритет надзаявление тип.Для сгенерированных регионов эти типы не могут быть обнаружены (например,max(data)), даже если установленоdetect_typesвместо этого он вернет параметры;str тип. По умолчанию (0) определение типа отключено.

Вставьте это сюда
В этом английском абзаце о ком говорится «на кого смотрят снизу вверх»?
В этом английском абзаце предметом «смотрят» являются те «типы данных, которые не поддерживаются SQLite изначально (типы данных, не поддерживаемые SQLite изначально)».Это предложение означает, что, используяregister_converter() Зарегистрированные преобразователи для поиска и преобразования типов данных, которые изначально не поддерживаются SQLite, в типы Python. Итак, субъекты — это те конкретные типы данных, которые необходимо найти и преобразовать.

уровень_изоляции (ул | Никто) – Управление поведением обработки устаревших транзакций. См.Уровень_изоляции_подключенияиУправление транзакциями через атрибут isolation_levelдля получения дополнительной информации. Может быть"DEFERRED"(по умолчанию),"EXCLUSIVE"или"IMMEDIATE"; илиNoneдля отключения открытия транзакций неявно. Не имеет никакого эффекта, еслиConnection.автокоммитустановлен наLEGACY_TRANSACTION_CONTROL(по умолчанию).
isolation_level(Строка | Нет) – Контролируйте поведение обработки устаревших транзакций.Для получения дополнительной информации см.Connection.isolation_levelи «пройтиisolation_levelСделка по контролю над имуществом». Может быть"DEFERRED"(значение по умолчанию),"EXCLUSIVE"или"IMMEDIATE";или установитеNone чтобы отключить неявное открытие транзакций неявно.Пока неConnection.autocommitУстановить какLEGACY_TRANSACTION_CONTROL(по умолчанию), в противном случае этот параметр не имеет никакого эффекта.
проверить_такую_тему (бул) - ЕслиTrue(по умолчанию),ОшибкаПрограммированиябудет вызвано, если соединение с базой данных используется потоком, отличным от того, который его создал. ЕслиFalse, доступ к соединению может осуществляться в нескольких потоках; операции записи могут потребовать от пользователя сериализации, чтобы избежать повреждения данных. См.потокобезопасностьЧтобы получить больше информации.
check_same_thread(логическое значение) – Если установленоTrue(по умолчанию), будет возникать, когда соединение с базой данных используется потоком, отличным от потока, который его создал.ProgrammingError аномальный.Если установлено значениеFalse , доступ к соединению разрешен нескольким потокам, но пользователям может потребоваться сериализовать (непрерывно) операции записи самостоятельно, чтобы избежать повреждения данных;Для получения дополнительной информации см.threadsafetyинструкция о.
фабрика (Связь) – Пользовательский подклассСвязьдля создания соединения, если оно не установлено по умолчаниюСвязьсорт.
factory(Связь) – Если не использовать значение по умолчаниюConnectionкласс, укажите пользовательскийConnection Подкласс для создания соединения. Этот параметр позволяет настроить поведение подключения к базе данных в соответствии с конкретными потребностями или расширениями.
кэшированные_заявления (инт) – Количество утверждений, которыеsqlite3следует внутренне кэшировать для этого соединения, чтобы избежать накладных расходов на разбор. По умолчанию 128 операторов.
cached_statements(инт) – sqlite3 Число операторов, которые должны быть кэшированы внутри для этого соединения, чтобы избежать накладных расходов на синтаксический анализ. По умолчанию кэшируется 128 операторов. Этот параметр позволяет настроить размер кэша для оптимизации производительности или использования памяти.
ури (бул) – Если установлено значениеTrue, база данныхинтерпретируется как URI с путем к файлу и необязательной строкой запроса. Схема частьдолженбыть"file:", и путь может быть относительным или абсолютным. Строка запроса позволяет передавать параметры в SQLite, позволяя различныеКак работать с URI SQLite.
uri(бул) – Если установленоTrue,ноdatabase Интерпретируется как универсальный идентификатор ресурса (URI) с путем к файлу и дополнительной строкой запроса. Часть схемы URIдолжен является «файл:», путь может быть относительным или абсолютным. Строки запроса позволяют передавать параметры в SQLite, обеспечивая различные способы работы с URI SQLite. Это позволяет использовать более сложные параметры подключения к базе данных, такие как установка режима только для чтения, указание размера кэша и т. д.
автокоммит (бул) - КонтрольПЭП 249Поведение обработки транзакций. СмотретьConnection.автокоммитиУправление транзакциями через атрибут autocommitЧтобы получить больше информации.автокоммитв настоящее время по умолчаниюLEGACY_TRANSACTION_CONTROL. Значение по умолчанию изменится наFalseв будущей версии Python.
autocommit(бул) – Контролируйте поведение обработки транзакций в соответствии с PEP 249.Для получения дополнительной информации см.Connection.autocommit и «Управление транзакциями с помощью атрибута autocommit». в настоящий момент,autocommitПо умолчанию установлено значениеLEGACY_TRANSACTION_CONTROL , что означает, что он соответствует устаревшему поведению управления транзакциями спецификации API базы данных Python (PEP 249).Однако в будущей версии Python значение по умолчанию изменится наFalseЭто означает, что транзакции не фиксируются автоматически по умолчанию и требуют от пользователя явного контроля начала и окончания транзакции.

Пожалуйста, обрати внимание,*Параметры используются в определениях функций как разделители между позиционными и ключевыми аргументами, что означаетautocommitВсе параметры после этого должны быть параметрами ключевого слова.

Тип возврата:Тип возврата：

Связь

Поднимаетаудит событий sqlite3.connectс аргументомdatabase.
sqlite3.connect: Когда используешьdatabaseПараметры, выдаваемые при подключении к базе данных.

Поднимаетаудит событий sqlite3.connect/handleс аргументомconnection_handle.
sqlite3.connect/handle: Когда дескриптор соединения (connection_handle) выбрасывается при его создании.

Изменено в версии 3.4: Добавленоурипараметр.
В версии 3.4: добавленоuriПараметр, позволяющий указать файл базы данных в формате URI.

Изменено в версии 3.7:база данныхтеперь также может бытьобъект, похожий на путь, а не только строка.
В версии 3.7:databaseПараметры теперь могут быть объектами, похожими на путь, а не просто строками.

Изменено в версии 3.10: Добавленоsqlite3.connect/handleаудиторское мероприятие.
В версии 3.10: добавленоsqlite3.connect/handleСобытие аудита, которое запускается при создании дескриптора соединения.

Изменено в версии 3.12: Добавленоавтокоммитпараметр.
В версии 3.12: добавленоautocommitПараметры, которые позволяют более точно контролировать поведение автоматической фиксации транзакций.

sqlite3.полное_заявление(заявление)

ВозвращатьсяTrueесли строказаявлениепохоже, содержит один или несколько полных операторов SQL. Никакой синтаксической проверки или разбора не выполняется, за исключением проверки отсутствия незакрытых строковых литералов и завершения оператора точкой с запятой.
если строкаstatementкажется, содержит один или несколько полных операторов SQL, затем вернитеTrue . Никакая проверка синтаксиса или синтаксический анализ не выполняются, кроме проверки отсутствия незамкнутых строковых литералов и того, что оператор заканчивается точкой с запятой.

Например:Пример

>>>


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

Эта функция может быть полезна во время ввода командной строки, чтобы определить, является ли введенный текст полным оператором SQL или требуется дополнительный ввод перед вызовом.выполнять().
Эта функция может быть полезна при вводе в командной строке, чтобы определить, выглядит ли введенный текст как полный оператор SQL, или при вызовеexecute()Требуется ли дополнительный ввод раньше.

Видетьrunsource()вLib/sqlite3/__main__.pyдля реального использования.
В практических приложениях вы можете обратиться кLib/sqlite3/__main__.pyсерединаrunsource()функцию, чтобы понять ее использование.

sqlite3.enable_callback_tracebacks(флаг, /)

Включить или отключить трассировки обратного вызова. По умолчанию вы не получите никаких трассировок в пользовательских функциях, агрегатах, конвертерах, обратных вызовах авторизатора и т. д. Если вы хотите отладить их, вы можете вызвать эту функцию с помощьюфлагустановлен вTrue. После этого вы получите трассировки от обратных вызовов наsys.stderr. ИспользоватьFalseчтобы снова отключить функцию.
Включите или отключите отслеживание обратных вызовов. По умолчанию вы не получите никаких обратных трассировок в пользовательских функциях, агрегатных функциях, конвертерах, обратных вызовах авторизации и т. д.Если вы хотите их отладить, вы можете вызвать эту функцию и заменитьflagУстановить какTrue .После этого вы сможетеsys.stderr Получите информацию трассировки из обратного вызова.использоватьFalseчтобы снова отключить эту функцию.

Примечание

Ошибки в пользовательских функциях обратного вызова регистрируются как невозбуждаемые исключения. Используйтенеподъемный обработчик крюкадля самоанализа неудачного обратного вызова.
Ошибки в обратных вызовах пользовательских функций регистрируются как неперехватываемые исключения. Используйте невозможный обработчик перехвата для выполнения самоанализа неудачных обратных вызовов.

Это означает, что когда возникают ошибки в обратных вызовах пользовательских функций SQLite (таких как агрегатные функции, скалярные функции и т. д.), эти ошибки не выбрасываются, как обычные исключения Python, и могут быть перехвачены блоками try-Exception. Вместо этого они захватываются модулем SQLite или sqlite3 Python и каким-либо образом протоколируются (обычно записываются в журнал или стандартный вывод ошибок), но не прерывают выполнение программы (если только ошибка не является очень серьезной).

Чтобы проверять и отлаживать эти неперехватываемые исключения, вы можете настроить «обработчик неперехватываемых перехватчиков». Этот обработчик представляет собой функцию, которую Python вызывает при возникновении неперехваченного исключения, передавая информацию об исключении в качестве параметра. Таким образом, вы можете написать код в функции процессора для регистрации или проверки этих исключений, чтобы помочь диагностировать проблему.

Обратите внимание, что конкретная реализация может различаться в зависимости от версии Python и деталей реализации модуля sqlite3. Поэтому рекомендуется обратиться к последней версии документации Python или документации модуля sqlite3, чтобы узнать, как настроить и использовать обработчик неперехватываемого перехвата.

**sqlite3.регистр_адаптер(тип, адаптер, /)**

Зарегистрируйтеадаптер отзывнойдля адаптации типа Pythonтипв тип SQLite. Адаптер вызывается с объектом Python типатипв качестве единственного аргумента и должен возвращать значениетип, который SQLite понимает изначально.
Зарегистрируйте вызываемый объект **адаптера** для преобразования Pythontype Тип адаптирован к типу, который SQLite может понимать изначально.Эта функция адаптера занимаетtypeОбъект типа вызывается как единственный аргумент и должен возвращать значение типа, который SQLite изначально поддерживает.

Следует отметить, что «typetype» может немного ввести в заблуждение, поскольку обычно мы не ссылаемся на встроенный в Pythontype Объекты (то есть сами типы) хранятся непосредственно в базе данных. Чаще всего мы хотим адаптировать объекты Python (которые могут быть экземплярами пользовательских типов) в формат, который может хранить SQLite.Однако, если понимать это предложение буквально, если вам действительно нужно иметь дело сtypeсамого объекта (хотя на практике это случается редко), вам потребуется написать адаптер для преобразования его в некоторую форму, которую может хранить SQLite, например, в строку, представляющую имя типа.

Однако более распространенным вариантом использования являются пользовательские типы Python или встроенные типы, такие какdatetime、decimal.Decimalи т. д.) писать адаптеры, чтобы их можно было правильно хранить и извлекать из базы данных SQLite.

Например, если у вас есть собственный класс PythonMyClassи хотите сохранить его экземпляр в базе данных SQLite, вы можете написать адаптер для преобразования экземпляра этого класса в строку (или другой тип), которая может быть сохранена в SQLite, а затем написать преобразователь для преобразования. Преобразовать эту строку обратно кMyClassпример.

Однако по этому вопросу, если вы просто хотите иметь дело с Pythontypeобъект (т. е. метаданные типа), вы можете написать адаптер для возврата имени типа (в виде строки), но обычно это не обычная практика хранения объектов в базе данных.

sqlite3.регистр_конвертер(имя_типа, преобразователь, /)

Зарегистрируйтесьпреобразователь отзывнойдля преобразования объектов SQLite типаимя_типав объект Python определенного типа. Конвертер вызывается для всех значений SQLite типаимя_типа; он передаетсябайтыобъект и должен возвращать объект нужного типа Python. Проконсультируйтесь с параметромопределить_типыизсоединять()для получения информации о том, как работает определение типа.
Зарегистрируйте вызываемый объект **converter** для преобразования типов SQLite вtypename Преобразует объект в объект Python определенного типа.Для всех типовtypenameЭтот преобразователь вызывается для любого значения SQLite, которое он получает;bytes объект в качестве аргумента и должен возвращать объект требуемого типа Python.О том, как работает определение типа, см.connect()Функциональныйdetect_typesпараметр.

Примечание:имя_типаи имя типа в вашем запросе сопоставляются без учета регистра.
Уведомление：typenameИмя типа в запросе при сопоставлении не учитывает регистр.

Константы модуля

sqlite3.LEGACY_TRANSACTION_CONTROL

Наборавтокоммитк этой константе, чтобы выбрать старый стиль (до Python 3.12) поведения управления транзакциями. СмотритеУправление транзакциями через атрибут isolation_levelЧтобы получить больше информации.
Воляautocommit Установите эту константу, чтобы выбрать поведение управления транзакциями в старом стиле (до Python 3.12).Для получения дополнительной информации, пожалуйста, обратитесь к разделу «Передатьisolation_levelСделки контроля свойств».

sqlite3.PARSE_COLNAMES

Передайте это значение флагаопределить_типыпараметрсоединять()для поиска функции преобразователя с использованием имени типа, полученного из имени столбца запроса, в качестве ключа словаря преобразователя. Имя типа должно быть заключено в квадратные скобки ([]).
Передайте значение этого флагаconnect()Функциональныйdetect_types Параметр для поиска функции преобразователя путем запроса разрешенного имени типа в имени столбца в качестве ключа словаря преобразователя. Имена типов должны быть заключены в квадратные скобки ([]).

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

Этот флаг можно комбинировать сPARSE_DECLTYPESиспользуя|Оператор (побитовое ИЛИ).
Этот флаг можно использовать|(побитовый ИЛИ) оператор ИPARSE_DECLTYPESВ сочетании с.

sqlite3.PARSE_DECLTYPES

Передайте это значение флагаопределить_типыпараметрсоединять()для поиска функции-конвертера, использующей объявленные типы для каждого столбца. Типы объявляются при создании таблицы базы данных.sqlite3будет искать функцию-конвертер, используя первое слово объявленного типа в качестве ключа словаря-конвертера. Например:
Передайте значение этого флагаconnect()Функциональныйdetect_types Параметры для поиска функции преобразователя, используя объявленный тип каждого столбца в базе данных. Эти типы объявляются при создании таблицы базы данных.sqlite3 Функция конвертера будет искаться с использованием первого слова объявленного типа в качестве ключа словаря конвертера. Например:


CREATE TABLE test(
   i integer primary key,  ! will look up a converter named "integer"
   p point,                ! will look up a converter named "point"
   n number(10)            ! will look up a converter named "number"
 )

Этот флаг можно комбинировать сPARSE_COLNAMESиспользуя|Оператор (побитовое ИЛИ).

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORE

Флаги, которые должны быть возвращеныавторизатор_обратный вызов отзывнойпереданоConnection.set_authorizer(), чтобы указать, что:
Перейти кConnection.set_authorizer()изauthorizer_callbackФлаги, которые вызываемая функция должна вернуть, чтобы указать:

Доступ разрешен (SQLITE_OK), доступ разрешен (SQLITE_OK）
Оператор SQL должен быть прерван с ошибкой (SQLITE_DENY)
Выполнение оператора SQL должно быть прервано с ошибкой (SQLITE_DENY）
Эту колонку следует рассматривать какNULLценить (SQLITE_IGNORE)
Столбцы следует рассматривать как значения NULL (SQLITE_IGNORE）

sqlite3.apilevel

Строковая константа, указывающая поддерживаемый уровень DB-API. Требуется DB-API. Жестко закодировано в"2.0".
Эти две строковые константыsqlite3Определенные в модулях, они соответствуют спецификации API базы данных Python (DB-API).

sqlite3.стиль параметров

Строковая константа, указывающая тип форматирования маркера параметра, ожидаемыйsqlite3Модуль. Требуется DB-API. Жестко закодирован в"qmark".
Эта строковая константа определяетsqlite3 Тип форматирования маркера параметра, ожидаемый модулем. Этого требует спецификация DB-API (интерфейс прикладного программирования базы данных).Это жестко запрограммировано как"qmark", означает, что при построении SQL-запросов маркеры параметров должны обозначаться вопросительными знаками (?).

Примечание

ThenamedТакже поддерживается стиль параметров DB-API.

sqlite3.sqlite_версия

Номер версии библиотеки SQLite времени выполнения какнить.
Номер версии библиотеки времени выполнения SQLite, выраженный в строковой форме.

sqlite3.sqlite_version_info

Номер версии библиотеки SQLite времени выполнения каккортежизцелые числа.
Номер версии библиотеки времени выполнения SQLite, выраженный в виде кортежа целых чисел.

sqlite3.безопасность потоков

Целочисленная константа, требуемая DB-API 2.0, указывающая уровень безопасности потокаsqlite3поддерживает модуль. Этот атрибут устанавливается на основе значения по умолчаниюрежим потоковой передачибазовая библиотека SQLite скомпилирована с помощью. Режимы потоков SQLite:
Целочисленная константа, требуемая DB-API 2.0, указывающаяsqlite3 Уровень безопасности потоков, поддерживаемый модулем. Это свойство устанавливается в соответствии с режимом потоковой обработки по умолчанию, с которым была скомпилирована базовая библиотека SQLite. Режимы потоков SQLite включают в себя:

Однопоточный: В этом режиме все мьютексы отключены, и SQLite небезопасно использовать более чем в одном потоке одновременно.
Однопоточный: в этом режиме все мьютексы отключены, и SQLite небезопасно использовать несколькими потоками одновременно.
Многопотоковый: В этом режиме SQLite может безопасно использоваться несколькими потоками при условии, что ни одно соединение с базой данных не используется одновременно в двух или более потоках.
Многопоточность: в этом режиме SQLite может безопасно использоваться несколькими потоками при условии, что ни одно соединение с базой данных не используется одновременно двумя или более потоками.
Сериализованный: В сериализованном режиме SQLite может безопасно использоваться несколькими потоками без ограничений.
Сериализованный: в сериализованном режиме SQLite может безопасно использоваться несколькими потоками без каких-либо ограничений.

Сопоставления режимов потоков SQLite с уровнями потокобезопасности DB-API 2.0 следующие:
Сопоставление режима потока SQLite с уровнем безопасности потока DB-API 2.0 выглядит следующим образом:

Режим потоковой передачи SQLite	потокобезопасность	SQLITE_THREADSAFE	Значение DB-API 2.0
однопоточный	0	0	Потоки не могут совместно использовать модуль
многопотоковый	1	2	Потоки могут совместно использовать модуль, но не соединения.
сериализованный	3	1	Потоки могут совместно использовать модуль, соединения и курсоры.

Изменено в версии 3.11: Установитьпотокобезопасностьдинамически, а не жестко запрограммировать его1.

sqlite3.версия

Номер версии этого модуля какнить. Это не версия библиотеки SQLite.
Номер версии этого модуля, выраженный в виде строки.этотнетНомер версии библиотеки SQLite.

Не рекомендуется с версии 3.12, будет удалено в версии 3.14: Эта константа использовалась для отображения номера версииpysqliteпакет, сторонняя библиотека, которая использовалась для внесения изменений вsqlite3. Сегодня это не имеет никакого смысла и практической ценности.
Устарело с версии 3.12 и будет удалено в версии 3.14: эта константа использовалась для отраженияpysqliteНомер версии пакета,pysqliteЭто сторонняя библиотека, загруженная в апстримsqlite3 Зафиксируйте изменения. Сейчас это не имеет ни реального смысла, ни практической ценности.

sqlite3.версия_информация

Номер версии этого модуля каккортежизцелые числа. Это не версия библиотеки SQLite.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE

sqlite3.SQLITE_DBCONFIG_DQS_DDL

sqlite3.SQLITE_DBCONFIG_DQS_DML

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP

sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

Эти константы используются дляConnection.setconfig()иполучитьконфигурацию()методы.
Эти константы используютсяConnection.setconfig()иgetconfig()метод.

Доступность этих констант зависит от версии SQLite, с которой был скомпилирован Python.
Доступность этих констант зависит от версии SQLite, с которой был скомпилирован SQLite Python.

Добавлено в версии 3.12.

Документация SQLite: Параметры конфигурации подключения к базе данных

Объекты соединения

сортsqlite3.Подключение

Каждая открытая база данных SQLite представленаConnectionобъект, который создан с использованиемsqlite3.подключить(). Их главная цель - созданиеКурсоробъекты иКонтроль транзакций.

Смотрите также

Подключение к базе данных SQLite имеет следующие атрибуты и методы:

курсор(фабрика=Курсор)

Создать и вернутьКурсоробъект. Метод курсора принимает один необязательный параметрфабрика. Если указано, это должно бытьотзывнойвозвращающий экземплярКурсорили его подклассы.
Создает и возвращаетCursorобъект.cursorМетод принимает необязательный одиночный параметрfactory .Если этот параметр указан, это должен быть вызываемый объект, который возвращаетCursorили экземпляр его подкласса.

blobopen(стол, столбец, ряд, /, , только для чтения=Ложь, имя='главный'*)

ОткройтеКаплядескриптор существующего BLOB-объекта.

Параметры:

стол (ул) – Имя таблицы, в которой находится объект blob.
Имя таблицы, содержащей данные BLOB.
столбец (ул) – Имя столбца, в котором находится blob.
Имя столбца, содержащего данные BLOB.
ряд (ул) – Имя строки, в которой расположен объект blob.
Имя строки (или, точнее, идентификатор строки), содержащей данные BLOB.
только для чтения (бул) - Установлен вTrueесли blob должен быть открыт без прав записи. По умолчаниюFalse.
Если установлено значение True, это означает, что BLOB-объект следует открывать без разрешения на запись. По умолчанию установлено значение False, что разрешает чтение и запись.
имя (ул) – Имя базы данных, в которой находится blob. По умолчанию"main".
Имя базы данных, содержащей данные BLOB. По умолчанию используется «main», которое является именем базы данных по умолчанию в SQLite.

Поднимает:

OperationalError– При попытке открыть блоб вWITHOUT ROWIDстол.
При попытке безРЯДПроисходит при открытии данных BLOB в таблице идентификаторов.

Тип возврата:

Капля

Примечание

Размер BLOB-объекта нельзя изменить с помощьюКаплякласс. Используйте функцию SQLzeroblobдля создания объекта фиксированного размера.

Добавлено в версии 3.11.

совершить()

Зафиксируйте любую ожидающую транзакцию в базе данных. ЕслиавтокоммитявляетсяTrue, или нет открытой транзакции, этот метод ничего не делает. ЕслиautocommitявляетсяFalse, новая транзакция неявно открывается, если ожидающая транзакция была зафиксирована этим методом.
Зафиксируйте все ожидающие транзакции в базе данных.еслиautocommit Если принимает значение True или открытая транзакция отсутствует, этот метод не выполняет никаких операций.еслиautocommitимеет значение False, и этот метод фиксирует ожидающую транзакцию, новая транзакция будет запущена неявно.

откат()

Откат к началу любой ожидающей транзакции. ЕслиавтокоммитявляетсяTrue, или нет открытой транзакции, этот метод ничего не делает. ЕслиautocommitявляетсяFalse, новая транзакция неявно открывается, если ожидающая транзакция была откачена этим методом.
Откат к началу всех ожидающих транзакций.еслиautocommit Если принимает значение True или открытая транзакция отсутствует, этот метод не выполняет никаких операций.еслиautocommitимеет значение False, и этот метод откатывает ожидающую транзакцию, новая транзакция будет запущена неявно.

закрывать()

Закройте соединение с базой данных. ЕслиавтокоммитявляетсяFalse, любая ожидающая транзакция неявно откатывается. ЕслиautocommitявляетсяTrueилиLEGACY_TRANSACTION_CONTROL, неявный контроль транзакций не выполняется. Убедитесь, чтосовершить()перед закрытием, чтобы не потерять ожидающие изменения.
Закройте соединение с базой данных.еслиautocommit Если значение равно False, любые ожидающие транзакции будут неявно отменены.еслиautocommitверно илиLEGACY_TRANSACTION_CONTROL (устаревший контроль транзакций), неявный контроль транзакций выполняться не будет.Перед закрытием обязательно позвонитеcommit()чтобы не потерять ожидающие изменения.

выполнять(sql, параметры=(), /)

Создать новыйКурсоробъект и вызоввыполнять()на нем с даннымsqlипараметры. Верните новый объект курсора.
создать новыйCursorвозразить и позвонитьexecute()метод, передавая заданныйsql операторы и параметры.верните это новоеCursorобъект.

выполнитьмногие(sql, параметры, /)

Создать новыйКурсоробъект и вызоввыполнитьмногие()на нем с даннымsqlипараметры. Верните новый объект курсора.
создать новыйCursorвозразить и позвонитьexecutemany()метод, передавая заданныйsql Операторы и последовательности параметров. Это позволяет одновременно выполнять несколько наборов параметров.верните это новоеCursorобъект.

выполнитьскрипт(sql_скрипт, /)

Создать новыйКурсоробъект и вызоввыполнитьскрипт()на нем с даннымsql_скрипт. Верните новый объект курсора.
создать новыйCursorвозразить и позвонитьexecutescript() метод, передавая заданный SQL-скрипт. Это позволяет выполнять в сценарии несколько операторов SQL, разделенных точкой с запятой.верните это новоеCursorобъект.

создать_функцию(имя, нарг, функц, , детерминированный=Ложь*)

Создать или удалить пользовательскую функцию SQL.
Создайте или удалите пользовательскую функцию SQL.

Параметры:

имя (ул) – Имя функции SQL.
name(str) – имя функции SQL.
нарг (инт) – Количество аргументов, которые может принять функция SQL. Если-1, может принимать любое количество аргументов.
narg (int) – количество аргументов, которые может принять функция SQL. Если -1, это означает, что он может принимать любое количество аргументов.
функц (перезвонить| Нет) – Аотзывнойкоторый вызывается при вызове функции SQL. Вызываемый должен возвращатьтип, изначально поддерживаемый SQLite. Установлен вNoneдля удаления существующей функции SQL.
func (обратный вызов | Нет) — этот вызываемый объект (обратный вызов) будет выполняться при вызове функции SQL. Этот вызываемый объект должен возвращать тип, который изначально поддерживается SQLite. Если установлено значение «Нет», существующие функции SQL удаляются.
детерминированный (бул) - ЕслиTrue, созданная функция SQL помечается какдетерминированный, что позволяет SQLite выполнять дополнительные оптимизации.
deterministic(bool) — если True, созданная функция SQL помечается как детерминированная, что позволяет SQLite выполнять дополнительную оптимизацию.

Поднимает:

НеподдерживаемаяОшибка- Еслидетерминированныйиспользуется с версиями SQLite старше 3.8.3.

Изменено в версии 3.8: Добавленодетерминированныйпараметр.

Пример:

>>>


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

создать_агрегат(имя, n_arg, агрегатный_класс)

Создать или удалить пользовательскую агрегатную функцию SQL.
Создайте или удалите определяемую пользователем агрегатную функцию SQL.

Параметры:

имя (ул) – Имя агрегатной функции SQL.
name(str) – имя агрегатной функции SQL.
n_arg (инт) – Количество аргументов, которые может принять агрегатная функция SQL. Если-1, может принимать любое количество аргументов.
Число параметров, которые может принять агрегатная функция SQL. Если -1, это означает, что он может принимать любое количество аргументов.
агрегатный_класс (сорт| Нет) –

Класс должен реализовывать следующие методы:
Класс должен реализовать следующие методы:
- step(): добавить строку в агрегат.
- finalize(): Вернуть окончательный результат агрегата кактип, изначально поддерживаемый SQLite.
  finalize(): этот метод используется для возврата окончательного результата агрегирования.
Число аргументов, которыеstep()метод должен принять контролируетсяn_arg.
step()Количество параметров, которые должен принимать метод, определяется выражениемn_argконтроль.

Установлен вNoneдля удаления существующей агрегатной функции SQL.
Установить какNoneудалить существующие агрегатные функции SQL.

Пример:


class MySum:
    def __init__(self):
        self.count = 0
 
    def step(self, value):
        self.count += value
 
    def finalize(self):
        return self.count
 
con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.execute("CREATE TABLE test(i)")
cur.execute("INSERT INTO test(i) VALUES(1)")
cur.execute("INSERT INTO test(i) VALUES(2)")
cur.execute("SELECT mysum(i) FROM test")
print(cur.fetchone()[0])
 
con.close()

создать_окно_функцию(имя, num_params, агрегатный_класс, /)

Создать или удалить пользовательскую агрегатную оконную функцию.

Параметры:

имя (ул) – Имя агрегатной оконной функции SQL, которую нужно создать или удалить.
num_params (инт) – Количество аргументов, которые может принять функция окна агрегата SQL. Если-1, может принимать любое количество аргументов.
агрегатный_класс (сорт| Нет) –

Класс, который должен реализовывать следующие методы:
- step(): Добавить строку в текущее окно.
- value(): Возврат текущего значения агрегата.
- inverse(): Удалить строку из текущего окна.
- finalize(): Вернуть окончательный результат агрегата кактип, изначально поддерживаемый SQLite.
Число аргументов, которыеstep()иvalue()методы должны принимать контролируетсяnum_params.

Установлен вNoneдля удаления существующей агрегатной оконной функции SQL.

Поднимает:

НеподдерживаемаяОшибка– При использовании с версией SQLite старше 3.25.0, которая не поддерживает агрегатные оконные функции.

Добавлено в версии 3.11.

Пример:

# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """Add a row to the current window."""
        self.count += value

    def value(self):
        """Return the current value of the aggregate."""
        return self.count

    def inverse(self, value):
        """Remove a row from the current window."""
        self.count -= value

    def finalize(self):
        """Return the final value of the aggregate.

        Any clean-up actions should be placed here.
        """
        return self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
values = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", values)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) AS sum_y
    FROM test ORDER BY x
""")
print(cur.fetchall())
con.close()

создать_сортировку(имя, отзывной, /)

Создайте сортировку с именемимяс использованием функции сопоставленияотзывной. отзывнойпрошло дванитьаргументы, и он должен вернутьцелое число:

1если первый упорядочен выше второго
-1если первый упорядочен ниже второго
0если они упорядочены одинаково

В следующем примере показана обратная сортировка:

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

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

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

Удалите функцию сортировки, установивотзывнойкNone.

Изменено в версии 3.11: Имя сортировки может содержать любой символ Unicode. Ранее допускались только символы ASCII.

прерывать()

Вызовите этот метод из другого потока, чтобы прервать любые запросы, которые могут выполняться на соединении. Прерванные запросы вызовутOperationalError.

установить_авторизатор(авторизатор_обратный вызов)

регистротзывной авторизатор_обратный вызоввызываться для каждой попытки доступа к столбцу таблицы в базе данных. Обратный вызов должен возвращать одно изSQLITE_OK, SQLITE_DENY, илиSQLITE_IGNOREдля указания того, как доступ к столбцу должен обрабатываться базовой библиотекой SQLite.

Первый аргумент обратного вызова указывает, какой тип операции должен быть авторизован. Второй и третий аргументы будут аргументами илиNoneв зависимости от первого аргумента. 4-й аргумент — имя базы данных («main», «temp» и т. д.), если применимо. 5-й аргумент — имя самого внутреннего триггера или представления, которое отвечает за попытку доступа илиNoneесли эта попытка доступа осуществляется непосредственно из входного кода SQL.

Пожалуйста, обратитесь к документации SQLite о возможных значениях для первого аргумента и значении второго и третьего аргумента в зависимости от первого. Все необходимые константы доступны вsqlite3модуль.

ПрохождениеNoneкакавторизатор_обратный вызовотключит авторизатор.

Изменено в версии 3.11: Добавлена поддержка отключения авторизатора с помощьюNone.

set_progress_handler(progress_handler, н)

регистротзывной progress_handlerбыть вызванным для каждогонинструкции виртуальной машины SQLite. Это полезно, если вы хотите вызывать SQLite во время длительных операций, например, для обновления GUI.

Если вы хотите очистить любой ранее установленный обработчик прогресса, вызовите метод с помощьюNoneдляprogress_handler.

Возврат ненулевого значения из функции-обработчика завершит текущий выполняемый запрос и вызовет исключениеОшибка базы данныхисключение.

set_trace_callback(трассировка_обратного вызова)

регистротзывной трассировка_обратного вызовадля вызова каждого оператора SQL, который фактически выполняется серверной частью SQLite.

Единственный аргумент, передаваемый в функцию обратного вызова, — это оператор (какул), который выполняется. Возвращаемое значение обратного вызова игнорируется. Обратите внимание, что бэкэнд не только запускает операторы, переданные вКурсор.execute()методы. Другие источники включаютуправление транзакциямипринадлежащийsqlite3модуль и выполнение триггеров, определенных в текущей базе данных.

ПрохождениеNoneкактрассировка_обратного вызоваотключит обратный вызов трассировки.

Примечание

Исключения, возникающие в обратном вызове трассировки, не распространяются. В качестве средства разработки и отладки используйтеenable_callback_tracebacks()для включения печати обратных трассировок из исключений, вызванных в обратном вызове трассировки.

Добавлено в версии 3.3.

включить_загрузку_расширения(включено, /)

Включите движок SQLite для загрузки расширений SQLite из общих библиотек, есливключеноявляетсяTrue; в противном случае запретить загрузку расширений SQLite. Расширения SQLite могут определять новые функции, агрегаты или совершенно новые реализации виртуальных таблиц. Одним из известных расширений является расширение полнотекстового поиска, распространяемое вместе с SQLite.

Примечание

Thesqlite3Модуль не построен с поддержкой загружаемых расширений по умолчанию, поскольку некоторые платформы (в частности, macOS) имеют библиотеки SQLite, которые скомпилированы без этой функции. Чтобы получить поддержку загружаемых расширений, необходимо передать--enable-loadable-sqlite-extensionsвозможностьнастроить.

Поднимаетаудит событий sqlite3.enable_load_extensionс аргументамиconnection, enabled.

Добавлено в версии 3.2.

Изменено в версии 3.10: Добавленоsqlite3.enable_load_extensionаудиторское мероприятие.

con.enable_load_extension(True)

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

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

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")
con.executescript("""
    INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');
    INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
    print(row)

загрузка_расширения(путь, /, *, точка входа=Нет)

Загрузить расширение SQLite из общей библиотеки. Включить загрузку расширения с помощьювключить_загрузку_расширения()перед вызовом этого метода.

Параметры:

путь (ул) – Путь к расширению SQLite.
входная точка (ул | Никто) – Имя точки входа. ЕслиNone(по умолчанию), SQLite придумает собственное имя точки входа; см. документацию SQLiteЗагрузка расширениядля получения подробной информации.

Поднимаетаудит событий sqlite3.load_extensionс аргументамиconnection, path.

Добавлено в версии 3.2.

Изменено в версии 3.10: Добавленоsqlite3.load_extensionаудиторское мероприятие.

Изменено в версии 3.12: Добавленовходная точкапараметр.

iterdump()

Возвратитератордля дампа базы данных как исходного кода SQL. Полезно при сохранении базы данных в памяти для последующего восстановления. Аналогично.dumpкоманда вsqlite3оболочка.

Пример:

# Convert file example.db to SQL dump file dump.sql
con = sqlite3.connect('example.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%sn' % line)
con.close()

резервное копирование(цель, *, страницы=-1, прогресс=Нет, имя='главный', сон=0,250)

Создайте резервную копию базы данных SQLite.

Работает, даже если к базе данных обращаются другие клиенты или одновременно по тому же соединению.

Параметры:

цель (Связь) – Подключение к базе данных, в которой будет сохранена резервная копия.
страницы (инт) – Количество страниц для копирования за раз. Если равно или меньше0, вся база данных копируется за один шаг. По умолчанию-1.
прогресс (перезвонить| Нет) – Если установлено значениеотзывной, он вызывается с тремя целочисленными аргументами для каждой итерации резервного копирования:положение делпоследней итерации,оставшийсяколичество страниц, которые еще предстоит скопировать, иобщийКоличество страниц. По умолчаниюNone.
имя (ул) – Имя базы данных для резервного копирования. Либо"main"(по умолчанию) для основной базы данных,"temp"для временной базы данных или имя пользовательской базы данных, прикрепленной с помощьюATTACH DATABASESQL-выражение.
спать (плавать) – количество секунд ожидания между последовательными попытками резервного копирования оставшихся страниц.

Пример 1. Копирование существующей базы данных в другую:

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

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
with dst:
    src.backup(dst, pages=1, progress=progress)
dst.close()
src.close()

Пример 2. Копирование существующей базы данных во временную копию:

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

Добавлено в версии 3.7.

получитьлимит(категория, /)

Получите ограничение на время выполнения соединения.

Параметры:

категория (инт) –Категория ограничений SQLiteбыть запрошенным.

Тип возврата:

инт

Поднимает:

ОшибкаПрограммирования- Есликатегорияне распознается базовой библиотекой SQLite.

Пример, запрос максимальной длины оператора SQL дляСвязь con(по умолчанию 1000000000):

>>>

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

Добавлено в версии 3.11.

установить предел(категория, предел, /)

Установить предел времени выполнения соединения. Попытки увеличить предел выше его жесткой верхней границы молча усекаются до жесткой верхней границы. Независимо от того, был ли изменен предел или нет, возвращается предыдущее значение предела.

Параметры:

категория (инт) –Категория ограничений SQLiteбыть установленным.
предел (инт) – Значение нового лимита. Если отрицательно, текущий лимит не изменяется.

Тип возврата:

инт

Поднимает:

ОшибкаПрограммирования- Есликатегорияне распознается базовой библиотекой SQLite.

Например, ограничьте количество подключенных баз данных до 1 дляСвязь con(лимит по умолчанию — 10):

>>>

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

Добавлено в версии 3.11.

получитьконфигурацию(оп, /)

Запросить логический параметр конфигурации соединения.

Параметры:

оп (инт) – АКод SQLITE_DBCONFIG.

Тип возврата:

бул

Добавлено в версии 3.12.

setconfig(оп, включить=Истина, /)

Установите логический параметр конфигурации соединения.

Параметры:

оп (инт) – АКод SQLITE_DBCONFIG.
давать возможность (бул) – Trueесли опция конфигурации должна быть включена (по умолчанию);Falseесли его следует отключить.

Добавлено в версии 3.12.

сериализовать(*, имя='главный')

Сериализация базы данных вбайтыобъект. Для обычного файла базы данных на диске сериализация — это просто копия файла на диске. Для базы данных в памяти или «временной» базы данных сериализация — это та же последовательность байтов, которая была бы записана на диск, если бы эта база данных была скопирована на диск.

Параметры:

имя (ул) – Имя базы данных для сериализации. По умолчанию"main".

Тип возврата:

байты

Примечание

Этот метод доступен только в том случае, если базовая библиотека SQLite имеет API сериализации.

Добавлено в версии 3.11.

десериализовать(данные, /, *, имя='главный')

Десериализоватьсериализованныйбазу данных вСвязь. Этот метод приводит к отключению соединения с базой данных.имя, и снова открытьимякак база данных в памяти, основанная на сериализации, содержащейся вданные.

Параметры:

данные (байты) – Сериализованная база данных.
имя (ул) – Имя базы данных для десериализации. По умолчанию"main".

Поднимает:

OperationalError– Если соединение с базой данных в данный момент задействовано в транзакции чтения или операции резервного копирования.
Ошибка базы данных- Еслиданныене содержит допустимую базу данных SQLite.
OverflowError- Еслиlen(данные)больше, чем2**63 - 1.

Примечание

Этот метод доступен только в том случае, если базовая библиотека SQLite имеет API десериализации.

Добавлено в версии 3.11.

автокоммит

Этот атрибут управляетПЭП 249- соответствующее транзакционное поведение.autocommitимеет три допустимых значения:

False: ВыбиратьПЭП 249- соответствующее транзакционное поведение, подразумевающее, чтоsqlite3гарантирует, что транзакция всегда открыта. Используйтесовершить()иоткат()для закрытия транзакций.

Это рекомендуемое значениеautocommit.
True: Используйте SQLiteрежим автокоммита. совершить()иоткат()не имеют никакого эффекта в этом режиме.
LEGACY_TRANSACTION_CONTROL: Pre-Python 3.12 (неПЭП 249-совместимый) контроль транзакций. Смотретьуровень_изоляцииБольше подробностей.

В настоящее время это значение по умолчаниюautocommit.

ИзменениеautocommitкFalseоткроет новую транзакцию и изменит ее наTrueзафиксирует любую ожидающую транзакцию.

ВидетьУправление транзакциями через атрибут autocommitБольше подробностей.

Примечание

Theуровень_изоляцииатрибут не имеет никакого эффекта, еслиавтокоммитявляетсяLEGACY_TRANSACTION_CONTROL.

Добавлено в версии 3.12.

в_транзакции

Этот атрибут, доступный только для чтения, соответствует низкоуровневому SQLiteрежим автокоммита.

Trueесли транзакция активна (есть незафиксированные изменения),Falseв противном случае.

Добавлено в версии 3.2.

уровень_изоляции

Контролируетустаревший режим обработки транзакцийизsqlite3. Если установлено значениеNone, транзакции никогда не открываются неявно. Если установлено одно из"DEFERRED", "IMMEDIATE", или"EXCLUSIVE", соответствующий базовомуПоведение транзакций SQLite, неявное управление транзакциямивыполняется.

Если не отмененоуровень_изоляциипараметрсоединять(), по умолчанию"", что является псевдонимом для"DEFERRED".

Примечание

С использованиемавтокоммитдля контроля обработки транзакций рекомендуется использоватьisolation_level. isolation_levelне имеет никакого эффекта, если толькоавтокоммитустановлен наLEGACY_TRANSACTION_CONTROL(по умолчанию).

row_factory

Начальныйrow_factoryдляКурсоробъекты, созданные из этого соединения. Назначение этого атрибута не влияет наrow_factoryиз существующих курсоров, принадлежащих этому соединению, только новые.Noneпо умолчанию, то есть каждая строка возвращается каккортеж.

ВидетьКак создавать и использовать фабрики строкБольше подробностей.

текстовая_фабрика

Аотзывнойкоторый принимаетбайтыпараметр и возвращает его текстовое представление. Вызываемый вызывается для значений SQLite сTEXTтип данных. По умолчанию этот атрибут установлен наул.

ВидетьКак обрабатывать текстовые кодировки, отличные от UTF-8Больше подробностей.

всего_изменений

Возвращает общее количество строк базы данных, которые были изменены, вставлены или удалены с момента открытия соединения с базой данных.

Объекты курсора

АCursorобъект представляет собойкурсор базы данныхкоторый используется для выполнения операторов SQL и управления контекстом операции выборки. Курсоры создаются с использованиемСоединение.курсор(), или с помощью любого изметоды быстрого подключения.

Объекты курсораитераторы, что означает, что если вывыполнять()аSELECTзапрос, вы можете просто выполнить итерацию по курсору, чтобы получить результирующие строки:
for row in cur.execute("SELECT t FROM data"):
    print(row)

сортsqlite3.Курсор

АКурсорэкземпляр имеет следующие атрибуты и методы.

выполнять(sql, параметры=(), /)

Выполнить один оператор SQL, опционально привязывая значения Python, используязаполнители.

Параметры:

sql (ул) – Один оператор SQL.
параметры (дикт | последовательность) – Значения Python для привязки к заполнителям вsql. Аdictесли используются именованные заполнители. Последовательность, если используются неименованные заполнители. СмотретьКак использовать заполнители для привязки значений в SQL-запросах.

Поднимает:

ОшибкаПрограммирования- Еслиsqlсодержит более одного оператора SQL.

ЕслиавтокоммитявляетсяLEGACY_TRANSACTION_CONTROL, уровень_изоляциине являетсяNone, sqlявляетсяINSERT, UPDATE, DELETE, илиREPLACEоператор, и нет открытой транзакции, транзакция неявно открывается перед выполнениемsql.

Не рекомендуется с версии 3.12, будет удалено в версии 3.14:УстареваниеПредупреждениеиспускается, еслиименованные заполнителииспользуются ипараметрыэто последовательность вместодиктНачиная с Python 3.14,ОшибкаПрограммированиявместо этого будет повышен.

Использоватьвыполнитьскрипт()для выполнения нескольких операторов SQL.

выполнитьмногие(sql, параметры, /)

Для каждого элемента впараметры, повторно выполнитьпараметризованныйОператор DML SQLsql.

Использует ту же неявную обработку транзакций, что ивыполнять().

Параметры:

sql (ул) – Один оператор SQL DML.
параметры (повторяемый) – Итерируемый набор параметров для привязки к заполнителям вsql. ВидетьКак использовать заполнители для привязки значений в SQL-запросах.

Поднимает:

ОшибкаПрограммирования- Еслиsqlсодержит более одного оператора SQL или не является оператором DML.

Пример:

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

Примечание

Все полученные строки отбрасываются, включая операторы DML сВОЗВРАЩАЮЩИЕСЯ положения.

Не рекомендуется с версии 3.12, будет удалено в версии 3.14:УстареваниеПредупреждениеиспускается, еслиименованные заполнителииспользуются и предметы впараметрыявляются последовательностями вместодиктs. Начиная с Python 3.14,ОшибкаПрограммированиявместо этого будет повышен.

выполнитьскрипт(sql_скрипт, /)

Выполнить операторы SQL вsql_скрипт. ЕслиавтокоммитявляетсяLEGACY_TRANSACTION_CONTROLи есть ожидающая транзакция, неявнаяCOMMITСначала выполняется оператор. Никакого другого неявного управления транзакциями не выполняется; любое управление транзакциями должно быть добавлено кsql_скрипт.

sql_скриптдолжно бытьнить.

Пример:

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

fetchone()

Еслиrow_factoryявляетсяNone, вернуть следующий набор результатов запроса строки каккортеж. В противном случае передайте его фабрике строк и верните ее результат. ВозвратNoneесли больше данных нет.

fetchmany(размер=курсор.размер массива)

Вернуть следующий набор строк результата запроса каксписок. Возвращает пустой список, если больше нет доступных строк.

Количество строк, которые необходимо извлечь за один вызов, указывается параметромразмерпараметр. Еслиразмерне дано,размер массиваопределяет количество строк для выборки. Если меньше, чемразмердоступны строки, возвращается столько строк, сколько доступно.

Обратите внимание, что существуют соображения производительности, связанные сразмерпараметр. Для оптимальной производительности обычно лучше использовать атрибут arraysize. Еслиразмерпараметр используется, то лучше всего сохранить для него то же значение из одногоfetchmany()звонок следующему.

fetchall()

Вернуть все (оставшиеся) строки результата запроса в видесписок. Возвращает пустой список, если нет доступных строк. Обратите внимание, чторазмер массиваатрибут может повлиять на производительность этой операции.

закрывать()

Закройте курсор сейчас (а не когда-либо__del__называется).

С этого момента курсор будет непригоден для использования;ОшибкаПрограммированияПри попытке выполнить какую-либо операцию с курсором возникнет исключение.

setinputsizes(размеры, /)

Требуется DB-API. Ничего не делает вsqlite3.

setoutputsize(размер, столбец=Нет, /)

Требуется DB-API. Ничего не делает вsqlite3.

размер массива

Атрибут чтения/записи, который управляет количеством строк, возвращаемыхfetchmany()Значение по умолчанию — 1, что означает, что за один вызов будет извлечена одна строка.

связь

Атрибут «только для чтения», предоставляющий базу данных SQLiteСвязьпринадлежащий курсору. AКурсоробъект создан путем вызоваcon.курсор()будет иметьсвязьатрибут, который относится кпротив:

>>>

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

описание

Атрибут только для чтения, который предоставляет имена столбцов последнего запроса. Чтобы оставаться совместимым с API Python DB, он возвращает 7-кортеж для каждого столбца, где последние шесть элементов каждого кортежаNone.

Он установлен дляSELECTзаявления без каких-либо соответствующих строк.

lastrowid

Атрибут только для чтения, который предоставляет идентификатор строки последней вставленной строки. Он обновляется только после успешногоINSERTилиREPLACEзаявления с использованиемвыполнять()метод. Для других утверждений послевыполнитьмногие()иливыполнитьскрипт(), или если вставка не удалась, значениеlastrowidостается неизменным. Начальное значениеlastrowidявляетсяNone.

Примечание

Вставляется вWITHOUT ROWIDтаблицы не регистрируются.

Изменено в версии 3.6: Добавлена поддержкаREPLACEзаявление.

количество строк

Атрибут только для чтения, который предоставляет количество измененных строк дляINSERT, UPDATE, DELETE, иREPLACEзаявления; есть-1для других утверждений, включая запросы CTE. Он обновляется тольковыполнять()ивыполнитьмногие()методы, после того, как оператор завершится. Это означает, что любые результирующие строки должны быть извлечены для того, чтобыrowcountбыть обновленным.

row_factory

Управляет тем, как извлекается строка из этогоCursorпредставлено. ЕслиNone, строка представлена каккортеж. Можно установить на включенныйsqlite3.Строка; илиотзывнойкоторый принимает два аргумента,Курсоробъект иtupleзначений строк и возвращает пользовательский объект, представляющий строку SQLite.

По умолчанию чтоConnection.row_factoryбыл установлен на момент, когдаCursorбыл создан. Назначение этого атрибута не влияетConnection.row_factoryродительского соединения.

ВидетьКак создавать и использовать фабрики строкБольше подробностей.

Строка объектов

сортsqlite3.Строка

АRowэкземпляр служит как высокооптимизированныйrow_factoryдляСвязьобъектов. Он поддерживает итерацию, проверку на равенство,лен(), икартографированиедоступ по имени столбца и индексу.

ДваRowобъекты считаются равными, если они имеют одинаковые имена столбцов и значения.

ВидетьКак создавать и использовать фабрики строкБольше подробностей.

ключи()

Возвратсписокимен столбцов какструны. Сразу после запроса это первый член каждого кортежа вКурсор.описание.

Изменения в версии 3.5: Добавлена поддержка нарезки.

Объекты-блобы

сортsqlite3.Блоб

Добавлено в версии 3.11.

АКапляэкземпляр - этофайлоподобный объекткоторый может читать и записывать данные в SQLite BLOB. Вызовlen(клякса)чтобы получить размер (количество байтов) блоба. Используйте индексы иломтикидля прямого доступа к данным BLOB-объектов.

ИспользоватьКаплякакменеджер контекстачтобы убедиться, что ручка-капля закрыта после использования.

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

# Write to our blob, using two write operations:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Modify the first and last bytes of our blob
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Read the contents of our blob
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # outputs "b'Hello, world!'"
con.close()

закрывать()

Закройте объект.

С этого момента этот объект будет непригоден для использования.Ошибка(или подкласса) будет вызвано исключение, если будет предпринята попытка выполнить какую-либо дальнейшую операцию с большим двоичным объектом.

читать(длина=-1, /)

Читатьдлинабайты данных из блоба в текущей позиции смещения. Если достигнут конец блоба, будут возвращены данные до EOF. Когдадлинане указан или отрицательный,читать()будет читаться до конца блоба.

писать(данные, /)

Писатьданныек blob по текущему смещению. Эта функция не может изменить длину blob. Запись за пределами конца blob вызоветЗначениеОшибка.

рассказывать()

Возвращает текущую позицию доступа к BLOB-объекту.

искать(компенсировать, происхождение=os.SEEK_SET, /)

Установите текущую позицию доступа к BLOB-объекту накомпенсировать.источникаргумент по умолчаниюos.SEEK_SET(абсолютное позиционирование капли). Другие значения дляисточникявляютсяos.SEEK_CUR(поиск относительно текущей позиции) иос.SEEK_END(поиск относительно конца блоба).

Объекты PrepareProtocol

сортsqlite3.Подготовить протокол

Единственная цель типа PrepareProtocol — действовать какПЭП 246протокол адаптации стиля для объектов, которые могутприспосабливаются самиксобственные типы SQLite.

Исключения

Иерархия исключений определяется DB-API 2.0 (ПЭП 249).

исключениеsqlite3.Предупреждение

Это исключение в настоящее время не поднимаетсяsqlite3модуль, но может быть поднят приложениями, использующимиsqlite3, например, если пользовательская функция обрезает данные при вставке.Warningявляется подклассомИсключение.

исключениеsqlite3.Ошибка

Базовый класс других исключений в этом модуле. Используйте это, чтобы перехватить все ошибки одним единственнымкромезаявление.Errorявляется подклассомИсключение.

Если исключение возникло в библиотеке SQLite, к исключению добавляются следующие два атрибута:

sqlite_код_ошибки

Числовой код ошибки изAPI SQLite

Добавлено в версии 3.11.

sqlite_errorname

Символическое имя числового кода ошибки изAPI SQLite

Добавлено в версии 3.11.

исключениеsqlite3.InterfaceError

Исключение, вызванное неправильным использованием низкоуровневого API SQLite C. Другими словами, если это исключение вызвано, это, вероятно, указывает на ошибку вsqlite3модуль.InterfaceErrorявляется подклассомОшибка.

исключениеsqlite3.Ошибка базы данных

Исключение, вызванное ошибками, связанными с базой данных. Это служит базовым исключением для нескольких типов ошибок базы данных. Оно вызывается только неявно через специализированные подклассы.DatabaseErrorявляется подклассомОшибка.

исключениеsqlite3.Ошибка данных

Исключение возникает из-за ошибок, вызванных проблемами с обработанными данными, такими как числовые значения, выходящие за пределы диапазона, и слишком длинные строки.DataErrorявляется подклассомОшибка базы данных.

исключениеsqlite3.ОперационнаяОшибка

Исключение, вызванное ошибками, связанными с работой базы данных, и не обязательно находящимися под контролем программиста. Например, путь к базе данных не найден или транзакция не может быть обработана.OperationalErrorявляется подклассомОшибка базы данных.

исключениеsqlite3.Ошибка целостности

Исключение возникает, когда нарушается реляционная целостность базы данных, например, проверка внешнего ключа не удалась. Это подклассОшибка базы данных.

исключениеsqlite3.ВнутренняяОшибка

Исключение, возникающее при обнаружении SQLite внутренней ошибки. Если это происходит, это может указывать на проблему с библиотекой SQLite времени выполнения.InternalErrorявляется подклассомОшибка базы данных.

исключениеsqlite3.Ошибка программирования

Исключение сделано дляsqlite3Ошибки программирования API, например, предоставление неправильного количества привязок к запросу или попытка работы с закрытымСвязь. ProgrammingErrorявляется подклассомОшибка базы данных.

исключениеsqlite3.NotSupportedError

Исключение возникает в случае, если метод или API базы данных не поддерживаются базовой библиотекой SQLite. Например, установкадетерминированныйкTrueвсоздать_функцию(), если базовая библиотека SQLite не поддерживает детерминированные функции.NotSupportedErrorявляется подклассомОшибка базы данных.

Типы SQLite и Python

SQLite изначально поддерживает следующие типы:NULL, INTEGER, REAL, TEXT, BLOB.

Таким образом, следующие типы Python можно без проблем отправить в SQLite:

Тип питона	Тип SQLite
`None`	`NULL`
инт	`INTEGER`
плавать	`REAL`
ул	`TEXT`
байты	`BLOB`

Вот как типы SQLite по умолчанию преобразуются в типы Python:

Тип SQLite	Тип питона
`NULL`	`None`
`INTEGER`	инт
`REAL`	плавать
`TEXT`	зависит оттекстовая_фабрика, улпо умолчанию
`BLOB`	байты

Система типовsqlite3Модуль расширяем двумя способами: вы можете хранить дополнительные типы Python в базе данных SQLite черезобъектные адаптеры, и вы можете позволитьsqlite3модуль преобразует типы SQLite в типы Python черезпреобразователи.

Адаптеры и конвертеры по умолчанию (устарели)

Примечание

Адаптеры и конвертеры по умолчанию устарели с версии Python 3.12. Вместо этого используйтеРецепты адаптеров и преобразователейи адаптируйте их к вашим потребностям.

Устаревшие адаптеры и преобразователи по умолчанию включают в себя:

Адаптер длядатавремя.датавозражает противструнывИСО 8601формат.
Адаптер длядата и время.дата и времявозражает против строк в формате ISO 8601.
Конвертер длязаявил«дата» типы длядатавремя.датаобъекты.
Конвертер для объявленных типов «временной метки» вдата и время.дата и времяобъекты. Дробные части будут усечены до 6 цифр (точность микросекунды).

Примечание

Конвертер «временной метки» по умолчанию игнорирует смещения UTC в базе данных и всегда возвращает наивное значениедата и время.дата и времяобъект. Чтобы сохранить смещения UTC в метках времени, либо оставьте конвертеры отключенными, либо зарегистрируйте конвертер, учитывающий смещения, с помощьюрегистр_конвертер().

Не рекомендуется с версии 3.12.

Интерфейс командной строки

Thesqlite3модуль может быть вызван как скрипт, используя интерпретатор-мswitch, чтобы предоставить простую оболочку SQLite. Сигнатура аргумента следующая:

python -m sqlite3 [-h] [-v] [filename] [sql]

Тип.quitили CTRL-D для выхода из оболочки.

-h, --help

Распечатать справку CLI.

-v, --версия

Распечатать версию базовой библиотеки SQLite.

Добавлено в версии 3.12.

Руководства по использованию

Как использовать заполнители для привязки значений в SQL-запросах

Операции SQL обычно требуют использования значений из переменных Python. Однако будьте осторожны при использовании строковых операций Python для сборки запросов, поскольку они уязвимы дляАтаки с использованием SQL-инъекций. Например, злоумышленник может просто закрыть одинарную кавычку и внедритьOR TRUEчтобы выбрать все строки:

>>>

>>> # Never do this -- insecure!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)

Вместо этого используйте подстановку параметров DB-API. Чтобы вставить переменную в строку запроса, используйте заполнитель в строке и подставьте фактические значения в запрос, предоставив их в качествекортежзначений второму аргументу курсоравыполнять()метод.

Оператор SQL может использовать один из двух видов заполнителей: вопросительные знаки (стиль qmark) или именованные заполнители (именованный стиль). Для стиля qmark,параметрыдолжно бытьпоследовательностьдлина которого должна соответствовать количеству заполнителей, илиОшибкаПрограммированияподнят. Для названного стиля,параметрыдолжен быть экземпляромдикт(или подкласс), который должен содержать ключи для всех именованных параметров; любые дополнительные элементы игнорируются. Вот пример обоих стилей:

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

# This is the named style used with executemany():
data = (
    {"name": "C", "year": 1972},
    {"name": "Fortran", "year": 1957},
    {"name": "Python", "year": 1991},
    {"name": "Go", "year": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

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

Примечание

ПЭП 249числовые заполнителинетподдерживаются. Если используются, они будут интерпретироваться как именованные заполнители.

Как адаптировать пользовательские типы Python к значениям SQLite

SQLite изначально поддерживает только ограниченный набор типов данных. Чтобы хранить пользовательские типы Python в базах данных SQLite,адаптироватьсяих к одному изТипы Python, которые SQLite понимает изначально.

Существует два способа адаптации объектов Python к типам SQLite: позволить объекту адаптироваться самому или использоватьадаптер вызываемый. Последнее будет иметь приоритет над первым. Для библиотеки, которая экспортирует пользовательский тип, может иметь смысл разрешить этому типу адаптироваться. Как разработчику приложения, может иметь смысл взять на себя прямой контроль, зарегистрировав пользовательские функции адаптера.

Как писать адаптивные объекты

Предположим, у нас естьPointкласс, представляющий пару координат,xиy, в декартовой системе координат. Пара координат будет сохранена в базе данных как текстовая строка, с использованием точки с запятой для разделения координат. Это можно реализовать, добавив__conform__(self, protocol)метод, который возвращает адаптированное значение. Объект, переданный впротоколбудет иметь типПодготовитьПротокол.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return f"{self.x};{self.y}"

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

cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()

Как зарегистрировать вызываемые адаптеры

Другая возможность — создать функцию, которая преобразует объект Python в тип, совместимый с SQLite. Эту функцию затем можно зарегистрировать с помощьюрегистр_адаптер().

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

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

cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()

Как преобразовать значения SQLite в пользовательские типы Python

Написание адаптера позволяет вам преобразоватьотпользовательские типы PythonкЗначения SQLite. Чтобы иметь возможность конвертироватьотЗначения SQLiteкпользовательские типы Python, которые мы используемпреобразователи.

Давайте вернемся кPointкласс. Мы сохранили координаты x и y, разделенные точкой с запятой, в виде строк в SQLite.

Сначала мы определим функцию-конвертер, которая принимает строку в качестве параметра и создаетPointобъект из него.

Примечание

Функции преобразователя:всегдапрошелбайтыобъект, независимо от базового типа данных SQLite.

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

Теперь нам нужно рассказатьsqlite3когда он должен преобразовать данное значение SQLite. Это делается при подключении к базе данных с помощьюопределить_типыпараметрсоединять(). Есть три варианта:

Неявный: наборопределить_типыкPARSE_DECLTYPES
Явный: наборопределить_типыкPARSE_COLNAMES
Оба: установленыопределить_типыкsqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES. Имена столбцов имеют приоритет над объявленными типами.

Следующий пример иллюстрирует неявный и явный подходы:

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

def adapt_point(point):
    return f"{point.x};{point.y}"

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

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

# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

Рецепты адаптеров и преобразователей

В этом разделе приведены рецепты для распространенных адаптеров и преобразователей.

import datetime
import sqlite3

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

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

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

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

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

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)

Как использовать методы быстрого подключения

Используявыполнять(), выполнитьмногие(), ивыполнитьскрипт()методыСвязьclass, ваш код может быть написан более лаконично, поскольку вам не придется создавать (часто излишние)Курсоробъекты явно. Вместо этого,Курсоробъекты создаются неявно, и эти сокращенные методы возвращают объекты курсора. Таким образом, вы можете выполнитьSELECTоператор и перебрать его напрямую, используя только один вызовСвязьобъект.

# Create and fill the table.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
    ("C++", 1985),
    ("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

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

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

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

Как использовать менеджер контекста подключения

АСвязьобъект может быть использован как менеджер контекста, который автоматически фиксирует или откатывает открытые транзакции при выходе из тела менеджера контекста. Если телосоператор завершается без исключений, транзакция фиксируется. Если эта фиксация не удается, или если телоwithоператор вызывает неперехваченное исключение, транзакция откатывается. ЕслиавтокоммитявляетсяFalse, новая транзакция неявно открывается после подтверждения или отката.

Если при выходе из тела нет открытой транзакцииwithзаявление, или еслиавтокоммитявляетсяTrue, менеджер контекста ничего не делает.

Примечание

Контекстный менеджер не открывает неявно новую транзакцию и не закрывает соединение. Если вам нужен закрывающий контекстный менеджер, рассмотрите возможность использованияcontextlib.закрытие().

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

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

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

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()

Как работать с URI SQLite

Вот некоторые полезные приемы URI:

Откройте базу данных в режиме только для чтения:

>>>

>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database

Не создавайте неявно новый файл базы данных, если он еще не существует; это вызоветOperationalErrorесли не удаётся создать новый файл:

>>>

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file

Создайте общую именованную базу данных в памяти:

db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
    con1.execute("CREATE TABLE shared(data)")
    con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)

con1.close()
con2.close()

Более подробную информацию об этой функции, включая список параметров, можно найти вДокументация SQLite URI.

Как создавать и использовать фабрики строк

По умолчанию,sqlite3представляет каждую строку каккортеж. Еслиtupleне соответствует вашим потребностям, вы можете использоватьsqlite3.Строкакласс или пользовательскийrow_factory.

Покаrow_factoryсуществует как атрибут как наКурсориСвязь, рекомендуется установитьConnection.row_factory, поэтому все курсоры, созданные из соединения, будут использовать одну и ту же фабрику строк.

Rowобеспечивает индексированный и нечувствительный к регистру именованный доступ к столбцам с минимальными затратами памяти и влиянием на производительностьtuple. ИспользоватьRowкак фабрику строк, назначьте ееrow_factoryатрибут:

>>>

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

Запросы теперь возвращаютсяRowобъекты:

>>>

>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0]         # Access by index.
'Earth'
>>> row["name"]    # Access by name.
'Earth'
>>> row["RADIUS"]  # Column names are case-insensitive.
6378
>>> con.close()

Примечание

TheFROMпункт может быть опущен вSELECTоператор, как в примере выше. В таких случаях SQLite возвращает одну строку со столбцами, определенными выражениями, например, литералами, с заданными псевдонимамиexpr AS alias.

Вы можете создать пользовательскийrow_factoryкоторый возвращает каждую строку какдикт, с именами столбцов, сопоставленными со значениями:

def dict_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    return {key: value for key, value in zip(fields, row)}

Используя его, запросы теперь возвращаютdictвместоtuple:

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
...     print(row)
{'a': 1, 'b': 2}
>>> con.close()

Следующая фабрика строк возвращаетименованный кортеж:

from collections import namedtuple

def namedtuple_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    cls = namedtuple("Row", fields)
    return cls._make(row)

namedtuple_factory()можно использовать следующим образом:

>>>

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0]  # Indexed access.
1
>>> row.b   # Attribute access.
2
>>> con.close()

С некоторыми изменениями приведенный выше рецепт можно адаптировать для использованиякласс данных, или любой другой пользовательский класс, вместоnamedtuple.

Как обрабатывать текстовые кодировки, отличные от UTF-8

По умолчанию,sqlite3используетулдля адаптации значений SQLite с помощьюTEXTтип данных. Это хорошо работает для текста в кодировке UTF-8, но может не работать для других кодировок и недопустимого UTF-8. Вы можете использовать пользовательскийтекстовая_фабрикадля рассмотрения таких случаев.

Из-за SQLiteгибкая типизация, нередко можно встретить столбцы таблиц сTEXTтип данных, содержащий не-UTF-8 кодировки, или даже произвольные данные. Для демонстрации предположим, что у нас есть база данных с текстом в кодировке ISO-8859-2 (Latin-2), например таблица чешско-английских словарных статей. Предположим, что теперь у нас естьСвязьпримерconПодключившись к этой базе данных, мы можем декодировать текст в кодировке Latin-2, используя этутекстовая_фабрика:

con.text_factory = lambda data: str(data, encoding="latin2")

Для недопустимых данных UTF-8 или произвольных данных, хранящихся вTEXTстолбцов таблицы, можно использовать следующую технику, заимствованную изЮникод HOWTO:

con.text_factory = lambda data: str(data, errors="surrogateescape")

Примечание

Thesqlite3API модуля не поддерживает строки, содержащие суррогаты.

Смотрите также

Юникод HOWTO

Объяснение

Контроль транзакций

sqlite3предлагает несколько методов контроля того, когда и как открываются и закрываются транзакции базы данных.Управление транзакциями через атрибут autocommitрекомендуется, в то время какУправление транзакциями через атрибут isolation_levelсохраняет поведение до Python 3.12.

Контроль транзакций через`autocommit`атрибут

Рекомендуемый способ контроля поведения транзакций — черезConnection.автокоммитатрибут, который желательно задать с помощьюавтокоммитпараметрсоединять().

Предлагается установитьавтокоммиткFalse, что подразумеваетПЭП 249-контроль транзакций, соответствующий требованиям. Это означает:

sqlite3гарантирует, что транзакция всегда открыта, поэтомусоединять(), Connection.commit(), иОткат соединения()неявно откроет новую транзакцию (сразу после закрытия ожидающей, для последних двух).sqlite3используетBEGIN DEFERREDвыписки при открытии сделок.
Транзакции должны быть совершены явно с использованиемcommit().
Транзакции следует откатывать явно, используяrollback().
Неявный откат выполняется, если база данныхзакрывать()-ed с ожидающими изменениями.

НаборавтокоммиткTrueдля включения SQLiteрежим автокоммита. В этом режимеConnection.commit()иОткат соединения()не имеют никакого эффекта. Обратите внимание, что режим автокоммита SQLite отличается отПЭП 249-соответствующийConnection.автокоммитатрибут; использованиеСоединение.в_транзакциидля запроса низкоуровневого режима автокоммита SQLite.

НаборавтокоммиткLEGACY_TRANSACTION_CONTROLоставить контроль поведения транзакций на усмотрениеУровень_изоляции_подключенияатрибут. СмотретьУправление транзакциями через атрибут isolation_levelЧтобы получить больше информации.

Контроль транзакций через`isolation_level`атрибут

Примечание

Рекомендуемый способ контроля транзакций — черезавтокоммитатрибут. СмотретьУправление транзакциями через атрибут autocommit.

ЕслиConnection.автокоммитустановлен наLEGACY_TRANSACTION_CONTROL(по умолчанию) поведение транзакции контролируется с помощьюУровень_изоляции_подключенияатрибут. В противном случае,isolation_levelне имеет никакого эффекта.

Если атрибут соединенияуровень_изоляциине являетсяNone, новые транзакции неявно открываются довыполнять()ивыполнитьмногие()выполняетINSERT, UPDATE, DELETE, илиREPLACEоператоры; для других операторов неявная обработка транзакций не выполняется. Используйтесовершить()иоткат()методы для соответственной фиксации и отката ожидающих транзакций. Вы можете выбрать базовыйПоведение транзакций SQLite— то есть, есть ли и какой типBEGINзаявленияsqlite3неявно выполняет – черезуровень_изоляцииатрибут.

Еслиуровень_изоляцииустановлен наNone, никакие транзакции не открываются неявно вообще. Это оставляет лежащую в основе библиотеку SQLite врежим автокоммита, но также позволяет пользователю выполнять собственную обработку транзакций с использованием явных операторов SQL. Базовый режим автокоммита библиотеки SQLite может быть запрошен с помощьюв_транзакцииатрибут.

Theвыполнитьскрипт()метод неявно фиксирует любую ожидающую транзакцию перед выполнением данного скрипта SQL, независимо от значенияуровень_изоляции.

Изменено в версии 3.6:sqlite3используется для неявного подтверждения открытой транзакции перед операторами DDL. Теперь это не так.

Изменено в версии 3.12: рекомендуемый способ контроля транзакций теперь черезавтокоммитатрибут.

Обмен технологиями