Electric

定位#

Electric 是一个专注于 Postgres 读取路径的实时同步引擎。它不是数据库代理或 ORM，而是通过 Shape 原语将云端 Postgres 数据以低延迟、可扩展的方式实时同步到本地客户端（浏览器、边缘节点、移动端）的中间件引擎。仅处理 Postgres → 客户端的单向同步，不接管写入路径。

同步核心能力#

• Shape 原语：以 table + 可选 WHERE + 可选 columns 定义同步数据子集，是整个系统的核心抽象。Shape 定义不可变，需通过创建新 Shape 来调整订阅范围，这保证了 Shape Log 的确定性与 CDN 可缓存性。
• 部分复制与扇出：内建解决 partial replication、fan-out、data delivery 等分布式同步难题。
• 渐进式数据加载：支持 changes-only 模式与按需子集快照（subset snapshot），兼容分页、搜索、过滤。
• 子查询追踪：跨表依赖追踪，当子查询引用的表数据变化时自动调整 Shape 内容（实验性，需功能开关）。
• 高吞吐存储引擎：自定义存储引擎优化 WHERE 子句批量求值，恒定吞吐约 5,000 行变更/秒。

协议与分发#

• 底层为低级 HTTP API（GET /v1/shape），原生适配 CDN 缓存与大规模扇出。
• 提供 OpenAPI 规范描述，便于代码生成与集成。
• live=true 参数启用长轮询，持续推送 Shape Log 条目流。

客户端集成#

• TypeScript 客户端（@electric-sql/client）：提供 ShapeStream / Shape 编程接口。
• React 集成（@electric-sql/react）：提供 useShape hook。
• Elixir 客户端：官方 Elixir 客户端库。
• TanStack DB 集成：将 Shape 数据对接 TanStack 生态。
• PGlite 配合：与可嵌入式 Postgres（PGlite）深度配合，实现浏览器/边缘端完整本地存储。

架构要点#

服务端基于 Elixir/Phoenix 构建，通过 Postgres 逻辑复制捕获变更，经自定义存储引擎批量求值后生成 Shape Log，通过 HTTP API 对外分发。Monorepo 结构使用 pnpm workspace 管理，关键包包括 packages/sync-service（Elixir 服务端）、packages/typescript-client、packages/elixir-client。

快速开始#

# Docker Compose 快速启动（需启用逻辑复制的 Postgres）
docker compose -f .support/docker-compose.yml up

# 验证 HTTP API
curl -i 'http://localhost:3000/v1/shape?table=foo&offset=-1'

# 安装客户端
npm i @electric-sql/client
npm i @electric-sql/react

关键环境变量：DATABASE_URL（Postgres 连接字符串）、ELECTRIC_LIVE_DASHBOARD_PORT（启用监控面板）、ELECTRIC_FEATURE_FLAGS（如 allow_subqueries,tagged_subqueries）。

适用场景#

• 本地优先应用（Local-first App）：构建类似 Figma/Linear 的快速响应体验。
• AI Agent 持久化状态层：为多 Agent 系统提供基于实时本地数据的持久化会话能力。
• 实时协作工具：通过 Shape 订阅实现多客户端间的实时数据共享。
• 离线/弱网环境：本地缓存 + 实时增量同步。
• CDN 加速的大规模数据扇出分发。

生态关联#

待确认信息#

• 最新稳定版本号（GitHub Releases 显示 electric-ax@0.1.17，可能为 Cloud 包版本）
• Electric Cloud 托管方案的定价与 SLA
• v1 与旧版 Electric（含 include tree）的迁移路径与兼容性
• CRDT 支持细节（仓库 topic 列出 crdt，但文档未详述实现机制）
• 写入路径冲突解决的官方推荐方案