Getting started

This page gets you from zero to a working read + write path. For what each package does, see Packages; for the model behind it, see Core concepts.

Prerequisites

• PostgreSQL 17+ (Supabase-compatible; the write path uses Supabase-style auth claims for RLS), running with wal_level = logical — the Circuits engine ingests logical replication and creates its own replication slot. Supabase’s images already ship it; verify with postgres -C wal_level.

• The read path’s two services: the Circuits engine (ghcr.io/pgxsinkit/circuits/engine) and a durable-streams server (ghcr.io/pgxsinkit/circuits/durable-streams). Both are built in pgxsinkit/circuits and released together under one tag, so pin the pair with the same one. The engine is configured entirely through four environment variables:

  CIRCUITS_PG_URL=postgres://…      # the database it replicates from
  CIRCUITS_DS_URL=http://ds:8791    # the durable-streams server it publishes into
  CIRCUITS_PG_TABLES=issue,team,…   # an EXPLICIT list of bare table names — never `*`
  CIRCUITS_BIND=0.0.0.0:7010        # its control API, which must not be client-reachable

  * introspects every public table with a primary key, which sweeps in tables you never meant to publish. The engine exits if a listed table is absent, so run it under a restart policy while migrations land.

• A supported browser for the client’s local database: Safari and iOS 18.4, Chrome 137, Firefox 131 or later (see Supported browsers). Older browsers cannot run it.

• The pgmq extension, but only if you use the event lane. Its generated migration runs CREATE EXTENSION IF NOT EXISTS pgmq, so the extension has to be present in the PostgreSQL image you deploy — Supabase’s images ship it; a stock postgres image does not. Registries with no streams need nothing.

• A runtime that serves a web fetch handler for the pgxsinkit server — Bun, Deno, Supabase Edge Functions, Cloudflare Workers, etc. The server core is runtime-neutral and framework-free (web-standard Request/Response, with the DB client injected); only the optional server.start() helper is Bun-specific. And Drizzle (drizzle-orm@1.0.0-rc.4+) for schema.

Install

bun

bun add @pgxsinkit/client @pgxsinkit/server @pgxsinkit/contracts
# React bindings (optional)
bun add @pgxsinkit/react
# An app that builds with Vite (see below)
bun add @pgxsinkit/pgwasm @pgxsinkit/pgwasm-c @pgxsinkit/pgwasm-pg-dump

pnpm

pnpm add @pgxsinkit/client @pgxsinkit/server @pgxsinkit/contracts
# React bindings (optional)
pnpm add @pgxsinkit/react
# An app that builds with Vite (see below)
pnpm add @pgxsinkit/pgwasm @pgxsinkit/pgwasm-c @pgxsinkit/pgwasm-pg-dump

npm

npm install @pgxsinkit/client @pgxsinkit/server @pgxsinkit/contracts
# React bindings (optional)
npm install @pgxsinkit/react
# An app that builds with Vite (see below)
npm install @pgxsinkit/pgwasm @pgxsinkit/pgwasm-c @pgxsinkit/pgwasm-pg-dump

yarn

yarn add @pgxsinkit/client @pgxsinkit/server @pgxsinkit/contracts
# React bindings (optional)
yarn add @pgxsinkit/react
# An app that builds with Vite (see below)
yarn add @pgxsinkit/pgwasm @pgxsinkit/pgwasm-c @pgxsinkit/pgwasm-pg-dump

The packages are published to public npm; install them with whichever package manager your app uses — pgxsinkit mandates none. Peer dependencies are drizzle-orm and zod. The client brings its local Postgres, pgwasm, and the C Postgres build as ordinary dependencies; there is nothing to override.

If your app builds with Vite, keep pgwasm and the two packages that ship WebAssembly files next to their code out of dependency pre-bundling, and list all three in your app’s own dependencies:

vite.config.ts

export default defineConfig({
  optimizeDeps: {
    exclude: ["@pgxsinkit/pgwasm", "@pgxsinkit/pgwasm-c", "@pgxsinkit/pgwasm-pg-dump"],
  },
});

