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

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

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 "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 указывает, как долго подключение должно ждать разблокировки до возбуждения исключения. Значение по умолчанию для параметра 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. Это позволяет указать параметры. Например, чтобы открыть базу данных в режиме только для чтения, вы можете использовать:

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

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

По умолчанию вы не получите никаких трассировок в пользовательских функциях, агрегатах, преобразователях, обратных вызовах авторизатора и т. д. Если вы хотите их отладить, вы можете вызвать эту функцию с flag, установленным в True. После этого вы получите трассировки обратных вызовов для 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() с заданными параметрами и возвращает курсор.

executemany(sql[, parameters])

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

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)

Создаёт сортировку (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:")

# 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 будет возвращать объекты Unicode для TEXT. Если вы хотите возвращать байтовые строки вместо этого, вы можете установить его в bytes.

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

Следующий пример кода проиллюстрирует это:

import sqlite3

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

AUSTRIA = "\xd6sterreich"

# by default, rows are returned as Unicode
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 или вызываемым объектом, который будет выполняться на каждой итерации с тремя целочисленными аргументами, соответственно: статус последней итерации, остаток страниц, которые ещё предстоит скопировать, и общее количество страниц.

Аргумент 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-запрос. 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

# This is the qmark style:
cur.execute("insert into people values (?, ?)", (who, age))

# And this is the named style:
cur.execute("select * from people where name_last=:who and age=:age", {"who": who, "age": age})

print(cur.fetchone())

con.close()

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-скрипт, полученный в качестве параметра.

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. Если он не указан, размер массива курсора определяет количество строк для извлечения. Метод должен попытаться извлечь столько строк, сколько указано в параметре size. Если это невозможно из-за того, что указанное количество строк недоступно, может быть возвращено меньше строк.

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

fetchall()

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

close()

Закрыть курсор сейчас (вместо того, чтобы ждать, когда будет вызван __del__).

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

rowcount

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

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

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

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

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

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

class sqlite3.Row

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

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

Если два объекта 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 в вашем коде.

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

import sqlite3

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

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

# Create the table
con.execute("create table person(firstname, lastname)")

# Fill the table
con.executemany("insert into person(firstname, lastname) values (?, ?)", persons)

# Print the table contents
for row in con.execute("select firstname, lastname from person"):
    print(row)

print("I just deleted", con.execute("delete from person").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 person (id integer primary key, firstname varchar unique)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("insert into person(firstname) values (?)", ("Joe",))

# 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 person(firstname) values (?)", ("Joe",))
except sqlite3.IntegrityError:
    print("couldn't add Joe twice")

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