mcpField
E
electricsql

electricsql

github.com/oakoss数据与数据库20102 次安装10 周前更新
代码仓库

关于 electricsql

ElectricSQL 技能介绍基于 Postgres Shapes 的实时同步，适用于构建本地优先客户端应用的开发者。它同步读取数据，写入仍经由现有 API。

主要功能

  1. 01实时同步 Postgres 数据
  2. 02按行和列筛选副本
  3. 03支持 ShapeStream 与 React hook
  4. 04通过 API 代理处理认证
  5. 05写入后同步已确认状态

适用场景

  1. 01为客户端应用提供 Postgres 实时数据
  2. 02减少轮询并接收流式更新
  3. 03构建基于 TanStack DB 的应用
  4. 04支持由 Postgres 驱动的协作应用

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oakoss/agent-skills --skill electricsql

安装后在 Claude Code 中输入/electricsql确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
auth-and-security.md
error-handling.md
monitoring.md
setup.md
shapes-and-streams.md
sync-performance.md
write-patterns.md

详细介绍

ElectricSQL

概述

ElectricSQL 是一个同步引擎，通过 Shapes 将 Postgres 数据的部分副本流式传输到本地客户端。它负责读取路径——使用逻辑复制，将 Postgres 中的行实时同步到客户端。写入操作通过你现有的 API 返回；Electric 会将已确认的状态同步回所有已连接的客户端。

适用场景： 将 Postgres 实时同步到客户端应用、需要从 Postgres 获取实时数据的本地优先架构、用流式更新替代轮询、使用 Electric 集合的 TanStack DB 应用、由 Postgres 支持的多客户端协作应用。

不适用场景： 非 Postgres 数据库、需要引擎内置客户端到服务端同步功能的应用（Electric 仅处理读取）、没有实时需求的简单 REST CRUD、无法从本地数据中获益的应用。

快速参考

模式API / 方法要点
Shape 请求GET /v1/shape?table=items&offset=-1首次同步会获取完整快照
实时更新?live=true&handle=...&offset=...首次同步后通过长轮询获取实时变更
SSE 流式传输?live=true&live_sse=true持久的 Server-Sent Events 连接
Where 子句?where=status='active'在服务端按 SQL 风格筛选行
参数化 where?where=user_id=$1&params[1]=abc使用可防止 SQL 注入的参数化筛选
列选择?columns=id,title,status仅同步所需列以减少带宽
完整副本?replica=full更新和删除时提供完整行数据
仅变更?log=changes_only跳过初始快照，仅接收新变更
ShapeStream（JS）new ShapeStream({ url, params: { table } })底层流式客户端，支持自动重连
Shape（JS）new Shape(stream)将流物化为包含当前值的 Map
useShape（React）useShape({ url, params: { table } })提供加载和错误状态的 React Hook
身份验证代理通过你的 API 服务路由 shapes验证令牌，并按用户注入 where 子句
Docker 设置docker run -e DATABASE_URL=... electricsql/electric单个容器，需要 wal_level=logical
Electric 密钥ELECTRIC_SECRET=key 环境变量生产环境必需；开发环境使用 ELECTRIC_INSECURE=true

常见错误

错误正确做法
直接将 Electric 暴露到互联网将 Electric 放在能够验证令牌的身份验证代理之后
忘记在 Postgres 配置中设置 wal_level=logical逻辑复制必需；未设置时 Electric 将无法启动
使用 Electric 执行写入Electric 仅用于读取路径；写入应通过你的 API 完成
写入处理程序未返回 txid返回 { txid }，以便 Electric 确认同步已完成
将整个表同步到每个客户端使用 where 子句和列选择进行部分复制
在客户端代码中硬编码 shape URL使用代理端点，在服务端添加身份验证和 where 子句
每次请求都使用 offset=-1仅在初始同步时使用 offset=-1；之后使用返回的 offset
未在 ShapeStream 中处理 FetchError 401使用 onError 回调刷新令牌并重试

委派

如果有 local-first skill，请将架构决策和同步引擎比较委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y 如果有 tanstack-db skill，请将集合设置、实时查询和乐观变更模式委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s tanstack-db -a claude-code -y 如果有 tanstack-start skill，请将使用服务器函数实现 shape 代理委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s tanstack-start -a claude-code -y

  • 设置和部署：使用 Task Agent 配置 Docker 和 Postgres
  • 架构审查：使用 Plan Agent 设计身份验证代理和写入模式

参考资料

评论

支持 Markdown