electric-sql Electric — Shape Streaming
Setup
import { ShapeStream, Shape } from '@electric-sql/client'
const stream = new ShapeStream({
url: '/api/todos', // Your proxy route, NOT direct Electric URL
// Built-in parsers auto-handle: bool, int2, int4, float4, float8, json, jsonb
// Add custom parsers for other types (see references/type-parsers.md)
parser: {
timestamptz: (date: string) => new Date(date),
},
})
const shape = new Shape(stream)
shape.subscribe(({ rows }) => {
console.log('synced rows:', rows)
})
// Wait for initial sync
const rows = await shape.rows
Core Patterns
Filter rows with WHERE clause and positional params
const stream = new ShapeStream({
url: '/api/todos',
params: {
table: 'todos',
where: 'user_id = $1 AND status = $2',
params: { '1': userId, '2': 'active' },
},
})
Select specific columns (must include primary key)
const stream = new ShapeStream({
url: '/api/todos',
params: {
table: 'todos',
columns: ['id', 'title', 'status'], // PK required
},
})
Map column names between snake_case and camelCase
import { ShapeStream, snakeCamelMapper } from '@electric-sql/client'
const stream = new ShapeStream({
url: '/api/todos',
columnMapper: snakeCamelMapper(),
})
// DB column "created_at" arrives as "createdAt" in client
// WHERE clauses auto-translate: "createdAt" → "created_at"
Handle errors with retry
const stream = new ShapeStream({
url: '/api/todos',
onError: (error) => {
console.error('sync error', error)
return {} // Return {} to retry; returning void stops the stream
},
})
For auth token refresh on 401 errors, see electric-proxy-auth/SKILL.md.
Resume from stored offset
const stream = new ShapeStream({
url: '/api/todos',
offset: storedOffset, // Both offset AND handle required
handle: storedHandle,
})
Get replica with old values on update
const stream = new ShapeStream({
url: '/api/todos',
params: {
table: 'todos',
replica: 'full', // Sends unchanged columns + old_value on updates
},
})
Common Mistakes
CRITICAL Returning void from onError stops sync permanently
Wrong:
const stream = new ShapeStream({
url: '/api/todos',
onError: (error) => {
console.error('sync error', error)
// Returning nothing = stream stops forever
},
})
Correct:
const stream = new ShapeStream({
url: '/api/todos',
onError: (error) => {
console.error('sync error', error)
return {} // Return {} to retry
},
})
onError returning undefined signals the stream to permanently stop. Return at least {} to retry, or return { headers, params } to retry with updated values.
Source: packages/typescript-client/src/client.ts:409-418
HIGH Using columns without including primary key
Wrong:
const stream = new ShapeStream({
url: '/api/todos',
params: {
table: 'todos',
columns: ['title', 'status'],
},
})
Correct:
const stream = new ShapeStream({
url: '/api/todos',
params: {
table: 'todos',
columns: ['id', 'title', 'status'],
},
})
Server returns 400 error. The columns list must always include the primary key column(s).
Source: website/docs/guides/shapes.md
HIGH Setting offset without handle for resumption
Wrong:
new ShapeStream({
url: '/api/todos',
offset: storedOffset,
})
Correct:
new ShapeStream({
url: '/api/todos',
offset: storedOffset,
handle: storedHandle,
})
Throws MissingShapeHandleError. Both offset AND handle are required to resume a stream from a stored position.
Source: packages/typescript-client/src/client.ts:1997-2003
HIGH Using non-deterministic functions in WHERE clause
Wrong:
const stream = new ShapeStream({
url: '/api/events',
params: {
table: 'events',
where: 'start_time > now()',
},
})
Correct:
const stream = new ShapeStream({
url: '/api/events',
params: {
table: 'events',
where: 'start_time > $1',
params: { '1': new Date().toISOString() },
},
})
Server rejects WHERE clauses with non-deterministic functions like now(), random(), count(). Use static values or positional params.
Source: packages/sync-service/lib/electric/replication/eval/env/known_functions.ex
HIGH Not parsing custom Postgres types
Wrong:
const stream = new ShapeStream({
url: '/api/events',
})
// createdAt will be string "2024-01-15T10:30:00.000Z", not a Date
Correct:
const stream = new ShapeStream({
url: '/api/events',
parser: {
timestamptz: (date: string) => new Date(date),
timestamp: (date: string) => new Date(date),
},
})
Electric auto-parses bool, int2, int4, float4, float8, json, jsonb, and int8 (→ BigInt). All other types arrive as strings — add custom parsers for timestamptz, date, numeric, etc. See references/type-parsers.md for the full list.
Source: AGENTS.md:300-308
MEDIUM Using reserved parameter names in params
Wrong:
const stream = new ShapeStream({
url: '/api/todos',
params: {
table: 'todos',
cursor: 'abc', // Reserved!
offset: '0', // Reserved!
},
})
Correct:
const stream = new ShapeStream({
url: '/api/todos',
params: {
table: 'todos',
page_cursor: 'abc',
page_offset: '0',
},
})
Throws ReservedParamError. Names cursor, handle, live, offset, cache-buster, and all subset__* prefixed params are reserved by the Electric protocol.
Source: packages/typescript-client/src/client.ts:1984-1985
MEDIUM Mutating shape options on a running stream
Wrong:
const stream = new ShapeStream({
url: '/api/todos',
params: { table: 'todos', where: "status = 'active'" },
})
// Later...
stream.options.params.where = "status = 'done'" // No effect!
Correct:
// Create a new stream with different params
const newStream = new ShapeStream({
url: '/api/todos',
params: { table: 'todos', where: "status = 'done'" },
})
Shapes are immutable per subscription. Changing params on a running stream has no effect. Create a new ShapeStream instance for different filters.
Source: AGENTS.md:106
References
- WHERE clause supported types and functions
- Built-in type parsers
See also: electric-proxy-auth/SKILL.md — Shape URLs must point to proxy routes, not directly to Electric. See also: electric-debugging/SKILL.md — onError semantics and backoff are essential for diagnosing sync problems.
Version
Targets @electric-sql/client v1.5.10.