@flowwright/store-postgres

The PostgreSQL RunStore for FlowWright team deployments — a drop-in backend for the runtime's async store interface when SQLite outgrows a single host. Runs are claimed with FOR UPDATE SKIP LOCKED, and an optional LISTEN/NOTIFY notifier fans run events out to multiple servers/workers.

FlowWright · Runtime · Server

Use it

import { openStore } from "@flowwright/store-postgres";

// Selects Postgres when a connection string is configured, else the node:sqlite store.
const store = await openStore({
  postgres: process.env.FW_DATABASE_URL, // e.g. "postgres://user:pass@host/flowwright"
  dataDir: ".flowwright",
});

const run = await store.createRun(/* ... */);
const claimed = await store.claimNextRun(/* worker filter */); // FOR UPDATE SKIP LOCKED

For a direct Postgres handle:

import { openPostgresStore, createPostgresEventNotifier } from "@flowwright/store-postgres";

const store = await openPostgresStore(process.env.FW_DATABASE_URL!);
const notifier = createPostgresEventNotifier(process.env.FW_DATABASE_URL!);
await notifier.subscribe((event) => {/* push to SSE */});

Public surface

| Area | Main exports | |---|---| | Store | openPostgresStore, openPostgresPool, initPostgresSchema | | Backend selector | openStore, isPostgresSelected, StoreSelection | | Event notifier | createPostgresEventNotifier, RUN_EVENTS_CHANNEL, PostgresEventNotifier | | Schema | PG_SCHEMA_VERSION, ensureSchemaVersion, PG_BASELINE_DDL |

Design boundary

• Implements the runtime's async RunStore interface against Postgres — same contract as the built-in node:sqlite store, so servers and workers are storage-agnostic.
• openStore is the seam that picks Postgres or SQLite from config; callers never branch.
• No HTTP, no scheduling logic beyond the atomic claim — this package owns persistence only.

Development

$ pnpm --filter @flowwright/store-postgres typecheck
$ pnpm --filter @flowwright/store-postgres test
$ pnpm --filter @flowwright/store-postgres build

Requires Node.js 24+. Licensed under MIT.