Pre-bundling would move the two packages’ code away from their WebAssembly files. Both import pgwasm, so a pre-bundled pgwasm would load a second time on the dev server, and an instanceof check against one of its error classes would fail. Vite resolves an excluded package from your app, not from the client that imports it, so a package manager that links only an app’s direct dependencies (pnpm, Bun workspaces) finds the three only when the app lists them.

Stand up the write path

1. Define your sync registry — the tables, their sync mode, and governance (managed fields like owner/timestamps). This is the single source of truth both paths read from.

   sync-registry.ts

   import { clockMicrosecondsSql, defineSyncRegistry, defineSyncTable } from "@pgxsinkit/contracts";
   import { bigint, uuid, varchar } from "drizzle-orm/pg-core";
   
   export const registry = defineSyncRegistry({
     widgets: defineSyncTable({
       tableName: "widgets",
       mode: "readwrite",
       makeColumns: () => ({
         id: uuid("id").primaryKey(),
         label: varchar("label", { length: 120 }).notNull(),
         ownerId: uuid("owner_id"),
         // Server version: a strictly-monotonic per-row token convergence keys on.
         updatedAtUs: bigint("updated_at_us", { mode: "bigint" }).notNull().default(clockMicrosecondsSql),
       }),
       // Both are REQUIRED for a writable table — no silent default:
       conflictPolicy: "reject-if-stale", // or "last-write-wins"
       governance: {
         managedFields: [
           { column: "updatedAtUs", applyOn: ["create", "update"], strategy: "nowMicroseconds" },
           // Stamp the owner from the verified `sub` claim. (`auth.uid()` is just claimPath: ["sub"];
           // use ["app_metadata","person_id"] etc. for an app-minted identity.)
           { column: "ownerId", applyOn: ["create"], strategy: "authClaim", claimPath: ["sub"] },
         ],
       },
       // Add a shape.rowFilter for row-level read filtering (see the security note below).
     }),
   });

   Writable tables have two hard requirements

   defineSyncRegistry throws unless every readwrite table declares both: a Server version (a nowMicroseconds-on-update managed field, conventionally updated_at_us) that optimistic convergence keys on, and a conflictPolicy (reject-if-stale | last-write-wins) — there is no silent default, because a silent last-write-wins is exactly the data loss the choice exists to surface. Fields stamped by authClaim (a verified claim at a JSON path — ["sub"] is the old auth.uid() owner) / nowMicroseconds are server-assigned; the server rejects them if present in a client write payload.

2. Provision the apply function. The write path applies batches through one in-database PL/pgSQL function, pgxsinkit_apply_mutations. Generate a drizzle-kit migration that installs it from your registry with the published pgxsinkit-generate CLI (a bin of @pgxsinkit/server), run from your own project. The CLI requires Bun on PATH — it imports your TypeScript registry and runs drizzle-kit — but the bin itself launches under any runner; bunx, or npx / pnpm exec / yarn once Bun is installed (it prints a clear message if Bun is missing).

   bunx pgxsinkit-generate \
     --registry ./sync-registry.ts \
     --export registry \
     --project-dir ./db \
     --config drizzle.config.ts \
     --name sync_artifact

   This writes a standard drizzle-kit migration you commit and apply through your normal migration flow. The migration lands wherever your drizzle config’s out points — pass --config and the generator reads out from it (or set --out explicitly); with neither it probes drizzle/ and infra/drizzle/.

   The generated apply function and the audit/version column DEFAULTs (clockMicrosecondsSql above) both call the canonical public.pgxsinkit_clock_us() microsecond clock, so its utilities migration must be the first folder in the chain — generate it once with --utilities, before the drizzle-kit schema baseline, passing an early-sorting folder name:

   bunx pgxsinkit-generate --utilities \
     --project-dir ./db \
     --config drizzle.config.ts \
     --name 20200101000000_pgxsinkit_utilities

   The generated function carries a fingerprint of itself (a COMMENT ON FUNCTION). It verifies itself on every call (ADR-0030): the server passes the fingerprint it expects for its registry + codegen, and the function compares that against its own stamped comment before touching any table — raising PXS01 and applying nothing on a mismatch. So a registry change or a @pgxsinkit/server upgrade you forgot to regenerate + apply fails loud (a stale — or hand-installed, unfingerprinted — function is refused) instead of writing against the wrong applier. The check rides the existing call: no extra round trip, no startup query, no read-then-call race. To catch the same drift in CI before it ships, run the generator in --check mode — read-only, writes nothing, non-zero exit on drift:

   bunx pgxsinkit-generate --check \
     --registry ./sync-registry.ts --export registry \
     --project-dir ./db --config drizzle.config.ts

