SKILL.md
ElectricSQL
Overview
ElectricSQL is a sync engine that streams partial replicas of Postgres data to local clients via Shapes. It handles the read path — syncing rows from Postgres to the client in real-time using logical replication. Writes flow back through your existing API; Electric syncs the confirmed state back to all connected clients.
When to use: Real-time sync from Postgres to client apps, local-first architectures needing live data from Postgres, replacing polling with streaming updates, apps using TanStack DB with Electric collections, multi-client collaborative apps backed by Postgres.
When NOT to use: Non-Postgres databases, apps needing client-to-server sync built into the engine (Electric handles reads only), simple REST CRUD with no real-time needs, apps that don't benefit from local data.
Quick Reference
| Pattern | API / Approach | Key Points |
|---|---|---|
| Shape request | GET /v1/shape?table=items&offset=-1 |
Initial sync fetches full snapshot |
| Live updates | ?live=true&handle=...&offset=... |
Long-poll for real-time changes after initial sync |
| SSE streaming | ?live=true&live_sse=true |
Persistent Server-Sent Events connection |
| Where clause | ?where=status='active' |
SQL-style row filtering at the server |
| Parameterized where | ?where=user_id=$1¶ms[1]=abc |
SQL injection safe parameterized filtering |
| Column selection | ?columns=id,title,status |
Sync only needed columns to reduce bandwidth |
| Full replica | ?replica=full |
Complete row data on updates and deletes |
| Changes only | ?log=changes_only |
Skip initial snapshot, receive only new changes |
| ShapeStream (JS) | new ShapeStream({ url, params: { table } }) |
Low-level streaming client with auto-reconnect |
| Shape (JS) | new Shape(stream) |
Materializes stream into a Map of current values |
| useShape (React) | useShape({ url, params: { table } }) |
React hook with loading/error states |
| Auth proxy | Route shapes through your API server | Validate tokens, inject where clauses per user |
| Docker setup | docker run -e DATABASE_URL=... electricsql/electric |
Single container, needs wal_level=logical |
| Electric secret | ELECTRIC_SECRET=key env var |
Required for production; ELECTRIC_INSECURE=true for dev |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Exposing Electric directly to the internet | Put Electric behind an auth proxy that validates tokens |
Forgetting wal_level=logical in Postgres config |
Required for logical replication; Electric will not start without it |
| Using Electric for writes | Electric is read-path only; writes go through your API |
Not returning txid from write handlers |
Return { txid } so Electric can confirm sync completion |
| Syncing entire tables to every client | Use where clauses and column selection for partial replication |
| Hardcoding shape URL in client code | Use a proxy endpoint that adds auth and where clauses server-side |
Using offset=-1 for every request |
Use offset=-1 only for initial sync; use returned offset after |
Not handling FetchError 401 in ShapeStream |
Use onError callback to refresh tokens and retry |
Delegation
If the
local-firstskill is available, delegate architecture decisions and sync engine comparison to it.
Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y
If thetanstack-dbskill is available, delegate collection setup, live queries, and optimistic mutation patterns to it.
Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s tanstack-db -a claude-code -y
If thetanstack-startskill is available, delegate shape proxy implementation with server functions to it.
Otherwise, recommend:pnpm dlx skills add oakoss/agent-skills -s tanstack-start -a claude-code -y
- Setup and deployment: Use
Taskagent for Docker and Postgres configuration - Architecture review: Use
Planagent for auth proxy and write pattern design
References
- [Setup, Docker, and Postgres configuration](references/setup.md)
- [Shapes, ShapeStream, and React hooks](references/shapes-and-streams.md)
- [Authentication and security patterns](references/auth-and-security.md)
- [Write patterns from online to through-the-DB](references/write-patterns.md)
- [Observability and monitoring](references/monitoring.md)
- [Sync performance optimization](references/sync-performance.md)
- [Error handling, retry patterns, txid flow, and control messages](references/error-handling.md)