electric-deployment

Electric — デプロイ

セットアップ

Postgres の設定

# 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

基本パターン

環境変数

変数	必須	説明
DATABASE_URL	はい	Postgres への直接接続（プーラーは使用しない）
ELECTRIC_SECRET	はい（本番）	API 認証シークレット
ELECTRIC_INSECURE	開発のみ	true に設定するとシークレット要件をスキップ
ELECTRIC_STORAGE_DIR	いいえ	永続的なシェイプキャッシュディレクトリ
ELECTRIC_POOLED_DATABASE_URL	いいえ	レプリケーション以外のクエリ用のプール接続
ELECTRIC_DATABASE_USE_IPV6	いいえ	IPv6 の Postgres 接続では true に設定

Kubernetes のヘルスチェック

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

レプリケーションスロットのクリーンアップ

-- 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();

よくある間違い

CRITICAL wal_level を logical に設定しない

誤り：

# postgresql.conf (default)
wal_level = replica

正しい例：

wal_level = logical
max_replication_slots = 10

Electric には論理レプリケーションが必要です。デフォルトの wal_level = replica は論理レプリケーションをサポートしていません。変更後は Postgres の再起動が必要です。

ソース：packages/sync-service/dev/postgres.conf

CRITICAL 本番環境で ELECTRIC_SECRET を設定せずに実行する

誤り：

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

正しい例：

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

v1.x 以降、ELECTRIC_SECRET は必須です。設定されていない場合、ELECTRIC_INSECURE=true（開発環境のみ）が設定されていない限り、Electric は起動を拒否します。

ソース：packages/sync-service/CHANGELOG.md:832-834

MEDIUM ELECTRIC_STORAGE_DIR に一時ストレージを使用する

誤り：

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

正しい例：

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

Electric はシェイプログをディスクにキャッシュします。一時ストレージを使用すると、コンテナーを再起動するたびに全件再同期が発生します。

ソース：website/docs/guides/deployment.md:133-157

HIGH Bun のプロキシは同時 256 件の fetch でボトルネックになる

誤り：

bun run proxy.ts

正しい例：

BUN_CONFIG_MAX_HTTP_REQUESTS=4096 bun run proxy.ts

Bun ランタイムで Electric の前段に認証／キャッシュプロキシをデプロイする場合は、BUN_CONFIG_MAX_HTTP_REQUESTS を想定される同時シェイプリクエスト数に合わせて設定してください。Bun のデフォルト上限である同時 256 件の fetch() 呼び出しを超えるリクエストは、キューに入れられますが、そのことは通知されません。プロキシは応答しているように見えても、Electric への上流呼び出しが滞り、エラーではなく負荷時のレイテンシーとして現れます。最大値は 65,336 です。Node と Deno にはこの上限はありません。

ソース：https://bun.com/docs/runtime/networking/fetch

MEDIUM 非推奨の ELECTRIC_QUERY_DATABASE_URL を使用する

誤り：

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

正しい例：

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

v1.3.x で ELECTRIC_QUERY_DATABASE_URL から ELECTRIC_POOLED_DATABASE_URL に名前が変更されました。旧名は将来のバージョンで使用できなくなる可能性があります。

ソース：packages/sync-service/CHANGELOG.md:415

関連項目：electric-proxy-auth/SKILL.md — 本番環境では ELECTRIC_SECRET を使用するプロキシが必要です。 関連項目：electric-postgres-security/SKILL.md — デプロイには適切な Postgres 設定が必要です。 関連項目：electric-debugging/SKILL.md — 多くの同期の問題はデプロイ設定に起因します。

バージョン

Electric sync service v1.x を対象としています。