ee-database Sync Client - Entity Enricher ドキュメント

ee-database sync client

スキーマデータベース 向けのオープンソースの適用クライアントです。あなた自身の PostgreSQL の隣で実行し、一度ペアリングすれば、そのデータベースをエンリッチメントと収束した状態に保ちます。スナップショットからブートストラップし、その後は単一の外向き WebSocket でライブのデルタフィードを適用します。接続文字列がマシンから出ることはありません。

Entity Enricherserver · outboxee-databaseあなたのマシンお客様のデータベースPostgres · MySQL · SQLitebatch · リース 120秒apply — 単一トランザクションcommitack 次のウィンドウが即座にプッシュされます

すべてのステートメントはリビジョンガード付きなので、再配信されたバッチは同じ行に収束します。SQLエラーが発生するとバッチはロールバックされて停止し、問題のあるデルタが暗黙的にスキップされることはありません。

クライアントが取得するのは 操作ではなく状態 です。各デルタは、変更されたエンティティの現在の全行を、冪等な INSERT … ON CONFLICT … DO UPDATE として持ち込むため、バッチを取りこぼしてもターゲットは収束します。

なぜ同期クライアントなのか？

スキーマデータベースは、n8n、Make.com、MCP、生のwebhook、REST デルタフィードなど、いくつかの方法で利用できます。同期クライアントは完全自動化された手段であり、構築するものが最も少なく、漏洩のリスクも最小です。

構築するワークフローはゼロ

n8nシナリオもcronもグルーコードも不要です。一度ペアリングすればスナップショットからブートストラップし、その後は到着するたびにすべてのデルタを適用します。

DSN がマシンから出ることはありません

接続文字列はコマンドラインで渡すか、ローカルに mode-600 で保存されます。Entity Enricher に送信されることは決してありません。クライアントは外向きにのみ接続します。

設計上、リプレイセーフです

各デルタは冪等でリビジョンガード付きのアップサートです。バッチの途中でクライアントが停止しても、リースの期限切れ後にバッチが再配信され、再適用によって同じ行に収束します。

エラーは明示的に、決して暗黙的にはしません

SQL エラーが発生するとバッチはロールバックされ、失敗したデルタが Databases ページに報告され、非ゼロで終了します。問題のあるデルタが黙ってスキップされることは決してありません。

クイックスタート

まずスキーマにデータベースを登録し、次にクライアントをペアリングして、データベースの隣で実行します。

  1. 1

    データベースを登録

    Databasesページで、ミラーリングしたいスキーマにデータベースを登録し、そのデータベースキーを確認します。完全なモデルについてはDatabasesをご覧ください。このステップで、クライアントが適用する対象のダイアレクトを宣言します。

  2. 2

    クライアントをインストール

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

    トークンをお使いですか？ Databasesページ（Sync client → Pair a client）で発行し、直接渡してください: ee-database pair --server … <refresh-token>。

  4. 4

    データベースの隣で実行

    初回実行時、クライアントは.sqlスナップショットを取得して適用し、その後接続してデルタをストリーミングします。--save-dsnは接続文字列をローカルに保存するため、以降の実行では引数が不要になります。

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

    「Next to」とはネットワーク的に近接していることを意味し、データベースサーバー上にある必要はありません：DSN に到達できるマシンやコンテナであれば動作します — 通常 TLS を強制するクラウドマネージドの PostgreSQL（Azure、OVHcloud、AWS RDS…）も含みます：…/mydb?sslmode=require。

配信の仕組み: リースとack

デルタは、データベースごとに厳密な FIFO アウトボックスを通じて Entity Enricher から送出されます。サーバーは表示ウィンドウを 120 秒間リースし、1 つのバッチとしてプッシュします。クライアントはバッチ全体を単一トランザクションで適用し、ack を返します。これによりカーソルが前進し、次のウィンドウが即座にトリガーされます。バッチの途中で停止したクライアントは、リースの期限切れとサーバー側の再プッシュによってカバーされるため、データの損失や二重コミットは発生しません。

スナップショット = ゼロからのデルタ

