SQLite¶

Support for the SQLite database.

The following table summarizes current support levels for database release versions.

DBAPI Support¶

The following dialect/DBAPI options are available. Please refer to individual DBAPI sections for connect information.

• pysqlite

• aiosqlite

• pysqlcipher

Типы даты и времени¶

SQLite не имеет встроенных типов DATE, TIME или DATETIME, а pysqlite не предоставляет встроенной функциональности для перевода значений между Python datetime objects and a SQLite-supported format. SQLAlchemy’s own DateTime and related types provide date formatting and parsing functionality when SQLite is used. The implementation classes are DATETIME, DATE and TIME. Эти типы представляют даты и время как строки в формате ISO, которые также поддерживают упорядочивание. Эти функции не зависят от типичных внутренних функций «libc», поэтому исторические даты полностью поддерживаются.

Поведение автоинкрементов в SQLite¶

Справочная информация об автоинкременте в SQLite находится по адресу: https://sqlite.org/autoinc.html.

Ключевые понятия:

• SQLite имеет неявную функцию «автоматического инкремента», которая имеет место для любого некомпозитного столбца с первичным ключом, который специально создан с использованием «INTEGER PRIMARY KEY» для типа + первичный ключ.

• SQLite также имеет явное ключевое слово «AUTOINCREMENT», которое не эквивалентно неявной функции автоинкремента; это ключевое слово не рекомендуется для общего использования. SQLAlchemy не отображает это ключевое слово, если не используется специальная директива, специфичная для SQLite (см. ниже). Однако при этом все равно требуется, чтобы тип столбца был назван «INTEGER».

Table('sometable', metadata,
        Column('id', Integer, primary_key=True),
        sqlite_autoincrement=True)

table = Table(
    "my_table", metadata,
    Column("id", BigInteger().with_variant(Integer, "sqlite"), primary_key=True)
)

from sqlalchemy import BigInteger
from sqlalchemy.ext.compiler import compiles

class SLBigInteger(BigInteger):
    pass

@compiles(SLBigInteger, 'sqlite')
def bi_c(element, compiler, **kw):
    return "INTEGER"

@compiles(SLBigInteger)
def bi_c(element, compiler, **kw):
    return compiler.visit_BIGINT(element, **kw)


table = Table(
    "my_table", metadata,
    Column("id", SLBigInteger(), primary_key=True)
)

Поведение блокировки базы данных / параллелизм¶

SQLite не рассчитан на высокий уровень параллелизма при записи. Сама база данных, будучи файлом, полностью блокируется во время операций записи в рамках транзакций, что означает, что только одно «соединение» (в действительности - дескриптор файла) имеет эксклюзивный доступ к базе данных в этот период - все остальные «соединения» будут заблокированы в это время.

Спецификация Python DBAPI также требует модели соединения, которое всегда находится в транзакции; здесь нет метода connection.begin(), только connection.commit() и connection.rollback(), после чего немедленно начинается новая транзакция. Может показаться, что это означает, что драйвер SQLite теоретически допускает только один файловый хэндл на конкретный файл базы данных в любое время; однако есть несколько факторов как в самом SQLite, так и в драйвере pysqlite, которые значительно ослабляют это ограничение.

Однако, независимо от того, какие режимы блокировки используются, SQLite всегда будет блокировать файл базы данных, как только транзакция запущена и DML (например, INSERT, UPDATE, DELETE), по крайней мере, был выполнен, и это будет блокировать другие транзакции, по крайней мере, в тот момент, когда они также попытаются выполнить DML. По умолчанию длительность этого блока очень мала, прежде чем он завершится с ошибкой.

Это поведение становится более критичным при использовании в сочетании с SQLAlchemy ORM. Объект SQLAlchemy Session по умолчанию работает внутри транзакции, и благодаря своей модели autoflush может испускать DML, предшествующий любому оператору SELECT. Это может привести к тому, что база данных SQLite будет блокироваться быстрее, чем ожидается. Режимом блокировки SQLite и драйвера pysqlite можно в некоторой степени управлять, однако следует отметить, что достижение высокой степени параллелизма записи в SQLite - это проигрышная битва.

Для получения дополнительной информации об отсутствии в SQLite параллелизма при записи по замыслу, пожалуйста, смотрите Situations Where Another RDBMS May Work Better - High Concurrency внизу страницы.

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

Уровень изоляции транзакций / автокоммит¶

SQLite поддерживает «изоляцию транзакций» нестандартным образом, по двум направлениям. Первая - это инструкция PRAGMA read_uncommitted. Этот параметр может переключать SQLite между стандартным режимом изоляции SERIALIZABLE и режимом изоляции «грязного чтения», обычно называемым READ UNCOMMITTED.

