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

Исходный код: Lib/sqlite3/

SQLite - это библиотека C, которая предоставляет легкую дисковую базу данных, не требующую отдельного серверного процесса и позволяющую обращаться к базе данных с помощью нестандартного варианта языка запросов SQL. Некоторые приложения могут использовать SQLite для внутреннего хранения данных. Также можно выполнить прототип приложения с помощью SQLite, а затем портировать код в более крупную базу данных, такую как PostgreSQL или Oracle.

Модуль sqlite3 был написан Gerhard Häring. Он предоставляет интерфейс SQL, совместимый со спецификацией DB-API 2.0, описанной в разделе PEP 249.

Для использования модуля необходимо сначала создать объект Connection, представляющий базу данных. Здесь данные будут сохранены в файле example.db:

import sqlite3
conn = sqlite3.connect('example.db')

Можно также указать специальное имя, :memory: для создания базы данных в оперативной памяти.

После создания Connection можно создать объект Cursor и вызвать его метод execute() для выполнения команд SQL:

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

# Мы также можем закрыть соединение, если завершили с ним. Просто убедитесь, что
# какие-либо изменения были внесены или они будут потеряны.
conn.close()

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

import sqlite3
conn = sqlite3.connect('example.db')
c = conn.cursor()

Обычно операции SQL должны использовать значения из Python переменных. Не следует собирать запрос с помощью операций Python’s строка, поскольку это небезопасно; это делает вашу программу уязвимой к атаке SQL инъекция (юмористический пример того, что может пойти не так, см. в https://xkcd.com/327/).

Вместо этого используйте подстановку параметров DB-API. Поместите ? в качестве местозаполнителя везде, где требуется использовать значение, а затем укажите кортеж значения в качестве второго аргумента метода execute() курсора. (Другие модули базы данных могут использовать другой местозаполнитель, например, %s или :1.) Например:

# Никогда не делай этого - небезопасно!
symbol = 'RHAT'
c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

# Вместо этого сделай
t = ('RHAT',)
c.execute('SELECT * FROM stocks WHERE symbol=?', t)
print(c.fetchone())

# Большой пример, который вставляет много записей одновременно
purchases = [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
             ('2006-04-05', 'BUY', 'MSFT', 1000, 72.00),
             ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
            ]
c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases)

Чтобы извлечь данные после выполнения инструкция SELECT, можно либо обработать курсор как итератор, вызвать метод fetchone() курсора для извлечения одной совпадающей строки, либо вызвать fetchall() для получения списка совпадающих строк.

В этом примере используется форма итератора:

>>> for row in c.execute('SELECT * FROM stocks ORDER BY price'):
        print(row)

('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
('2006-04-06', 'SELL', 'IBM', 500, 53.0)
('2006-04-05', 'BUY', 'MSFT', 1000, 72.0)

См.также

https://www.sqlite.org: Веб-страница SQLite; в документации описаны синтаксис и доступные типы данных для поддерживаемого диалекта SQL.
https://www.w3schools.com/sql/: Учебное пособие, справочник и примеры для изучения синтаксиса SQL.
PEP 249 - спецификация API базы данных 2.0: PEP написана Marc-André Lemburg.

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

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

Открывает подключение к database файла базы данных SQLite. По умолчанию возвращает объект 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 для вызова соединения. Однако можно подкласс класс 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.

Raises an auditing event sqlite3.connect with argument 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 set to True. После этого вы получите трейсбэки от колбэки на sys.stderr. Используйте False для повторного отключения функции.

Объекты Connection¶

class sqlite3.Connection¶

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

isolation_level¶: Получение или установка текущего уровня изоляции по умолчанию. None для режима автоматического ввода в эксплуатацию или одного из следующих: «DEFERRED», «IMMEDIATE» или «EXCLUSIVE». Более подробное объяснение см. в разделе Управление транзакциями.

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

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

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

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

rollback()¶: Метод выполняет откат всех изменений в базе данных с момента последнего вызова commit().

close()¶: Приведет к закрытию подключения к базе данных. Обратите внимание, что это не вызывает commit() автоматически. Если закрыть подключение к базе данных без предварительного вызова commit(), изменения будут потеряны!

execute(sql[, parameters])¶: Нестандартный ярлык, который создает объект курсора путем вызова метода cursor(), вызывает метод execute() курсора с заданным parameters и возвращает курсор.

executemany(sql[, parameters])¶: Нестандартный ярлык, который создает объект курсора путем вызова метода cursor(), вызывает метод executemany() курсора с заданным 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)¶

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

