ee-database sync client

The client pulls state, not operations: each delta carries the full current row(s) for a changed entity as an idempotent INSERT … ON CONFLICT … DO UPDATE, so the target converges even if a batch was missed.

Why the sync client?

Database syncs can be consumed several ways — n8n, Make.com, MCP, raw webhooks, or the REST delta feed. The sync client is the fully-automated path: the least to build and the least to leak.

Quick start

Register a database on a schema first, then pair a client and run it on a machine that can reach your database.

1. 1

   Register a database

   On the Database Sync page, register a database on the schema you want to mirror and review its database keys. See Database Sync for the full model. This step declares the target dialect the client will apply.

2. 2

   Install the client

   Paste this in a terminal. The script verifies a cosign signature before installing.

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

   Windows: iwr -useb https://entityenricher.ai/install-eedatabase.ps1 | iex. Or download a signed binary from Releases, or build from source (Go ≥ 1.23): go build -o ee-database .

   Source and signed releases live at TOT-Concept/ee-database (MIT).

3. 3

   Pair via your browser

   Run ee-database pair. A browser tab opens at /database/connect with a short code — confirm it, and pick which database this client should sync.

   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...

   Prefer a token? Issue one on the Database Sync page (Sync client → Pair a client) and pass it directly: ee-database pair --server … <refresh-token>.

   

4. 4

   Run it on a machine that can reach your database

   On first run the client fetches the .sql snapshot and applies it, then connects and streams deltas. --save-dsn stores the connection string locally so later runs need no arguments.

   Each run also self-checks the login's provisioning rights (create database, DDL, DML) and reports the result to the Sync client card, so a missing grant is visible before deltas fail to apply. If no linked schema is published yet, the client stays connected and waits — the first publish starts the feed on its own, no restart needed.

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

   “Next to” means network-adjacent, not on the database server: any machine or container that can reach the DSN works — including cloud-managed PostgreSQL (Azure, OVHcloud, AWS RDS…), which usually enforces TLS: …/mydb?sslmode=require.

   

Managed sync hosts

Several databases landing on one machine? A sync host moves the pairing ceremony one level up: pair the machine once, and every database sync you assign to it is claimed, provisioned and kept in sync automatically — registering a new sync never needs another terminal session. Requires client 1.5.0 or later, which pairs once per server rather than once per machine — so one host can serve several Entity Enricher instances side by side.

1. 1

   Register a host

   On the Database Sync page, click the Sync hosts toolbar button and add a host named after the machine. A one-time pairing token appears exactly once, embedded in a copy-paste host pair command with guided setup steps.

2. 2

   Pair the machine once

   Run the command on the machine that can reach your database server. The --dsn is a base connection string naming the server, with no database name — each assigned sync derives its own database from it. Like every DSN it is stored mode-600 locally and never sent to Entity Enricher.

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

   Pairing self-checks the login’s provisioning rights (create database, DDL, DML) and fails fast on a missing grant. Prefer a least-privilege login? Add --admin-dsn and provisioning creates each missing role and database through the admin connection instead — the admin DSN is used at provision time only, never stored.

   

3. 3

   Run it, then assign syncs from the UI

   ee-database host run

   The host holds one control-plane WebSocket and reacts to assignments made in the UI: pick the host when registering a database, or later on the database’s Overview tab. Each assigned sync is claimed, its database created if missing (snake_cased from the sync’s name; override per sync via database_names in the host’s config.json), then synced by the ordinary loop below.

   A database already paired with another client is reported and skipped — never taken over. Revoking the host in the UI cuts the machine off instantly, including every per-database credential it claimed; assignments and already-synced data stay, so a re-paired host resumes where the old one stopped.

How delivery works: lease & ack

Deltas leave Entity Enricher through a strict per-database FIFO outbox. The server leases the visible window for 120 seconds and pushes it as one batch; the client applies the whole batch in a single transaction and replies ack , which advances the cursor and triggers the next window immediately. A client that dies mid-batch is covered by lease expiry and a server-side re-push — nothing is lost or double-committed.

What each window writes

Every applied window reports the shape it wrote, per table — so sizing a nightly re-enrichment never needs log archaeology on deltas that are already acked and gone.

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

One upsert is one row, so the counts are row counts; a prune is the single revision-guarded DELETE that clears the child or junction rows a new payload no longer claims. Children are reconciled in place — never wiped and re-inserted. Add --verbose for one line per delta, with its entity type, wall time and its own shape.

Databases & dialects

The target dialect is fixed by the schema-database registration in Entity Enricher — the client applies whatever SQL the server renders. PostgreSQL is the launch dialect; MySQL / MariaDB, SQL Server and Oracle renderers are planned (the MySQL driver is already bundled). Multi-statement application is handled per driver (pgx simple protocol, MySQL multiStatements).

Required database rights (PostgreSQL)

Assuming the target database already exists, the login needs only CONNECT on the database and USAGE + CREATE on the target schema. (Since PostgreSQL 15, public no longer grants CREATE to everyone by default.)

Everything else follows from ownership: the client creates the replica tables itself, so it owns them, and ownership implies the reads and writes the data deltas need. Ownership is not optional — the feed also ships migration statements (ALTER TABLE …, CREATE INDEX …) that PostgreSQL restricts to the table owner, and no combination of grants substitutes for it.

When a delta is quarantined

A statement your database refuses — a pre-existing duplicate under a new unique index is the usual cause — does not stop the feed. The batch rolls back, the client reports the failing delta together with the whole offending statement (never truncated), and the server quarantines that enrichment's batch and re-pushes the queue without it. Your client keeps applying everything that follows.

Quarantined work stays listed in the Quarantine tab of the Database Sync page until you deal with it: fix the cause in your database and reinject — which re-projects the entity from its current state rather than replaying the stale statement — or drop it if the row no longer matters.

A failed bootstrap is different: the snapshot is one transaction, so nothing is partially applied, and the client saves it to the pairing's profile directory as snapshot-failed.sql (mode 0600, replaced on each attempt, removed on the next success) so you can inspect or replay it with psql -f.

Security

CLI reference

Credentials are stored mode-600, one profile per paired database, under ~/.config/ee-database/profiles/ — pair once per database, and --database NAME selects one when several are paired. Prefer no automation at all? The same feed is plain REST: GET /api/databases//changes then POST /api/databases//ack — see Database Sync.

Open source