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=100, uri=False)

Открыть подключение к базе данных SQLite.

Параметры

• database (объект-путь) – Путь к файлу базы данных для открытия. Передайте ":memory:" для открытия подключения к базе данных в оперативной памяти, а не на диске.
• 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 должно кэшировать внутри для этого подключения, чтобы избежать расходов на разбор. По умолчанию 100 предложений.
• 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 чтобы отключить эту функцию.

sqlite3.register_adapter(type, adapter, /)

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

sqlite3.register_converter(typename, converter, /)

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

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

Модульные константы

sqlite3.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, указывающая уровень безопасности потоков, поддерживаемый модулем sqlite3. В настоящее время закодировано как 1, что означает «Потоки могут использовать модуль, но не соединения». Однако это не всегда верно. Вы можете проверить режим работы с потоками библиотеки SQLite во время компиляции с помощью следующего запроса:

import sqlite3
con = sqlite3.connect(":memory:")
con.execute("""
    select * from pragma_compile_options
    where compile_options like 'THREADSAFE=%'
""").fetchall()

Обратите внимание, что уровни threadsafety SQLITE_THREADSAFE не соответствуют уровням DB-API 2.0.

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 или его подклассов.

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-функцию.

Parameters

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

Raises

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

New in version 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-функцию агрегации.

Parameters

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

interrupt()

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

set_authorizer(authorizer_callback)

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

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

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

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

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

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

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

Параметры

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

in_transaction

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

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

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

isolation_level

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

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

row_factory

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

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

text_factory

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

Пример:

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

AUSTRIA = "Österreich"

# by default, rows are returned as str
cur.execute("SELECT ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

# but we can make sqlite3 always return bytestrings ...
con.text_factory = bytes
cur.execute("SELECT ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# the bytestrings will be encoded in UTF-8, unless you stored garbage in the
# database ...
assert row[0] == AUSTRIA.encode("utf-8")

# we can also implement a custom text_factory ...
# here we implement one that appends "foo" to all strings
con.text_factory = lambda x: x.decode("utf-8") + "foo"
cur.execute("SELECT ?", ("bar",))
row = cur.fetchone()
assert row[0] == "barfoo"

con.close()

total_changes

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

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

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

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

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

class sqlite3.Cursor

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

execute(sql, parameters=(), /)

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

Параметры

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

Исключения

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

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

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

executemany(sql, parameters, /)

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

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

Параметры

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

Исключения

• Ошибка программирования – Если sql не является утверждением DML.
• Предупреждение – Если sql содержит более одного SQL-утверждения.

Пример:

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

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

Только для чтения атрибут, который предоставляет SQLite базу данных Connection принадлежащую курсору. Объект 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 утверждений; равно -1 для других утверждений, включая запросы CTE. Он обновляется только методами execute() и executemany().

row_factory

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

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

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

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

class sqlite3.Row

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

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

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

keys()

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

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

Объекты PrepareProtocol

class sqlite3.PrepareProtocol

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

Исключения

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

exception sqlite3.Warning

Это исключение возбуждается sqlite3 , если SQL-запрос не является string или если несколько операторов передаются в execute() или executemany(). Warning является подклассом Exception.

exception sqlite3.Error

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

exception sqlite3.InterfaceError

Это исключение возбуждается sqlite3 для извлечения данных после отката или если sqlite3 не может привязать параметры. InterfaceError является подклассом Error.

exception sqlite3.DatabaseError

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

exception sqlite3.DataError

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

exception sqlite3.OperationalError

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

exception sqlite3.IntegrityError

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

exception sqlite3.InternalError

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

exception sqlite3.ProgrammingError

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

exception sqlite3.NotSupportedError

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

Типы SQLite и Python

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

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

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

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

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

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

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

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

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

import sqlite3
import datetime

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

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

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

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

con.close()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

sqlite3.register_adapter(Point, adapt_point)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import datetime
import sqlite3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Некоторые полезные хитрости с URI:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

from collections import namedtuple

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

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

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

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

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

Модуль sqlite3 не соответствует рекомендациям по обработке транзакций, предложенным PEP 249.

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

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

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