SQLAlchemy связывается с этим оператором PRAGMA с помощью параметра create_engine.isolation_level create_engine(). Допустимыми значениями этого параметра при использовании с SQLite являются "SERIALIZABLE" и "READ UNCOMMITTED", что соответствует значению 0 и 1, соответственно. По умолчанию SQLite имеет значение SERIALIZABLE, однако на его поведение влияет поведение по умолчанию драйвера pysqlite.

При использовании драйвера pysqlite также доступен уровень изоляции "AUTOCOMMIT", который изменит соединение pysqlite с помощью атрибута .isolation_level на соединении DBAPI и установит его в None на время настройки.

Другая ось, на которую влияет транзакционная блокировка SQLite, - это характер используемого оператора BEGIN. Есть три разновидности: «отложенная», «немедленная» и «эксклюзивная», как описано в BEGIN TRANSACTION. Прямой оператор BEGIN использует «отложенный» режим, при котором файл базы данных не блокируется до первой операции чтения или записи, а доступ на чтение остается открытым для других транзакций до первой операции записи. Но опять же, важно отметить, что драйвер pysqlite вмешивается в это поведение, не выдавая даже BEGIN до первой операции записи.

ВСТАВКА/ОБНОВЛЕНИЕ/УДАЛЕНИЕ… ВОЗВРАЩЕНИЕ¶

Диалект SQLite поддерживает синтаксис INSERT|UPDATE|DELETE..RETURNING в SQLite 3.35. В некоторых случаях INSERT..RETURNING может использоваться автоматически для получения вновь созданных идентификаторов вместо традиционного подхода использования cursor.lastrowid, однако cursor.lastrowid в настоящее время все еще предпочтительнее для простых случаев с одним выражением из-за его лучшей производительности.

Чтобы указать явное предложение RETURNING, используйте метод _UpdateBase.returning() на основе каждого предложения:

# INSERT..RETURNING
result = connection.execute(
    table.insert().
    values(name='foo').
    returning(table.c.col1, table.c.col2)
)
print(result.all())

# UPDATE..RETURNING
result = connection.execute(
    table.update().
    where(table.c.name=='foo').
    values(name='bar').
    returning(table.c.col1, table.c.col2)
)
print(result.all())

# DELETE..RETURNING
result = connection.execute(
    table.delete().
    where(table.c.name=='foo').
    returning(table.c.col1, table.c.col2)
)
print(result.all())

Поддержка SAVEPOINT¶

SQLite поддерживает SAVEPOINTs, которые работают только после начала транзакции. Поддержка SAVEPOINT в SQLAlchemy доступна с помощью метода Connection.begin_nested() на уровне Core и Session.begin_nested() на уровне ORM. Однако SAVEPOINT вообще не будут работать с pysqlite, если не предпринять обходных путей.

Транзакционный DDL¶

База данных SQLite также поддерживает транзакции DDL. В этом случае драйвер pysqlite не только не запускает транзакции, но и завершает все существующие транзакции при обнаружении DDL, поэтому снова требуются обходные пути.

Поддержка иностранных ключей¶

SQLite поддерживает синтаксис FOREIGN KEY при создании операторов CREATE для таблиц, однако по умолчанию эти ограничения не влияют на работу таблицы.

Проверка ограничений в SQLite имеет три предпосылки:

• Должна использоваться версия SQLite не менее 3.6.19

• Библиотека SQLite должна быть скомпилирована без включенных символов SQLITE_OMIT_FOREIGN_KEY или SQLITE_OMIT_TRIGGER.

• Оператор PRAGMA foreign_keys = ON должен выдаваться на всех соединениях перед использованием - включая начальный вызов MetaData.create_all().

SQLAlchemy позволяет автоматически создавать оператор PRAGMA для новых соединений с помощью событий:

from sqlalchemy.engine import Engine
from sqlalchemy import event

@event.listens_for(Engine, "connect")
def set_sqlite_pragma(dbapi_connection, connection_record):
    cursor = dbapi_connection.cursor()
    cursor.execute("PRAGMA foreign_keys=ON")
    cursor.close()

ПО КОНФЛИКТУ поддержка ограничений¶

SQLite поддерживает нестандартное предложение DDL, известное как ON CONFLICT, которое может применяться к ограничениям первичного ключа, уникальности, проверки и не null. В DDL он отображается либо в предложении «CONSTRAINT», либо в самом определении столбца, в зависимости от расположения целевого ограничения. Для отображения этого условия в DDL, параметр расширения sqlite_on_conflict может быть указан с алгоритмом разрешения конфликта строк в объектах PrimaryKeyConstraint, UniqueConstraint, CheckConstraint. Внутри объекта Column имеются отдельные параметры sqlite_on_conflict_not_null, sqlite_on_conflict_primary_key, sqlite_on_conflict_unique, которые соответствуют трем типам соответствующих ограничений, которые могут быть указаны из объекта Column.

