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

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

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

Установить подключение к базе данных SQLite.

Параметры:

• database (объект, подобный пути) – Путь к файлу базы данных, который нужно открыть. Вы можете передать ":memory:" для создания базы данных SQLite, существующей только в памяти, и установить подключение к ней.
• timeout (float) – Количество секунд, которое подключение должно ждать, прежде чем сгенерировать исключение OperationalError, когда таблица заблокирована. Если другое подключение открывает транзакцию для изменения таблицы, эта таблица будет заблокирована до тех пор, пока транзакция не будет подтверждена. По умолчанию пять секунд.
• detect_types (int) – Управление тем, как и будут ли обрабатываться типы данных, не поддерживаемые SQLite напрямую для преобразования в типы Python, используя конвертеры, зарегистрированные с помощью register_converter(). Установите любое сочетание (используя |, побитовое ИЛИ) PARSE_DECLTYPES и PARSE_COLNAMES для включения этого. Имена столбцов имеют приоритет над объявленными типами, если оба флага установлены. Типы не могут быть обнаружены для сгенерированных полей (например, max(data)), даже когда параметр detect_types установлен; вместо этого будет возвращено str. По умолчанию (0), обнаружение типов отключено.
• isolation_level (str | None) – Управление поведением обработки транзакций в стиле legacy. См. Connection.isolation_level и Управление транзакциями с помощью атрибута isolation_level для получения дополнительной информации. Может быть "DEFERRED" (по умолчанию), "EXCLUSIVE" или "IMMEDIATE"; или None для отключения неявного открытия транзакций. Не имеет эффекта, если Connection.autocommit установлено в LEGACY_TRANSACTION_CONTROL (значение по умолчанию).
• check_same_thread (bool) – Если True (по умолчанию), ProgrammingError будет поднято, если подключение к базе данных используется потоком, отличным от того, который его создал. Если False, к подключению можно получить доступ в нескольких потоках; операциям записи может потребоваться сериализация пользователем, чтобы избежать повреждения данных. См. threadsafety для получения дополнительной информации.
• factory (Connection) – Пользовательский подкласс Connection для создания подключения, если не используется стандартный класс Connection.
• cached_statements (int) – Количество предложений, которое sqlite3 должно кэшировать для этого подключения, чтобы избежать расходов на разбор. По умолчанию 128 предложений.
• uri (bool) – Если установлено в True, database интерпретируется как URI с путём к файлу и необязательной строкой запроса. Часть схемы должна быть "file:", а путь может быть относительным или абсолютным. Строка запроса позволяет передавать параметры в SQLite, что позволяет использовать различные Способы работы с URI SQLite.
• autocommit (bool) – Управление поведением обработки транзакций PEP 249. См. Connection.autocommit и Управление транзакциями с помощью атрибута autocommit для получения дополнительной информации. В настоящее время по умолчанию autocommit установлен в LEGACY_TRANSACTION_CONTROL. Значение по умолчанию будет изменено на False в будущей версии Python.

Тип возвращаемого значения:

Connection

Вызывает событие аудита аудита sqlite3.connect с аргументом database.

Вызывает событие аудита аудита sqlite3.connect/handle с аргументом connection_handle.

Изменено в версии 3.4: Добавлен параметр uri.

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

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

Изменено в версии 3.12: Добавлен параметр autocommit.

sqlite3.complete_statement(statement)

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

Например:

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

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

См. runsource() в Lib/sqlite3/__main__.py для примеров реального использования.

sqlite3.enable_callback_tracebacks(flag, /)

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

Примечание

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

sqlite3.register_adapter(type, adapter, /)

Зарегистрировать adapter вызываемый объект для адаптации типа Python type в тип SQLite. Адаптер вызывается с единственным аргументом — объектом Python типа type и должен вернуть значение типа, напрямую поддерживаемого SQLite.

sqlite3.register_converter(typename, converter, /)

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

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

Постоянные значения модуля

sqlite3.LEGACY_TRANSACTION_CONTROL

