# Electric — Postgres Sync Engine for Local-First Apps

> A sync engine that streams data from Postgres into local apps, browsers, and edge services in real time, enabling local-first architectures with partial replication and CDN-friendly delivery.

## Install

Save in your project root:

# Electric — Postgres Sync Engine for Local-First Apps

## Quick Use
```bash
# Run Electric sync service alongside your Postgres
docker run -e DATABASE_URL=postgresql://user:pass@host/db 
  -p 3000:3000 electricsql/electric

# Client-side: fetch a Shape (subset of data)
curl "http://localhost:3000/v1/shape?table=items&where=status=active"
```

## Introduction
Electric is a Postgres sync engine that streams real-time data changes from your database into client applications. It uses a concept called Shapes to define partial replicas of your data, and delivers them through an HTTP API designed to work with CDNs for scalable fan-out.

## What Electric Does
- Streams real-time change data from Postgres tables to any HTTP client
- Supports partial replication using Shapes that filter by table, columns, and where clauses
- Delivers data over a simple HTTP API compatible with CDNs and edge caching
- Provides client libraries for React, TypeScript, and Elixir with reactive data hooks
- Maintains causal consistency guarantees for synced data subsets

## Architecture Overview
Electric connects to Postgres via logical replication and consumes the WAL (write-ahead log) to track data changes. It maintains an internal shape log that partitions changes by shape definition. Clients subscribe to shapes over HTTP using long-polling or streaming responses. The HTTP protocol is designed so that CDNs can cache and serve shape responses, reducing load on the Electric service for high fan-out scenarios.

## Self-Hosting & Configuration
- Deploy Electric as a Docker container or standalone binary alongside your Postgres instance
- Set the `DATABASE_URL` environment variable pointing to your Postgres database
- Enable logical replication on your Postgres (`wal_level = logical`)
- Define shapes via query parameters on the HTTP API (`table`, `columns`, `where`)
- Place a CDN in front of the Electric HTTP endpoint for production-scale delivery

## Key Features
- Shape-based sync: clients subscribe to exactly the data subset they need
- CDN-compatible: HTTP responses use standard cache headers for edge delivery
- Framework integrations: `useShape()` hooks for React and helpers for other frameworks
- Incremental sync: clients receive only the changes since their last sync offset
- No vendor lock-in: uses standard Postgres logical replication with no database extensions required

## Comparison with Similar Tools
- **Supabase Realtime** — WebSocket-based change notifications; Electric provides full data sync with offline support
- **Firebase** — proprietary real-time database; Electric syncs from your own Postgres
- **PowerSync** — Postgres sync to SQLite; Electric syncs to any client without requiring SQLite
- **Liveblocks** — real-time collaboration primitives; Electric is a general-purpose data sync layer
- **Debezium** — CDC pipeline for backend services; Electric is optimized for client-facing partial replication

## FAQ
**Q: Does Electric require changes to my Postgres schema?**
A: No. Electric reads from standard Postgres tables via logical replication. No extensions, triggers, or schema modifications are needed.

**Q: Can clients work offline?**
A: Yes. Client libraries cache synced shapes locally. When the connection resumes, Electric sends only the changes that occurred while offline.

**Q: How does Electric handle write conflicts?**
A: Electric is a read-path sync engine. Writes go directly to Postgres through your application API. If you need conflict resolution for offline writes, you implement that logic in your application layer.

**Q: What scale can Electric handle?**
A: The HTTP/CDN architecture allows horizontal fan-out to many clients. A single Electric instance handles the Postgres connection, while CDN edges serve cached shape responses.

## Sources
- https://github.com/electric-sql/electric
- https://electric-sql.com/docs

---
Source: https://tokrepo.com/en/workflows/asset-037c28d3
Author: AI Open Source