клиент синхронизации ee-database

Клиент получает состояние, а не операции: каждая дельта несёт полные текущие строки изменённой сущности в виде идемпотентного INSERT … ON CONFLICT … DO UPDATE, поэтому целевая база сходится, даже если пакет был пропущен.

Зачем нужен клиент синхронизации?

Синхронизации базы данных можно потреблять несколькими способами — n8n, Make.com, MCP, сырые webhook'и или REST-поток дельт. Клиент синхронизации — полностью автоматизированный путь: меньше всего разрабатывать и меньше всего утечек.

Быстрый старт

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

1. 1

   Зарегистрируйте базу данных

   На странице Database Sync зарегистрируйте базу данных для схемы, которую хотите зеркалировать, и проверьте её ключи базы данных. Полное описание модели см. в разделе Database Sync. На этом шаге объявляется целевой диалект, который применит клиент.

2. 2

   Установите клиент

   Вставьте это в терминал. Скрипт проверяет подпись cosign перед установкой.

   curl -fsSL https://entityenricher.ai/install-eedatabase.sh | sh

   Windows: iwr -useb https://entityenricher.ai/install-eedatabase.ps1 | iex. Или скачайте подписанный бинарный файл из раздела Releases, либо соберите из исходного кода (Go ≥ 1.23): go build -o ee-database .

   Исходный код и подписанные релизы — на TOT-Concept/ee-database (MIT).

3. 3

   Свяжите через браузер

   Запустите ee-database pair. Откроется вкладка браузера на /database/connect с коротким кодом — подтвердите его и выберите, какую базу данных должен синхронизировать этот клиент.

   ee-database pair --server https://entityenricher.ai
   
   Open this URL in your browser to confirm pairing:
      https://entityenricher.ai/database/connect?code=7QX-KP2
   
     Code: 7QX-KP2
   
   Waiting for confirmation...

   Предпочитаете токен? Выпустите его на странице Database Sync (Клиент синхронизации → Привязать клиент) и передайте напрямую: ee-database pair --server … <refresh-token>.

   

4. 4

   Запустите его на машине, у которой есть доступ к вашей базе данных

   При первом запуске клиент загружает снимок .sql и применяет его, затем подключается и получает поток дельт. --save-dsn сохраняет строку подключения локально, поэтому последующие запуски не требуют аргументов.

   Каждый запуск также самостоятельно проверяет права логина на подготовку (создание базы данных, DDL, DML) и сообщает результат на карточку клиента синхронизации, поэтому отсутствующее разрешение видно до того, как дельты не смогут примениться. Если ещё не опубликована связанная схема, клиент остаётся подключённым и ждёт — первая публикация запускает поток сама, перезапуск не нужен.

   ee-database run --dsn "postgres://user:pass@localhost:5432/mydb" --save-dsn

   «Рядом» означает сетевую близость, а не размещение на сервере базы данных: подойдёт любая машина или контейнер, способные достучаться до DSN, — включая облачный управляемый PostgreSQL (Azure, OVHcloud, AWS RDS…), который обычно требует TLS: …/mydb?sslmode=require.

   

Управляемые хосты синхронизации

Несколько баз данных на одной машине? Хост синхронизации поднимает процедуру привязки на уровень выше: привяжите машину один раз — и каждая синхронизация базы данных, которую вы ей назначаете, автоматически подхватывается, разворачивается и поддерживается в актуальном состоянии; регистрация новой синхронизации больше никогда не требует сеанса в терминале. Требуется клиент 1.5.0 или новее: он выполняет привязку один раз для каждого сервера, а не один раз для машины, — поэтому один хост может обслуживать сразу несколько экземпляров Entity Enricher.

1. 1

   Зарегистрировать хост

   На странице Database Sync нажмите кнопку Sync hosts на панели инструментов и добавьте хост с именем машины. Одноразовый токен сопряжения показывается ровно один раз — внутри готовой к копированию команды host pair с пошаговыми инструкциями по настройке.

2. 2

   Свяжите машину один раз

   Выполните команду на машине, которая имеет доступ к вашему серверу баз данных. --dsn — это базовая строка подключения, указывающая сервер, без имени базы данных: каждая назначенная синхронизация выводит из неё собственную базу данных. Как и любой DSN, она хранится локально в режиме mode-600 и никогда не отправляется в Entity Enricher.

   ee-database host pair --server https://entityenricher.ai \
     --dsn "postgres://user:pass@host:5432/" <token>

   Привязка самостоятельно проверяет права логина на подготовку (создание базы данных, DDL, DML) и сразу завершается ошибкой при отсутствии разрешения. Предпочитаете логин с минимальными привилегиями? Добавьте --admin-dsn, и подготовка создаст каждую отсутствующую роль и базу данных через административное подключение — административный DSN используется только во время подготовки и никогда не сохраняется.

   

