Настройка SQL-адаптера

Результат этой процедуры — работающий SQL-адаптер: контейнер по расписанию выполняет запрос к базе-источнику Oracle, превращает каждую строку выборки в событие и публикует его для модуля Flow. Успех распознаётся по успешному ответу пробы готовности и по записям о выполненной выборке в логе адаптера.

Что умеет адаптер и где проходят границы его применимости — в обзорной статье SQL-адаптер.

Предусловия

Перед настройкой проверьте четыре зависимости.

Особенности сетевой конфигурации при подключении к Redis описаны в статье Особенности подключения к Redis.

Шаги

1. Загрузите образ адаптера

Выполните команду:

docker load < flows_sql_adapter_<версия>.tar.gz

<версия> — номер версии из архива поставки. В выводе появится строка Loaded image, а команда docker images покажет образ flows_sql_adapter.

2. Создайте файл конфигурации

Создайте файл docker-compose.yaml по образцу:

services:
  sql_adapter:
    image: devcubesolutions/flows_sql_adapter:<версия>
    container_name: sql_adapter
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - ADAPTER_NAME=<имя адаптера>
      - REDIS_CONNECTION=redis://<адрес Redis>:6379
      - BROKER_CONNECTION=amqp://<пользователь>:<пароль>@<адрес RabbitMQ>:5672
      - DRIVER=Oracle
      - DB_USER=<пользователь БД>
      - DB_PASSWORD=<пароль БД>
      - CONNECTION_STRING=<хост>:<порт>/<сервис Oracle>
      - STATEMENT=SELECT * FROM <схема>.<таблица>
      - CRON=0 */5 * * * *
      - ID_FIELD=<колонка идентификатора клиента>
      - EVENT_NAME=<имя события>
      - EVENT_CONTEXT=<имя поля>,{{<колонка>}}
      - ENABLE_METRICS=true
      - METRICS_PORT=3010

Значения в угловых скобках замените под своё окружение. Команду запуска в файле не указывайте: точка входа встроена в образ. Образ в примере выше подставляется из шага 1 — сверьте имя и версию по docker images.

3. Заполните переменные подключения

Все переменные этой группы обязательны: без любой из них адаптер завершается при старте.

4. Заполните переменные события

Эта группа определяет, как строка выборки превращается в событие.

5. Запустите адаптер

Выполните команду:

docker compose -f <путь к файлу> up -d

Команда docker ps покажет контейнер sql_adapter в статусе Up.

Инкрементальное чтение

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

Добавьте в environment группу переменных. При MAX_VALUE=true обязательны все перечисленные: без любой из них адаптер завершается при старте.

Проверка

1. Выполните curl http://localhost:3010/ready — ожидается успешный ответ: источник, брокер и Redis доступны. Проба работает при ENABLE_METRICS=true из образца конфигурации.
2. Дождитесь первого срабатывания расписания и откройте лог: docker logs -f sql_adapter — появятся записи о выполнении выборки.
3. Убедитесь, что счётчик прочитанных строк растёт: curl -s http://localhost:3010/metrics | grep events_counter — значение больше нуля после первой непустой выборки.

Решение проблем

Контейнер завершается сразу после запуска

Симптом: docker ps контейнер не показывает, docker ps -a — статус Exited (1).

Причина: не прошла проверка конфигурации — не задана обязательная переменная, DRIVER отличен от Oracle либо CRON не проходит валидацию.

Шаги: прочитайте причину в docker logs sql_adapter, сверьте переменные с таблицами шагов 3 и 4, перезапустите. Если не помогло — проверьте, что в значениях нет невидимых символов и лишних пробелов после знака =.

После запуска в логе нет активности

Причина: либо расписание ещё не сработало, либо недоступен RabbitMQ — расписание заводится только после установления канала с брокером.

Шаги: проверьте доступность брокера пробой curl http://localhost:3010/ready; сверьте CRON с учётом московской таймзоны. Если не помогло — временно установите частое расписание, например */30 * * * * *, и убедитесь, что выборка выполняется.

Строки читаются, события во Flow не приходят

Причина: не задана ни EVENT_NAME, ни EVENT_FIELD; либо FLOW_ID указывает не на тот сценарий; либо в сценарии нет триггера на это имя события.

Шаги: проверьте лог на ошибки формирования события; сверьте имя события с триггером сценария; уберите FLOW_ID для проверки — событие уйдёт во все сценарии. Если не помогло — проверьте в метриках broker_connection_status: значение 0 означает разрыв с брокером, события не публикуются.

Одни и те же события приходят повторно

Причина: инкрементальное чтение выключено, и каждая выборка возвращает те же строки.

Шаги: включите инкрементальное чтение по разделу выше либо ограничьте STATEMENT условием по времени. Если не помогло — проверьте, что второй экземпляр адаптера с тем же ADAPTER_NAME не перезаписывает курсор.

В логе предупреждение о пропущенном запуске

Причина: предыдущая выборка ещё выполняется — параллельные прогоны исключены, пропущенный запуск не навёрстывается.

Шаги: разредите расписание или уменьшите объём выборки условиями в STATEMENT. Если не помогло — проверьте значение EVENTS_PER_SECOND: заданный потолок замедляет и чтение, растягивая прогон.

Остановка и откат

Остановите адаптер командой:

docker compose -f <путь к файлу> down

Курсор инкрементального чтения при остановке сохраняется в Redis: после повторного запуска выборка продолжится с сохранённого места, повторной загрузки не будет.

Связанные страницы

• SQL-адаптер — обзор: возможности и границы модуля
• Особенности подключения к Redis
• Хранение секретных данных в Docker Secret
• Получение секретных данных из HashiCorp Vault
• Метрики Prometheus
• Метрики Zabbix