К основному содержанию
скилл CX Codex

electricsql — скилл для Claude Code: что делает и как установить

Скилл для ИИ-кодинга по ElectricSQL: как стримить строки Postgres в клиент через Shapes, фильтровать их и не пускать запись мимо своего API.

MIT 109 установок ★ 29 обновлён 2026-08-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add oakoss/agent-skills --skill electricsql -a claude-code
Открыть на GitHub

Что делает electricsql

Скилл разбирает ElectricSQL — движок, который стримит клиенту частичную реплику таблиц Postgres через Shapes. Внутри справочник по ShapeStream и Shape, хуку useShape для React, фильтрам where и выбору колонок, чтобы не гнать в браузер лишние поля. В references/ лежат отдельные файлы про Docker и настройку Postgres, auth-прокси, схемы записи, обработку ошибок и скорость синхронизации.

Чтение и запись разделены: Electric тянет строки из Postgres в реальном времени, а запись идёт через ваш API, и подтверждённое состояние возвращается всем подключённым клиентам. Отсюда разбор txid, который обработчик записи обязан вернуть, и прогрессивных стратегий от online-only до записи через базу.

Заранее понадобится wal_level=logical в конфиге Postgres: без него Electric не запустится. В продакшене нужен ELECTRIC_SECRET, для разработки хватит ELECTRIC_INSECURE=true. Открывать Electric прямо в интернет скилл не велит — shapes пропускают через прокси, который проверяет токен и подставляет where под пользователя.

Какие задачи решает

  • Поднять Electric в Docker и включить логическую репликацию в Postgres
  • Собрать поток через ShapeStream с фильтром where и нужными колонками
  • Написать auth-прокси, который подставляет where под конкретного пользователя
  • Вернуть txid из обработчика записи, чтобы клиент увидел подтверждение
  • Выбрать стратегию записи для local-first приложения

Примеры запросов агенту

  • Настрой ElectricSQL на Postgres с wal_level=logical и запусти его в Docker
  • Сделай useShape для таблицы items с фильтром status='active' и колонками id,title
  • Напиши auth-прокси, который добавляет where по user_id перед запросом shape

Как установить electricsql

1Через Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill electricsql -a claude-code

2Вручную: положить файлы

~/.claude/skills/electricsql/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/electricsql/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об electricsql

Как установить electricsql в Claude Code?

Выполните npx skills add oakoss/agent-skills --skill electricsql -a claude-code. Скилл окажется в ~/.claude/skills/electricsql/SKILL.md.

Что делает electricsql?

Описывает для агента работу с ElectricSQL: частичную реплику Postgres через Shapes, API ShapeStream, хук useShape, фильтрацию по where, auth-прокси и стратегии записи.

Можно ли писать в Postgres через Electric?

Нет, движок отвечает только за чтение. Запись идёт через ваш API, а подтверждённое состояние Electric раздаёт клиентам; для этого обработчик записи возвращает txid.

Исходный текст

SKILL.md · MIT
---
name: electricsql
description: |
  ElectricSQL real-time Postgres sync engine using Shapes for partial replication. Covers ShapeStream API, React hooks, where clause filtering, column selection, auth proxy patterns, and progressive write strategies from online-only to through-the-database.

  Use when setting up ElectricSQL, configuring Postgres sync, implementing shape-based data loading, building auth proxies for shapes, or choosing write patterns for local-first apps with Electric.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://electric-sql.com/docs'
user-invocable: false
---

# 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](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)

© oakoss · MIT · oakoss/agent-skills

Похожие скиллы

Все скиллы по теме «Данные и базы» →
neon-realtime neondatabase Скилл neon-realtime для Claude Code превращает SQL-запросы в живые подписки на изменения строк Lakebase Postgres. Передаёт изменения батчами для дашбордов, лент и синхронизации между устройствами. CX Codex +1 24 200установок diagnosing-failed-warehouse-syncs PostHog Скилл diagnosing-failed-warehouse-syncs для Claude Code разбирает сбои синхронизации хранилища данных и подбирает действие для восстановления. Запускается по запросу о зависшей таблице, ошибке источника или неверных данных. CX Codex +1 401установок supabase-skills fcakyon Добавляет в ассистент набор навыков для работы с базой данных Postgres, аутентификацией, Edge Functions и утилитой командной строки Supabase. CX Codex ★ 1 216звёзд репо performance-profiler OneWave-AI Скилл performance-profiler для Claude Code находит узкие места в сети, рендеринге, памяти и вычислениях. Разбирает медленные приложения и утечки памяти. CX Codex +1 333установок Instant docker MCP-сервер Instant от docker к базе, устроенной как Firebase: синхронизация в реальном времени и приложения, которые работают без сети. CX Codex +1 python-fastapi-scalable-api-cursorrules-prompt-fil PatrickJS Правило python-fastapi-scalable-api-cursorrules-prompt-fil для Cursor задаёт стиль разработки масштабируемых API на FastAPI и интерфейсов на React. Оно применяется к файлам по маске **/*. CX Codex +1 ★ 41 178звёзд репо

Из того же набора106

Весь набор →
tanstack-store Объясняет агенту устройство TanStack Store: стор, производные значения, батчи и эффекты. Описывает общее состояние нескольких компонентов. CX Codex +1 113установок hono Скилл по веб-фреймворку Hono для создания API и edge-функций на Cloudflare Workers, Bun, Deno и Node.js. CX Codex +1 112установок astro Скилл Claude Code объясняет агенту Astro: коллекции контента, островную гидратацию, view transitions и режимы рендеринга. Описывает статичные сайты с вкраплениями интерактива. CX Codex +1 111установок db-enforcer Скилл db-enforcer для Claude Code проверяет целостность PostgreSQL-схем и согласованность с Prisma. Включается при проектировании схем, подготовке миграций и настройке RLS. CX Codex +1 109установок trpc trpc — скилл для Claude Code, который помогает строить типобезопасные API на TypeScript с tRPC v11. Он подключается к задачам с роутерами, процедурами, React-клиентом и тестами. CX Codex +1 109установок tauri Помогает собирать приложения на Tauri v2 с веб-интерфейсом и бэкендом на Rust. Подключается при настройке проекта, IPC, разрешений или выпуска приложения. CX Codex +1 108установок turborepo Помогает настраивать Turborepo в монорепозиториях на JavaScript и TypeScript. Запускается при настройке задач, кэша, зависимостей между пакетами и CI. CX Codex +1 108установок realtime-sync Скилл realtime-sync помогает проектировать синхронизацию данных с низкой задержкой, связывать WebTransport, CRDT и пакетный рендеринг потоков ИИ-токенов. CX Codex +1 108установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой