База данных

Пулы подключений к SQL-базам данных. Поддерживаются PostgreSQL, MySQL и SQLite.

Типы записей

Настройка

Стандартные базы данных (PostgreSQL, MySQL)

# src/data/_index.yaml
version: "1.0"
namespace: app.data

entries:
  - name: main_db
    kind: db.sql.postgres
    host: "localhost"
    port: 5432
    database: "myapp"
    username: "dbuser"
    password: "dbpass"
    pool:
      max_open: 25
      max_idle: 5
      max_lifetime: "1h"
    options:
      sslmode: "disable"
    lifecycle:
      auto_start: true

SQLite

  - name: cache_db
    kind: db.sql.sqlite
    file: "/var/data/cache.db"  # Для in-memory используйте :memory:
    pool:
      max_open: 4
      max_idle: 2
      max_lifetime: "1h"
    lifecycle:
      auto_start: true

Поля подключения

Стандартные поля

Поля SQLite

max_mutation_changes и max_mutation_bytes ограничивают находящийся в памяти наблюдатель зафиксированных мутаций, который питает источник db.cdc.sqlite. Ноль в любом из полей выбирает значение по умолчанию; отрицательные значения отклоняются. Ограничения консервативные, а не точные: SQLite передаёт в pre-update hook целую строку, поэтому одна строка может материализоваться до того, как ограничение отклонит кандидата.

Секреты и значения из окружения

Значения подключения берутся из реестра окружения через плейсхолдеры ${env:NAME}, разрешаемые при декодировании. NAME — публичное имя зарегистрированной переменной или её ID записи (например, app.secrets:db_password); это не сырая переменная окружения ОС.

- name: prod_db
  kind: db.sql.postgres
  host: ${env:DB_HOST}
  port: ${env:DB_PORT}
  database: ${env:DB_NAME}
  username: ${env:DB_USER}
  password: ${env:app.secrets:db_password}

Пул подключений

Настройка поведения пула. Параметры соответствуют пулу подключений database/sql в Go.

pool:
  max_open: 25      # Ограничить параллельные подключения
  max_idle: 5       # Держать 5 подключений готовыми
  max_lifetime: "30m"  # Обновлять подключения каждые 30 минут

Форматы DSN

Для каждого типа БД формируется свой DSN из конфигурации. Любые options добавляются в конец (отсортированные по ключу); по умолчанию не включается ни одна.

PostgreSQL {id="dsn-postgresql"}

host='host' port=port user='username' password='password' dbname='database' [option='value' ...]

Каждое значение, кроме порта, заключено в одинарные кавычки, а встроенные ' и \ экранируются обратным слэшем, поэтому хосты, пароли и значения опций с пробелами или кавычками передаются без искажений.

MySQL {id="dsn-mysql"}

username:password@tcp(host:port)/database[?option=value&...]

SQLite {id="dsn-sqlite"}

file:/path/to/database.db?mode=rwc
:memory:

Опции баз данных

Типичные опции для разных БД:

PostgreSQL {id="options-postgresql"}

options:
  sslmode: "require"      # disable, require, verify-ca, verify-full
  connect_timeout: "10"   # Тайм-аут подключения в секундах
  application_name: "myapp"

MySQL {id="options-mysql"}

options:
  charset: "utf8mb4"
  parseTime: "true"       # Парсить значения времени в time.Time
  loc: "Local"            # Часовой пояс

SQLite {id="options-sqlite"}

SQLite не применяет карту options к своему DSN. Файловые базы всегда открываются с mode=rwc, а режим журнала всегда устанавливается в WAL. Поле options принимается, но игнорируется.

Примеры

PostgreSQL с SSL

- name: secure_postgres
  kind: db.sql.postgres
  host: "db.example.com"
  port: 5432
  database: "production"
  username: "app_user"
  password: ${env:app.secrets:db_password}
  pool:
    max_open: 50
    max_idle: 10
    max_lifetime: "1h"
  options:
    sslmode: "verify-full"
    sslcert: "/certs/client.crt"
    sslkey: "/certs/client.key"
    sslrootcert: "/certs/ca.crt"
  lifecycle:
    auto_start: true

MySQL реплика для чтения

- name: mysql_replica
  kind: db.sql.mysql
  host: "replica.db.example.com"
  port: 3306
  database: "app"
  username: "readonly"
  password: ${env:app.secrets:replica_password}
  pool:
    max_open: 20
    max_idle: 5
    max_lifetime: "30m"
  options:
    charset: "utf8mb4"
    parseTime: "true"
    readTimeout: "30s"

SQLite в памяти

- name: test_db
  kind: db.sql.sqlite
  file: ":memory:"

Несколько баз данных

entries:
  # Основная база
  - name: users_db
    kind: db.sql.postgres
    host: ${env:USERS_DB_HOST}
    port: 5432
    database: "users"
    username: ${env:USERS_DB_USER}
    password: ${env:app.secrets:users_db_password}
    lifecycle:
      auto_start: true

  # Аналитика
  - name: analytics_db
    kind: db.sql.mysql
    host: ${env:ANALYTICS_DB_HOST}
    port: 3306
    database: "analytics"
    username: ${env:ANALYTICS_DB_USER}
    password: ${env:app.secrets:analytics_db_password}
    lifecycle:
      auto_start: true

  # Локальный кеш
  - name: cache
    kind: db.sql.sqlite
    file: "/var/cache/app.db"
    lifecycle:
      auto_start: true

Регистрация во время работы

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

Lua API

См. Модуль SQL для API работы с базами данных.

См. также

• Модуль SQL — справочник Lua API
• Store — key-value хранилище на основе базы db.sql.*
• Queue — обработчик очередей на основе SQL
• Change Data Capture — стриминг построчных изменений из базы db.sql.sqlite или Postgres