alco/electric repository overview

⁠Electric Sync

Electric is an open-source Postgres sync engine. It reads changes from Postgres over logical replication and syncs subsets of your data, called shapes⁠, into local apps and services. Each client subscribes only to the rows it needs (partial replication), and Electric keeps them up to date in real time. Data goes out over plain HTTP, so standard caching proxies and CDNs can fan it out to very large numbers of clients.

Source code: https://github.com/electric-sql/electric⁠

⁠Quickstart

Save this as docker-compose.yaml. It runs Postgres with logical replication turned on, plus Electric, for local development:

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: electric
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    command: ["postgres", "-c", "wal_level=logical"]
    ports:
      - "54321:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  electric:
    image: electricsql/electric
    environment:
      DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable
      ELECTRIC_INSECURE: "true" # local development only
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy

Start it, create a table, and sync it:

docker compose up -d
docker compose exec postgres psql -U postgres -d electric \
  -c "CREATE TABLE items (id serial PRIMARY KEY, name text); INSERT INTO items (name) VALUES ('hello'), ('world');"

curl http://localhost:3000/v1/health
curl "http://localhost:3000/v1/shape?table=items&offset=-1"

Using your own Postgres? Point DATABASE_URL at it instead. It must have wal_level = logical, and the user needs the REPLICATION attribute. If Postgres runs on the same machine as Docker, use host.docker.internal as the hostname. On Linux without Docker Desktop, that name only exists if you add --add-host=host.docker.internal:host-gateway (or extra_hosts: ["host.docker.internal:host-gateway"] in Compose). Postgres must also listen on the Docker bridge interface (listen_addresses) and allow that subnet in pg_hba.conf.

Full walkthrough: Quickstart⁠

⁠Running with a secret and persistent storage

For any deployment beyond your laptop, set ELECTRIC_SECRET and put Electric's storage on a volume:

docker volume create electric_data

docker run -d --name electric --restart unless-stopped -p 3000:3000 \
  -e DATABASE_URL="postgresql://electric:[email protected]:5432/mydb" \
  -e ELECTRIC_SECRET="<long random string>" \
  -e ELECTRIC_STORAGE_DIR=/var/lib/electric \
  -v electric_data:/var/lib/electric \
  electricsql/electric:1.8.1

• The secret. Every request must include ?secret=<ELECTRIC_SECRET>. Add it in your backend or authorizing proxy⁠; never send it from browsers or apps.
• Storage. Electric keeps shape logs and metadata on disk. That data must survive container restarts and re-creation. Without a volume it lives inside the container and disappears when the container is removed, even though the instance looked healthy. The data on disk and the replication slot in Postgres must stay in sync: if you wipe one, clean up the other (details⁠).

⁠Configuration

Electric is configured with environment variables. The most important ones:

* Required unless ELECTRIC_INSECURE=true.

All options: Configuration reference⁠

⁠Production notes

• Postgres 14+, with logical replication enabled⁠ (wal_level = logical).
• Connect as a role with the REPLICATION attribute (permissions guide⁠).
• Use persistent storage for ELECTRIC_STORAGE_DIR, ideally fast local SSD.
• Protect the API: set ELECTRIC_SECRET and put an authorizing proxy in front of Electric (security guide⁠).
• Health check: GET /v1/health needs no authentication and suits liveness and readiness probes. The image has a built-in HEALTHCHECK.
• At scale, run Electric behind a caching proxy or CDN⁠.

Full guide: Deployment⁠

⁠Tags

Images are published for linux/amd64 and linux/arm64. Release notes: GitHub Releases⁠. Before upgrading, read the upgrading guide⁠.

⁠Links

• Documentation: https://electric.ax/docs/sync⁠
• Source code: https://github.com/electric-sql/electric⁠
• Issues: https://github.com/electric-sql/electric/issues⁠
• Security policy: https://github.com/electric-sql/electric/blob/main/SECURITY.md⁠
• Community: Discord⁠

⁠License

Apache-2.0. See LICENSE⁠.