pg-workflows

library0.13.0jsnpmunverified

pg-workflows v0.13.0 is a TypeScript workflow engine that uses PostgreSQL as its sole backing store for durable execution, event-driven orchestration, and automatic retries. It eliminates the need for Redis, message brokers, or external workflow servers by storing all state in Postgres. Released under MIT, it targets Node >=18.0.0 and Postgres >=10. Key differentiators include a minimal API that feels like plain async TypeScript (no DSL), built-in step-level persistence with exactly-once semantics, event-driven pauses (step.waitFor), scheduling primitives (delay, waitUntil), and client/worker separation. Compared to Temporal or BullMQ, it requires zero new infrastructure and automatically runs schema migrations on start. Peer dependencies are pg (Postgres client) and optionally @opentelemetry/api for tracing. The package ships TypeScript types and is ESM-only.

database

npm install pg-workflows

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-WORKFLOWS

pg-workflows

databasejavascriptv0.13.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WorkflowEngine

✓ import { WorkflowEngine } from 'pg-workflows'

✗ const { WorkflowEngine } = require('pg-workflows')

ESM-only since v0.13.0. CommonJS require() will not work. Use ESM imports or dynamic import().

workflow

✓ import { workflow } from 'pg-workflows'

✗ import workflow from 'pg-workflows'

Named export, not default export.

WorkflowContext

✓ import type { WorkflowContext } from 'pg-workflows'

TypeScript type import. Available as a type export for use in workflow function signatures.

Defines a simple two-step workflow, initializes the engine with a Postgres connection, starts it, triggers a run, and then stops cleanly.

import { workflow, WorkflowEngine } from 'pg-workflows'; import { z } from 'zod'; const myWorkflow = workflow( 'my-workflow', async ({ step, input }) => { const result = await step.run('step-1', async () => { return { id: '123', email: input.email }; }); await step.run('step-2', async () => { console.log('Processing', result.email); }); return result; }, { inputSchema: z.object({ email: z.string().email() }) } ); const engine = new WorkflowEngine({ connectionString: process.env.DATABASE_URL ?? '', workflows: [myWorkflow], }); await engine.start(); await engine.startWorkflow({ workflowId: 'my-workflow', input: { email: 'alice@example.com' }, }); // Graceful shutdown await engine.stop();

Debug

Known issues

breakingv0.13.0 drops CommonJS support completely. Package is ESM-only.

fix

Ensure your project uses ESM (type: 'module' in package.json or .mjs extension). Switch from require() to import statements.

affects: >=0.13.0

gotchaThe engine runs database migrations automatically on start. This can be disruptive in production if you have strict schema change control.

fix

Set the 'disableMigrations' option to true in the WorkflowEngine config and run migrations separately (if supported) or review the migration SQL.

affects: >=0.1.0

deprecatedWorkflow engine constructor no longer accepts 'schema' in v0.13.0. Use 'pgSchema' instead.

fix

Replace 'schema' with 'pgSchema' in the engine configuration object.

affects: >=0.13.0

gotchaWorkflow functions must be synchronous in their top-level definition; you cannot use 'await' at the top level inside the workflow callback (only inside step.run).

fix

Wrap all async logic inside step.run() calls. The workflow callback itself should not be async (but step.run accepts async functions).

affects: >=0.1.0

gotchastep.waitFor requires an event to be emitted via engine.emitEvent(). The event name must match exactly, including case.

fix

Ensure you emit the event with the exact same eventName string. Use constants to avoid typos.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'pg-workflows'

Package not installed or not in node_modules.

fix

Run 'npm install pg-workflows pg' and ensure your Node.js version >=18.

TypeError: WorkflowEngine is not a constructor

Using CommonJS require() instead of ESM import.

fix

Change to 'import { WorkflowEngine } from 'pg-workflows'' and ensure your project is configured for ESM.

error: relation "pg_workflows_workflows" does not exist

Migrations haven't run. The engine creates tables on start, but may fail if it doesn't have permissions.

fix

Ensure the database user has CREATE privileges, or set 'disableMigrations: true' and run migrations manually if you have a management process.

ValidationError: input must match schema

Workflow input does not match the Zod schema defined in inputSchema.

fix

Check the input object against the schema. Use a type-safe input or add validation before calling startWorkflow.

Error: Timeout waiting for event 'user-confirmed' after 86400000 ms

step.waitFor reached its timeout without receiving the matching event.

fix

Ensure the event is emitted within the timeout window. Check event name spelling and that engine.emitEvent is called correctly.

Upgrade

Version history

0.13.0latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client - required for database connection

@opentelemetry/apioptionalOpenTelemetry API for tracing - peer dependency, required if you enable tracing

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/SokratisVidros/pg-workflows ↗

packagepg-workflows ↗

homepagehttps://github.com/SokratisVidros/pg-workflows#readme ↗