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

Функции и константы модуля

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

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

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 "Expiration date [datetime]"' в своём SQL, то мы будем анализировать всё до первого '[' для имени столбца и убирать предшествующий пробел: имя столбца будет просто «Дата истечения срока действия».

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

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

database — это объект-путь, предоставляющий имя файла (абсолютное или относительное к текущей рабочей директории) базы данных, которую нужно открыть. Вы можете использовать ":memory:" для открытия подключения к базе данных в оперативной памяти вместо диска.

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

# Open a database in read-only mode.
con = sqlite3.connect("file:template.db?mode=ro", uri=True)

# Don't implicitly create a new database file if it does not already exist.
# Will raise sqlite3.OperationalError if unable to open a database file.
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)

# Create a shared named in-memory database.
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, как в следующем примере:

# A minimal SQLite shell for experiments

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)

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

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

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 равно true, созданная функция помечается как детерминированная, что позволяет 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)

Создаёт сортировку (коллирование) с заданным именем 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 в зависимости от первого аргумента. 4-й аргумент — имя базы данных (“main”, “temp” и т.д.), если применимо. 5-й аргумент — имя самого внутреннего триггера или представления, ответственного за попытку доступа, или 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:")

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

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

Иллюстративный пример кода см. ниже:

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

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

iterdump()

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

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

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),) # this is a 1-tuple

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 в случае, если над курсором не выполнялись операции, или количество строк последней операции не может быть определено интерфейсом». Это включает 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

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

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

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

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

Исключения

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

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)

# Register the adapter
sqlite3.register_adapter(Point, adapt_point)

# Register the converter
sqlite3.register_converter("point", convert_point)

p = Point(4.0, -3.2)

#########################
# 1) Using declared types
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) Using column names
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()

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

Базовая 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, что эквивалентно указанию DEFERRED. Другие возможные значения — IMMEDIATE и EXCLUSIVE.

Вы можете отключить неявное управление транзакциями модуля sqlite3, установив isolation_level в значение None. Это позволит базовой библиотеке sqlite3 работать в режиме autocommit. Затем вы сможете полностью контролировать состояние транзакции, явно выполнив операторы BEGIN, ROLLBACK, SAVEPOINT и RELEASE в своем коде.

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

Использование sqlite3 эффективно

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

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

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