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

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

sqlite3.version¶

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

sqlite3.version_info¶

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

sqlite3.sqlite_version¶

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

sqlite3.sqlite_version_info¶

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

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, – это только первое слово имени столбца; то есть если используется что-то вроде 'as "x [datetime]"' в SQL, то будет извлечено всё до первого пробела: именем столбца будет просто "x".

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

Открывает соединение с файлом базы данных SQLite database. Можно использовать ":memory:" для открытия соединения с базой данных, которая находится в оперативной памяти, вместо файла на диске.

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

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

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

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

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

Если uri равно true, database интерпретируется как URI. Это позволяет задавать параметры. Например, чтобы открыть базу данных в режиме только для чтения, можно использовать:

db = sqlite3.connect('file:path/to/database?mode=ro', uri=True)

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

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

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, чтобы снова отключить эту возможность.

12.6.2. Объекты соединений¶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() курсора с переданными параметрами и возвращает курсор.

executemany(sql[, parameters])¶

Это нестандартное сокращение, которое создаёт объект курсора вызовом метода cursor(), затем вызывает метод executemany() курсора с переданными параметрами и возвращает курсор.

executescript(sql_script)¶

Это нестандартное сокращение, которое создаёт объект курсора вызовом метода cursor(), затем вызывает метод executescript() курсора с переданным sql_script и возвращает курсор.

create_function(name, num_params, func)¶

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

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

Пример:

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

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

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.

Единственный аргумент, передаваемый колбэку, – это выполняемый оператор (в виде строки). Возвращаемое значение колбэка игнорируется. Обратите внимание, что бэкенд выполняет не только операторы, переданные методам Cursor.execute(). Другие источники включают управление транзакциями модуля Python и выполнение триггеров, определённых в текущей базе данных.

Передача None в качестве trace_callback отключает трассировочный колбэк.

Новое в версии 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)

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"])

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

text_factory¶

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

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

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

import sqlite3

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

AUSTRIA = "\xd6sterreich"

# по умолчанию строки возвращаются как Unicode
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"

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)

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

class sqlite3.Cursor¶

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

execute(sql[, parameters])¶

Выполняет SQL-выражение. SQL-выражение может быть параметризованным (т. е. с использованием плейсхолдеров вместо литералов SQL). Модуль sqlite3 поддерживает два вида плейсхолдеров: вопросительные знаки (стиль qmark) и именованные плейсхолдеры (именованный стиль).

Вот пример обоих стилей:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table people (name_last, age)")

who = "Yeltsin"
age = 72

# Это стиль qmark:
cur.execute("insert into people values (?, ?)", (who, age))

# А это именованный стиль:
cur.execute("select * from people where name_last=:who and age=:age", {"who": who, "age": age})

print(cur.fetchone())

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

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

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

executescript(sql_script)¶

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

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
    );
    """)

fetchone()¶

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

fetchmany(size=cursor.arraysize)¶

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

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

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

fetchall()¶

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

close()¶

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

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

rowcount¶

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

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

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

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

lastrowid¶

Этот атрибут только для чтения возвращает rowid последней измененной строки. Он устанавливается только при выполнении оператора INSERT или REPLACE с использованием метода execute(). Для операций, отличных от INSERT или REPLACE, или при вызове executemany(), lastrowid устанавливается в None.

Если оператору INSERT или REPLACE не удалось выполнить вставку, возвращается 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

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

class sqlite3.Row¶

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

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

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

keys()¶

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

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

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

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

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

>>> conn.row_factory = sqlite3.Row
>>> c = conn.cursor()
>>> c.execute('select * from stocks')
<sqlite3.Cursor object at 0x7f4e7dd8fa80>
>>> r = c.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

12.6.5. Исключения¶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.

12.6.6. Типы 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])

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

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

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

12.6.7. Управление транзакциями¶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 в коде.

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

import sqlite3

persons = [
    ("Hugo", "Boss"),
    ("Calvin", "Klein")
    ]

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

# Создать таблицу
con.execute("create table person(firstname, lastname)")

# Заполнить таблицу
con.executemany("insert into person(firstname, lastname) values (?, ?)", persons)

# Выводит содержимое таблицы.
for row in con.execute("select firstname, lastname from person"):
    print(row)

print("I just deleted", con.execute("delete from person").rowcount, "rows")

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"]

import sqlite3

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

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

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

12.6.9. Часто встречающиеся проблемы¶Common issues