Класс aggregate должен реализовать метод 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» и т. д.), если применимо. Пятый аргумент - это имя самого внутреннего триггера или представления, ответственного за попытку доступа или 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.

load_extension(path)¶

Подпрограмма загружает расширение SQLite из общей библиотеки. Перед использованием этой подпрограммы необходимо включить загрузку внутренней линии с помощью enable_load_extension().

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

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

row_factory¶

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

Пример:

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

text_factory¶

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

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

Для иллюстрации см. следующий пример код

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

iterdump()¶

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

Пример:

# Конвертировать файл existing_db.db в SQL дампp файл 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()

sqlite3.backup(target, *, pages=-1, progress=None, name="main", sleep=0.250)¶

Метод создает резервную копию базы данных SQLite, даже если к ней обращаются другие клиенты или одновременно одно и то же подключение. Копия будет записана в обязательный аргумент target, который должен быть другим Connection сущность.

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

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

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

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

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

import sqlite3

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

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

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

import sqlite3

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

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

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

Объекты Cursor¶

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

close()¶

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

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

rowcount¶

Несмотря на то, что класс Cursor модуля sqlite3 реализует эту атрибут, собственная поддержка ядра сУБД для определения «затронутых строк «/» выбранных строк» является нежелательной.

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

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

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

lastrowid¶

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

Если INSERT или REPLACE инструкция, подведенный, чтобы вставить предыдущий успешный rowid, являются возвращенный.

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

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

description¶

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

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

connection¶

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

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

Объекты Row¶

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

Исключения¶

exception sqlite3.Warning¶: Подкласс Exception.

exception sqlite3.Error¶: Базовый класс других исключений в этом модуле. Это подкласс Exception.

exception sqlite3.DatabaseError¶: Исключение для ошибок, связанных с базой данных.

exception sqlite3.IntegrityError¶: Исключение, возникающее при нарушении реляционной целостности базы данных, например, сбой проверки внешнего ключа. Это подкласс DatabaseError.

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

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

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

SQLite и типы Python¶

Введение¶

SQLite изначально поддерживает следующие типы: NULL, INTEGER, REAL, TEXT, BLOB.

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

Python тип	SQLite тип
`None`	`NULL`
`int`	`INTEGER`
`float`	`REAL`
`str`	`TEXT`
`bytes`	`BLOB`

По умолчанию типы SQLite преобразуются в типы Python:

SQLite тип	Python тип
`NULL`	`None`
`INTEGER`	`int`
`REAL`	`float`
`TEXT`	зависит от `text_factory`, `str` по умолчанию
`BLOB`	`bytes`

Система типов модуля sqlite3 является расширяемой двумя способами: можно сохранить дополнительные типы Python в базе данных SQLite с помощью адаптации объектов, а также разрешить модулю sqlite3 преобразовывать типы SQLite в различные типы Python с помощью преобразователей.

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

Как описано выше, SQLite поддерживает только ограниченный набор типов. Чтобы использовать другие типы Python с SQLite, необходимо адаптировать их в один из поддерживаемых модулей sqlite3 типов для SQLite: один из типов, int, float, str, байт.

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

Позвольте вашему объекту адаптироваться¶

Это хороший подход, если вы пишете класс сами. Предположим, у вас такой класс:

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

Теперь необходимо сохранить точку в одном столбце SQLite. Сначала необходимо выбрать один из поддерживаемых типов, который будет используемый для представления точки. Давайте просто используем str и разделим координаты, используя точку с запятой. Затем необходимо дать своему классу метод __conform__(self, protocol) который должен возвращает преобразованный значение. Будет PrepareProtocol protocol параметров.

Регистрация адаптера с возможностью вызова¶

Другая возможность состоит в создании функции, которая преобразует тип в строка представление и регистрирует функцию с помощью register_adapter().

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

Модуль sqlite3 имеет два адаптера по умолчанию для Python’s встроенных типов datetime.date и datetime.datetime. Теперь предположим, что мы хотим сохранить datetime.datetime объекты не в представлении ISO, а в виде метки времени Unix.

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

Преобразование значений SQLite в пользовательские типы Python¶

Запись адаптера позволяет отправлять пользовательские типы Python в SQLite. Но чтобы сделать это действительно полезным, нам нужно сделать Python SQLite, чтобы Python работу в оба конца.

