sqlite3 – интерфейс DB-API 2.0 для баз данных SQLite¶sqlite3 – DB-API 2.0 interface for SQLite databases

Функции модуля¶Module functions

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, чтобы включить это. Если установлены оба флага, имена столбцов имеют приоритет над объявленными типами. По умолчанию (0) определение типов отключено.

• isolation_level (str | None) – управляет устаревшим поведением обработки транзакций. См. Connection.isolation_level и Управление транзакциями через атрибут isolation_level для получения дополнительной информации. Может быть "DEFERRED" (по умолчанию), "EXCLUSIVE" или "IMMEDIATE"; или None для отключения неявного открытия транзакций. Не действует, если Connection.autocommit не установлено в LEGACY_TRANSACTION_CONTROL (по умолчанию).

• check_same_thread (bool) – Если True (по умолчанию), будет возбуждено ProgrammingError, если соединение с базой данных используется потоком, отличным от того, который его создал. Если False, к соединению можно обращаться из нескольких потоков; пользователю может потребоваться сериализовать операции записи во избежание повреждения данных. См. threadsafety для получения дополнительной информации.

• factory (Connection) – пользовательский подкласс Connection для создания соединения, если не используется стандартный класс Connection.

• cached_statements (int) – количество операторов, которые sqlite3 должен кэшировать для этого соединения, чтобы избежать накладных расходов на разбор. По умолчанию 128 операторов.

• uri (bool) – Если установлено в True, database интерпретируется как URI с путём к файлу и необязательной строкой запроса. Часть схемы должна быть "file:", а путь может быть относительным или абсолютным. Строка запроса позволяет передавать параметры SQLite, открывая возможности, описанные в Работа с URI SQLite.

• autocommit (bool) – управляет поведением обработки транзакций PEP 249. См. Connection.autocommit и Управление транзакциями через атрибут autocommit для получения дополнительной информации. autocommit в настоящее время по умолчанию равен LEGACY_TRANSACTION_CONTROL. Значение по умолчанию будет изменено на False в одном из будущих выпусков Python.

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

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

Регистрирует адаптер – вызываемый объект, который адаптирует тип Python type в тип SQLite. Адаптер вызывается с объектом Python типа type в качестве единственного аргумента и должен возвращать значение типа, который SQLite понимает изначально.

sqlite3.register_converter(typename, converter, /)¶

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

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

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

sqlite3.LEGACY_TRANSACTION_CONTROL¶

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

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 с помощью оператора | (побитовое ИЛИ).

Примечание

Сгенерированные поля (например, MAX(p)) возвращаются как str. Используйте PARSE_COLNAMES, чтобы принудительно задать типы для таких запросов.

sqlite3.PARSE_COLNAMES¶

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

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

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

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 во время выполнения в виде string.

sqlite3.sqlite_version_info¶

Номер версии библиотеки SQLite времени выполнения как 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: параметры конфигурации соединения с базой данных

Объекты Connection¶Connection objects

class sqlite3.Connection¶

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

См. также

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

• Как использовать контекстный менеджер соединенияHow to use the connection context manager