Установите autocommit на это значение, чтобы выбрать поведение управления транзакциями в старом стиле (до Python 3.12). Дополнительную информацию см. в разделе Управление транзакциями с помощью атрибута isolation_level.

sqlite3.PARSE_COLNAMES

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

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

Этот флаг можно объединить с флагом PARSE_DECLTYPES с помощью оператора | (побитовое ИЛИ).

sqlite3.PARSE_DECLTYPES

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

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

Этот флаг можно объединить с флагом PARSE_COLNAMES с помощью оператора | (побитовое ИЛИ).

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORE

Флаги, которые должна возвращать функция authorizer_callback вызываемый объект, переданная методу Connection.set_authorizer(), чтобы указать, разрешен ли доступ (SQLITE_OK), необходимо ли прервать выполнение SQL-запроса с ошибкой (SQLITE_DENY) или столбец должен обрабатываться как значение NULL (SQLITE_IGNORE)

sqlite3.apilevel

Строковая константа, указывающая поддерживаемый уровень DB-API. Требуется DB-API. Задано значение "2.0".

sqlite3.paramstyle

Строковая константа, указывающая тип форматирования маркеров параметров, ожидаемый модулем sqlite3. Требуется DB-API. Задано значение "qmark".

Примечание

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

sqlite3.sqlite_version

Номер версии библиотеки SQLite, выполняющейся в runtime, как string.

sqlite3.sqlite_version_info

Номер версии библиотеки SQLite, выполняющейся в runtime, как tuple целых чисел integers.

sqlite3.threadsafety

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

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

Соответствие режимов многопоточности SQLite уровням потоковой безопасности DB-API 2.0:

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

Изменено в версии 3.11: Значение threadsafety задаётся динамически вместо жёсткого кодирования значения 1.

sqlite3.version

Номер версии этого модуля как string. Это не версия библиотеки SQLite.

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

sqlite3.version_info

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

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

sqlite3.SQLITE_DBCONFIG_DEFENSIVE

sqlite3.SQLITE_DBCONFIG_DQS_DDL

sqlite3.SQLITE_DBCONFIG_DQS_DML

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP

sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

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

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

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

См. также

https://www.sqlite.org/c3ref/c_dbconfig_defensive.html

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

Объекты подключения

class sqlite3.Connection

Каждая открытая база данных SQLite представлена объектом Connection, который создаётся с помощью sqlite3.connect(). Основное назначение этих объектов — создание объектов Cursor и управление транзакциями Управление транзакциями.

См. также

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

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

cursor(factory=Cursor)

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

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

Открывает обработчик Blob для существующего BLOB.

Параметры:

• table (str) – Название таблицы, где расположен BLOB.
• column (str) – Название столбца, где расположен BLOB.
• row (str) – Название строки, где расположен BLOB.
• readonly (bool) – Устанавливается в True если BLOB нужно открыть без прав записи. По умолчанию False.
• name (str) – Название базы данных, где расположен BLOB. По умолчанию "main".

Возможные исключения:

OperationalError – При попытке открыть BLOB в WITHOUT ROWID таблице.

Тип возвращаемого значения:

Blob

Примечание

Размер BLOB не может быть изменён с помощью класса Blob. Используйте SQL-функцию zeroblob для создания BLOB с фиксированным размером.

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

commit()

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

rollback()

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

close()

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

execute(sql, parameters=(), /)

Создаёт новый объект Cursor и вызывает execute() на нём с заданными sql и parameters. Возвращает новый объект курсора.

executemany(sql, parameters, /)

Создаёт новый объект Cursor и вызывает executemany() на нём с заданными sql и parameters. Возвращает новый объект курсора.

executescript(sql_script, /)

Создаёт новый объект Cursor и вызывает executescript() на нём с заданным sql_script. Возвращает новый объект курсора.

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

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

Параметры:

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

Возможные исключения:

NotSupportedError – Если deterministic используется с версиями SQLite старше 3.8.3.

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

Пример:

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

create_aggregate(name, n_arg, aggregate_class)

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

