Базы данных

db работает с внешней базой через выбранный драйвер. Универсальность — один блок и набор адаптеров с явными схемами, а не SQL для любой базы.

Параметры

Параметр	Назначение	По умолчанию
driver	postgresql, sqlite, mysql, mongodb, redis	Обязательно
connection	Строка подключения через объявленный секрет	Обязательно
operation	Операция, поддержанная выбранным драйвером	Обязательно
timeout_seconds	Лимит операции	30
Остальные поля	Схема зависит от пары driver + operation	По операции

База движка автоматически не выбирается. Сам драйвер не выбирается по содержимому запроса.

Пример

YAMLПараметризованный запрос PostgreSQL

- id: products
  block: db
  params:
    driver: postgresql
    connection: "{secret.CATALOG_DB}"
    operation: query
    statement: "SELECT id, name FROM products WHERE available = :available LIMIT :limit"
    parameters:
      available: true
      limit: 20

Имена таблиц здесь — данные приложения; движок не знает их значения.

Результат

Форма задаётся операцией: SQL — rows, affected, table; поиск документов — documents, count; чтение ключа — found, value. Например, {products.rows} — строки SQL-ответа. Неприменимые к операции поля не добавляются фиктивно.

Поведение

Неподдержанная пара драйвера и операции отклоняется до действия. Значения SQL передаются параметрами, имена таблиц/колонок проверяются и экранируются. affected=null, если драйвер не сообщает количество строк; у произвольного query — table=null.

Транзакция ограничивается одним вызовом, если драйвер и операция её поддерживают; общей транзакции через workflow или согласование нет. Неопределённые записи не повторяются автоматически. Служебные таблицы движка не являются API приложения.

Поддержанные драйверы

Класс	Драйверы	Операции
Реляционные	PostgreSQL, SQLite, MySQL	insert, upsert, параметризованный query для чтения, обновления и удаления
Документные	MongoDB	document.find, document.insert, document.update, document.delete; фильтр, проекция, сортировка, лимит
Ключ — значение	Redis	kv.get, kv.set, kv.delete, kv.increment; срок жизни ключа

Операции разделены по классу базы данных. Графовые, аналитические, векторные и специализированные time-series адаптеры добавляются при подтверждённой задаче; их поддержка из этого списка не следует.

Как расширять

Новый адаптер регистрирует поддержанные операции, схемы входов/выходов, преобразование ошибок и проверку совместимости. Драйверы устанавливаются как опциональные зависимости. MongoDB не получает поле statement с SQL, Redis — произвольный shell или серверный скрипт.

Для SQL у insert нужны table, data; у upsert также conflict; у query — statement, parameters. У каждого адаптера своя схема операции.

Параметры операций

driver, operation, connection — разные выборы: реализация базы, действие и адрес/учётные данные. Подключение обязательно и не наследует БД движка. SQL-параметры остаются отдельно от текста запроса. Для операций чтения нужны явные лимиты и сортировка, для записи — критерий изменения; универсальной неограниченной команды для всех драйверов не вводим.

Результаты типизируются по операции. Нативные идентификаторы и даты драйвер приводит к документированной JSON-форме, а не отдаёт внутренние Python-объекты. Драйверы и их доступность подключаются по общей схеме плагинов.

Плагины и установка

В составе блока: Общий контракт и выбор драйвера. Драйверов по умолчанию нет.

Плагин	Возможности
sqlite	SQL-запросы, вставка, upsert
postgresql	SQL-запросы, вставка, upsert
mysql	SQL-запросы, вставка, upsert
mongodb	Чтение и изменение документов
redis	Ключи, TTL, атомарный счётчик

Каждый драйвер, включая SQLite, выбирается явно. Служебная база движка не используется как подключение блока.

Для MySQL upsert требует единственного однозначного уникального ключа, совпадающего с conflict. Если в таблице есть другие уникальные ключи, операция отклоняется до записи.