3. Create the server and serve its fetch. All writes go through POST /api/mutations; adding readPath also mounts the read path’s control plane — /sync/v1/subscribe, /sync/v1/refresh, /sync/v1/barrier — beside it, in the same app.

   import { createCircuitsEngineClient, createSyncServer, importStreamTokenKey } from "@pgxsinkit/server";
   import { registry } from "./sync-registry";
   
   const server = createSyncServer({
     registry,
     db, // your Drizzle database
     resolveAuthClaims: async (_request) => {
       // verify the request's JWT and return its claims, or null — never a claims object with no `sub`
       return null;
     },
     readPath: {
       // The engine's control API. Only shape LIFECYCLE goes through it; reads never do.
       engine: createCircuitsEngineClient({ baseUrl: process.env.CIRCUITS_ENGINE_URL! }),
       // The stream-token signing key, shared with the edge and with nothing else.
       key: await importStreamTokenKey(process.env.STREAM_TOKEN_SECRET!),
     },
   });
   
   export default { fetch: server.fetch };
   // `server.fetch` is a web-standard handler — deploy it on Bun, Deno, Supabase Edge
   // Functions, or Cloudflare Workers. Only the optional `server.start()` helper needs Bun.

   readPath requires resolveAuthClaims — createSyncServer refuses the combination without it, because the control plane cannot mint a stream token for a subject it cannot resolve. The edge that serves the stream bytes is a separate mount on its own origin; see Deploying the server, which also covers the two concrete steps a non-Bun runtime (Deno / Supabase Edge Functions) needs — a path rewrite and resolving claims from the platform’s JWT.

Two execution contexts enforce the same authorization

Authorization runs in two different engines, so the subject is referenced two ways — derive both from one predicate so a row is never readable-but-unwritable (or the reverse) by accident:

• Write path — RLS in Postgres: the applier sets the auth context (role, current_setting('request.jwt.claims')) before applying a batch, and RLS policies read it (auth.uid() is just request.jwt.claims ->> 'sub'). The owner/author column itself is stamped from those same claims by an authClaim managed field at a claim path — ["sub"] is the old auth.uid() owner, but it can be any verified claim (e.g. ["app_metadata","person_id"]).
• Read path — the shape rowFilter: the control plane compiles the filter into a predicate AST once per shape, at subscribe, and the sync engine evaluates it — not Postgres. So a customPredicate returns a Predicate built with the p.* builders over the real Drizzle column objects: p.eq, p.and/p.or/p.not, p.isNull, p.in/p.notIn. Comparisons are checked against each column’s own TypeScript type, so a mistyped enum label or a null against a NOT NULL column is a compile error rather than a silently-wrong filter. There is no cast to write: the AST carries typed JSON scalars, so an enum column compares against its label directly. Return DENY_ALL_PREDICATE to block all rows, or null to bypass filtering — null means no filter, all rows visible, so an owner filter must return DENY_ALL_PREDICATE (not null) when the claim is absent. When you define the table and its filter together in one defineSyncTable, write shape.rowFilter as a function of the built columns — rowFilter: (columns) => ({ customPredicate: (claims) => … p.eq(columns.ownerId, claims.sub) … }) — so the predicate references the real typed columns this call is creating (the same columns extras receives), with no separately-built table needed.

defineSyncTable and defineReadProjection refuse a rowFilter that restricts nothing — one with neither a customPredicate nor a column allow-list. A filter that filters nothing is either an authoring mistake or an unfinished one, and both fail at definition time instead of shipping open.

