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

Функции и константы модуля¶Module functions and constants

sqlite3.apilevel¶

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

sqlite3.paramstyle¶

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

Примечание

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

sqlite3.version¶

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

sqlite3.version_info¶

Номер версии этого модуля в виде кортежа целых чисел. Это не версия библиотеки SQLite.

sqlite3.sqlite_version¶

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

sqlite3.sqlite_version_info¶

Номер версии библиотеки SQLite времени выполнения в виде кортежа целых чисел.

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 не соответствуют уровням DB-API 2.0 threadsafety.

sqlite3.PARSE_DECLTYPES¶

Эта константа предназначена для использования с параметром detect_types функции connect().

Установка этого флага заставляет модуль sqlite3 анализировать объявленный тип для каждого возвращаемого столбца. Он выделит первое слово объявленного типа, т. е. для «integer primary key» выделит «integer», а для «number(10)» выделит «number». Затем для этого столбца он заглянет в словарь преобразователей и использует зарегистрированную там функцию преобразования для этого типа.

sqlite3.PARSE_COLNAMES¶

Эта константа предназначена для использования с параметром detect_types функции connect().

Установка этого флага заставляет интерфейс SQLite анализировать имя столбца для каждого возвращаемого столбца. Он будет искать строку вида [mytype] и затем решать, что «mytype» – это тип столбца. Он попытается найти запись для «mytype» в словаре преобразователей и затем использовать найденную функцию преобразования для возврата значения. Имя столбца, найденное в Cursor.description, не включает тип; например, если в SQL используется что-то вроде 'as "Expiration date [datetime]"', то будет выделено всё до первого '[' для имени столбца и удалён предшествующий пробел: имя столбца будет просто «Expiration date».

sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])¶

Открывает соединение с файлом базы данных SQLite database. По умолчанию возвращает объект Connection, если не указана пользовательская factory.

database is a path-like object giving the pathname (absolute or relative to the current working directory) of the database file to be opened. You can use ":memory:" to open a database connection to a database that resides in RAM instead of on disk.

Когда к базе данных обращаются несколько соединений и один из процессов изменяет базу данных, база данных SQLite блокируется до завершения этой транзакции. Параметр timeout задаёт, как долго соединение должно ждать снятия блокировки, прежде чем возникнет исключение. Значение по умолчанию для параметра timeout – 5.0 (пять секунд).

По поводу параметра isolation_level обратитесь к свойству isolation_level объектов Connection.

SQLite изначально поддерживает только типы TEXT, INTEGER, REAL, BLOB и NULL. Если вы хотите использовать другие типы, необходимо добавить поддержку самостоятельно. Параметр detect_types и использование пользовательских преобразователей, зарегистрированных с помощью функции модуля register_converter(), позволяют легко это сделать.

detect_types по умолчанию равен 0 (т. е. выключено, определение типов отсутствует); вы можете установить его в любую комбинацию PARSE_DECLTYPES и PARSE_COLNAMES, чтобы включить определение типов. Из-за поведения SQLite типы не могут быть определены для генерируемых полей (например, max(data)), даже если установлен параметр detect_types. В таком случае возвращаемый тип – str.

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

По умолчанию модуль sqlite3 использует свой класс Connection для вызова connect. Однако вы можете создать подкласс класса Connection и заставить connect() использовать ваш класс, передав его в параметре factory.

Подробности см. в разделе Типы SQLite и Python данного руководства.

Модуль sqlite3 внутренне использует кэш операторов для снижения накладных расходов на разбор SQL. Если вы хотите явно задать количество операторов, кэшируемых для соединения, можно установить параметр cached_statements. Текущая реализация по умолчанию кэширует 100 операторов.

Если uri равен True, database интерпретируется как URI с путём к файлу и необязательной строкой запроса. Схема должна быть "file:". Путь может быть относительным или абсолютным путём к файлу. Строка запроса позволяет передавать параметры в SQLite. Некоторые полезные приёмы с URI включают:

# Открыть базу данных в режиме только для чтения.
con = sqlite3.connect("file:template.db?mode=ro", uri=True)