Параметры:

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

• aggregate_class (класс | None) –

  Класс должен реализовывать следующие методы:

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

  Количество аргументов, которое должен принимать метод step(), контролируется параметром n_arg.

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

Пример:

class MySum:
    def __init__(self):
        self.count = 0

    def step(self, value):
        self.count += value

    def finalize(self):
        return self.count

con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.execute("CREATE TABLE test(i)")
cur.execute("INSERT INTO test(i) VALUES(1)")
cur.execute("INSERT INTO test(i) VALUES(2)")
cur.execute("SELECT mysum(i) FROM test")
print(cur.fetchone()[0])

con.close()

create_window_function(name, num_params, aggregate_class, /)

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

Параметры:

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

• aggregate_class (класс | None) –

  Класс, который должен реализовывать следующие методы:

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

  Количество аргументов, которые должны принимать методы step() и value(), контролируется параметром num_params.

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

Исключения:

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

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

Пример:

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

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

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

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

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

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


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

create_collation(name, callable, /)

Создает сортировку с именем name, используя функцию сортировки callable. callable получает два string аргумента и должна возвращать integer:

• 1 если первый аргумент больше второго
• -1 если первый аргумент меньше второго
• 0 если они равны

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

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

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

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

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

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

interrupt()

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

set_authorizer(authorizer_callback)

Регистрирует функцию authorizer_callback для вызова при каждой попытке доступа к столбцу таблицы в базе данных. Функция обратного вызова должна возвращать одно из значений SQLITE_OK, SQLITE_DENY или SQLITE_IGNORE для указания, как обрабатывать доступ к столбцу в подлежащей библиотеке SQLite.

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

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

Передача значения None в качестве authorizer_callback отключит механизм авторизации.

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

set_progress_handler(progress_handler, n)

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

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

Возврат ненулевого значения из функции обратного вызова приведёт к завершению текущего запроса и к возникновению исключения DatabaseError.

set_trace_callback(trace_callback)

Регистрирует функцию trace_callback, которая вызывается для каждого SQL-запроса, фактически выполненного SQLite-бекендом.

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

Передача значения None в качестве trace_callback отключит функцию отслеживания.

Примечание

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

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

enable_load_extension(enabled, /)

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

Примечание

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

Вызывает событие аудита auditing event sqlite3.enable_load_extension с аргументами connection, enabled.

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

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

con.enable_load_extension(True)

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

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

# disable extension loading again
con.enable_load_extension(False)

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

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

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

Параметры:

• path (строка) – Путь к SQLite-расширению.
• entrypoint (строка | None) – Имя точки входа. Если None (по умолчанию), SQLite самостоятельно определит имя точки входа; см. документацию SQLite Loading an Extension для подробностей.

Вызывает событие аудита auditing event sqlite3.load_extension с аргументами connection, path.

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

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

Изменено в версии 3.12: Добавлен параметр entrypoint.

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('%s\n' % line)
con.close()

См. также

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

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

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

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

Параметры:

• target (Connection) – Подключение к базе данных для сохранения резервной копии.
• pages (int) – Количество страниц для копирования за один раз. Если равно или меньше 0, вся база данных копируется за один шаг. По умолчанию -1.
• progress (callback | None) – Если задано как callable, вызывается с тремя целочисленными аргументами для каждой итерации резервного копирования: статус последней итерации, оставшееся количество страниц, которые ещё нужно скопировать и общее количество страниц. По умолчанию None.
• name (str) – Имя базы данных для резервного копирования. Либо "main" (по умолчанию) для основной базы данных, "temp" для временной базы данных, или имя настраиваемой базы данных, добавленной с помощью оператора SQL ATTACH DATABASE.
• sleep (float) – Количество секунд, на которое следует приостановить выполнение между последовательными попытками резервного копирования оставшихся страниц.

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

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

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

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

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

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

См. также

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

getlimit(category, /)

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

Параметры:

category (int) – Категория ограничения SQLite для запроса.