For a cross-table membership fan-out (sync a row only if the subject belongs to its container), p.subquery names the inner set by the column it projects — the table is read off that column, so there is no table name to get wrong. Factor it into a helper so every filter that needs it shares one:

import { DENY_ALL_PREDICATE, p, type Predicate, type SubqueryRef } from "@pgxsinkit/contracts";

const memberContainers = (subject: string): SubqueryRef<string> =>
  p.subquery(memberships.containerId, p.eq(memberships.memberId, subject));

const widgetsReadFilter = (claims: JwtClaims): Predicate =>
  claims.sub ? p.in(widgets.containerId, memberContainers(claims.sub)) : DENY_ALL_PREDICATE;

Sharing that helper is not just tidiness: the engine maintains the inner set incrementally and shares it across every shape that references it, so N filters over one membership cost one index between them rather than N. The subquery must be uncorrelated — its inner where reads the membership table’s own columns only. packages/board-schema/src/schema.ts is a worked end-to-end example.

For RLS, @pgxsinkit/contracts ships buildSupabaseOwnerOrAdminNativePolicies and buildSupabaseMembershipNativePolicies for the owner and membership shapes — they take Drizzle columns and derive the table from them, so call them inside defineSyncTable’s extras: (t) => … callback. The read filter and the write policy build from the same Drizzle columns, so they cannot silently drift. For anything beyond them (e.g. collaborative any-member writes), compose your own from pgPolicy + Drizzle operators (and/or/eq).

Each family also ships the read half of that one declaration, so you never hand-write the mirror: return buildOwnerOrAdminShapePredicate(ownerColumn, claims) (an admin gets null — no filter — mirroring the policy’s bypass; everyone else gets buildOwnershipShapePredicate), buildMembershipShapePredicate(columns, claims), or buildGrantScopeAccessShapePredicate(scopeColumn, claims, options) for a JWT-resident grant set (a bypass grant → null too; the bare resolveGrantScopeIds + buildGrantScopeShapePredicate pair cannot see one) — hand each the same options object you gave the policy builder — straight from customPredicate. Each denies with DENY_ALL_PREDICATE when the claims resolve to no access: the ownership, owner-or-admin and membership mirrors when there is no subject, the grant-scope mirror when the resolved grant set is empty. They mirror the SELECT policy only (a row filter filters a read stream), and they render containment as the AST’s IN (subquery) where the policy renders = ANY(ARRAY(select …)) for Postgres’ index-scan discipline — same columns, two dialects.

Stand up the read path

The client writes locally into an overlay + a durable journal, flushes the journal to the server’s write route, and subscribes to shape streams that land in the local store (pgwasm). Reads are served from that store. The client does not construct stream URLs: it asks the control plane what it may read and is told, then reads those streams through the edge, which checks the token it was granted.

import { createSyncClient } from "@pgxsinkit/client";
import { registry } from "./sync-registry";

const client = await createSyncClient({
  registry,
  controlPlaneUrl: "/", // where /sync/v1/subscribe|refresh|barrier are mounted
  streamBaseUrl: "https://stream.example.com/v1/stream", // the edge, on its own origin
  batchWriteUrl: "/api/mutations", // the exact pgxsinkit batch endpoint
  getAuthToken: async () => currentJwt(),
});
// `createSyncClient` resolves at LOCAL-READ readiness (ADR-0041): cached rows are queryable immediately —
// offline included — and writes transparently await the write runtime, so you can read and write straight
// away. `await client.ready` below is optional: it waits for WHOLE-SYNC catch-up (every eager group), which
// this demo does so the first read reflects the server. For a UI, paint at creation and drive per-view
// loading with `hydrating`/`groupReady` instead of blocking on `ready`.
await client.ready;

// Optimistic local write — staged in the overlay + journal, flushed on the next pass.
await client.tables.widgets.create({ id: crypto.randomUUID(), label: "Hello" });

// Reads come from the local read model (the overlay unioned over synced rows).
const widgets = await client.drizzle.select().from(client.views.widgets);

These snippets compile against the published packages, so they stay in step with the shipped API. See The read path and The write path for the full flow, and Packages for the client entry points.

Naming the local store