# Не создавать неявно новый файл базы данных, если его ещё не существует.
# Вызовет sqlite3.OperationalError, если не удастся открыть файл базы данных.
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)

# Создать общую именованную базу данных в памяти.
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
con1.executescript("create table t(t); insert into t values(28);")
rows = con2.execute("select * from t").fetchall()

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

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

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

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

sqlite3.register_converter(typename, callable)¶

Регистрирует вызываемый объект для преобразования байтовой строки из базы данных в пользовательский тип Python. Вызываемый объект будет вызываться для всех значений базы данных, имеющих тип typename. Смотрите параметр detect_types функции connect(), чтобы узнать, как работает определение типа. Обратите внимание, что typename и имя типа в запросе сравниваются без учёта регистра.

sqlite3.register_adapter(type, callable)¶

Регистрирует вызываемый объект для преобразования пользовательского типа Python type в один из поддерживаемых типов SQLite. Вызываемый объект callable принимает в качестве единственного параметра значение Python и должен возвращать значение одного из следующих типов: int, float, str или bytes.

sqlite3.complete_statement(sql)¶

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

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

# Минимальная оболочка SQLite для экспериментов

import sqlite3

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

buffer = ""

print("Enter your SQL commands to execute in sqlite3.")
print("Enter a blank line to exit.")

while True:
    line = input()
    if line == "":
        break
    buffer += line
    if sqlite3.complete_statement(buffer):
        try:
            buffer = buffer.strip()
            cur.execute(buffer)

            if buffer.lstrip().upper().startswith("SELECT"):
                print(cur.fetchall())
        except sqlite3.Error as e:
            print("An error occurred:", e.args[0])
        buffer = ""

con.close()

sqlite3.enable_callback_tracebacks(flag)¶

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

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

class sqlite3.Connection¶

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

isolation_level¶

Получает или устанавливает текущий уровень изоляции по умолчанию. None для режима автокоммита или одно из значений «DEFERRED», «IMMEDIATE» или «EXCLUSIVE». Смотрите раздел Управление транзакциями для более подробного объяснения.

in_transaction¶

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

Новое в версии 3.2.

cursor(factory=Cursor)¶

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

commit()¶

Этот метод фиксирует текущую транзакцию. Если не вызвать этот метод, все изменения, сделанные после последнего вызова commit(), не будут видны из других подключений к базе данных. Если вы не видите данные, которые записали в базу, проверьте, не забыли ли вызвать этот метод.

rollback()¶

Этот метод откатывает все изменения в базе данных, сделанные после последнего вызова commit().

close()¶

Это закрывает подключение к базе данных. Обратите внимание, что это не вызывает автоматически commit(). Если просто закрыть подключение к базе данных, не вызвав предварительно 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, num_params, func, *, deterministic=False)¶

Создаёт пользовательскую функцию, которую впоследствии можно использовать в SQL-выражениях под именем функции name. num_params – количество параметров, принимаемых функцией (если num_params равно -1, функция может принимать любое количество аргументов), а func – это вызываемый объект Python, который вызывается как SQL-функция. Если deterministic истинно, созданная функция помечается как детерминированная, что позволяет SQLite выполнять дополнительные оптимизации. Этот флаг поддерживается в SQLite 3.8.3 и выше; при использовании с более старыми версиями будет вызвано NotSupportedError.

Функция может возвращать любой из типов, поддерживаемых SQLite: bytes, str, int, float и None.

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

Пример:

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, num_params, aggregate_class)¶

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

Класс агрегата должен реализовывать метод step, который принимает количество параметров num_params (если num_params равно -1, функция может принимать любое количество аргументов), и метод finalize, который возвращает окончательный результат агрегата.

Метод finalize может возвращать любой из типов, поддерживаемых SQLite: bytes, str, int, float и None.

Пример:

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

Создаёт collation с указанными name и callable. Вызываемый объект будет получать два строковых аргумента. Он должен возвращать -1, если первый меньше второго, 0, если они равны, и 1, если первый больше второго. Обратите внимание, что это управляет сортировкой (ORDER BY в SQL), поэтому сравнения не влияют на другие операции SQL.

