如果把 ElectricSQL 当成完整的 local-first 应用框架来理解，它很容易被误读。更有用的采用框架要窄一些：Electric 是 Postgres 的读路径同步基础设施。它接收被选中的数据库状态，把这些状态转成 shape streams，让客户端经由 HTTP 消费这些 streams，同时现有应用继续负责写入、授权与业务规则。[1][2][3]
这种更窄的理解并不会降低 Electric 的价值，反而解释了它重新变得值得关注的原因。许多团队希望 UI 更快、更有本地感，却不想替换 Postgres、重写 mutation 层，或者接受一个新的全能型后端。Electric 当前的架构给出了一条实用的中间路线：继续把 Postgres 作为事实来源，通过 logical replication 跟随变更，把有边界的数据子集同步到 edge 或浏览器，让客户端在每一次读取上少依赖往返请求。[1][2][6]
截至 2026-05-18T09:32:44Z UTC，GitHub API 显示 electric-sql/electric 拥有 10,187 stars、331 forks、296 个 open issues，采用 Apache-2.0 license，最近一次 push 时间为 2026-05-18T09:30:51Z。[4] releases feed 显示 2026-05-13 有新的 package tags，其中包括 [email protected]。[5] 这些数字本身不能证明适配度，但它们说明这是一个仍在活跃推进的项目，采用问题应当落在架构判断上，仓库是否已经沉睡只处在次要位置。
配图说明：题图展示的是 Tim Berners-Lee 用作第一台 World Wide Web server 的 NeXT 工作站。[8] ElectricSQL 与这台机器没有历史关系，但这张图能提供一个有用的视觉锚点：本文讨论的是如何让同步继续作为 web 基础设施被理解。真正有意思的部分在于那个旧问题：如何通过运维人员能够理解的边界，让网络化状态变得可用。
1. 从 Shapes 开始，因为它们才是采用单位
Electric 的关键原语是 Shape。文档把 Shapes 定义为 Electric 将 Postgres 数据的小型子集同步到本地应用和服务的方式：一个 table、一个可选的 where clause，以及可选 columns，共同定义客户端应该接收什么。[2] 这正是制定采用计划时合适的单位。团队起步时不应先问“我们能不能同步整个应用”，而应问“哪些数据切片稳定、有用，并且足够安全，适合进入同步”。
这个问题会立刻暴露真实边界。Shapes 当前是单表的，虽然 preview 中可以用 subqueries 做相关数据过滤，并且 shape definitions 是 immutable 的。[2] Where clauses 支持许多常见 PostgreSQL operators 和 functions，但并不覆盖 PostgreSQL 的全部能力。Shapes guide 列出了不支持的 JSONB、full-text search、geometric、network-address 与 range operators。[2] 这些限制很重要，因为它们阻止 Electric 变成看不见的魔法。如果本地视图依赖复杂的 server-side 语义，团队就必须决定是简化 shape、使用 backend endpoint，还是等待功能支持。
这也是 Electric 更适合读模型可以被显式写出的场景的原因。Task lists、dashboards、edge caches、agent context、analytics views 与 collaborative app panels 往往天然带有子集边界：一个 project、account、workspace、organization、device，或者一张 table 中当前可见的一段切片。[1][2] 较弱的适配场景，是每个屏幕都依赖任意 cross-table query 语义、而这些语义从未被写成同步契约的产品。
2. 把写入视为一个有意留下的非功能
Writes guide 的说法直截了当，而且很有帮助：Electric 做 read-path sync，没有提供或规定内建的 write-path sync 回 Postgres。[3] 这句话应该进入每一份迁移计划。Electric 要求团队把写入继续留在 API 里，然后让 Postgres 变更再经由同步流出，避免要求团队把 mutations 搬进一种新的分布式协议。
当写入本来就需要集中验证时，这个设计非常合适：payments、permissions、inventory changes、server-side workflows、AI jobs、audit trails，或者任何不能随意采用“稍后合并本地 mutation”处理方式的场景。[3] UI 仍然可以使用 optimistic state，但规范性的写入决定继续留在应用现有 endpoint 后面。[3][7]
取舍也同样清楚。如果产品的核心功能是真正的 offline writes，并且伴随复杂 conflict resolution，Electric 单独使用时答案仍然留有明显缺口。团队还需要围绕它配置 outbox、optimistic mutation model、conflict policy，或者另一层 local-first 机制。[3][7] 这属于架构交换条件，不应被视为工具失败。Electric 降低的是实时本地读取的成本；它不会让分布式写入免费发生。
3. 把授权留在同步引擎之外
Electric 的 auth guide 建议通过 proxy 或 middleware stack 路由请求，让应用在请求到达 Electric 之前完成 shape access 授权。[6] 在 simple proxy pattern 中，应用验证 credentials，在 server-side 设置 shape parameters，再把被授权的响应 stream 回客户端。[6] 在 gatekeeper pattern 中，API 会签发一个 shape-scoped token，由 proxy 根据请求的 shape 进行验证。[6]
这种安排很重要，因为 synced data 通常比 fetched data 更危险。普通 endpoint 返回一次响应；shape stream 会在底层 table 变化时持续交付变更。如果客户端可以在缺少 server 控制的情况下自行选择 table 和 where clause，同步层就会变成数据外流表面。[2][6]
因此，采用清单应当把授权放在 client polish 前面。每个 shape 由哪条 backend route 拥有？哪些 parameters 固定在 server-side？哪些 user-supplied filters 只允许缩小结果？哪些 shape-scoped tokens 会过期，group membership 变化时又怎样处理？Electric 文档已经把这一点写得足够明确，团队应当抵制把 /v1/shape 直接暴露给 public client 的捷径。[6]
4. 诚实计算运维表面
Electric 以 Docker 打包为一个 Elixir web service，通过 DATABASE_URL 连接 Postgres。[1][7] Deployment guide 写明，Postgres 必须是 version 14 或以上，logical replication 必须启用，database role 需要 replication privileges。[7] 它还提醒，通常需要 direct Postgres connections，因为大多数 connection poolers 不支持 logical replication，尽管 pgBouncer support 随时间推进会改变这条边界。[7]
这里还有一层 storage surface。Electric 会创建 publication 和 replication slot，保持 active database connections，并在 persistent filesystem 上缓存 shape logs 与 metadata。[7] 文档把 disk speed 列为服务 Electric 的 hosts 上最高优先级的优化因素，排在 memory 和 CPU 之前。[7] 这对规划很重要。Electric 会移除一部分定制 polling endpoints，也会减少 client waterfalls，但它同时加入了一个真实的同步服务，带来 disk、replication、cache 与 upgrade 责任。
运维收益在于 runtime 使用 HTTP。HTTP API 支持 initial shape sync 和通过 long polling 实现的 live updates，也提供 Server-Sent Events 作为效率更高的 live mode。[1] 这让 client boundary 比专有 binary protocol 更容易检查。当授权设计成立时，它也让 CDN 与 edge proxy pattern 更有现实基础。[1][6]
5. 把 TanStack DB 和 PGlite 当作适配信号，作为适配信号，区别于前置条件
Electric 的生态现在指向一个更宽的 local-data stack。Electric 文档列出 PGlite examples 和 TanStack DB integration；TanStack DB 则把自己描述为 reactive client store，可以把数据载入 normalized collections、运行 live queries，并使用 ElectricSQL 等 sync engines 作为 collection sources。[1][2][7]
这是一个有用信号，但不应变成照搬。Electric 可以通过 HTTP API、TypeScript client、React hooks，或者更高层的 collection systems 来消费。[1][2] 正确的 client layer 取决于应用需要多少本地 query 行为。如果 components 主要需要 live list 或 detail view，useShape 加一层薄 store 就足够。如果应用需要 local joins、optimistic collection mutations、derived views，或者 query-driven loading，TanStack DB 就更有吸引力。[2][7]
同样的纪律也适用于 PGlite。客户端内嵌 Postgres 可以很强，尤其适合更丰富的 local state 或 test/dev environments，但它并非每个 Electric deployment 都需要的组件。[1] 先确定同步边界。只有当应用的 offline、query 或 agent-workload 需求支撑这层重量时，再加入更重的 local database。
收束
当团队把同步视为显式读路径层，并将其同替代性应用平台拉开距离时，ElectricSQL 最强。[1][2][3] 迁移路径应当从少量有边界的 Shapes 开始，让它们经过 backend-controlled auth proxy，写入继续留在现有 API 中，并在扩大表面之前衡量 logical replication 加 shape-log storage 的运维成本。[2][3][6][7]
失败模式来自过度宣称。Electric 可以让基于 Postgres 的应用显得更快、更接近本地体验，但前提是数据切片选择得当，write/auth boundaries 保持可见。以这种方式使用时，它给团队提供了一条务实路径，在不把每个产品都改造成定制分布式数据库的前提下，获得更有本地感的软件体验。
来源
- Electric Docs，《Electric Sync》——read-path sync 概览、基于 HTTP 的 client model、examples，以及 self-hosting/cloud 入口。
- Electric Docs，《Shapes》——shape definition、single-table limitation、supported filters、live subscriptions、subset loading 与 client usage。
- Electric Docs，《Writes》——read-path-only boundary、缺少内建 write-path sync、online writes，以及 optimistic-state patterns。
- GitHub API snapshot for
electric-sql/electric——文章创建时的 repository stars、forks、open issues、license 与 recent push metadata。 - GitHub releases feed for
electric-sql/electric——recent package tags，包括[email protected]。 - Electric Docs，《Auth》——proxy auth、gatekeeper auth、shape parameters 的 server-side control，以及 edge/CDN authorization patterns。
- Electric Docs，《Deployment》——Postgres 14+、logical replication、direct connection guidance、replication resources、Docker service 与 shape-log storage requirements。
- Wikimedia Commons，《File:First Web Server.jpg》——Tim Berners-Lee 的 NeXT 工作站在 CERN 陈列时的真实摄影题图来源页。