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 изначально, чтобы преобразовать их в типы 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 и использовать различные возможности, описанные в разделе Как работать с URI SQLite.

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

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.

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	Потокобезопасность	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) – Имя таблицы, в которой находится большой двоичный объект.
• column (str) – Имя столбца, в котором находится большой двоичный объект.
• row (str) – Имя строки, в которой находится большой двоичный объект.
• readonly (bool) – Установите значение True, если большой двоичный объект нужно открыть без разрешения на запись. По умолчанию — False.
• name (str) – Имя базы данных, в которой находится большой двоичный объект. По умолчанию — "main".

Вызывает исключение:

OperationalError – При попытке открыть большой двоичный объект в таблице WITHOUT ROWID.

Возвращаемый тип:

Blob

Примечание

Размер большого двоичного объекта нельзя изменить с помощью класса Blob. Используйте функцию SQL zeroblob для создания большого двоичного объекта фиксированного размера.

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

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

См. также

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

getlimit(category, /)

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

Параметры:

category (int) – Категория ограничений SQLite, которую нужно запросить.

Возвращаемый тип:

int

Вызывает исключение:

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

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

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

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

setlimit(category, limit, /)

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

Параметры:

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

Возвращаемый тип:

int

Вызывает исключение:

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

Пример: ограничение количества присоединённых баз данных до 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

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

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

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

isolation_level

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

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

row_factory

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

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

text_factory

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

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

total_changes

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

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

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

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

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

class sqlite3.Cursor

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

execute(sql, parameters=(), /)

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

Параметры:

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

Вызывает исключения:

ProgrammingError – если sql содержит более одной инструкции SQL.

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

Для выполнения нескольких инструкций SQL используйте executescript().

executemany(sql, parameters, /)

Для каждого элемента в parameters повторно выполняет параметризованную инструкцию SQL DML sql, используя параметры.

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

Параметры:

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

Вызывает исключения:

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

Пример:

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

Примечание

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

executescript(sql_script, /)

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

sql_script должен иметь тип string.

Пример:

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

fetchone()

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

fetchmany(size=cursor.arraysize)

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

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

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

fetchall()

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

close()

Немедленно закрывает курсор (вместо того чтобы ждать вызова __del__).

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

setinputsizes(sizes, /)

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

setoutputsize(size, column=None, /)

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

arraysize

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

connection

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

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

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 родительского подключения.

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

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

class sqlite3.Row

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

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

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

keys()

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

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

Объекты BLOB

class sqlite3.Blob

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

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

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

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

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

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

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

close()

Закрывает BLOB.

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

read(length=-1, /)

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

write(data, /)

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

tell()

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

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

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

Объекты PrepareProtocol

class sqlite3.PrepareProtocol

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

Исключения

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

exception sqlite3.Warning

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

exception sqlite3.Error

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

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

sqlite_errorcode

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

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

sqlite_errorname

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

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

exception sqlite3.InterfaceError

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

exception sqlite3.DatabaseError

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

exception sqlite3.DataError

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

exception sqlite3.OperationalError

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

exception sqlite3.IntegrityError

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

exception sqlite3.InternalError

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

exception sqlite3.ProgrammingError

Исключение, вызываемое при ошибках программирования при работе с API sqlite3, например при передаче неверного числа значений для связывания с запросом или попытке выполнить операцию с закрытым объектом 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 с помощью адаптеров объектов, а также преобразовывать типы SQLite в типы Python с помощью модуля sqlite3 и преобразователей.

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

Для типов 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 цифр, преобразователь временных меток усекает её значение до точности в микросекунды.

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

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

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

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

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

Как адаптировать пользовательские типы 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 создаются неявно, а эти сокращённые методы возвращают объекты курсора. Таким образом, достаточно одного вызова объекта Connection, чтобы выполнить инструкцию SELECT и сразу перебрать её результаты.

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

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

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

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

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

Объект 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,)

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

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

По умолчанию 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, перед выполнением INSERT, UPDATE, DELETE или REPLACE инструкций методы execute() и executemany() неявно открывают новые транзакции; для остальных инструкций неявная обработка транзакций не выполняется. Используйте методы commit() и rollback(), чтобы соответственно фиксировать и откатывать ожидающие транзакции. С помощью атрибута isolation_level можно выбрать поведение транзакций SQLite — то есть определить, будет ли и какой тип инструкций BEGIN неявно выполнять sqlite3.

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

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