Тип возвращаемого значения:

int

Исключения:

ProgrammingError – Если category не распознаётся базовой библиотекой SQLite.

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

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

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

setlimit(category, limit, /)

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

Параметры:

• category (int) – Категория ограничения SQLite для установки.
• limit (int) – Значение нового ограничения. Если отрицательное, текущее ограничение не изменяется.

Тип возвращаемого значения:

int

Исключения:

ProgrammingError – Если category не распознаётся базовой библиотекой SQLite.

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

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

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

getconfig(op, /)

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

Параметры:

op (int) – Код SQLITE_DBCONFIG.

Тип возвращаемого значения:

bool

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

setconfig(op, enable=True, /)

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

Параметры:

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

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

serialize(*, name='main')

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

Параметры:

name (str) – Имя базы данных, подлежащей сериализации. По умолчанию "main".

Тип возвращаемого значения:

bytes

Примечание

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

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

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

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

Параметры:

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

Исключения:

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

Примечание

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

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

autocommit

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

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

  Это рекомендуемое значение для autocommit.

• True: Используйте режим автоматического подтверждения SQLite. commit() и rollback() не имеют эффекта в этом режиме.

• LEGACY_TRANSACTION_CONTROL: Управление транзакциями до Python 3.12 (несовместимое с PEP 249). Подробнее см. в isolation_level.

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

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

Подробнее см. Управление транзакциями с помощью атрибута autocommit.

Примечание

Атрибут isolation_level не имеет эффекта, если autocommit равен LEGACY_TRANSACTION_CONTROL.

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

in_transaction

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

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

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

isolation_level

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

Если не переопределён параметром isolation_level в connect(), по умолчанию установлено значение "", являющееся псевдонимом "DEFERRED".

Примечание

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

row_factory

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

Подробнее см. Как создать и использовать фабрики строк.

text_factory

Функция, принимающая параметр bytes и возвращающая текстовое представление. Функция вызывается для значений SQLite с типом данных TEXT. По умолчанию этот атрибут установлен в str.

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

total_changes

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

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

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

Объекты курсора являются итераторами, поэтому если вы execute() запрос SELECT, вы можете просто перебирать курсор, чтобы извлечь полученные строки:

for row in cur.execute("SELECT t FROM data"):
    print(row)

class sqlite3.Cursor

Объект Cursor имеет следующие атрибуты и методы.

execute(sql, parameters=(), /)

Выполняет одно SQL-предложение, необязательно связывая значения Python с помощью заменителей.

Параметры:

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

Возможные исключения:

ProgrammingError – Если sql содержит более одного SQL-предложения.

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

Устарело начиная с версии 3.12, будет удалено в версии 3.14: DeprecationWarning генерируется, если используются именованные заменёнте и parameters является последовательностью, а не dict. Начиная с Python 3.14, будет генерироваться ProgrammingError.

Используйте executescript() для выполнения нескольких SQL-предложений.

executemany(sql, parameters, /)

Для каждого элемента в parameters повторяет выполнение параметризованного SQL-предложения DML sql.

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

Параметры:

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

Возможные исключения:

ProgrammingError – Если sql содержит более одного SQL-предложения или не является предложением DML.

Пример:

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

Примечание

Любые полученные строки игнорируются, включая операторы DML с RETURNING-условиями.

Устарело начиная с версии 3.12, будет удалено в версии 3.14: DeprecationWarning генерируется, если используются именованные заменёнте и элементы в parameters являются последовательностями, а не dict. Начиная с Python 3.14, будет генерироваться ProgrammingError.

executescript(sql_script, /)

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

sql_script должно быть string.

Пример:

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

fetchone()

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

fetchmany(size=cursor.arraysize)

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

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

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

fetchall()

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

close()

Закрыть курсор сейчас (а не тогда, когда __del__ будет вызван).

Курсор больше недоступен; при попытке выполнить любую операцию с курсором будет возбуждено исключение ProgrammingError.

setinputsizes(sizes, /)

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

setoutputsize(size, column=None, /)

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

