---
referenceVersion: 2
---

# Базы данных

`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`. У каждого адаптера своя схема операции.

<span id="решения-по-параметрам"></span>

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

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

Результаты типизируются по операции. Нативные идентификаторы и даты драйвер приводит к документированной JSON-форме, а не отдаёт внутренние Python-объекты. Драйверы и их доступность подключаются по <a href="/doc/store" target="_self">общей схеме плагинов</a>.

<span id="модули-и-поставка"></span>

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

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

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

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

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