Pass a storePath to name the local store — a plain name, never a storage URL:

const client = await createSyncClient({
  registry,
  controlPlaneUrl: "/",
  streamBaseUrl: "https://stream.example.com/v1/stream",
  batchWriteUrl: "/api/mutations",
  storePath: "my-app-store", // a plain name; omit it to use the built-in default
});

The storage backend is derived from where the code runs — IndexedDB in the browser, the filesystem on Node/Bun — so you never write idb://… or file://… yourself. A scheme-bearing string is rejected at boot with a clear error. A memory-backed store is deliberately not a production option; pgxsinkit’s durability guarantees (persistent retention, the optimistic write journal) assume a persisted store.

Testing

For unit tests that want a fast, throwaway in-memory store, import memoryStoreForTests from @pgxsinkit/client/testing and spread it into the options — a named, deliberate opt-in whose durability caveats are documented on the helper:

import { memoryStoreForTests } from "@pgxsinkit/client/testing";

const client = await createSyncClient({
  registry,
  controlPlaneUrl: "/",
  streamBaseUrl: "https://stream.example.com/v1/stream",
  batchWriteUrl: "/api/mutations",
  ...memoryStoreForTests("my-test"),
});

createSyncClient runs the engine on the calling thread — right for Node, tests, and as a fallback. In a browser app you will usually attach through a SharedWorker instead: defineSyncWorker in a worker entry and attachSyncClient in the tab return the same client shape off the main thread. Capability placement can host the OPFS engine in that SharedWorker on Safari or behind it in an elected worker on Chromium/Firefox. See Worker mode.

Project a writable table read-only per client

When two clients consume the same table at different capabilities — a teacher writes a posting_restriction a learner only reads, or a learner writes a report a teacher only moderates — mode is per-client, not a property of the table. Define the table once in an authoritative registry at its writable capability, generate the server from that, and give each client a projection of it.

mode is resolved at defineSyncTable time and drives the local write machinery (overlay + journal) and the overlay-merged read-model view, so you cannot hand-spread { ...entry, mode: "readonly" } — the entry would keep a view over overlay state the readonly client never creates. Use asReadonly, which re-derives a true readonly entry: it drops the overlay/journal projection, the read-model view, and conflictPolicy/governance/writeMode, and keeps the read contract (columns, primary key, synced table, the shape/row filter) intact.

import { asReadonly, assertReadContractPreserved, defineSyncRegistry } from "@pgxsinkit/contracts";
import { postingRestriction } from "./tables"; // defineSyncTable(…, { mode: "readwrite", conflictPolicy, governance })

// One authoritative registry — the server's apply function + read-path shapes are generated from this.
export const authoritativeRegistry = defineSyncRegistry({ posting_restriction: postingRestriction });

// Per-client projections: the teacher writes the table; the learner only reads it.
export const teacherRegistry = defineSyncRegistry({ posting_restriction: postingRestriction });
export const learnerRegistry = defineSyncRegistry({ posting_restriction: asReadonly(postingRestriction) });

// Fail closed if a projection ever diverges the data it syncs (columns / pk / row-filter shape):
assertReadContractPreserved(authoritativeRegistry, teacherRegistry, { label: "teacher" });
assertReadContractPreserved(authoritativeRegistry, learnerRegistry, { label: "learner" });

A projection that must append events has to re-declare its streams

The bare-registry-map overload used above (defineSyncRegistry({ posting_restriction: … })) has nowhere to declare event streams, and a registry’s streams ride a non-enumerable symbol — so spreading a table map (or a registry) into a projection carries the tables and silently leaves the streams behind, and that client’s appendEvent throws “no Event streams registered”. If a projection is meant to serve the event lane, build it with the definition-object form and re-declare them: defineSyncRegistry({ tables: { … }, streams }). Re-declaring is cheap and safe — a stream provisions a queue and touches no synced table, no local schema and no apply function.

Generate the server from the authoritative registry