arraysize

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

connection

Только для чтения атрибут, предоставляющий объект SQLite базы данных Connection, принадлежащей курсору. Объект Cursor, созданный вызовом con.cursor(), будет иметь атрибут connection, который ссылается на con:

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

description

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

Также устанавливается для SELECT операций без соответствующих строк.

lastrowid

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

Примечание

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

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

rowcount

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

row_factory

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

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

Для получения дополнительных сведений см. Как создавать и использовать фабрики строк.

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

class sqlite3.Row

Экземпляр Row служит высокооптимизированной row_factory для объектов Connection. Поддерживает итерацию, проверку на равенство, len() и доступ к данным по имени столбца и индексу (доступ по названию отображения).

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

Для получения дополнительных сведений см. Как создавать и использовать фабрики строк.

keys()

Возвращает list имен столбцов в виде strings. Непосредственно после запроса это первый член каждой кортежи в Cursor.description.

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

Объекты BLOB

class sqlite3.Blob

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

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

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

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

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

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

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

close()

Закрыть BLOB.

BLOB больше недоступен. Если будет попытка дальнейшей работы с BLOB, будет возбуждено исключение Error (или подкласс).

read(length=-1, /)

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

write(data, /)

Записать data в BLOB в текущей позиции смещения. Эта функция не может изменить длину BLOB. Запись за пределами конца BLOB вызовет ValueError.

tell()

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

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

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

Объекты PrepareProtocol

class sqlite3.PrepareProtocol

Тип PrepareProtocol предназначен для реализации протокола адаптации в стиле PEP 246 для объектов, которые могут адаптироваться к родным типам SQLite.

Исключения

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

exception sqlite3.Warning

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

exception sqlite3.Error

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

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

sqlite_errorcode

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

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

sqlite_errorname

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

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

exception sqlite3.InterfaceError

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

exception sqlite3.DatabaseError

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

exception sqlite3.DataError

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

exception sqlite3.OperationalError

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

exception sqlite3.IntegrityError

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

exception sqlite3.InternalError

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

exception sqlite3.ProgrammingError

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

exception sqlite3.NotSupportedError

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

Типы SQLite и Python

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

Следующие типы Python могут быть отправлены в SQLite без проблем:

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

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

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

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

• Адаптер для объектов datetime.date в strings формате ISO 8601.
• Адаптер для объектов datetime.datetime в формате строк ISO 8601.
• Конвертер для типов “date”, объявленных в объявленном формате, в объекты datetime.date.
• Конвертер для типов “timestamp”, объявленных в объявленном формате, в объекты datetime.datetime. Дробные части будут усечены до 6 знаков (точность микросекунд).

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

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

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

Введите .quit или CTRL-D для выхода из оболочки.

-h, --help

Вывести справку CLI.

-v, --version

Вывести версию основной библиотеки SQLite.

Как использовать плейсхолдеры для привязки значений в запросах 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. Для вставки переменной в строку запроса используйте плейсхолдер в строке, а подставляйте фактические значения в запрос, предоставляя их как tuple значений во второй аргумент метода курсора execute().

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

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

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

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

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

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

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

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

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 из нее.

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

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

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

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

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

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

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

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

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

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

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

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

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

Рецепты адаптеров и конвертеров

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

import datetime
import sqlite3

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

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

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

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

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

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

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

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

Как использовать методы сокращений соединения

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

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

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

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

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

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

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

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

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

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

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

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

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

Некоторые полезные трюки с URI включают:

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

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

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

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

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

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. Если tuple не подходит для ваших нужд, вы можете использовать класс sqlite3.Row или настраиваемую фабрику строк row_factory.

Хотя row_factory существует как атрибут как в Cursor, так и в Connection, рекомендуется задать Connection.row_factory, чтобы все курсоры, созданные из соединения, использовали одну и ту же фабрику строк.

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

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

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

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

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

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

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

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

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

from collections import namedtuple

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

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

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

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

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

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

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

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

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

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

Управление транзакциями

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