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

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

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

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

Parameters

• database (path-like object) – Путь к открываемому файлу базы данных. Передайте ":memory:", чтобы открыть соединение с базой данных, которая находится в оперативной памяти, а не на диске.

• timeout (float) – Сколько секунд соединение должно подождать, прежде чем поднять исключение, если база данных заблокирована другим соединением. Если другое соединение открывает транзакцию для изменения базы данных, она будет заблокирована до тех пор, пока транзакция не будет зафиксирована. По умолчанию 5 секунд.

• detect_types (int) – Управляет тем, ищутся ли типы данных, не относящиеся к natively supported by 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 (по умолчанию), только создающий поток может использовать соединение. Если False, соединение может быть общим для нескольких потоков; в этом случае операции записи должны быть сериализованы пользователем во избежание повреждения данных.

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

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

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

Result type

Connection

Вызывает auditing event sqlite3.connect с аргументом database.

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

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

Изменено в версии 3.7: Теперь database может быть не только строкой, но и path-like object.

Добавлено в версии 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, /)¶

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

sqlite3.register_converter(typename, converter, /)¶

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

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

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

sqlite3.PARSE_COLNAMES¶

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

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

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

sqlite3.PARSE_DECLTYPES¶

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

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

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

sqlite3.SQLITE_OK¶

sqlite3.SQLITE_DENY¶

sqlite3.SQLITE_IGNORE¶

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

• Доступ разрешен (SQLITE_OK),

• Оператор SQL должен быть прерван с ошибкой (SQLITE_DENY)

• Столбец должен рассматриваться как значение NULL (SQLITE_IGNORE)

sqlite3.apilevel¶

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

sqlite3.paramstyle¶

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

Примечание

Модуль sqlite3 поддерживает оба стиля параметров qmark и numeric DB-API, поскольку именно это поддерживает базовая библиотека SQLite. Однако DB-API не позволяет использовать несколько значений для атрибута paramstyle.

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

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

sqlite3.version¶

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

sqlite3.version_info¶

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

Объекты подключения¶

class sqlite3.Connection¶

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

См.также

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

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

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

isolation_level¶

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

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

in_transaction¶

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

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

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

row_factory¶

Вызываемый объект, который принимает два аргумента, объект Cursor и необработанные результаты строк в виде tuple, и возвращает пользовательский объект, представляющий строку SQLite.

Пример:

import sqlite3

def dict_factory(cursor, row):
    d = {}
    for idx, col in enumerate(cursor.description):
        d[col[0]] = row[idx]
    return d

con = sqlite3.connect(":memory:")
con.row_factory = dict_factory
cur = con.cursor()
cur.execute("select 1 as a")
print(cur.fetchone()["a"])

con.close()

Если возврата кортежа недостаточно и вам нужен доступ к столбцам на основе имен, вам следует установить row_factory в высоко оптимизированный тип sqlite3.Row. Row обеспечивает доступ к столбцам как на основе индексов, так и на основе имен без учета регистра почти без затрат памяти. Это, вероятно, будет лучше, чем ваш собственный подход на основе словаря или даже решение на основе db_row.

text_factory¶

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

Пример:

import sqlite3

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(factory=Cursor)¶

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

commit()¶

Зафиксировать любую незавершенную транзакцию в базе данных. Если нет открытой транзакции, этот метод не работает.

rollback()¶

Откат к началу любой незавершенной транзакции. Если нет открытой транзакции, этот метод не работает.

close()¶

Закройте соединение с базой данных. Любая незавершенная транзакция не фиксируется неявно; убедитесь, что commit() перед закрытием, чтобы избежать потери незавершенных изменений.

execute(sql, parameters=(), /)¶

Создайте новый объект Cursor и вызовите на нем execute() с заданными sql и параметрами. Верните новый объект курсора.

executemany(sql, parameters, /)¶

Создайте новый объект Cursor и вызовите на нем executemany() с заданными sql и параметрами. Верните новый объект курсора.

executescript(sql_script, /)¶

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

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

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

Parameters

• name (str) – Имя функции SQL.

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

