electric-deployment

# Electric — Deployment ## Setup ### Postgres configuration ```conf # postgresql.conf wal_level = logical max_replication_slots = 10 ``` ### Docker Compose ```yaml 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 ```sh 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 ```yaml 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 ```sql -- 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: ```conf # postgresql.conf (default) wal_level = replica ``` Correct: ```conf 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: ```sh docker run electricsql/electric \ -e DATABASE_URL=postgres://user:pass@host/db ``` Correct: ```sh 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: ```yaml electric: image: electricsql/electric:latest # No volume — shape cache lost on restart ``` Correct: ```yaml 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: ```sh bun run proxy.ts ``` Correct: ```sh 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: ```sh ELECTRIC_QUERY_DATABASE_URL=postgres://user:pass@pooler:6432/db ``` Correct: ```sh 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.