Обратите внимание, что вызываемый объект будет получать свои параметры в виде байтовых строк Python, которые обычно закодированы в UTF-8.

Следующий пример показывает пользовательскую коллацию, которая сортирует «в обратном порядке»:

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

Чтобы удалить коллацию, вызовите create_collation с None в качестве вызываемого объекта:

con.create_collation("reverse", None)

interrupt()¶

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

set_authorizer(authorizer_callback)¶

Эта процедура регистрирует колбэк. Колбэк вызывается при каждой попытке доступа к столбцу таблицы в базе данных. Колбэк должен возвращать SQLITE_OK, если доступ разрешён, SQLITE_DENY, если весь SQL-запрос должен быть прерван с ошибкой, и SQLITE_IGNORE, если столбец должен рассматриваться как значение NULL. Эти константы доступны в модуле sqlite3.

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

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

set_progress_handler(handler, n)¶

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

Чтобы очистить ранее установленный обработчик прогресса, вызовите метод с None для 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 из разделяемых библиотек. Расширения SQLite могут определять новые функции, агрегатные функции или целые реализации виртуальных таблиц. Одним из известных расширений является расширение полнотекстового поиска, распространяемое с SQLite.

Загружаемые расширения по умолчанию отключены. См. 1.

Новое в версии 3.2.

import sqlite3

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

# включить загрузку расширений
con.enable_load_extension(True)

# Загрузить расширение полнотекстового поиска.
con.execute("select load_extension('./fts3.so')")

# в качестве альтернативы можно загрузить расширение с помощью вызова API:
# con.load_extension("./fts3.so")

# отключить загрузку расширения снова
con.enable_load_extension(False)

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

Загружаемые расширения по умолчанию отключены. См. 1.

Новое в версии 3.2.

row_factory¶

Этот атрибут можно заменить на вызываемый объект, который принимает курсор и исходную строку в виде кортежа и возвращает реальную результирующую строку. Таким образом можно реализовать более продвинутые способы возврата результатов, например возврат объекта, который также может обращаться к столбцам по имени.

Пример:

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¶

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

Также можно установить его в любой другой вызываемый объект, принимающий единственный параметр – байтовую строку и возвращающий результирующий объект.

См. следующий пример для иллюстрации:

import sqlite3

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

AUSTRIA = "Österreich"

# по умолчанию строки возвращаются как str
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

# но можно заставить sqlite3 всегда возвращать байтовые строки...
con.text_factory = bytes
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# байтовые строки будут в кодировке UTF-8, если только в базу не попал мусор
# база данных...
assert row[0] == AUSTRIA.encode("utf-8")

# можно также реализовать собственный text_factory...
# здесь реализован такой, который добавляет "foo" ко всем строкам
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¶

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

iterdump()¶

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

Пример:

# Преобразовать файл existing_db.db в SQL-дамп 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, даже когда к ней обращаются другие клиенты или одновременно то же самое подключение. Копия будет записана в обязательный аргумент target, который должен быть другим экземпляром Connection.

По умолчанию, или когда pages равен 0 или отрицательному целому, вся база данных копируется за один шаг; в противном случае метод выполняет цикл, копируя до pages страниц за раз.

Если указан progress, он должен быть либо None, либо вызываемым объектом, который будет выполняться на каждой итерации с тремя целочисленными аргументами: status последней итерации, remaining количество страниц, оставшихся для копирования, и total общее количество страниц.

Аргумент name задаёт имя базы данных, которая будет скопирована: это должна быть строка, содержащая либо "main" (по умолчанию) для основной базы данных, "temp" для временной базы данных, либо имя, указанное после ключевого слова AS в выражении ATTACH DATABASE для присоединённой базы данных.

Аргумент sleep задаёт количество секунд ожидания между последовательными попытками резервного копирования оставшихся страниц; может быть указан как целое или число с плавающей запятой.

Пример 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)

Доступность: SQLite 3.6.11 или выше

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

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

class sqlite3.Cursor¶

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

execute(sql[, parameters])¶

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

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