• func (callback | None) – Вызываемая переменная, которая вызывается при вызове функции SQL. Вызываемая функция должна возвращать a type natively supported by SQLite. Установите значение None для удаления существующей SQL-функции.

• deterministic (bool) – Если True, созданная SQL-функция помечается как deterministic, что позволяет SQLite выполнять дополнительную оптимизацию.

Exception

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

Добавлено в версии 3.8: Параметр детерминированности.

Пример:

import sqlite3
import hashlib

def md5sum(t):
    return hashlib.md5(t).hexdigest()

con = sqlite3.connect(":memory:")
con.create_function("md5", 1, md5sum)
cur = con.cursor()
cur.execute("select md5(?)", (b"foo",))
print(cur.fetchone()[0])

con.close()

create_aggregate(name, /, n_arg, aggregate_class)¶

Создание или удаление определяемой пользователем агрегатной функции SQL.

Parameters

• name (str) – Имя агрегатной функции SQL.

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

• aggregate_class (class | None) – Класс должен реализовывать следующие методы: * step(): Добавить строку в агрегат. * finalize(): Возвращать конечный результат агрегата в виде a type natively supported by SQLite. Количество аргументов, которые должен принимать метод step(), контролируется параметром n_arg. Установите значение None для удаления существующей агрегатной функции SQL.

Пример:

import sqlite3

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.cursor()
cur.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 если они упорядочены одинаково

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

import sqlite3

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.cursor()
cur.execute("create table test(x)")
cur.executemany("insert into test(x) values (?)", [("a",), ("b",)])
cur.execute("select x from test order by x collate reverse")
for row in cur:
    print(row)
con.close()

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

interrupt()¶

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

set_authorizer(authorizer_callback)¶

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

Первый аргумент обратного вызова указывает, какая операция должна быть авторизована. Второй и третий аргументы будут аргументами или None в зависимости от первого аргумента. 4-й аргумент - это имя базы данных («main», «temp» и т.д.), если применимо. 5-й аргумент - имя самого внутреннего триггера или представления, ответственного за попытку доступа, или 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(). Другие источники включают transaction management модуля 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.

Вызывает auditing event sqlite3.enable_load_extension с аргументами connection, enabled.

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

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

import sqlite3

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

# enable extension loading
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().

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

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

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

iterdump()¶

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

Пример:

# Convert file existing_db.db to SQL dump file dump.sql
import sqlite3

