Бэкенды хранилища
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 >!--}
- Асинхронный интерфейс является основным нативным (
aget/aset/atransaction/aExecute), синхронный API — слой совместимости - Персистентность конфигурации самого фреймворка, инбоксы сессий, чекпоинты диалогов и т.д. — всё проходит через один и тот же бэкенд хранилища; смена бэкенда означает миграцию всего и сразу
- 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 не приводит к падению фреймворка или невозможности запуска:
- При мгновенном сбое создания пула выполняется автоматический повтор с экспоненциальной задержкой (по умолчанию 3 попытки)
- Исчерпание попыток → логируется WARNING (с причиной и длительностью периода охлаждения), фреймворк запускается / продолжает работу как обычно, временно недоступны только операции хранилища
- В период охлаждения (по умолчанию 30 секунд) последующие операции хранилища быстро завершаются ошибкой (без блокировки, не замедляя остальные функции)
- По окончании охлаждения автоматически выполняется пробное переподключение — после восстановления базы данных хранилище также восстанавливается, перезапуск не требуется
Пример записи в логе: финальный сбой создания пула соединений 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 и получить возможности цепочечных запросов к таблицам (фильтрация в памяти, подходит для малых и средних объёмов данных).
Связанная документация
- Конструктор SQL-запросов - синтаксис цепочечных запросов и сопоставление с асинхронным API
- API основных модулей - полный API модуля Storage
- API базовых классов хранилища - абстрактные интерфейсы SQLStorageBase / SQLDialect