executemany(sql, seq_of_parameters)¶

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

import sqlite3

class IterChars:
    def __init__(self):
        self.count = ord('a')

    def __iter__(self):
        return self

    def __next__(self):
        if self.count > ord('z'):
            raise StopIteration
        self.count += 1
        return (chr(self.count - 1),) # это кортеж из одного элемента

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

theIter = IterChars()
cur.executemany("insert into characters(c) values (?)", theIter)

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

Вот более короткий пример с использованием генератора:

import sqlite3
import string

def char_generator():
    for c in string.ascii_lowercase:
        yield (c,)

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

cur.executemany("insert into characters(c) values (?)", char_generator())

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

executescript(sql_script)¶

Это нестандартный удобный метод для выполнения нескольких SQL-выражений за один раз. Сначала он выполняет выражение COMMIT, а затем выполняет SQL-скрипт, переданный в качестве параметра. Этот метод игнорирует isolation_level; любое управление транзакциями должно быть добавлено в sql_script.

sql_script может быть экземпляром str.

Пример:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.executescript("""
    create table person(
        firstname,
        lastname,
        age
    );

    create table book(
        title,
        author,
        published
    );

    insert into book(title, author, published)
    values (
        'Dirk Gently''s Holistic Detective Agency',
        'Douglas Adams',
        1987
    );
    """)
con.close()

fetchone()¶

Извлекает следующую строку результата запроса, возвращая одну последовательность или None, если данные закончились.

fetchmany(size=cursor.arraysize)¶

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

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

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

fetchall()¶

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

close()¶

Закрывает курсор сейчас (а не при вызове __del__).

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

setinputsizes(sizes)¶

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

setoutputsize(size[, column])¶

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

rowcount¶

Хотя класс Cursor модуля sqlite3 реализует этот атрибут, собственная поддержка определения «затронутых строк»/«выбранных строк» в движке базы данных работает непредсказуемо.

Для выражений executemany() количество изменений суммируется в rowcount.

В соответствии со спецификацией Python DB API, атрибут rowcount «равен -1, если над курсором не выполнялось executeXX() или количество строк последней операции не может быть определено интерфейсом». Это включает выражения SELECT, потому что количество строк, полученных запросом, нельзя определить, пока не будут извлечены все строки.

В SQLite версий до 3.6.5 rowcount устанавливается в 0, если выполнить DELETE FROM table без условия.

lastrowid¶

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

Примечание

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

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

arraysize¶

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

description¶

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

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

connection¶

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

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

Объекты строк¶Row Objects

class sqlite3.Row¶

Экземпляр Row служит высокооптимизированной row_factory для объектов Connection. Он старается имитировать кортеж в большинстве своих возможностей.

Он поддерживает доступ по имени столбца и индексу, итерацию, представление, проверку равенства и len().

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

keys()¶

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

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

Предположим, мы инициализируем таблицу, как в приведённом выше примере:

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute('''create table stocks
(date text, trans text, symbol text,
 qty real, price real)''')
cur.execute("""insert into stocks
            values ('2006-01-05','BUY','RHAT',100,35.14)""")
con.commit()
cur.close()

Теперь подключаем Row:

>>> con.row_factory = sqlite3.Row
>>> cur = con.cursor()
>>> cur.execute('select * from stocks')
<sqlite3.Cursor object at 0x7f4e7dd8fa80>
>>> r = cur.fetchone()
>>> type(r)
<class 'sqlite3.Row'>
>>> tuple(r)
('2006-01-05', 'BUY', 'RHAT', 100.0, 35.14)
>>> len(r)
5
>>> r[2]
'RHAT'
>>> r.keys()
['date', 'trans', 'symbol', 'qty', 'price']
>>> r['qty']
100.0
>>> for member in r:
...     print(member)
...
2006-01-05
BUY
RHAT
100.0
35.14

Исключения¶Exceptions

exception sqlite3.Warning¶

Подкласс Exception.

exception sqlite3.Error¶

Базовый класс остальных исключений в этом модуле. Он является подклассом Exception.

exception sqlite3.DatabaseError¶

