ee-database 同步客户端

客户端拉取的是 状态，而非操作：每个增量都以幂等的 INSERT … ON CONFLICT … DO UPDATE 形式携带已变更实体的完整当前行，因此即使漏掉某个批次，目标也能收敛一致。

为什么使用同步客户端？

数据库同步可通过多种方式使用——n8n、Make.com、MCP、原始 webhook，或 REST 差异馈送。同步客户端是全自动的方式：构建工作最少，泄露风险也最小。

快速开始

请先在 schema 上注册数据库，然后配对客户端并在一台能访问你数据库的机器上运行它。

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。或从版本发布页下载已签名的二进制文件，或从源码构建（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）并将结果报告到同步客户端卡片，因此缺失的授权会在增量应用失败之前就可见。如果尚未发布任何关联的 schema，客户端会保持连接并等待——首次发布会自行启动数据流，无需重启。

   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 命名；可通过主机 config.json 中的 database_names 为每个同步单独覆盖），然后由下方的常规循环进行同步。

   已与其他客户端配对的数据库会被报告并跳过——绝不会被接管。在界面中撤销主机会立即断开该机器的连接，包括它所占用的每个数据库凭据；分配关系和已同步的数据会保留，因此重新配对的主机会从旧主机停止的位置继续。

投递机制：租约与确认

增量通过严格的按数据库 FIFO 发件箱离开 Entity Enricher。服务器租用可见窗口 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 中 Schema 与数据库的注册绑定决定——客户端只执行服务端生成的 SQL。首发支持的方言为 PostgreSQL；MySQL / MariaDB、SQL Server 和 Oracle 渲染器正在规划中（MySQL 驱动已内置）。多语句执行由各驱动分别处理（pgx 简单协议、MySQL multiStatements）。

所需的数据库权限（PostgreSQL）

假设目标数据库已存在，该登录账号只需对数据库拥有 CONNECT 权限，并对目标模式拥有 USAGE + CREATE 权限。（自 PostgreSQL 15 起，public 默认不再向所有人授予 CREATE。）

其余一切都源于所有权：副本表由客户端自行创建，因此归其所有，而所有权意味着具备数据增量所需的读写权限。所有权并非可选项——数据流还会下发迁移语句（ALTER TABLE …、CREATE INDEX …），PostgreSQL 仅允许表的所有者执行这些语句，任何权限授予组合都无法替代它。

增量何时会被隔离

被你的数据库拒绝的语句——通常是新建唯一索引下已存在的重复数据——不会中断数据流。批次会回滚，客户端会报告出错的增量以及完整的问题语句（绝不截断），服务器则隔离该次富集的批次，并在剔除它后重新推送队列。你的客户端会继续应用后续的所有内容。

被隔离的任务会一直显示在 Database Sync 页面的隔离区标签页中，直到你处理为止：在你的数据库中修复原因后重新注入——它会按实体的当前状态重新投影，而不是重放过时的语句——或者在该行已无关紧要时将其丢弃。

引导初始化失败则不同：快照是单个事务，因此不会出现部分应用的情况；客户端会把它以 snapshot-failed.sql 为名保存到该配对的配置目录（权限 0600，每次尝试都会覆盖，下次成功后删除），你可以用 psql -f 检查或重放。

安全

CLI 参考

凭据以 mode-600 权限存储在 ~/.config/ee-database/profiles/ 下，每个已配对的数据库对应一份配置文件——每个数据库只需配对一次；配对了多个时，可用 --database NAME 指定其中之一。完全不想用自动化？同一数据流也是纯 REST：先 GET /api/databases//changes，再 POST /api/databases//ack——参见 Database Sync。

开源