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

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

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

Открывает соединение с базой данных SQLite.

Параметры:

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

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

Connection

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

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

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

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

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

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

Изменено в версии 3.13: Использование параметров timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements и uri в позиционной форме объявлено устаревшим. В Python 3.15 они станут параметрами, которые можно задавать только по имени.

sqlite3.complete_statement(statement)

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

Например:

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

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

Пример использования в реальном приложении см. в runsource() в файле Lib/sqlite3/__main__.py.

sqlite3.enable_callback_tracebacks(flag, /)

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

Примечание

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

sqlite3.register_adapter(type, adapter, /)

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

sqlite3.register_converter(typename, converter, /)

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

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

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

sqlite3.LEGACY_TRANSACTION_CONTROL

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

sqlite3.PARSE_DECLTYPES

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

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

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

Примечание

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

sqlite3.PARSE_COLNAMES

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

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

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

sqlite3.SQLITE_OK

sqlite3.SQLITE_DENY

sqlite3.SQLITE_IGNORE

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

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

sqlite3.apilevel

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

sqlite3.paramstyle

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

Примечание

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

sqlite3.sqlite_version

Номер версии исполняемой библиотеки SQLite в виде string.

sqlite3.sqlite_version_info

Номер версии исполняемой библиотеки SQLite в виде tuple из значений типа integers.

sqlite3.threadsafety

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

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

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

Изменено в версии 3.11: Значение threadsafety теперь устанавливается динамически, а не жестко задается равным 1.

sqlite3.version

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

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

sqlite3.version_info

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

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

sqlite3.SQLITE_DBCONFIG_DEFENSIVE

sqlite3.SQLITE_DBCONFIG_DQS_DDL

sqlite3.SQLITE_DBCONFIG_DQS_DML

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP

sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

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

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

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

См. также

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

Документация SQLite: параметры конфигурации соединения с базой данных

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

class sqlite3.Connection

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

См. также

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

Изменено в версии 3.13: Выдаётся предупреждение ResourceWarning, если перед удалением объекта Connection не был вызван метод close().

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

cursor(factory=Cursor)

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

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

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

Параметры:

• table (str) – Имя таблицы, в которой находится большой двоичный объект.
• column (str) – Имя столбца, в котором находится большой двоичный объект.
• rowid (int) – Идентификатор строки, в которой находится большой двоичный объект.
• readonly (bool) – Установите значение True, чтобы открыть большой двоичный объект без разрешения на запись. По умолчанию — False.
• name (str) – Имя базы данных, в которой находится большой двоичный объект. По умолчанию — "main".

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

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

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

Blob

Примечание

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

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

commit()

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

rollback()

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

close()

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

execute(sql, parameters=(), /)

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

executemany(sql, parameters, /)

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

executescript(sql_script, /)

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

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

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

Параметры:

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

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

Пример:

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

Изменено в версии 3.13: Передача name, narg и func в качестве именованных аргументов устарела. В Python 3.15 эти параметры можно будет передавать только позиционно.

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

Изменено в версии 3.13: Передача name, n_arg и aggregate_class в качестве именованных аргументов устарела. В Python 3.15 эти параметры можно будет передавать только позиционно.

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())
con.close()

create_collation(name, callable, /)

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

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

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

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

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

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

Чтобы удалить функцию сортировки, задайте для callable значение None.

Изменено в версии 3.11: Имя последовательности сортировки может содержать любые символы 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.

Изменено в версии 3.13: Передача authorizer_callback в качестве именованного аргумента устарела. В Python 3.15 этот параметр можно будет передавать только позиционно.

set_progress_handler(progress_handler, n)

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

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

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

Изменено в версии 3.13: Передача progress_handler в качестве именованного аргумента устарела. В Python 3.15 этот параметр можно будет передавать только позиционно.

set_trace_callback(trace_callback)

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

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

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

Примечание

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

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

Изменено в версии 3.13: Передача trace_callback в качестве именованного аргумента устарела. В Python 3.15 этот параметр можно будет передавать только позиционно.

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)

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

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

Параметры:

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

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

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

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

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

iterdump(*, filter=None)

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

Параметры:

filter (str | None) – Необязательный шаблон LIKE для объектов базы данных, которые нужно выгрузить, например prefix_%. Если задано None (значение по умолчанию), будут включены все объекты базы данных.

Пример:

# 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

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

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)
dst.close()
src.close()

Добавлено в версии 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.

getconfig(op, /)

Запрашивает логическую настройку подключения.

Параметры:

op (int) – код SQLITE_DBCONFIG.

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

bool

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

setconfig(op, enable=True, /)

Задаёт логическую настройку подключения.

Параметры:

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

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

serialize(*, name='main')

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

Параметры:

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

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

bytes

Примечание

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

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

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

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

Параметры:

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

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

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

Примечание

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

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

autocommit

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

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

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

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

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

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

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

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

Примечание

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

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

in_transaction

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

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

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

isolation_level

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

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

Примечание

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

row_factory

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

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

text_factory

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

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

total_changes

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

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

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

Объекты курсора являются итераторами, поэтому после выполнения запроса 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.

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

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

Для выполнения нескольких инструкций 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.

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

executescript(sql_script, /)

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

sql_script должен быть значением типа string.

Пример:

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

fetchone()

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

fetchmany(size=cursor.arraysize)

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

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

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

Изменено в версии 3.13.8: Отрицательные значения size отклоняются с вызовом исключения ValueError.

fetchall()

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

close()

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

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

setinputsizes(sizes, /)

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

setoutputsize(size, column=None, /)

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

arraysize

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

Изменено в версии 3.13.8: Отрицательные значения отклоняются с вызовом исключения ValueError.

connection

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

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

description

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

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

lastrowid

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

Примечание

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

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

rowcount

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

row_factory

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

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

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

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

class sqlite3.Row

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

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

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

keys()

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

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

Объекты BLOB

class sqlite3.Blob

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

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

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

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

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

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

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

close()

Закрывает BLOB-объект.

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

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

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

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

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

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

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

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

-h, --help

Выводит справку по интерфейсу командной строки.

-v, --version

Выводит версию используемой библиотеки SQLite.

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

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

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

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

В SQL-операторе можно использовать один из двух видов заполнителей: вопросительные знаки (стиль qmark) или именованные заполнители (именованный стиль). Для стиля qmark параметры должны быть последовательностью, длина которой должна совпадать с количеством заполнителей, иначе будет вызвано исключение 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())
con.close()

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

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

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

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

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

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

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

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

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

sqlite3.register_adapter(Point, adapt_point)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры адаптеров и конвертеров

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

import datetime
import sqlite3

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

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.replace(tzinfo=None).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)

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

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

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

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

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

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

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

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

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

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

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

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

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

Как работать с 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
>>> con.close()

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

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

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

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

con1.close()
con2.close()

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

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

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

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

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

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

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

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

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

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

При её использовании запросы возвращают dict вместо tuple:

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

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

from collections import namedtuple

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

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

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

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

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

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

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

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

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

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

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

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