electric-shapes

name	electric-shapes
description	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.
type	core
library	electric
library_version	1.5.10
sources	["electric-sql/electric:packages/typescript-client/src/client.ts","electric-sql/electric:packages/typescript-client/src/shape.ts","electric-sql/electric:packages/typescript-client/src/types.ts","electric-sql/electric:packages/typescript-client/src/parser.ts","electric-sql/electric:packages/typescript-client/src/column-mapper.ts","electric-sql/electric:website/docs/guides/shapes.md"]

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.