3. 3

   Запустите её, затем назначьте синхронизации в интерфейсе

   ee-database host run

   Хост поддерживает один WebSocket плоскости управления и реагирует на назначения, сделанные в интерфейсе: выберите хост при регистрации базы данных или позже на вкладке Обзор базы данных. Каждая назначенная синхронизация захватывается, её база данных создаётся при отсутствии (имя в snake_case из имени синхронизации; переопределяется для каждой синхронизации через database_names в файле config.json хоста), затем синхронизируется обычным циклом ниже.

   База данных, уже связанная с другим клиентом, отмечается и пропускается — она никогда не перехватывается. Отзыв хоста в интерфейсе мгновенно отключает машину, включая все учётные данные для каждой базы данных, которые она заявила; назначения и уже синхронизированные данные сохраняются, поэтому повторно связанный хост продолжает с того места, где остановился прежний.

Как работает доставка: аренда и подтверждение

Дельты покидают Entity Enricher через строгую очередь FIFO, отдельную для каждой базы данных. Сервер арендует видимое окно на 120 секунд и отправляет его одним пакетом; клиент применяет весь пакет в одной транзакции и отвечает ack , что продвигает курсор и немедленно запускает следующее окно. Если клиент прерывается посреди пакета, его защищают истечение аренды и повторная отправка на стороне сервера — ничего не теряется и не фиксируется дважды.

Что записывает каждое окно

Каждое применённое окно сообщает форму записанных данных в разбивке по таблицам — поэтому для оценки объёма ночного повторного обогащения не придётся раскапывать логи по дельтам, которые уже подтверждены и удалены.

applying 12 delta(s) (10831 .. 10842) in one transaction
applied 12 delta(s) in 84ms — 38 statement(s): mushroom 4 upserts,
  mushroom_common_names 12 upserts + 4 prunes, mushroom_human_uses 14 upserts + 4 prunes
acked up to delta 10842

Один upsert — это одна строка, поэтому счётчики показывают количество строк; prune — это единственный DELETE с защитой по ревизии, который удаляет дочерние или связующие строки, больше не заявленные новой полезной нагрузкой. Дочерние записи согласуются на месте — их никогда не удаляют и не вставляют заново. Добавьте --verbose, чтобы получить по одной строке на дельту с типом сущности, фактическим временем и собственной формой записи.

Базы данных и диалекты

Целевой диалект задаётся при регистрации схемы-базы данных в Entity Enricher — клиент применяет тот SQL, который формирует сервер. PostgreSQL — стартовый диалект; генераторы для MySQL / MariaDB, SQL Server и Oracle запланированы (драйвер MySQL уже включён). Применение нескольких инструкций обрабатывается на уровне драйвера (простой протокол pgx, multiStatements в MySQL).

Необходимые права в базе данных (PostgreSQL)

Если целевая база данных уже существует, учётной записи нужны только CONNECT для базы данных и USAGE + CREATE для целевой схемы. (Начиная с PostgreSQL 15, public по умолчанию больше не выдаёт CREATE всем подряд.)

Всё остальное вытекает из владения: клиент сам создаёт таблицы реплики, поэтому владеет ими, а владение подразумевает права на чтение и запись, необходимые для дельт данных. Владение не опционально — поток также передаёт миграционные команды (ALTER TABLE …, CREATE INDEX …), которые PostgreSQL разрешает только владельцу таблицы, и никакая комбинация грантов его не заменит.

Когда дельта помещается в карантин

Запрос, который отвергает ваша база данных — обычная причина в том, что под новым уникальным индексом уже есть дубликат, — не останавливает поток. Пакет откатывается, клиент сообщает о сбойной дельте вместе с полным проблемным запросом (без обрезки), а сервер помещает пакет этого обогащения в карантин и заново отправляет очередь без него. Ваш клиент продолжает применять всё последующее.

Помещённая в карантин работа остаётся во вкладке Карантин страницы Database Sync, пока вы ею не займётесь: устраните причину в своей базе данных и выполните повторную отправку — она заново проецирует сущность из её текущего состояния, а не повторяет устаревший запрос, — либо отбросьте её, если строка больше не важна.

С неудавшимся bootstrap дело обстоит иначе: снимок — это одна транзакция, поэтому ничего не применяется частично, а клиент сохраняет его в каталог профиля сопряжения как snapshot-failed.sql (режим 0600, перезаписывается при каждой попытке, удаляется после следующего успеха), чтобы вы могли изучить или воспроизвести его через psql -f.

Безопасность

Справочник по CLI

Учётные данные хранятся с правами 600, по одному профилю на каждую сопряжённую базу данных, в каталоге ~/.config/ee-database/profiles/ — сопряжение выполняется один раз для каждой базы, а --database NAME выбирает нужную, если сопряжено несколько. Вообще не нужна автоматизация? Тот же поток доступен как обычный REST: GET /api/databases//changes, затем POST /api/databases//ack — см. Database Sync.

Открытый исходный код