Соединение с базой данных 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.12.

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 (колбэк | 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 (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 (str) – Имя агрегатной оконной SQL-функции для создания или удаления.

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

• aggregate_class (class | None) –

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

  • step(): Добавить строку в текущее окно.

  • value(): Возвращает текущее значение агрегата.

  • inverse(): Удаляет строку из текущего окна.

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

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

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

Возбуждает:

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

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

Пример:

# Пример взят с https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """Добавить строку в текущее окно."""
        self.count += value

    def value(self):
        """Возвращает текущее значение агрегата."""
        return self.count

    def inverse(self, value):
        """Удалить строку из текущего окна."""
        self.count -= value

    def finalize(self):
        """Возвращает окончательное значение агрегата.

        Здесь следует разместить любые операции очистки.
        """
        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, /)¶

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

• 1, если первый больше второго

• -1, если первый меньше второго

• 0, если они равны

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

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

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

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

Удаляет функцию collation, устанавливая callable в None.

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

interrupt()¶

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

set_authorizer(authorizer_callback)¶

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

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

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

Передача None в качестве authorizer_callback отключает авторизатор.

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

set_progress_handler(progress_handler, n)¶

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

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

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

set_trace_callback(trace_callback)¶

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

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

Передача None в качестве trace_callback отключает трассировочный колбэк.

Примечание

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

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

enable_load_extension(enabled, /)¶

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

Примечание

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

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

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

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

con.enable_load_extension(True)

# Загрузить расширение полнотекстового поиска.
con.execute("select load_extension('./fts3.so')")

# в качестве альтернативы можно загрузить расширение с помощью вызова API:
# con.load_extension("./fts3.so")

# отключить загрузку расширения снова
con.enable_load_extension(False)

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

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

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

Параметры:

• path (str) – путь к расширению SQLite.

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

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

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

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

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

iterdump()¶

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

Пример:

# Преобразовать файл example.db в дамп SQL 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 (колбэк | None) – Если задан как callable, то вызывается с тремя целочисленными аргументами на каждой итерации резервного копирования: status последней итерации, remaining количество ещё не скопированных страниц, и total общее количество страниц. По умолчанию 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.12.

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.12.

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.12.

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 содержит deserialize API.

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

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 objects

Объект 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 | sequence) – Значения 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 повторно выполнить параметризованный DML SQL-запрос sql.

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

Параметры:

• sql (str) – Один SQL-запрос DML.

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

Возбуждает:

ProgrammingError – если sql содержит более одного SQL-запроса или не является DML-инструкцией.

Пример:

rows = [
    ("row1",),
    ("row2",),
]
# cur – объект sqlite3.Cursor
cur.executemany("INSERT INTO data VALUES(?)", rows)

Примечание

Все результирующие строки отбрасываются, включая запросы DML с предложениями RETURNING.

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

executescript(sql_script, /)¶

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

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

Пример:

# cur – объект sqlite3.Cursor
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

fetchone()¶

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

fetchmany(size=cursor.arraysize)¶

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

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

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

fetchall()¶

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

close()¶

Закрывает курсор сейчас (а не при вызове __del__).

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

setinputsizes(sizes, /)¶

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

setoutputsize(size, column=None, /)¶

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

arraysize¶

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

connection¶

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

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

description¶

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

Он также устанавливается для операторов SELECT, не имеющих подходящих строк.

lastrowid¶

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

Примечание

Вставки в таблицы WITHOUT ROWID не записываются.

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

rowcount¶

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

row_factory¶

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

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

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

Объекты Row¶Row objects

class sqlite3.Row¶

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

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

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

keys()¶

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

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

Объекты Blob¶Blob objects

class sqlite3.Blob¶

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

Экземпляр Blob – это объект, похожий на файл, который может читать и записывать данные в BLOB SQLite. Вызывайте 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))")

# Записать данные в blob с помощью двух операций записи:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Изменить первый и последний байты нашего blob
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Прочитать содержимое нашего blob
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # выводит "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¶PrepareProtocol objects

class sqlite3.PrepareProtocol¶

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

Исключения¶Exceptions

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

exception sqlite3.Warning¶

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

exception sqlite3.Error¶

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

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

sqlite_errorcode¶

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

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

sqlite_errorname¶

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

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

exception sqlite3.InterfaceError¶

Исключение возбуждается при неправильном использовании низкоуровневого C API SQLite. Другими словами, если это исключение возбуждено, вероятно, это указывает на ошибку в модуле 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 sqlite3, например, при указании неверного количества привязок к запросу или при попытке работы с закрытым Connection. ProgrammingError является подклассом DatabaseError.

exception sqlite3.NotSupportedError¶

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

Типы SQLite и Python¶SQLite and Python types

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

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

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

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