The apply function emits a write branch for every table and stamps managed fields / reject-if-stale from the entry’s write contract, so it must be generated from the writable entry — generate from the authoritative registry, not a readonly projection. A claims-branching customPredicate then serves every client from one shape definition (each request carries its own claims). A projection may differ only in write capability and lifecycle (subscription/retention/group), never in the read contract — that is what assertReadContractPreserved enforces. It cannot see the customPredicate body, so bump rowFilter.revision on a logic change. The full registry fingerprint differs between the writable and readonly variants — expected and fine: it is client-local, guarding each client’s own store, and the server never sees it. See ADR-0025.

Register an event stream (queue-shaped data)

Not everything belongs on a synced table. High-volume, append-only client facts — “the user viewed this”, interaction logs, review grades — are never edited, never conflict, and are never read back down, so putting them on the sync rail makes every client re-download its own log. They go on the event lane instead, registered on the same registry under a streams key whose record key is the stream name:

import { defineEventStream, defineSyncRegistry } from "@pgxsinkit/contracts";
import { z } from "zod";

export const registry = defineSyncRegistry({
  tables: { issue },
  streams: {
    issue_viewed: defineEventStream({
      // Strict is REQUIRED for an object payload, and validated at `appendEvent` as well as at ingest.
      payload: z.object({ issueId: z.uuid() }).strict(),
      // Stamped SERVER-side from the verified claims — the same claimPath addressing managed fields use.
      identity: { viewerId: { claimPath: ["sub"] } },
    }),
  },
});

Then await client.appendEvent("issue_viewed", { issueId }) stages the event in a durable local Outbox and resolves — delivery happens in the background, and an append made offline drains on reconnect. Three rules worth knowing at authoring time:

• Never put a viewer/actor id in the payload. A payload is client-supplied and can lie; identity is read from verified claims, and the client’s envelope carries no identity at all.
• Stream names are validated when the module evaluates — lowercase [a-z][a-z0-9_]*, at most 30 characters — so a name that could not be provisioned fails at definition rather than at deployment.
• An object payload must be strict — .strict() or z.strictObject(), on the root and on every object in a union — and the registry throws if it is not, so an unknown key can never be stripped in silence.
• A payload schema may only evolve backward-compatibly. Events written offline under the old schema are still in flight; an incompatible change needs a new stream name. Bump revision whenever you change acceptance logic the lock’s JSON-Schema hash cannot see (a .refine, a transform), or the review gate never fires.

Registering a stream touches no synced table and no apply function, so it never rebuilds a client’s read cache — but it does add a deploy step (per-stream queues) and a consumer process. Full model: The event lane; deployment: Deploying the server.

Try the demo

The repository’s apps/board (a Linear-style board + chat) drives all of the above end-to-end against a trimmed Supabase + Circuits stack — Postgres, GoTrue, an Envoy gateway, durable-streams, the Circuits engine, and three edge functions (board-write, board-sync for the control plane, and board-stream for the edge):

mise install && bun install
mkcert -install       # one-time: trust the local CA so the browser accepts the gateway's TLS cert
cp .env.example .env
bun run infra:up      # the full board stack via Podman compose
bun run seed:board    # GoTrue identities + fixtures
bun run dev:board

The board's gateway is served over HTTPS (HTTP/2) — mkcert is a prerequisite

@pgxsinkit/client holds one live long-poll connection per synced stream, and the board syncs six. Over plain HTTP/1.1 those long-polls exhaust the browser’s ~6-connections-per-origin cap and writes starve behind them (see Deploying the server → the gateway must speak HTTP/2). So the demo fronts its gateway with a TLS-terminating HTTP/2 + HTTP/3 Caddy sidecar, and the board’s browser origin is https://localhost:54343. infra:up issues the cert with mkcert, but the local CA must be trusted first — mkcert -install (one-time) — because a browser fetch() to an untrusted cert fails outright (no click-through), and HTTP/3’s QUIC refuses an untrusted cert entirely. Without mkcert the stack still comes up on plain http://localhost:54331 (used by the integration tests and seed scripts); only the fast browser path is unavailable.

For the minimal @pgxsinkit/server reference instead, use bun run infra:harness:up (PostgreSQL + durable-streams + the Circuits engine) + bun run dev:api. See Demo & harness for what each is for.