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)

Установить соединение с базой данных SQLite.

Параметры

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

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

Connection

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

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

Новое в версии 3.4: Параметр uri.

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

Новое в версии 3.10: Событие аудита sqlite3.connect/handle.

sqlite3.complete_statement(statement)

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

Например:

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

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

sqlite3.enable_callback_tracebacks(flag, /)

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

Зарегистрируйте unraisable hook handler для улучшения опыта отладки:

>>> sqlite3.enable_callback_tracebacks(True)
>>> con = sqlite3.connect(":memory:")
>>> def evil_trace(stmt):
...     5/0
>>> con.set_trace_callback(evil_trace)
>>> def debug(unraisable):
...     print(f"{unraisable.exc_value!r} in callback {unraisable.object.__name__}")
...     print(f"Error message: {unraisable.err_msg}")
>>> import sys
>>> sys.unraisablehook = debug
>>> cur = con.execute("SELECT 1")
ZeroDivisionError('division by zero') in callback evil_trace
Error message: None

sqlite3.register_adapter(type, adapter, /)

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

sqlite3.register_converter(typename, converter, /)

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

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

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

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 библиотеки в виде 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 библиотеки.

sqlite3.version_info

Номер версии этого модуля в виде tuple целых чисел integers. Это не версия 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()

Сохранить все ожидающие транзакции в базе данных. Если открытых транзакций нет, этот метод ничего не делает.

rollback()

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

close()

Закрыть соединение с базой данных. Любые ожидающие транзакции не сохраняются неявно; убедитесь, что вы 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',)

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 (str) – Имя SQL агрегатной функции окна для создания или удаления.
• num_params (int) – Количество аргументов, которые может принимать 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())

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.

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

set_trace_callback(trace_callback)

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

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

Передача 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.

Вызывает событие аудита 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)

con.close()

load_extension(path, /)

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

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

Введено в версии 3.2.

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

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 (Соединение) – Соединение с базой данных, в которую будет сохранена резервная копия.
• pages (int) – Количество страниц, копируемых за один раз. Если равно или меньше 0, вся база данных копируется за один шаг. По умолчанию -1.
• progress (обратный вызов | None) – Если установлено значение вызываемого объекта, оно вызывается с тремя целочисленными аргументами для каждой итерации резервного копирования: статус последней итерации, остаток количества страниц, которые еще предстоит скопировать, и общее количество страниц. По умолчанию 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)

Введено в версии 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.

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.

in_transaction

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

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

Введено в версии 3.2.

isolation_level

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

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

row_factory

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

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

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

An instance of a Cursor has the following attributes and methods.

execute(sql, parameters=(), /)

Execute a single SQL statement, optionally binding Python values using placeholders.

Parameters

• sql (строка) – A single SQL statement.
• parameters (dict | последовательность) – Python values to bind to placeholders in sql. A dict if named placeholders are used. A последовательность if unnamed placeholders are used. See How to use placeholders to bind values in SQL queries.

Raises

ProgrammingError – If sql contains more than one SQL statement.

If isolation_level is not None, sql is an INSERT, UPDATE, DELETE, or REPLACE statement, and there is no open transaction, a transaction is implicitly opened before executing sql.

Use executescript() to execute multiple SQL statements.

executemany(sql, parameters, /)

For every item in parameters, repeatedly execute the parameterized DML SQL statement sql.

Uses the same implicit transaction handling as execute().

Parameters

• sql (строка) – A single SQL DML statement.
• parameters (итерируемый объект) – An итерируемый объект of parameters to bind with the placeholders in sql. See How to use placeholders to bind values in SQL queries.

Raises

ProgrammingError – If sql contains more than one SQL statement, or is not a DML statement.

Example:

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

Примечание

Any resulting rows are discarded, including DML statements with RETURNING clauses.

executescript(sql_script, /)

Execute the SQL statements in sql_script. If there is a pending transaction, an implicit COMMIT statement is executed first. No other implicit transaction control is performed; any transaction control must be added to sql_script.

sql_script must be a string.

Example:

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

If row_factory is None, return the next row query result set as a tuple. Else, pass it to the row factory and return its result. Return None if no more data is available.

fetchmany(size=cursor.arraysize)

Return the next set of rows of a query result as a list. Return an empty list if no more rows are available.

