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 thelocal-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 -yIf 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 -yIf 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