con = sqlite3.connect('existing_db.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.

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

Parameters

• target (Connection) – Подключение к базе данных для сохранения резервной копии.

• pages (int) – Количество страниц, копируемых за один раз. Если равно или меньше 0, вся база данных копируется за один шаг. По умолчанию установлено значение -1.

• progress (callback | None) – Если задан как вызываемый, то вызывается с тремя целочисленными аргументами для каждой итерации резервного копирования: статус последней итерации, оставшееся количество страниц, которые еще предстоит скопировать, и общее количество страниц. По умолчанию имеет значение None.

• name (str) – Имя базы данных для резервного копирования. Либо "main" (по умолчанию) для основной базы данных, "temp" для временной базы данных, либо имя пользовательской базы данных, присоединенное с помощью SQL-оператора ATTACH DATABASE.

• sleep (float) – Количество секунд сна между последовательными попытками резервного копирования оставшихся страниц.

Пример 1, копирование существующей базы данных в другую:

import sqlite3

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

con = sqlite3.connect('existing_db.db')
bck = sqlite3.connect('backup.db')
with bck:
    con.backup(bck, pages=1, progress=progress)
bck.close()
con.close()

Пример 2, копирование существующей базы данных в переходную копию:

import sqlite3

source = sqlite3.connect('existing_db.db')
dest = sqlite3.connect(':memory:')
source.backup(dest)

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

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

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

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

for row in cur.execute("select * from data"):
    print(row)

class sqlite3.Cursor¶

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

execute(sql, parameters=(), /)¶

Выполните SQL-оператор sql. Привяжите значения к оператору с помощью placeholders, которые отображаются на sequence или dict параметры.

execute() выполнит только один оператор SQL. Если вы попытаетесь выполнить с его помощью более одного оператора, он выдаст ошибку Warning. Используйте executescript(), если вы хотите выполнить несколько операторов SQL одним вызовом.

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

executemany(sql, parameters, /)¶

Выполнить parameterized SQL-оператор sql против всех последовательностей параметров или отображений, найденных в последовательности параметров. Также можно использовать iterator, передающий параметры вместо последовательности. Использует ту же неявную обработку транзакций, что и execute().

Пример:

data = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("insert into t values(?)", data)

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

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

rowcount¶

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

lastrowid¶

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

Примечание

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

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

arraysize¶

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

description¶

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

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

connection¶

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

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

Строковые объекты¶

class sqlite3.Row¶

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

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

keys()¶

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

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

Пример:

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

Объекты PrepareProtocol¶

class sqlite3.PrepareProtocol¶

Единственное назначение типа PrepareProtocol - действовать как протокол адаптации в стиле PEP 246 для объектов, которые могут adapt themselves в native SQLite types.

Исключения¶

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

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

Операции SQL обычно должны использовать значения из переменных Python. Однако остерегайтесь использовать строковые операции Python для сборки запросов, поскольку они уязвимы к SQL injection attacks (см. xkcd webcomic для юмористического примера того, что может пойти не так):

# Never do this -- insecure!
symbol = 'RHAT'
cur.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

Вместо этого используйте подстановку параметров DB-API. Чтобы вставить переменную в строку запроса, используйте в ней заполнитель, а фактические значения подставьте в запрос, предоставив их в виде tuple значений второму аргументу метода курсора execute(). В SQL-запросе может использоваться один из двух видов заполнителей: вопросительные знаки (стиль qmark) или именованные заполнители (стиль named). Для стиля qmark, parameters должен быть sequence. Для именованного стиля это может быть либо экземпляр sequence, либо dict. Длина sequence должна соответствовать количеству заполнителей, иначе возникает ошибка ProgrammingError. Если задан dict, он должен содержать ключи для всех именованных параметров. Любые лишние элементы игнорируются. Вот пример обоих стилей:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table lang (name, first_appeared)")

# This is the qmark style:
cur.execute("insert into lang values (?, ?)", ("C", 1972))

# The qmark style used with executemany():
lang_list = [
    ("Fortran", 1957),
    ("Python", 1991),
    ("Go", 2009),
]
cur.executemany("insert into lang values (?, ?)", lang_list)

# And this is the named style:
cur.execute("select * from lang where first_appeared=:year", {"year": 1972})
print(cur.fetchall())

con.close()

Использование адаптеров для хранения пользовательских типов Python в базах данных SQLite¶

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

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

import sqlite3

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

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

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

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

con.close()

import sqlite3

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

def adapt_point(point):
    return "%f;%f" % (point.x, point.y)

sqlite3.register_adapter(Point, adapt_point)

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

p = Point(4.0, -3.2)
cur.execute("select ?", (p,))
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. Имена столбцов имеют приоритет над объявленными типами.

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

import sqlite3

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}".encode("utf-8")

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

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

В модуле datetime имеются адаптеры по умолчанию для типов date и datetime. Они будут передаваться в SQLite как даты/временные метки 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 чисел, ее значение будет усечено до микросекундной точности конвертером временных меток.

Рецепты адаптеров и преобразователей¶

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

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)

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

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(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.

import sqlite3

langs = [
    ("C++", 1985),
    ("Objective-C", 1984),
]

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

# Create the table
con.execute("create table lang(name, first_appeared)")

# Fill the table
con.executemany("insert into lang(name, first_appeared) values (?, ?)", langs)

# 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,
# so the connection object should be closed manually
con.close()

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

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

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

import sqlite3

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

Работа с URIs SQLite¶

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

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

  con = sqlite3.connect("file:template.db?mode=ro", uri=True)
  

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

  con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
  

• Создайте общую именованную базу данных in-memory:

  con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
  con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
  con1.execute("create table t(t)")
  con1.execute("insert into t values(28)")
  con1.commit()
  rows = con2.execute("select * from t").fetchall()
  

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

Контроль транзакций¶

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

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

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

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