The number of rows to fetch per call is specified by the size parameter. If size is not given, arraysize determines the number of rows to be fetched. If fewer than size rows are available, as many rows as are available are returned.

Note there are performance considerations involved with the size parameter. For optimal performance, it is usually best to use the arraysize attribute. If the size parameter is used, then it is best for it to retain the same value from one fetchmany() call to the next.

fetchall()

Return all (remaining) rows of a query result as a list. Return an empty list if no rows are available. Note that the arraysize attribute can affect the performance of this operation.

close()

Close the cursor now (rather than whenever __del__ is called).

The cursor will be unusable from this point forward; a ProgrammingError exception will be raised if any operation is attempted with the cursor.

setinputsizes(sizes, /)

Required by the DB-API. Does nothing in sqlite3.

setoutputsize(size, column=None, /)

Required by the DB-API. Does nothing in sqlite3.

arraysize

Read/write attribute that controls the number of rows returned by fetchmany(). The default value is 1 which means a single row would be fetched per call.

connection

Read-only attribute that provides the SQLite database Connection belonging to the cursor. A Cursor object created by calling con.cursor() will have a connection attribute that refers to con:

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

description

Read-only attribute that provides the column names of the last query. To remain compatible with the Python DB API, it returns a 7-tuple for each column where the last six items of each tuple are None.

It is set for SELECT statements without any matching rows as well.

lastrowid

Read-only attribute that provides the row id of the last inserted row. It is only updated after successful INSERT or REPLACE statements using the execute() method. For other statements, after executemany() or executescript(), or if the insertion failed, the value of lastrowid is left unchanged. The initial value of lastrowid is None.

Примечание

Inserts into WITHOUT ROWID tables are not recorded.

Изменено в версии 3.6: Added support for the REPLACE statement.

rowcount

Read-only attribute that provides the number of modified rows for INSERT, UPDATE, DELETE, and REPLACE statements; is -1 for other statements, including CTE queries. It is only updated by the execute() and executemany() methods, after the statement has run to completion. This means that any resulting rows must be fetched in order for rowcount to be updated.

row_factory

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

Объект 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!'"

close()

Закрыть BLOB.

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

read(length=- 1, /)

Прочитать length байтов данных из BLOB по текущей позиции смещения. Если достигнут конец BLOB, возвращаются данные до конца файла. Если 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

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

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

sqlite_errorname

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

Добавлен в версии 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 с помощью конвертеров.

Конвертеры и адаптеры по умолчанию

Существуют адаптеры по умолчанию для типов date и datetime в модуле datetime. Они будут отправляться в SQLite как ISO-даты/ISO-временные метки.

Конвертеры по умолчанию регистрируются под именем «date» для datetime.date и под именем «timestamp» для datetime.datetime.

Таким образом, в большинстве случаев вы можете использовать даты/временные метки из Python без дополнительных действий. Формат адаптеров также совместим с экспериментальными функциями даты/времени SQLite.

Следующий пример демонстрирует это.

import sqlite3
import datetime

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(d date, ts timestamp)")

today = datetime.date.today()
now = datetime.datetime.now()

cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
cur.execute("select d, ts from test")
row = cur.fetchone()
print(today, "=>", row[0], type(row[0]))
print(now, "=>", row[1], type(row[1]))

cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
row = cur.fetchone()
print("current_date", row[0], type(row[0]))
print("current_timestamp", row[1], type(row[1]))

con.close()

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

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

Как адаптировать пользовательские типы 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])

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

Как преобразовать значения 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])

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

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

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 вызывает необработанное исключение, транзакция отменяется.

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

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительную информацию об этой функции, включая список параметров, можно найти в документации 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

Вы можете создать пользовательскую 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}

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

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

С некоторыми корректировками, вышеуказанный рецепт можно адаптировать для использования 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 не придерживается рекомендаций по обработке транзакций, предложенных PEP 249.

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

Если isolation_level установлен в None, транзакции вообще не открываются неявно. Это оставляет базовую библиотеку SQLite в режиме автоматического подтверждения, но также позволяет пользователю выполнять свою собственную обработку транзакций с помощью явных SQL-операторов. Режим автоматического подтверждения базовой библиотеки SQLite можно запросить с помощью атрибута in_transaction.

Метод executescript() неявно фиксирует любые ожидаемые транзакции перед выполнением данного SQL-скрипта, независимо от значения isolation_level.