Исключение, вызываемое для ошибок, связанных с базой данных.

exception sqlite3.IntegrityError¶

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

exception sqlite3.ProgrammingError¶

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

exception sqlite3.OperationalError¶

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

exception sqlite3.NotSupportedError¶

Исключение вызывается, если используется метод или API базы данных, который не поддерживается базой данных, например, вызов метода rollback() для соединения, которое не поддерживает транзакции или имеет транзакции отключены. Является подклассом DatabaseError.

Типы SQLite и Python¶SQLite and Python types

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

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

import sqlite3
import datetime
import time

def adapt_datetime(ts):
    return time.mktime(ts.timetuple())

sqlite3.register_adapter(datetime.datetime, adapt_datetime)

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

now = datetime.datetime.now()
cur.execute("select ?", (now,))
print(cur.fetchone()[0])

con.close()

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

import sqlite3

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

    def __repr__(self):
        return "(%f;%f)" % (self.x, self.y)

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

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

# Зарегистрировать адаптер
sqlite3.register_adapter(Point, adapt_point)

# Зарегистрировать конвертер
sqlite3.register_converter("point", convert_point)

p = Point(4.0, -3.2)

#########################
# 1) Использование объявленных типов
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.cursor()
cur.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()

#######################
# 1) Использование имён столбцов
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.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 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()

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

Лежащая в основе библиотека sqlite3 по умолчанию работает в режиме autocommit, а модуль Python sqlite3 по умолчанию – нет.

Режим autocommit означает, что операторы, изменяющие базу данных, вступают в силу немедленно. Оператор BEGIN или SAVEPOINT отключает режим autocommit, а оператор COMMIT, ROLLBACK или RELEASE, завершающий внешнюю транзакцию, снова включает режим autocommit.

Модуль Python sqlite3 по умолчанию неявно выполняет оператор BEGIN перед оператором языка модификации данных (DML) (т.е. INSERT/UPDATE/DELETE/REPLACE).

Можно управлять тем, какие операторы BEGIN sqlite3 выполняет неявно, с помощью параметра isolation_level вызова connect(), или через свойство isolation_level соединений. Если не указывать isolation_level, используется простой BEGIN, что eквивалентно указанию DEFERRED. Другие возможные значения: IMMEDIATE и EXCLUSIVE.

Можно отключить неявное управление транзакциями модуля sqlite3, установив isolation_level в None. При этом лежащая в основе библиотека sqlite3 продолжит работать в режиме autocommit. После этого можно полностью управлять состоянием транзакции, явно выполняя операторы BEGIN, ROLLBACK, SAVEPOINT и RELEASE в коде.

Обратите внимание, что executescript() игнорирует isolation_level; любое управление транзакциями должно быть добавлено явно.

Эффективное использование sqlite3¶Using sqlite3 efficiently

import sqlite3

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

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

# Создать таблицу
con.execute("create table lang(name, first_appeared)")

# Заполнить таблицу
con.executemany("insert into lang(name, first_appeared) values (?, ?)", langs)

# Выводит содержимое таблицы.
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 не является методом-ярлыком и не вызывается автоматически,
# поэтому объект соединения следует закрывать вручную.
con.close()

import sqlite3

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

cur = con.cursor()
cur.execute("select 'John' as name, 42 as age")
for row in cur:
    assert row[0] == row["name"]
    assert row["name"] == row["nAmE"]
    assert row[1] == row["age"]
    assert row[1] == row["AgE"]

con.close()

import sqlite3

con = sqlite3.connect(":memory:")
con.execute("create table lang (id integer primary key, name varchar unique)")

# При успешном выполнении con.commit() вызывается автоматически.
with con:
    con.execute("insert into lang(name) values (?)", ("Python",))

# con.rollback() вызывается после завершения блока with с исключением,
# исключение все равно возбуждается, и его необходимо перехватить
try:
    with con:
        con.execute("insert into lang(name) values (?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Объект Connection, используемый как контекстный менеджер, только фиксирует или откатывает транзакции,
# поэтому объект соединения следует закрывать вручную.
con.close()