# Electric SQL — Sync Engine for Postgres and Local-First Apps

> An open-source sync layer that streams Postgres data to local apps and agents in real time, enabling offline-capable and instant-loading user experiences.

## Install

Save as a script file and run:

# Electric SQL — Sync Engine for Postgres and Local-First Apps

## Quick Use
```bash
# Install the Electric sync service
npm install @electric-sql/client
# Or run the sync service via Docker
docker run -e DATABASE_URL=postgresql://user:pass@host/db 
  -p 3000:3000 electricsql/electric

# Subscribe to a Postgres table from the client
import { ShapeStream } from '@electric-sql/client'
const stream = new ShapeStream({
  url: 'http://localhost:3000/v1/shape',
  params: { table: 'items' }
})
```

## Introduction
Electric SQL is an open-source Postgres sync engine that brings real-time data streaming to local-first applications and AI agent runtimes. Instead of polling or building custom replication, developers subscribe to shapes of Postgres data that automatically sync to clients, enabling offline-capable apps with instant reads.

## What Electric SQL Does
- Streams partial or full Postgres table data to client applications in real time
- Supports shape-based subscriptions to sync only the rows and columns you need
- Enables local-first architectures where reads happen from a local cache
- Provides a simple HTTP API that works with any programming language or framework
- Handles conflict resolution and consistency for bidirectional sync scenarios

## Architecture Overview
Electric runs as a sidecar service next to your Postgres database. It reads the Postgres write-ahead log (WAL) to detect changes, then serves those changes over HTTP as shape streams. Clients connect to the Electric HTTP endpoint and receive an initial snapshot followed by a continuous stream of incremental updates. The system uses logical replication internally and manages shape definitions, caching, and delivery. No changes to your Postgres schema are required.

## Self-Hosting & Configuration
- Deploy as a single Docker container alongside your existing Postgres instance
- Requires Postgres 14+ with logical replication enabled (wal_level=logical)
- Configure via environment variables: DATABASE_URL, ELECTRIC_PORT, and shape definitions
- Supports horizontal scaling by running multiple Electric instances behind a load balancer
- Use the TypeScript, Elixir, or HTTP client libraries to consume shape streams

## Key Features
- Sub-second sync latency from Postgres write to client delivery
- Shape-based subscriptions let you sync exactly the data each client needs
- Zero schema changes required — works with any existing Postgres database
- Built-in caching layer reduces load on the source database
- Framework-agnostic HTTP API with official TypeScript and React integrations

## Comparison with Similar Tools
- **Supabase Realtime** — tied to the Supabase platform; Electric works with any Postgres instance
- **Hasura Subscriptions** — GraphQL-based; Electric provides a simpler shape-based HTTP model
- **PowerSync** — commercial local-first sync; Electric is fully open-source
- **CRDTs / Yjs** — conflict-free data types for collaboration; Electric syncs Postgres state rather than operation-based documents
- **Debezium** — CDC for event streaming; Electric is optimized for client-facing sync rather than backend pipelines

## FAQ
**Q: Does Electric replace my existing backend API?**
A: No. Electric handles data sync from Postgres to clients. You still use your backend for writes, authentication, and business logic.

**Q: Can I use Electric with an existing Postgres database?**
A: Yes. Electric reads the WAL and requires no schema modifications. Enable logical replication and point Electric at your database URL.

**Q: How does Electric handle large tables?**
A: Shape subscriptions let you sync subsets of tables using WHERE clauses. Electric only streams the matching rows, keeping payloads small.

**Q: Is there support for offline-first mobile apps?**
A: Yes. The client library caches synced data locally so reads work offline. When connectivity returns, the stream resumes from the last known position.

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

---
Source: https://tokrepo.com/en/workflows/asset-4bcb8c05
Author: Script Depot