Installation
npx skills add oakoss/agent-skills --skill electricsql 41
Installs
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
Installs
Security Audit
View Source
oakoss/agent-skills
More from this source
EU-Hosted Inference API Power your AI Agents with
the best open-source models.
Drop-in OpenAI-compatible API. No data leaves Europe.
Explore Inference APIGLM
GLM 5
$1.00 / $3.20
per M tokens
Kimi
Kimi K2.5
$0.60 / $2.80
per M tokens
MiniMax
MiniMax M2.5
$0.30 / $1.20
per M tokens
Qwen
Qwen3.5 122B
$0.40 / $3.00
per M tokens
How to use this skill
Install electricsql by running npx skills add oakoss/agent-skills --skill electricsql in your project directory. Run the install command above in your project directory. The skill file will be downloaded from GitHub and placed in your project.
No configuration needed. Your AI agent (Claude Code, Cursor, Windsurf, etc.) automatically detects installed skills and uses them as context when generating code.
The skill enhances your agent's understanding of electricsql, helping it follow established patterns, avoid common mistakes, and produce production-ready output.
What you get
Skills are plain-text instruction files — not executable code. They encode expert knowledge about frameworks, languages, or tools that your AI agent reads to improve its output. This means zero runtime overhead, no dependency conflicts, and full transparency: you can read and review every instruction before installing.
Compatibility
This skill works with any AI coding agent that supports the skills.sh format, including Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider, and other tools that read project-level context files. Skills are framework-agnostic at the transport level — the content inside determines which language or framework it applies to.
Made in Europe Chat with 100+ AI Models in one App.
Use Claude, ChatGPT, Gemini alongside with EU-Hosted Models like Deepseek, GLM-5, Kimi K2.5 and many more.
