ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Бэкенды хранилища

Tip

Когда стоит читать этот документ: при переключении между sqlite / mysql / postgres или при использовании пользовательского бэкенда хранилища. Если это не требуется — пропустите, на использование остальных функций это не влияет.

ErisPulse включает три встроенных нативно-асинхронных бэкенда хранилища, переключаемых одной строкой конфигурации — API полностью идентичен, переключение не требует изменений кода:

Бэкенд Драйвер Установка Особенности
SQLite (по умолчанию) aiosqlite работает из коробки нулевая настройка, один файл, параллелизм WAL
MySQL / MariaDB aiomysql pip install ErisPulse[mysql] подходит при существующей инфраструктуре MySQL, совместное использование несколькими экземплярами
PostgreSQL asyncpg pip install ErisPulse[postgres] мощные транзакции, экосистема JSONB, высокая конкурентность

{!--< tips >!--}

  1. Асинхронный интерфейс является основным нативным (aget/aset/atransaction/aExecute), синхронный API — слой совместимости
  2. Персистентность конфигурации самого фреймворка, инбоксы сессий, чекпоинты диалогов и т.д. — всё проходит через один и тот же бэкенд хранилища; смена бэкенда означает миграцию всего и сразу
  3. Extra [mysql] уже включает cryptography — он необходим для аутентификации caching_sha2_password, используемой по умолчанию в MySQL 8; при его отсутствии инициализация пула соединений завершится ошибкой {!--< /tips >!--}

Выбор бэкенда

Настройка производится в config/config.toml:

[ErisPulse.storage]
backend = "sqlite"        # "sqlite" (по умолчанию) / "mysql" / "postgres"
use_global_db = false     # только для SQLite: использовать глобальную базу данных пакета data/config.db

Также поддерживается переопределение через переменные окружения (Docker / 12-factor):

ERISPULSE_STORAGE_BACKEND=postgres
ERISPULSE_STORAGE_POSTGRES_HOST=db.example.com
ERISPULSE_STORAGE_POSTGRES_PASSWORD=secret

Правила именования переменных окружения: путь конфигурации в верхнем регистре, точки заменяются подчёркиваниями (ErisPulse.storage.postgres.host → ERISPULSE_STORAGE_POSTGRES_HOST).

Параметры соединения

MySQL (ErisPulse.storage.mysql)

[ErisPulse.storage.mysql]
host = "127.0.0.1"
port = 3306
user = "erispulse"
password = ""
database = "erispulse"
charset = "utf8mb4"
pool_min = 1
pool_max = 10

PostgreSQL (ErisPulse.storage.postgres)

[ErisPulse.storage.postgres]
host = "127.0.0.1"
port = 5432
user = "erispulse"
password = ""
database = "erispulse"
pool_min = 1
pool_max = 10

Note

Чтобы изменения параметров соединения вступили в силу, требуется перезапуск фреймворка (при горячем обновлении конфигурации в лог выводится напоминание о перезапуске). Пул соединений создаётся лениво для каждого event loop; при мгновенном сбое создания (сетевые сбои / окно перезапуска БД) выполняется автоматический повтор с экспоненциальной задержкой.

Поведение при сбое соединения

Запуск и работа фреймворка не зависят от доступности базы данных — сбой соединения с MySQL / PostgreSQL не приводит к падению фреймворка или невозможности запуска:

  1. При мгновенном сбое создания пула выполняется автоматический повтор с экспоненциальной задержкой (по умолчанию 3 попытки)
  2. Исчерпание попыток → логируется WARNING (с причиной и длительностью периода охлаждения), фреймворк запускается / продолжает работу как обычно, временно недоступны только операции хранилища
  3. В период охлаждения (по умолчанию 30 секунд) последующие операции хранилища быстро завершаются ошибкой (без блокировки, не замедляя остальные функции)
  4. По окончании охлаждения автоматически выполняется пробное переподключение — после восстановления базы данных хранилище также восстанавливается, перезапуск не требуется

Пример записи в логе: финальный сбой создания пула соединений mysql (выполнено 3 повторные попытки), автоматическое переподключение через 30 секунд; в это время операции хранилища будут быстро завершаться ошибкой, остальные функции фреймворка не затрагиваются

Семантика сбоев (начиная с 2.12)

Сценарий Поведение
Сбой выполнения операции (таймаут блокировки записи / ошибка SQL / конфликт ограничений) Выбрасывается StorageOperationError (пути записи: aset / adelete / aclear / set_multi и те же пути синхронного моста) — больше никаких молчаливых False, сбои важных записей должны быть видимы
Недоступность на уровне соединения (быстрый сбой в период охлаждения) Возвращается False / None (семантика отказоустойчивости фреймворка по правилу 26; также предусмотрены события storage.unreachable / storage.recovered)
Таймаут открытия транзакции (>30s) Выбрасывается StorageOperationError (STORAGE_TXN_BEGIN_TIMEOUT_SECS)

Важные записи оборачивайте в try/except с компенсационной логикой; внутри блока транзакции размещайте только чистые операции с БД.

Нативный асинхронный API

# KV-операции
await sdk.storage.aset("app.name", "MyApp")
value = await sdk.storage.aget("app.name")
keys = await sdk.storage.aget_all_keys()

# Операции с таблицами
await sdk.storage.aCreateTable("users", {
    "id": "INTEGER PRIMARY KEY AUTOINCREMENT",
    "name": "TEXT NOT NULL",
})
rows = await sdk.storage.Table("users").Select("name").ToDict().aExecute()

