electric-deployment

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.

25 stars

byComeOnOliver

View on GitHub Installation ↓

Best use case

electric-deployment is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using electric-deployment should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/electric-deployment/SKILL.md --create-dirs "https://raw.githubusercontent.com/ComeOnOliver/skillshub/main/skills/electric-sql/electric/electric-deployment/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/electric-deployment/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How electric-deployment Compares

Feature / Agent	electric-deployment	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# 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`

### 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.

Related Skills

orchestrating-deployment-pipelines

from ComeOnOliver/skillshub

Deploy use when you need to work with deployment and CI/CD. This skill provides deployment automation and orchestration with comprehensive guidance and automation. Trigger with phrases like "deploy application", "create pipeline", or "automate deployment".

managing-deployment-rollbacks

from ComeOnOliver/skillshub

kubernetes-deployment-creator

from ComeOnOliver/skillshub

Kubernetes Deployment Creator - Auto-activating skill for DevOps Advanced. Triggers on: kubernetes deployment creator, kubernetes deployment creator Part of the DevOps Advanced skill category.

creating-kubernetes-deployments

from ComeOnOliver/skillshub

Deploy applications to Kubernetes with production-ready manifests. Supports Deployments, Services, Ingress, HPA, ConfigMaps, Secrets, StatefulSets, and NetworkPolicies. Includes health checks, resource limits, auto-scaling, and TLS termination. Use when working with creating kubernetes deployments. Trigger with 'creating', 'kubernetes', 'deployments'.

canary-deployment-setup

from ComeOnOliver/skillshub

Canary Deployment Setup - Auto-activating skill for ML Deployment. Triggers on: canary deployment setup, canary deployment setup Part of the ML Deployment skill category.

adk-deployment-specialist

from ComeOnOliver/skillshub

Deploy and orchestrate Vertex AI ADK agents using A2A protocol. Manages AgentCard discovery, task submission, Code Execution Sandbox, and Memory Bank. Use when asked to "deploy ADK agent" or "orchestrate agents". Trigger with phrases like 'deploy', 'infrastructure', or 'CI/CD'.

azure-deployment-preflight

from ComeOnOliver/skillshub

Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision.

electric-yjs

from ComeOnOliver/skillshub

Set up ElectricProvider for real-time collaborative editing with Yjs via Electric shapes. Covers ElectricProvider configuration, document updates shape with BYTEA parser (parseToDecoder), awareness shape at offset='now', LocalStorageResumeStateProvider for reconnection with stableStateVector diff, debounceMs for batching writes, sendUrl PUT endpoint, required Postgres schema (ydoc_update and ydoc_awareness tables), CORS header exposure, and sendErrorRetryHandler. Load when implementing collaborative editing with Yjs and Electric.

electric-shapes

from ComeOnOliver/skillshub

Configure ShapeStream and Shape to sync a Postgres table to the client. Covers ShapeStreamOptions (url, table, where, columns, replica, offset, handle), custom type parsers (timestamptz, jsonb, int8), column mappers (snakeCamelMapper, createColumnMapper), onError retry semantics, backoff options, log modes (full, changes_only), requestSnapshot, fetchSnapshot, subscribe/unsubscribe, and Shape materialized view. Load when setting up sync, configuring shapes, parsing types, or handling sync errors.

electric-schema-shapes

from ComeOnOliver/skillshub

Design Postgres schema and Electric shape definitions together for a new feature. Covers single-table shape constraint, cross-table joins using multiple shapes, WHERE clause design for tenant isolation, column selection for bandwidth optimization, replica mode choice (default vs full for old_value), enum casting in WHERE clauses, and txid handshake setup with pg_current_xact_id() for optimistic writes. Load when designing database tables for use with Electric shapes.

electric-proxy-auth

from ComeOnOliver/skillshub

Set up a server-side proxy to forward Electric shape requests securely. Covers ELECTRIC_PROTOCOL_QUERY_PARAMS forwarding, server-side shape definition (table, where, params), content-encoding/content-length header cleanup, CORS configuration for electric-offset/electric-handle/ electric-schema/electric-cursor headers, auth token injection, ELECTRIC_SECRET/SOURCE_SECRET server-side only, tenant isolation via WHERE positional params, onError 401 token refresh, and subset security (AND semantics). Load when creating proxy routes, adding auth, or configuring CORS for Electric.

electric-postgres-security

from ComeOnOliver/skillshub

Pre-deploy security checklist for Postgres with Electric. Checks REPLICATION role, SELECT grants, CREATE on database, table ownership, REPLICA IDENTITY FULL on all synced tables, publication management (auto vs manual with ELECTRIC_MANUAL_TABLE_PUBLISHING), connection pooler exclusion for DATABASE_URL (use direct connection), and ELECTRIC_POOLED_DATABASE_URL for pooled queries. Load before deploying Electric to production or when diagnosing Postgres permission errors.