electricsql

ElectricSQL 是一个同步引擎，通过 Shapes 把 Postgres 数据的部分副本实时流式同步到本地客户端。它只处理读路径，借助逻辑复制把行数据从 Postgres 同步到客户端；写入仍通过你现有的 API 完成，Electric 再把已确认状态同步回所有连接的客户端。

适用场景：从 Postgres 到客户端应用的实时同步、需要 Postgres 实时数据的本地优先架构、用流式更新替代轮询、配合 TanStack DB 的 Electric collections、以 Postgres 为后端的多客户端协作应用。不适用：非 Postgres 数据库、需要引擎内置客户端到服务端同步的应用（Electric 只处理读）、无实时需求的简单 REST CRUD、不需要本地数据的应用。

主要能力与用法：Shape 请求用 GET /v1/shape?table=items&offset=-1 做初始全量快照；之后用 ?live=true&handle=...&offset=... 长轮询实时变更，或用 ?live=true&live_sse=true 建立 SSE 长连接。支持 ?where=status='active' 服务端行过滤，参数化写法 ?where=user_id=$1&params[1]=abc 可防注入；?columns=id,title,status 只同步所需列以省带宽；?replica=full 在更新和删除时返回完整行；?log=changes_only 跳过初始快照只收新变更。JS 侧可用 new ShapeStream({ url, params: { table } }) 低层流客户端（自动重连），new Shape(stream) 物化为当前值 Map，React 用 useShape({ url, params: { table } }) 并带加载/错误状态。

部署与安全：可用 docker run -e DATABASE_URL=... electricsql/electric 单容器运行，Postgres 需 wal_level=logical，否则无法启动。生产需设置 ELECTRIC_SECRET=key，开发可用 ELECTRIC_INSECURE=true。不要把 Electric 直接暴露到公网，应放在验证令牌并按用户注入 where 条件的鉴权代理之后。

常见限制与注意：Electric 仅读，写入走 API；写处理器应返回 { txid } 以便确认同步完成；offset=-1 只用于初始同步，之后用返回的 offset；ShapeStream 需用 onError 处理 FetchError 401 以刷新令牌重试。资料未提供收费、价格与平台信息。