electricsql

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&params[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-first skill 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 the tanstack-db skill 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 the tanstack-start skill 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 Task agent for Docker and Postgres configuration
• Architecture review: Use Plan agent for auth proxy and write pattern design

References

• Setup, Docker, and Postgres configuration
• Shapes, ShapeStream, and React hooks
• Authentication and security patterns
• Write patterns from online to through-the-DB
• Observability and monitoring
• Sync performance optimization
• Error handling, retry patterns, txid flow, and control messages