Адаптеры и конвертеры по умолчанию (устарело)¶Default adapters and converters (deprecated)

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

• Адаптер для объектов datetime.date в strings в формате ISO 8601.

• Адаптер для объектов datetime.datetime в строки в формате ISO 8601.

• Конвертер для объявленных типов "date" в объекты datetime.date.

• Конвертер для объявленных типов "timestamp" в объекты datetime.datetime. Дробные части будут усечены до 6 цифр (точность до микросекунд).

Интерфейс командной строки¶Command-line interface

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

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

Введите .quit или CTRL-D, чтобы выйти из оболочки.

-h, --help¶

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

-v, --version¶

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

Как использовать плейсхолдеры для подстановки значений в SQL-запросы¶How to use placeholders to bind values in SQL queries

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

>>> # Никогда не делайте этого – это небезопасно!
>>> 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 параметры должны быть последовательностью, длина которой должна совпадать с количеством плейсхолдеров, иначе возникает ProgrammingError. Для именованного стиля параметры должны быть экземпляром dict (или подкласса), который должен содержать ключи для всех именованных параметров; любые лишние элементы игнорируются. Вот пример обоих стилей:

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

# Это стиль с именованными параметрами, используемый с 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)

# Это стиль с вопросительными знаками, используемый в запросе SELECT:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

Как адаптировать пользовательские типы Python к значениям SQLite¶How to adapt custom Python types to SQLite values

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¶How to convert SQLite values to custom Python types

Написание адаптера позволяет преобразовывать из пользовательских типов 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)

# Зарегистрировать адаптер и конвертер
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Разбор с использованием объявленных типов
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) Разбор с использованием имён столбцов
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()

Рецепты адаптеров и конвертеров¶Adapter and converter recipes

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

import datetime
import sqlite3

def adapt_date_iso(val):
    """Адаптировать datetime.date к дате в формате ISO 8601."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Преобразует datetime.datetime в дату ISO 8601 без часового пояса."""
    return val.isoformat()

def adapt_datetime_epoch(val):
    """Преобразует datetime.datetime в метку времени Unix."""
    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):
    """Преобразует дату ISO 8601 в объект datetime.date."""
    return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Преобразует дату и время ISO 8601 в объект datetime.datetime."""
    return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Преобразует метку времени Unix (эпоха) в объект datetime.datetime."""
    return datetime.datetime.fromtimestamp(int(val))

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

Как использовать сокращенные методы соединения¶How to use connection shortcut methods

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

# Создаёт и заполняет таблицу.
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)

# Выводит содержимое таблицы.
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() не является сокращённым методом и не вызывается автоматически.
# Объект соединения следует закрывать вручную.
con.close()

Как использовать менеджер контекста соединения¶How to use the connection context manager

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

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

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

# При успешном выполнении con.commit() вызывается автоматически.
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() вызывается после завершения блока with с исключением,
# исключение по-прежнему возбуждается и должно быть перехвачено.
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Объект Connection, используемый как контекстный менеджер, только фиксирует или откатывает транзакции,
# поэтому объект соединения следует закрывать вручную.
con.close()

Как работать с SQLite URI¶How to work with SQLite URIs

Некоторые полезные приёмы работы с 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
>>> con.close()

• Не создавать неявно новый файл базы данных, если он ещё не существует; будет вызвано исключение 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.

Как создавать и использовать фабрики строк¶How to create and use row factories

По умолчанию 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]         # Доступ по индексу.
'Earth'
>>> row["name"]    # Доступ по имени.
'Earth'
>>> row["RADIUS"]  # Имена столбцов нечувствительны к регистру.
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]  # Индексный доступ.
1
>>> row.b   # Доступ через атрибут.
2
>>> con.close()

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

Как работать с текстовыми кодировками, отличными от UTF-8¶How to handle non-UTF-8 text encodings

По умолчанию 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 HOWTO:

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

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

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