Electric

Positioning#

Electric is a real-time sync engine focused on the Postgres read path. It is not a database proxy or ORM, but a middleware engine that syncs cloud Postgres data to local clients (browsers, edge nodes, mobile) with low latency and high scalability via the Shape primitive. It only handles unidirectional Postgres → client sync and does not manage the write path.

Core Sync Capabilities#

• Shape Primitive: Defines a sync data subset via table + optional WHERE + optional columns. Shape definitions are immutable—adjusting filters requires creating a new Shape—which ensures Shape Log determinism and CDN cacheability.
• Partial Replication & Fan-out: Built-in solutions for partial replication, fan-out, and data delivery challenges.
• Progressive Data Loading: Supports changes-only mode and on-demand subset snapshots, compatible with pagination, search, and filtering.
• Subquery Tracking: Cross-table dependency tracking that auto-adjusts Shape content when referenced table data changes (experimental, requires feature flags).
• High-Throughput Storage Engine: Custom storage engine optimized for batch WHERE clause evaluation, achieving ~5,000 row changes/sec sustained throughput.

Protocol & Distribution#

• Low-level HTTP API (GET /v1/shape), natively compatible with CDN caching and large-scale fan-out.
• OpenAPI specification provided for code generation and integration.
• live=true parameter enables long-polling for continuous Shape Log entry streaming.

Client Integrations#

• TypeScript Client (@electric-sql/client): ShapeStream / Shape programming interfaces.
• React Integration (@electric-sql/react): useShape hook.
• Elixir Client: Official Elixir client library.
• TanStack DB Integration: Connects Shape data to the TanStack ecosystem.
• PGlite Integration: Works with PGlite (embeddable Postgres) for full browser/edge local storage.

Architecture#

Server built on Elixir/Phoenix, captures changes via Postgres logical replication, batch-evaluates through a custom storage engine, and distributes Shape Logs via HTTP API. Monorepo managed with pnpm workspace; key packages include packages/sync-service (Elixir server), packages/typescript-client, packages/elixir-client.

Quick Start#

# Docker Compose (requires Postgres with logical replication enabled)
docker compose -f .support/docker-compose.yml up

# Verify HTTP API
curl -i 'http://localhost:3000/v1/shape?table=foo&offset=-1'

# Install clients
npm i @electric-sql/client
npm i @electric-sql/react

Key Environment Variables: DATABASE_URL (Postgres connection string), ELECTRIC_LIVE_DASHBOARD_PORT (enable monitoring dashboard), ELECTRIC_FEATURE_FLAGS (e.g., allow_subqueries,tagged_subqueries).

Use Cases#

• Local-first Apps: Build Figma/Linear-like responsive experiences.
• AI Agent State Persistence: Provide real-time local data persistence for multi-agent systems.
• Real-time Collaboration: Multi-client data sharing via Shape subscriptions.
• Offline/Weak Network: Local cache + real-time incremental sync.
• CDN-accelerated Large-scale Data Fan-out.

Ecosystem#

Unconfirmed Information#

• Latest stable version (GitHub Releases shows electric-ax@0.1.17, possibly Cloud package version)
• Electric Cloud hosted plan pricing and SLA
• v1 vs. old Electric (with include tree) migration path and compatibility
• CRDT support details (repo topics list crdt but docs don't detail implementation)
• Official recommended write-path conflict resolution approach