Параметры sqlite_on_conflict принимают строковый аргумент, который является просто именем разрешения, которое нужно выбрать, которое в SQLite может быть одним из ROLLBACK, ABORT, FAIL, IGNORE и REPLACE. Например, чтобы добавить ограничение UNIQUE, определяющее алгоритм IGNORE:

some_table = Table(
    'some_table', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', Integer),
    UniqueConstraint('id', 'data', sqlite_on_conflict='IGNORE')
)

Вышеприведенный DDL CREATE TABLE выглядит следующим образом:

CREATE TABLE some_table (
    id INTEGER NOT NULL,
    data INTEGER,
    PRIMARY KEY (id),
    UNIQUE (id, data) ON CONFLICT IGNORE
)

При использовании флага Column.unique для добавления ограничения UNIQUE к одному столбцу, к параметру sqlite_on_conflict_unique можно добавить и Column, который будет добавлен к ограничению UNIQUE в DDL:

some_table = Table(
    'some_table', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', Integer, unique=True,
           sqlite_on_conflict_unique='IGNORE')
)

оказание услуг:

CREATE TABLE some_table (
    id INTEGER NOT NULL,
    data INTEGER,
    PRIMARY KEY (id),
    UNIQUE (data) ON CONFLICT IGNORE
)

Чтобы применить алгоритм FAIL для ограничения NOT NULL, используется sqlite_on_conflict_not_null:

some_table = Table(
    'some_table', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', Integer, nullable=False,
           sqlite_on_conflict_not_null='FAIL')
)

это отображает колонку в строке ON CONFLICT phrase:

CREATE TABLE some_table (
    id INTEGER NOT NULL,
    data INTEGER NOT NULL ON CONFLICT FAIL,
    PRIMARY KEY (id)
)

Аналогично, для встроенного первичного ключа используйте sqlite_on_conflict_primary_key:

some_table = Table(
    'some_table', metadata,
    Column('id', Integer, primary_key=True,
           sqlite_on_conflict_primary_key='FAIL')
)

SQLAlchemy отображает ограничение PRIMARY KEY отдельно, поэтому алгоритм разрешения конфликтов применяется к самому ограничению:

CREATE TABLE some_table (
    id INTEGER NOT NULL,
    PRIMARY KEY (id) ON CONFLICT FAIL
)

INSERT…ON CONFLICT (Upsert)¶

Начиная с версии 3.24.0, SQLite поддерживает «апсерт» (обновление или вставку) строк в таблицу с помощью пункта ON CONFLICT оператора INSERT. Строка-кандидат будет вставлена только в том случае, если она не нарушает никаких ограничений уникальности или первичного ключа. В случае нарушения уникального ограничения может произойти вторичное действие, которое может быть либо «DO UPDATE», что указывает на то, что данные в целевой строке должны быть обновлены, либо «DO NOTHING», что означает молчаливый пропуск этой строки.

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

SQLAlchemy обеспечивает поддержку ON CONFLICT через специфическую для SQLite функцию insert(), которая предоставляет генеративные методы Insert.on_conflict_do_update() и Insert.on_conflict_do_nothing():

>>> from sqlalchemy.dialects.sqlite import insert

>>> insert_stmt = insert(my_table).values(
...     id='some_existing_id',
...     data='inserted value')

>>> do_update_stmt = insert_stmt.on_conflict_do_update(
...     index_elements=['id'],
...     set_=dict(data='updated value')
... )

>>> print(do_update_stmt)
{printsql}INSERT INTO my_table (id, data) VALUES (?, ?)
ON CONFLICT (id) DO UPDATE SET data = ?{stop}

>>> do_nothing_stmt = insert_stmt.on_conflict_do_nothing(
...     index_elements=['id']
... )

>>> print(do_nothing_stmt)
{printsql}INSERT INTO my_table (id, data) VALUES (?, ?)
ON CONFLICT (id) DO NOTHING

>>> stmt = insert(my_table).values(id='some_id', data='inserted value')

>>> do_update_stmt = stmt.on_conflict_do_update(
...     index_elements=['id'],
...     set_=dict(data='updated value')
... )

>>> print(do_update_stmt)
{printsql}INSERT INTO my_table (id, data) VALUES (?, ?)
ON CONFLICT (id) DO UPDATE SET data = ?

>>> stmt = insert(my_table).values(
...     id='some_id',
...     data='inserted value',
...     author='jlh'
... )

>>> do_update_stmt = stmt.on_conflict_do_update(
...     index_elements=['id'],
...     set_=dict(data='updated value', author=stmt.excluded.author)
... )

>>> print(do_update_stmt)
{printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?)
ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author

>>> stmt = insert(my_table).values(
...     id='some_id',
...     data='inserted value',
...     author='jlh'
... )

>>> on_update_stmt = stmt.on_conflict_do_update(
...     index_elements=['id'],
...     set_=dict(data='updated value', author=stmt.excluded.author),
...     where=(my_table.c.status == 2)
... )
>>> print(on_update_stmt)
{printsql}INSERT INTO my_table (id, data, author) VALUES (?, ?, ?)
ON CONFLICT (id) DO UPDATE SET data = ?, author = excluded.author
WHERE my_table.status = ?

>>> stmt = insert(my_table).values(id='some_id', data='inserted value')
>>> stmt = stmt.on_conflict_do_nothing(index_elements=['id'])
>>> print(stmt)
{printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT (id) DO NOTHING

>>> stmt = insert(my_table).values(id='some_id', data='inserted value')
>>> stmt = stmt.on_conflict_do_nothing()
>>> print(stmt)
{printsql}INSERT INTO my_table (id, data) VALUES (?, ?) ON CONFLICT DO NOTHING

Тип Отражение¶

Типы SQLite отличаются от типов большинства других бэкендов баз данных тем, что строковое имя типа обычно не соответствует «типу» один к одному. Вместо этого SQLite связывает поведение типа в каждом столбце с одним из пяти так называемых «сродств типов» на основе шаблона соответствия строки типу.

Процесс отражения SQLAlchemy при проверке типов использует простую таблицу поиска, чтобы связать возвращаемые ключевые слова с предоставляемыми типами SQLAlchemy. Эта таблица поиска присутствует в диалекте SQLite, как и во всех других диалектах. Однако диалект SQLite имеет другую «запасную» процедуру для случаев, когда имя конкретного типа не находится в карте поиска; вместо этого он реализует схему «сродства типов» SQLite, описанную в разделе 2.1 https://www.sqlite.org/datatype3.html.

Предоставленная карта типов будет создавать прямые ассоциации на основе точного совпадения строкового имени для следующих типов:

BIGINT, BLOB, BOOLEAN, BOOLEAN, CHAR, DATE, DATETIME, FLOAT, DECIMAL, FLOAT, INTEGER, INTEGER, NUMERIC, REAL, SMALLINT, TEXT, TIME, TIMESTAMP, VARCHAR, NVARCHAR, NCHAR

Если имя типа не соответствует ни одному из вышеперечисленных типов, вместо него используется поиск «сродства типов»:

• INTEGER возвращается, если имя типа включает строку INT.

• TEXT возвращается, если имя типа включает строку CHAR, CLOB или TEXT.

• NullType возвращается, если имя типа включает строку BLOB.

• REAL возвращается, если имя типа включает строку REAL, FLOA или DOUB.

• В противном случае используется тип NUMERIC.

Частичные индексы¶

Частичный индекс, например, использующий предложение WHERE, можно задать в системе DDL с помощью аргумента sqlite_where:

tbl = Table('testtbl', m, Column('data', Integer))
idx = Index('test_idx1', tbl.c.data,
            sqlite_where=and_(tbl.c.data > 5, tbl.c.data < 10))

Индекс будет отображаться во время создания как:

CREATE INDEX test_idx1 ON testtbl (data)
WHERE data > 5 AND data < 10

Имена столбцов с точками¶

Использование имен таблиц или столбцов, в которых явно присутствуют точки, не рекомендуется. Хотя в целом это плохая идея для реляционных баз данных, поскольку точка является синтаксически значимым символом, драйвер SQLite до версии 3.10.0 SQLite имеет ошибку, которая требует, чтобы SQLAlchemy отфильтровывала эти точки в наборах результатов.

Ошибка, совершенно не относящаяся к SQLAlchemy, может быть проиллюстрирована следующим образом:

import sqlite3

assert sqlite3.sqlite_version_info < (3, 10, 0), "bug is fixed in this version"

conn = sqlite3.connect(":memory:")
cursor = conn.cursor()

cursor.execute("create table x (a integer, b integer)")
cursor.execute("insert into x (a, b) values (1, 1)")
cursor.execute("insert into x (a, b) values (2, 2)")

cursor.execute("select x.a, x.b from x")
assert [c[0] for c in cursor.description] == ['a', 'b']

cursor.execute('''
    select x.a, x.b from x where a=1
    union
    select x.a, x.b from x where a=2
''')
assert [c[0] for c in cursor.description] == ['a', 'b'], \
    [c[0] for c in cursor.description]

Второе утверждение не работает:

Traceback (most recent call last):
  File "test.py", line 19, in <module>
    [c[0] for c in cursor.description]
AssertionError: ['x.a', 'x.b']

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

SQLAlchemy полагается на то, что имена столбцов предсказуемы в том, как они соответствуют исходному утверждению, поэтому у диалекта SQLAlchemy нет другого выбора, кроме как отфильтровать их:

from sqlalchemy import create_engine

eng = create_engine("sqlite://")
conn = eng.connect()

conn.exec_driver_sql("create table x (a integer, b integer)")
conn.exec_driver_sql("insert into x (a, b) values (1, 1)")
conn.exec_driver_sql("insert into x (a, b) values (2, 2)")

result = conn.exec_driver_sql("select x.a, x.b from x")
assert result.keys() == ["a", "b"]

result = conn.exec_driver_sql('''
    select x.a, x.b from x where a=1
    union
    select x.a, x.b from x where a=2
''')
assert result.keys() == ["a", "b"]

Обратите внимание, что, несмотря на то, что SQLAlchemy отфильтровывает точки, обои имена по-прежнему адресуемы:

>>> row = result.first()
>>> row["a"]
1
>>> row["x.a"]
1
>>> row["b"]
1
>>> row["x.b"]
1

Поэтому обходной путь, применяемый SQLAlchemy, влияет только на CursorResult.keys() и Row.keys() в публичном API. В очень специфическом случае, когда приложение вынуждено использовать имена столбцов, содержащие точки, и функциональность CursorResult.keys() и Row.keys() должна возвращать эти точечные имена без изменений, может быть предоставлена опция выполнения sqlite_raw_colnames, либо на основе каждого из Connection:

result = conn.execution_options(sqlite_raw_colnames=True).exec_driver_sql('''
    select x.a, x.b from x where a=1
    union
    select x.a, x.b from x where a=2
''')
assert result.keys() == ["x.a", "x.b"]

или на пер-Engine основе:

engine = create_engine("sqlite://", execution_options={"sqlite_raw_colnames": True})

При использовании опции выполнения per-Engine обратите внимание, что Запросы Core и ORM, использующие UNION, могут работать некорректно.

Параметры таблиц, специфичные для SQLite¶

Один из вариантов CREATE TABLE поддерживается непосредственно диалектом SQLite в сочетании с конструкцией Table:

• WITHOUT ROWID:

  Table("some_table", metadata, ..., sqlite_with_rowid=False)

Отражение таблиц внутренней схемы¶

Методы отражения, возвращающие списки таблиц, опускают имена так называемых «внутренних объектов схемы SQLite», которыми SQLite называет любое имя объекта с префиксом sqlite_. Примером такого объекта является таблица sqlite_sequence, которая создается при использовании параметра столбца AUTOINCREMENT. Чтобы вернуть эти объекты, параметр sqlite_include_internal=True может быть передан таким методам, как MetaData.reflect() или Inspector.get_table_names().

Типы данных SQLite¶

Как и во всех диалектах SQLAlchemy, все типы UPPERCASE, которые, как известно, действительны в SQLite, импортируются из диалекта верхнего уровня, независимо от того, происходят ли они из sqlalchemy.types или из локального диалекта:

from sqlalchemy.dialects.sqlite import (
    BLOB,
    BOOLEAN,
    CHAR,
    DATE,
    DATETIME,
    DECIMAL,
    FLOAT,
    INTEGER,
    NUMERIC,
    JSON,
    SMALLINT,
    TEXT,
    TIME,
    TIMESTAMP,
    VARCHAR,
)

class sqlalchemy.dialects.sqlite.DATETIME¶

Представьте объект Python datetime в SQLite с помощью строки.

По умолчанию формат хранения строк следующий:

"%(year)04d-%(month)02d-%(day)02d %(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d"

например:

2021-03-15 12:05:57.105542

Формат входящего хранилища по умолчанию разбирается с помощью функции Python datetime.fromisoformat().

Изменено в версии 2.0: datetime.fromisoformat() используется для разбора строки datetime по умолчанию.

Формат хранения может быть в некоторой степени настроен с помощью параметров storage_format и regexp, например:

import re
from sqlalchemy.dialects.sqlite import DATETIME

dt = DATETIME(storage_format="%(year)04d/%(month)02d/%(day)02d "
                             "%(hour)02d:%(minute)02d:%(second)02d",
              regexp=r"(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)"
)

Параметры:

• storage_format – строка формата, которая будет применена к дикте с ключами year, month, day, hour, minute, second и microsecond.

• regexp – регулярное выражение, которое будет применяться к входящим строкам результатов, заменяя использование datetime.fromisoformat() для разбора входящих строк. Если regexp содержит именованные группы, то полученный дикт совпадений применяется к конструктору Python datetime() в качестве аргументов ключевых слов. В противном случае, если используются позиционные группы, конструктор datetime() вызывается с позиционными аргументами через *map(int, match_obj.groups(0)).

Классная подпись

класс sqlalchemy.dialects.sqlite.DATETIME (sqlalchemy.dialects.sqlite.base._DateTimeMixin, sqlalchemy.types.DateTime)

class sqlalchemy.dialects.sqlite.DATE¶

Представьте объект даты Python в SQLite с помощью строки.

По умолчанию формат хранения строк следующий:

"%(year)04d-%(month)02d-%(day)02d"

например:

2011-03-15

Формат входящего хранилища по умолчанию разбирается с помощью функции Python date.fromisoformat().

Изменено в версии 2.0: date.fromisoformat() используется для разбора строки даты по умолчанию.

Формат хранения может быть в некоторой степени настроен с помощью параметров storage_format и regexp, например:

import re
from sqlalchemy.dialects.sqlite import DATE

d = DATE(
        storage_format="%(month)02d/%(day)02d/%(year)04d",
        regexp=re.compile("(?P<month>\d+)/(?P<day>\d+)/(?P<year>\d+)")
    )

Параметры:

• storage_format – строка формата, которая будет применена к дикте с ключами year, month и day.

• regexp – регулярное выражение, которое будет применяться к входящим строкам результатов, заменяя использование date.fromisoformat() для разбора входящих строк. Если regexp содержит именованные группы, то полученный дикт совпадений применяется к конструктору Python date() в качестве аргументов ключевых слов. В противном случае, если используются позиционные группы, конструктор date() вызывается с позиционными аргументами через *map(int, match_obj.groups(0)).

Классная подпись

класс sqlalchemy.dialects.sqlite.DATE (sqlalchemy.dialects.sqlite.base._DateTimeMixin, sqlalchemy.types.Date)

class sqlalchemy.dialects.sqlite.JSON¶

Тип SQLite JSON.

SQLite поддерживает JSON начиная с версии 3.9 через расширение JSON1. Обратите внимание, что JSON1 - это loadable extension и как таковой может быть недоступен или может потребовать загрузки во время выполнения.

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

См.также

JSON - основная документация по общему кроссплатформенному типу данных JSON.

Тип JSON поддерживает сохранение значений JSON, а также основные индексные операции, предоставляемые типом данных JSON, адаптируя операции для отображения функции JSON_EXTRACT, обернутой в функцию JSON_QUOTE на уровне базы данных. Извлеченные значения заключаются в кавычки, чтобы гарантировать, что результаты всегда являются строковыми значениями JSON.

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

Members

__init__()

Классная подпись

класс sqlalchemy.dialects.sqlite.JSON (sqlalchemy.types.JSON)

method sqlalchemy.dialects.sqlite.JSON.__init__(none_as_null: bool = False)¶

наследуется от sqlalchemy.types.JSON.__init__ метода JSON

Сконструируйте тип JSON.

Параметры:

none_as_null=False – если True, сохранять значение None как значение SQL NULL, а не JSON-кодировку null. Обратите внимание, что когда этот флаг равен False, конструкция null() все еще может быть использована для сохранения значения NULL, которое может быть передано непосредственно как значение параметра, которое специально интерпретируется типом JSON как SQL NULL:: from sqlalchemy import null conn.execute(table.insert(), {«data»: null()}) … note:: JSON.none_as_null не применяется к значениям, переданным в Column.default и Column.server_default; значение None, переданное для этих параметров, означает «по умолчанию отсутствует». Кроме того, при использовании в выражениях сравнения SQL, значение Python None продолжает ссылаться на SQL null, а не на JSON NULL. Флаг JSON.none_as_null явно указывает на постоянство значения в операторе INSERT или UPDATE. Значение JSON.NULL следует использовать для SQL-выражений, которые хотят сравнить с JSON null. … см. также:: JSON.NULL

class sqlalchemy.dialects.sqlite.TIME¶

Представьте объект времени Python в SQLite с помощью строки.

По умолчанию формат хранения строк следующий:

"%(hour)02d:%(minute)02d:%(second)02d.%(microsecond)06d"

например:

12:05:57.10558

Формат входящего хранилища по умолчанию разбирается с помощью функции Python time.fromisoformat().

Изменено в версии 2.0: time.fromisoformat() используется для разбора строки времени по умолчанию.

Формат хранения может быть в некоторой степени настроен с помощью параметров storage_format и regexp, например:

import re
from sqlalchemy.dialects.sqlite import TIME

t = TIME(storage_format="%(hour)02d-%(minute)02d-"
                        "%(second)02d-%(microsecond)06d",
         regexp=re.compile("(\d+)-(\d+)-(\d+)-(?:-(\d+))?")
)

Параметры:

• storage_format – строка формата, которая будет применена к дикте с ключами hour, minute, second и microsecond.

• regexp – регулярное выражение, которое будет применяться к входящим строкам результатов, заменяя использование datetime.fromisoformat() для разбора входящих строк. Если regexp содержит именованные группы, то полученный дикт совпадений применяется к конструктору Python time() в качестве аргументов ключевых слов. В противном случае, если используются позиционные группы, конструктор time() вызывается с позиционными аргументами через *map(int, match_obj.groups(0)).

Классная подпись

класс sqlalchemy.dialects.sqlite.TIME (sqlalchemy.dialects.sqlite.base._DateTimeMixin, sqlalchemy.types.Time)

Конструкции SQLite DML¶

function sqlalchemy.dialects.sqlite.insert(table)¶

Создайте конструкцию sqlite-специфического варианта Insert.

Функция sqlalchemy.dialects.sqlite.insert() создает sqlalchemy.dialects.sqlite.Insert. Этот класс основан на диалектно-агностической конструкции Insert, которая может быть построена с помощью функции insert() в SQLAlchemy Core.

Конструкция Insert включает дополнительные методы Insert.on_conflict_do_update(), Insert.on_conflict_do_nothing().

class sqlalchemy.dialects.sqlite.Insert¶

Специфическая для SQLite реализация INSERT.

Добавляет методы для специфических для SQLite синтаксисов, таких как ON CONFLICT.

Объект Insert создается с помощью функции sqlalchemy.dialects.sqlite.insert().

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

См.также

INSERT…ON CONFLICT (Upsert)

Members

excluded, inherit_cache, on_conflict_do_nothing(), on_conflict_do_update()

Классная подпись

класс sqlalchemy.dialects.sqlite.Insert (sqlalchemy.sql.expression.Insert)

attribute sqlalchemy.dialects.sqlite.Insert.excluded¶

Предоставьте пространство имен excluded для оператора ON CONFLICT

Пункт ON CONFLICT в SQLite позволяет ссылаться на строку, которая будет вставлена, известную как excluded. Этот атрибут обеспечивает возможность ссылки на все столбцы в этой строке.

Совет

Атрибут Insert.excluded является экземпляром ColumnCollection, который предоставляет интерфейс, аналогичный интерфейсу коллекции Table.c, описанной в Доступ к таблицам и столбцам. В этой коллекции обычные имена доступны как атрибуты (например, stmt.excluded.some_column), но к специальным именам и именам методов словаря следует обращаться с помощью индексного доступа, например, stmt.excluded["column name"] или stmt.excluded["values"]. Дополнительные примеры см. в строке документации для ColumnCollection.

attribute sqlalchemy.dialects.sqlite.Insert.inherit_cache: Optional[bool] = False¶

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

По умолчанию атрибут имеет значение None, что указывает на то, что конструкция еще не приняла во внимание целесообразность ее участия в кэшировании; функционально это эквивалентно установке значения False, за исключением того, что при этом выдается предупреждение.

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

См.также

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

method sqlalchemy.dialects.sqlite.Insert.on_conflict_do_nothing(index_elements=None, index_where=None) → Self¶

Указывает действие DO NOTHING для пункта ON CONFLICT.

Параметры:

• index_elements – Последовательность, состоящая из строковых имен столбцов, объектов Column или других объектов выражения столбцов, которые будут использоваться для вывода целевого индекса или уникального ограничения.

• index_where – Дополнительный критерий WHERE, который может быть использован для вывода условного целевого индекса.

method sqlalchemy.dialects.sqlite.Insert.on_conflict_do_update(index_elements=None, index_where=None, set_=None, where=None) → Self¶

Указывает действие DO UPDATE SET для условия ON CONFLICT.

Параметры:

• index_elements – Последовательность, состоящая из строковых имен столбцов, объектов Column или других объектов выражения столбцов, которые будут использоваться для вывода целевого индекса или уникального ограничения.

• index_where – Дополнительный критерий WHERE, который может быть использован для вывода условного целевого индекса.

• set_ – Словарь или другой объект отображения, где ключами являются либо имена столбцов в целевой таблице, либо Column объекты или другие ORM-сопоставленные столбцы, совпадающие со столбцами целевой таблицы, а в качестве значений - выражения или литералы, определяющие действия SET, которые необходимо предпринять. … versionadded:: 1.4 Параметр Insert.on_conflict_do_update.set_ поддерживает Column объекты из целевой Table в качестве ключей. … предупреждение:: Этот словарь не учитывает значения UPDATE по умолчанию, определенные Python, или функции генерации, например, указанные с помощью Column.onupdate. Эти значения не будут использоваться для UPDATE в стиле ON CONFLICT, если они не указаны вручную в словаре Insert.on_conflict_do_update.set_.

• where – Необязательный аргумент. Если присутствует, может быть литеральной строкой SQL или допустимым выражением для предложения WHERE, которое ограничивает строки, затрагиваемые DO UPDATE SET. Строки, не удовлетворяющие условию WHERE, не будут обновлены (эффективно DO NOTHING для этих строк).

Pysqlite¶

Поддержка базы данных SQLite через драйвер pysqlite. Обратите внимание, что pysqlite - это тот же драйвер, что и модуль sqlite3, включенный в дистрибутив Python.

sqlite+pysqlite:///file_path

driver://user:pass@host/database

# relative path
e = create_engine('sqlite:///path/to/database.db')

# absolute path
e = create_engine('sqlite:////path/to/database.db')

# absolute path on Windows
e = create_engine('sqlite:///C:\\path\\to\\database.db')

# in-memory database
e = create_engine('sqlite://')

e = create_engine("sqlite:///file:path/to/database?mode=ro&uri=true")

e = create_engine(
    "sqlite:///file:path/to/database?"
    "check_same_thread=true&timeout=10&mode=ro&nolock=1&uri=true"
)

sqlite3.connect(
    "file:path/to/database?mode=ro&nolock=1",
    check_same_thread=True, timeout=10, uri=True
)

def regexp(a, b):
    return re.search(a, b) is not None

sqlite_connection.create_function(
    "regexp", 2, regexp,
)

engine = create_engine('sqlite://',
    connect_args={'detect_types':
        sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES},
    native_datetime=True
)

from sqlalchemy import NullPool
engine = create_engine("sqlite:///myfile.db", poolclass=NullPool)

from sqlalchemy.pool import StaticPool
engine = create_engine('sqlite://',
                    connect_args={'check_same_thread':False},
                    poolclass=StaticPool)

# maintain the same connection per thread
from sqlalchemy.pool import SingletonThreadPool
engine = create_engine('sqlite:///mydb.db',
                    poolclass=SingletonThreadPool)


# maintain the same connection across all threads
from sqlalchemy.pool import StaticPool
engine = create_engine('sqlite:///mydb.db',
                    poolclass=StaticPool)

from sqlalchemy import String
from sqlalchemy import TypeDecorator

class MixedBinary(TypeDecorator):
    impl = String
    cache_ok = True

    def process_result_value(self, value, dialect):
        if isinstance(value, str):
            value = bytes(value, 'utf-8')
        elif value is not None:
            value = bytes(value)

        return value

from sqlalchemy import create_engine, event

engine = create_engine("sqlite:///myfile.db")

@event.listens_for(engine, "connect")
def do_connect(dbapi_connection, connection_record):
    # disable pysqlite's emitting of the BEGIN statement entirely.
    # also stops it from emitting COMMIT before any DDL.
    dbapi_connection.isolation_level = None

@event.listens_for(engine, "begin")
def do_begin(conn):
    # emit our own BEGIN
    conn.exec_driver_sql("BEGIN")

@event.listens_for(engine, "begin")
def do_begin(conn):
    conn.exec_driver_sql("BEGIN EXCLUSIVE")

from sqlalchemy import create_engine
from sqlalchemy import event
from sqlalchemy import text


def udf():
    return "udf-ok"


engine = create_engine("sqlite:///./db_file")


@event.listens_for(engine, "connect")
def connect(conn, rec):
    conn.create_function("udf", 0, udf)


for i in range(5):
    with engine.connect() as conn:
        print(conn.scalar(text("SELECT UDF()")))

Айосклит¶

Support for the SQLite database via the aiosqlite driver.

sqlite+aiosqlite:///file_path

Диалект aiosqlite обеспечивает поддержку интерфейса SQLAlchemy asyncio, работающего поверх pysqlite.

aiosqlite - это обертка вокруг pysqlite, которая использует фоновый поток для каждого соединения. На самом деле она не использует неблокирующий ввод-вывод, поскольку базы данных SQLite не основаны на сокетах. Однако она предоставляет рабочий интерфейс asyncio, который полезен для тестирования и создания прототипов.

Используя специальный посреднический слой asyncio, диалект aiosqlite можно использовать в качестве бэкенда для пакета расширения SQLAlchemy asyncio.

Обычно этот диалект следует использовать только с функцией создания двигателя create_async_engine():

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("sqlite+aiosqlite:///filename")

URL передает все аргументы драйвера pysqlite, поэтому все аргументы соединения такие же, как и для драйвера Pysqlite.

Pysqlcipher¶

Поддержка базы данных SQLite через драйвер pysqlcipher.Диалект для поддержки DBAPI, использующих бэкенд SQLCipher.

sqlite+pysqlcipher://:passphrase@/file_path[?kdf_iter=<iter>]

import sqlcipher_compatible_driver

from sqlalchemy import create_engine

e = create_engine(
    "sqlite+pysqlcipher://:password@/dbname.db",
    module=sqlcipher_compatible_driver
)

e = create_engine('sqlite+pysqlcipher://:testing@/foo.db')

e = create_engine('sqlite+pysqlcipher://:testing@//path/to/foo.db')

e = create_engine('sqlite+pysqlcipher://:testing@/foo.db?cipher=aes-256-cfb&kdf_iter=64000')