Введите конвертеры.

Вернемся к классу Point. Мы сохранили координаты x и y, разделенные точкой с запятой, как строки в SQLite.

Сначала мы определим функцию конвертера, которая принимает строка как параметр и создает из него Point объект.

Примечание

Функции конвертера всегда вызываются с помощью объекта bytes, независимо от типа данных, который вы отправили значение в SQLite.

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

Теперь необходимо сделать так, чтобы модуль sqlite3 знал, что то, что вы выбираете из базы данных, на самом деле является точкой. Есть два способа сделать это:

Неявно через объявленный тип
Явно через имя столбца

Оба способа описаны в разделе Функции и константы модуля, в записях для констант PARSE_DECLTYPES и PARSE_COLNAMES.

Следующий пример иллюстрирует оба подхода.

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

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

Существуют адаптеры по умолчанию для типов даты и datetime в модуле datetime. Они будут отправлены как даты ISO/временные метки ISO в SQLite.

Преобразователи по умолчанию регистрируются под именем «date» для datetime.date и под именем «timestamp» для datetime.datetime.

Таким образом, в большинстве случаев можно использовать метки даты/времени из Python без дополнительной проверки. Формат адаптеров также совместим с экспериментальными функциями даты/времени SQLite.

Следующий пример демонстрирует это.

import sqlite3
import datetime

con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES)
cur = con.cursor()
cur.execute("create table test(d date, ts timestamp)")

today = datetime.date.today()
now = datetime.datetime.now()

cur.execute("insert into test(d, ts) values (?, ?)", (today, now))
cur.execute("select d, ts from test")
row = cur.fetchone()
print(today, "=>", row[0], type(row[0]))
print(now, "=>", row[1], type(row[1]))

cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"')
row = cur.fetchone()
print("current_date", row[0], type(row[0]))
print("current_timestamp", row[1], type(row[1]))

con.close()

Если временная метка, сохраненная в SQLite, имеет дробную часть длиной более 6 чисел, ее значение будет усечена до микросекундной точности преобразователем временных меток.

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

Базовая библиотека 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 инструкции в вашем код.

Изменено в версии 3.6: sqlite3 используемый неявно зафиксировать открытую транзакцию перед инструкции DDL. Это уже не так.

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

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

Используя нестандартный execute(), executemany() и методы executescript() объекта Connection, ваш код может быть написан более кратко, потому что вы не должны создавать (часто лишний) объекты Cursor явно. Вместо этого Cursor объекты создаются неявно, и эти методы быстрого вызова возвращает объекты курсора. Таким образом, можно выполнить SELECT инструкция и выполнить над ним итерацию непосредственно, используя только один вызов объекта Connection.

Доступ к столбцам по имени, а не по индексу¶

Одной из полезных особенностей модуля sqlite3 является встроенный класс sqlite3.Row, предназначенный для используемый в качестве фабрики ряда.

Строки, обернутые этим классом, доступны как по индексу (как кортежи), так и без учета регистра по имени:

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

Объекты подключения можно используемый как менеджеры контекст, которые автоматически фиксируют или откатывают транзакции. В случае исключения выполняется откат транзакции; в противном случае транзакция фиксируется:

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

Сноски

[1]

(1, 2) Модуль sqlite3 не построен с поддержкой загружаемых расширений по умолчанию, поскольку некоторые платформы (особенно Mac OS X) имеют библиотеки SQLite, скомпилированные без этой функции. Чтобы получить поддержку загружаемых расширений, необходимо передать –enable-loadable-sqlite-extensions для настройки.

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

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

Объекты Connection¶

Объекты Cursor¶

Объекты Row¶

Исключения¶

SQLite и типы Python¶

Введение¶

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

Позвольте вашему объекту адаптироваться¶

Регистрация адаптера с возможностью вызова¶

Преобразование значений SQLite в пользовательские типы Python¶

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

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

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

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

Доступ к столбцам по имени, а не по индексу¶

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

Содержание

Предыдущий раздел

Следующий раздел

Эта страница

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

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

Объекты Connection¶

Объекты Cursor¶

Объекты Row¶

Исключения¶

SQLite и типы Python¶

Введение¶

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

Позвольте вашему объекту адаптироваться¶

Регистрация адаптера с возможностью вызова¶

Преобразование значений SQLite в пользовательские типы Python¶

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

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

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

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

Доступ к столбцам по имени, а не по индексу¶

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

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

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