@electric-sql/client 1.5.11 → 1.5.12

package/bin/intent.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.mjs" }
+await import(`@tanstack/intent/intent-library`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@electric-sql/client",
   "description": "Postgres everywhere - your data, in sync, wherever you need it.",
-  "version": "1.5.11",
+  "version": "1.5.12",
   "author": "ElectricSQL team and contributors.",
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"
@@ -10,6 +10,7 @@
     "@microsoft/fetch-event-source": "^2.0.1"
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.0.9",
     "@types/pg": "^8.11.6",
     "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^7.14.1",
@@ -45,9 +46,15 @@
       }
     }
   },
+  "bin": {
+    "intent": "./bin/intent.mjs"
+  },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "homepage": "https://electric-sql.com",
   "license": "Apache-2.0",

package/skills/electric-debugging/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: electric-debugging
+description: >
+  Troubleshoot Electric sync issues. Covers fast-loop detection from CDN/proxy
+  cache key misconfiguration, stale cache diagnosis (StaleCacheError),
+  MissingHeadersError from CORS misconfiguration, 409 shape expired handling,
+  SSE proxy buffering (nginx proxy_buffering off, Caddy flush_interval -1),
+  HTTP/1.1 6-connection limit in local dev (Caddy HTTP/2 proxy), WAL growth
+  from replication slots (max_slot_wal_keep_size), Vercel CDN cache issues,
+  and onError/backoff behavior. Load when shapes are not receiving updates,
+  sync is slow, or errors appear in the console.
+type: lifecycle
+library: electric
+library_version: '1.5.10'
+requires:
+  - electric-shapes
+  - electric-proxy-auth
+sources:
+  - 'electric-sql/electric:packages/typescript-client/src/client.ts'
+  - 'electric-sql/electric:packages/typescript-client/src/fetch.ts'
+  - 'electric-sql/electric:packages/typescript-client/src/error.ts'
+  - 'electric-sql/electric:website/docs/guides/troubleshooting.md'
+---
+
+This skill builds on electric-shapes and electric-proxy-auth. Read those first.
+
+# Electric — Debugging Sync Issues
+
+## Setup
+
+Enable debug logging to see retry and state machine behavior:
+
+```ts
+import { ShapeStream, FetchError } from '@electric-sql/client'
+
+const stream = new ShapeStream({
+  url: '/api/todos',
+  backoffOptions: {
+    initialDelay: 1000,
+    maxDelay: 32000,
+    multiplier: 2,
+    debug: true, // Logs retry attempts
+  },
+  onError: (error) => {
+    if (error instanceof FetchError) {
+      console.error(`Sync error: ${error.status} at ${error.url}`, error.json)
+    }
+    return {} // Always return {} to retry
+  },
+})
+```
+
+## Core Patterns
+
+### Error retry behavior
+
+| Error                 | Auto-retry?                | Action                                                        |
+| --------------------- | -------------------------- | ------------------------------------------------------------- |
+| 5xx server errors     | Yes (exponential backoff)  | Wait and retry                                                |
+| 429 rate limit        | Yes (respects Retry-After) | Wait and retry                                                |
+| Network errors        | Yes (exponential backoff)  | Wait and retry                                                |
+| 4xx (non-429)         | No                         | Calls `onError` — return `{}` to retry manually               |
+| 409 shape expired     | Yes (automatic reset)      | Client resets and refetches                                   |
+| `MissingHeadersError` | Never                      | Fix CORS/proxy — not retryable even if `onError` returns `{}` |
+
+### Diagnosing MissingHeadersError
+
+This error means Electric response headers (`electric-offset`, `electric-handle`) are being stripped, usually by CORS:
+
+```
+MissingHeadersError: This is often due to a proxy not setting CORS correctly
+so that all Electric headers can be read by the client.
+```
+
+Fix: expose Electric headers in proxy CORS configuration:
+
+```ts
+headers.set(
+  'Access-Control-Expose-Headers',
+  'electric-offset, electric-handle, electric-schema, electric-cursor'
+)
+```
+
+### Diagnosing fast-loop detection
+
+Console message: "Detected possible fast loop" with diagnostic info.
+
+Cause: proxy/CDN cache key doesn't include `handle` and `offset` query params, so the client gets the same stale response repeatedly.
+
+Fix: ensure your proxy/CDN includes all query parameters in its cache key.
+
+For Vercel, add to `vercel.json`:
+
+```json
+{
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "CDN-Cache-Control", "value": "no-store" },
+        { "key": "Vercel-CDN-Cache-Control", "value": "no-store" }
+      ]
+    }
+  ]
+}
+```
+
+## Common Mistakes
+
+### HIGH Proxy or CDN not including query params in cache key
+
+Wrong:
+
+```nginx
+# nginx caching without query params in key
+proxy_cache_key $scheme$host$uri;
+```
+
+Correct:
+
+```nginx
+# Include query params (handle, offset) in cache key
+proxy_cache_key $scheme$host$request_uri;
+```
+
+Fast-loop detection fires after 5 requests in 500ms at the same offset. The client auto-clears caches once, then applies backoff, then throws after 5 consecutive detections.
+
+Source: `packages/typescript-client/src/client.ts:929-1002`
+
+### HIGH SSE responses buffered by proxy
+
+Wrong:
+
+```nginx
+location /v1/shape {
+  proxy_pass http://electric:3000;
+  # Default: proxy_buffering on — SSE responses delayed
+}
+```
+
+Correct:
+
+```nginx
+location /v1/shape {
+  proxy_pass http://electric:3000;
+  proxy_buffering off;
+}
+```
+
+For Caddy:
+
+```
+reverse_proxy localhost:3000 {
+  flush_interval -1
+}
+```
+
+Nginx and Caddy buffer responses by default, causing long delays for SSE live updates. Disable buffering for Electric endpoints. Do NOT disable caching entirely — Electric uses cache headers for request collapsing.
+
+Source: `website/docs/guides/troubleshooting.md:69-109`
+
+### MEDIUM Running 6+ shapes in local dev without HTTP/2
+
+Wrong:
+
+```sh
+# Running Electric directly on localhost:3000
+# With 7+ shapes, browser HTTP/1.1 queues all requests (6 connection limit)
+```
+
+Correct:
+
+```sh
+# Run Caddy as HTTP/2 proxy on host (not in Docker — Docker prevents HTTP/2)
+caddy run --config - --adapter caddyfile <<EOF
+localhost:3001 {
+  reverse_proxy localhost:3000
+}
+EOF
+```
+
+Browser HTTP/1.1 limits to 6 TCP connections per origin. With many shapes, requests queue behind each other. Use Caddy as a local HTTP/2 proxy.
+
+Source: `website/docs/guides/troubleshooting.md:28-53`
+
+### HIGH Leaving replication slot active when Electric is stopped
+
+Wrong:
+
+```sh
+docker stop electric
+# Replication slot retains WAL indefinitely — disk fills up
+```
+
+Correct:
+
+```sh
+docker stop electric
+
+# Drop slot when stopping for extended periods
+psql -c "SELECT pg_drop_replication_slot('electric_slot_default');"
+
+# Or set a safety limit
+psql -c "ALTER SYSTEM SET max_slot_wal_keep_size = '10GB';"
+psql -c "SELECT pg_reload_conf();"
+```
+
+Replication slots retain WAL indefinitely when Electric is disconnected. Postgres disk fills up. Either drop the slot or set `max_slot_wal_keep_size`.
+
+Source: `website/docs/guides/troubleshooting.md:203-316`
+
+See also: electric-deployment/SKILL.md — Many sync issues stem from deployment configuration.
+See also: electric-shapes/SKILL.md — onError semantics and backoff behavior.
+
+## Version
+
+Targets @electric-sql/client v1.5.10.

package/skills/electric-deployment/SKILL.md

@@ -0,0 +1,196 @@
+---
+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
+
+```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.