ブートストラップと定常状態は同一のコードパスを共有します。データベースがすでにシードされている場合は、--skip-bootstrap でブートストラップをスキップできます。

リビジョンガード付き

各ステートメントは _sync_revision を持つため、順序が前後しても、古い行が新しい行を上書きすることは決してありません。

失敗時に停止

SQL エラーが発生すると、失敗したデルタ ID が Databases ページ → Sync client カードに保存され、プロセスは非ゼロで終了して、スーパーバイザーによる再起動を促します。

データベースとダイアレクト

ターゲットの方言は、Entity Enricher でのスキーマデータベース登録によって固定されます。クライアントはサーバーがレンダリングした SQL をそのまま適用します。PostgreSQL がローンチ時の方言です。MySQL と SQLite のドライバは、それぞれの SQL レンダラーが出荷された際に備えて、すでにバンドルされています。複数ステートメントの適用はドライバごとに処理されます（pgx シンプルプロトコル、MySQL の multiStatements、CGO 不要の SQLite）。

セキュリティ

送信のみ

クライアントは :443/wss 経由で WebSocket を開始します。データベースホストがインバウンド接続を受け付けることは決してありません。開放するポートも、設定するイングレスもありません。

1つの認証情報、1つのデータベース、1つのクライアント

認証情報は単一のスキーマデータベースにバインドされます。再度ペアリングすると認証情報がローテーションされ、以前のライブ接続が即座に切断されます。

短命なアクセストークン

365日のリフレッシュトークン（mode-600 で保存）は、WebSocket を認証する15分間のアクセストークンと交換されます。UI から取り消すと、稼働中のクライアントは約1秒以内に切断されます。

最小権限を推奨します

同期対象のスキーマに限定した専用データベースロールでクライアントを実行することで、トークンが漏洩しても他には一切アクセスできないようにします。

CLI リファレンス

コマンド機能内容
ee-database pair --server URLブラウザで確認するデバイスコードペアリングです。同期するデータベースを選択してください。
ee-database pair --server URL <token>Databasesページで発行されたトークンでペアリングします（ヘッドレス対応）。
ee-database run --dsn DSN [--save-dsn] [--skip-bootstrap]スナップショットからブートストラップし（スキップされない限り）、接続してデルタを適用します。
ee-database run … --create-missingターゲットデータベースが存在しない場合は、DSN 自身の認証情報を使用して最初に作成します（postgres には CREATEDB、mysql には CREATE 権限が必要です。sqlite ファイルはいずれにせよ自動的に作成されます）。
ee-database run … --create-missing --admin-dsn DSN対象 DSN が指定するすべてのものを、管理者接続でブートストラップします。存在しないロール／ユーザー（DSN のパスワードを使用）と、それが所有するデータベースを作成します。これにより対象 DSN には作成権限が不要になり、管理者 DSN は一切保存されません。
ee-database run --allペアリング済みのすべてのデータベースを1つのプロセスから並行して同期します（それぞれに保存済みの DSN が必要です）。
ee-database statusペアリング状態、サーバー URL、およびペアリング済みデータベースを表示します。
ee-database disconnect1つのペアリングのローカル認証情報を削除します。サーバー側での取り消しは UI から行います。
ee-database version印刷版。

認証情報は mode-600 で保存され、ペアリング済みデータベースごとに1つのプロファイルが ~/.config/ee-database/profiles/ 配下に置かれます。ペアリングはデータベースごとに一度だけ行い、複数がペアリングされている場合は --database NAME で1つを選択します。自動化をまったく使わないことをお好みですか？同じフィードはプレーンな REST でも利用できます。GET /api/databases//changes の後に POST /api/databases//ack を実行してください。Databases を参照してください。

オープンソース

クライアントは MIT ライセンスで、公開リポジトリに存在するため、誰でも自分のデータベースに対して何が実行されるのかを正確に監査できます。

ソース: github.com/TOT-Concept/ee-database

リリース: github.com/TOT-Concept/ee-database/releases — 各バイナリは公開前に署名されます。