electric-deployment

name	electric-deployment
description	Deploy Electric via Docker, Docker Compose, or Electric Cloud. Covers DATABASE_URL (direct connection, not pooler), ELECTRIC_SECRET (required since v1.x), ELECTRIC_INSECURE for dev, wal_level=logical, max_replication_slots, ELECTRIC_STORAGE_DIR persistence, ELECTRIC_POOLED_DATABASE_URL for pooled queries, IPv6 with ELECTRIC_DATABASE_USE_IPV6, Kubernetes readiness probes (200 vs 202), replication slot cleanup, and Postgres v14+ requirements. Load when deploying Electric or configuring Postgres for logical replication.
type	lifecycle
library	electric
library_version	1.5.10
sources	["electric-sql/electric:website/docs/guides/deployment.md","electric-sql/electric:packages/sync-service/dev/postgres.conf","electric-sql/electric:packages/sync-service/CHANGELOG.md"]

Electric — Deployment

Setup

Postgres configuration

# postgresql.conf
wal_level = logical
max_replication_slots = 10

Docker Compose

name: 'electric-backend'
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: electric
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    ports: ['54321:5432']
    volumes: ['./postgres.conf:/etc/postgresql/postgresql.conf:ro']
    tmpfs: ['/var/lib/postgresql/data', '/tmp']
    command: ['postgres', '-c', 'config_file=/etc/postgresql/postgresql.conf']

  electric:
    image: electricsql/electric:latest
    environment:
      DATABASE_URL: postgresql://postgres:password@postgres:5432/electric?sslmode=disable
      ELECTRIC_SECRET: ${ELECTRIC_SECRET}
    ports: ['3000:3000']
    volumes: ['electric_data:/var/lib/electric']
    depends_on: ['postgres']

volumes:
  electric_data:

Electric Cloud

npx @electric-sql/start my-app
pnpm claim && pnpm deploy

Core Patterns

Environment variables

Variable	Required	Description
DATABASE_URL	Yes	Direct Postgres connection (not pooler)
ELECTRIC_SECRET	Yes (prod)	API authentication secret
ELECTRIC_INSECURE	Dev only	Set true to skip secret requirement
ELECTRIC_STORAGE_DIR	No	Persistent shape cache directory
ELECTRIC_POOLED_DATABASE_URL	No	Pooled connection for non-replication queries
ELECTRIC_DATABASE_USE_IPV6	No	Set true for IPv6 Postgres connections

Kubernetes health checks

livenessProbe:
  httpGet:
    path: /v1/health
    port: 3000
readinessProbe:
  exec:
    command: ['curl', '-sf', 'http://localhost:3000/v1/health']
  # Use exec, not httpGet — 202 means "alive but not ready"
  # Only 200 means fully ready for traffic

Replication slot cleanup

-- When stopping Electric for extended periods:
SELECT pg_drop_replication_slot('electric_slot_default');

-- Prevent unbounded WAL growth:
ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';
SELECT pg_reload_conf();

Common Mistakes

CRITICAL Not setting wal_level to logical

Wrong:

# postgresql.conf (default)
wal_level = replica

Correct:

wal_level = logical
max_replication_slots = 10

Electric requires logical replication. The default wal_level = replica does not support it. Requires Postgres restart after change.

Source: packages/sync-service/dev/postgres.conf

CRITICAL Running without ELECTRIC_SECRET in production

Wrong:

docker run electricsql/electric \
  -e DATABASE_URL=postgres://user:pass@host/db

Correct:

docker run electricsql/electric \
  -e DATABASE_URL=postgres://user:pass@host/db \
  -e ELECTRIC_SECRET=my-secret-key

Since v1.x, ELECTRIC_SECRET is required. Without it, Electric refuses to start unless ELECTRIC_INSECURE=true is set (dev only).

Source: packages/sync-service/CHANGELOG.md:832-834

MEDIUM Using ephemeral storage for ELECTRIC_STORAGE_DIR

Wrong:

electric:
  image: electricsql/electric:latest
  # No volume — shape cache lost on restart

Correct:

electric:
  image: electricsql/electric:latest
  volumes: ['electric_data:/var/lib/electric']

Electric caches shape logs on disk. Ephemeral storage causes full re-sync on every container restart.

Source: website/docs/guides/deployment.md:133-157

HIGH Bun proxy bottlenecks at 256 concurrent fetches

Wrong:

bun run proxy.ts

Correct:

BUN_CONFIG_MAX_HTTP_REQUESTS=4096 bun run proxy.ts

When deploying an auth/caching proxy in front of Electric on the Bun runtime, set BUN_CONFIG_MAX_HTTP_REQUESTS to match expected concurrent shape requests. Bun's default cap of 256 simultaneous fetch() calls queues excess requests silently — the proxy appears responsive but upstream calls to Electric stall, surfacing as latency under load rather than errors. Max value is 65,336. Node and Deno do not impose this cap.

Source: https://bun.com/docs/runtime/networking/fetch

MEDIUM Using deprecated ELECTRIC_QUERY_DATABASE_URL

Wrong:

ELECTRIC_QUERY_DATABASE_URL=postgres://user:pass@pooler:6432/db

Correct:

ELECTRIC_POOLED_DATABASE_URL=postgres://user:pass@pooler:6432/db

Renamed from ELECTRIC_QUERY_DATABASE_URL to ELECTRIC_POOLED_DATABASE_URL in v1.3.x. The old name may stop working in future versions.

Source: packages/sync-service/CHANGELOG.md:415

See also: electric-proxy-auth/SKILL.md — Production requires proxy with ELECTRIC_SECRET. See also: electric-postgres-security/SKILL.md — Deployment requires correct Postgres configuration. See also: electric-debugging/SKILL.md — Many sync issues stem from deployment configuration.

Version

Targets Electric sync service v1.x.