# Асинхронные транзакции
async with sdk.storage.atransaction():
    await sdk.storage.aset("key1", "value1")
    await sdk.storage.Table("users").Insert({"name": "Alice"}).aExecute()

Синхронный API (get/set/transaction/Table(...).Execute()) по-прежнему доступен; внутри он выполняется через фоновый event loop AsyncBridge — вызов в асинхронном handler кратковременно блокирует этот event loop, при первом вызове выводится однократное предупреждение («рекомендуется перейти на асинхронные методы с префиксом a»), рекомендуется в первую очередь использовать асинхронные методы с префиксом a. О двух ограничениях необходимо знать:

  • Внутри потока моста запрещено повторно вызывать синхронные интерфейсы: синхронные интерфейсы выполняются в потоке моста; повторный вызов синхронного интерфейса в этот момент выбросит RuntimeError (защита от повторного входа, предотвращение самодедлока)
  • Вызов после закрытия целевого цикла моста завершится ошибкой: после uninit() не вызывайте интерфейсы хранилища

Полное сопоставление методов см. в Конструкторе SQL-запросов.

Различия в поведении диалектов

Все различия диалектов инкапсулированы внутри фреймворка — вызывающему коду о них знать не нужно:

Аспект SQLite MySQL PostgreSQL
Плейсхолдеры ? %s (автоперевод) $1..$n (автоперевод)
KV UPSERT INSERT OR REPLACE ON DUPLICATE KEY UPDATE ON CONFLICT DO UPDATE
Тип столбца значения KV TEXT LONGTEXT TEXT
Автоинкрементный первичный ключ нативная поддержка AUTO_INCREMENT (автоперевод) SERIAL (автоперевод)

Типы столбцов при создании таблиц задаются единообразно в стиле SQLite (например, "INTEGER PRIMARY KEY AUTOINCREMENT", "TEXT NOT NULL", "DOUBLE DEFAULT 0.0"), а диалект автоматически переводит их в эквивалентный синтаксис целевого бэкенда.

Диагностика ошибки SQLite "database is locked"

В SQLite-бэкенде фреймворка уже встроены: режим журналирования WAL (чтение и запись не блокируют друг друга) + busy_timeout 5000ms (автоматическое ожидание при конкуренции за блокировку записи) + autocommit-соединения + разделяемое соединение у каждого из нескольких event loop + транзакции BEGIN IMMEDIATE (начиная с 2.12 — блокировка записи берётся сразу в момент начала транзакции, что устраняет SQLITE_BUSY_SNAPSHOT при повышении deferred-транзакции по схеме «сначала чтение — потом запись»; такой busy не ретраится и не может быть смягчён через busy_timeout, и именно он является первопричиной внутри фреймворка периодических locked при смешении высокочастотных чтений и записей).

При чистом использовании фреймворка 2.12+ (хранилище / ORM / чередующиеся записи по смешанным двойным путям) locked больше не должно возникать; если проблема всё же встречается, проверяйте в следующем порядке:

Сценарий Признак Решение
Медленные операции внутри транзакции В блоке atransaction есть медленные операции (внешний HTTP, тяжёлые вычисления), блокировка удерживается дольше busy_timeout В блоке транзакции выполнять только операции с БД, медленные операции выносить наружу
Смешивание второй ORM Внутри одного процесса sqlmodel / SQLAlchemy / голый sqlite3 открывают собственные соединения и пишут в тот же файл БД Для одного файла БД использовать только одну ORM (встроенная изначально нативно-асинхронная), не смешивать в переходный период
Несколько процессов с одним файлом Несколько экземпляров / Dashboard / инструменты для БД открывают один и тот же файл sqlite Отдельный каталог config/ для каждого экземпляра; административные инструменты открывать в режиме только чтение; при сценариях с высокочастотной записью перейти на mysql / postgres (изменение одной настройки — миграция без правки кода)
Старая версия фреймворка Проблема повышения deferred-транзакций в версиях <2.12 Обновить фреймворк

busy_timeout в настоящее время является константой класса _SQLITE_BUSY_TIMEOUT_MS = 5000 (Core/storage/sqlite.py); при необходимости изменения — это правка на уровне исходного кода и не предоставляется как конфигурация времени выполнения.

Пользовательский SQL-бэкенд

Чистые SQL-бэкенды могут наследовать общий базовый класс; достаточно предоставить управление соединениями и воронку выполнения диалекта:

from ErisPulse.Core.Bases.sql_base import SQLDialect, SQLStorageBase

class MyDialect(SQLDialect):
    name = "mydb"
    # Переопределение: перевод плейсхолдеров / экранирование идентификаторов / UPSERT / маппинг типов ...

class MyStorage(SQLStorageBase):
    dialect = MyDialect()

    async def _create_loop_resource(self): ...   # пул соединений
    async def _destroy_loop_resource(self, r): ...
    async def _acquire_resource_conn(self, r): ...
    async def _release_resource_conn(self, r, c): ...
    async def _open_txn_conn(self): ...
    async def _close_txn_conn(self, c): ...
    async def _exec_query_on(self, kind, sql, params, conn): ...  # воронка выполнения

Не-SQL бэкенды (например, Redis) после наследования от BaseStorage и реализации асинхронного KV-интерфейса могут напрямую использовать KVQueryBuilder и получить возможности цепочечных запросов к таблицам (фильтрация в памяти, подходит для малых и средних объёмов данных).

Связанная документация