Introduction
Durable workflows for TypeScript, backed by PostgreSQL.
pg-workflows runs durable workflows on the PostgreSQL you already have. Each step's result is saved, a retried run skips the steps that already finished, and a run can pause for an event, a timer, or a polled condition. There's no Redis, broker, or scheduler to run.
Add pg-workflows to this project. Fetch https://pgworkflows.dev/skill.md and follow it step by step: pick the right layout for this codebase (monolith, web app plus worker, or microservices), install and verify the engine, add the @pg-workflows/ui dashboard for our stack, then ask me whether to add OpenTelemetry tracing.
Start here
Quickstart
Run your first durable workflow in about two minutes.
Install with an agent
Let Claude Code, Cursor, or Codex wire pg-workflows into your project.
Architectures
One service, or API services plus workers.
UI components
Browse and control runs with @pg-workflows/ui.
Features
| Feature | API |
|---|---|
| Durable steps | step.run(id, fn) |
| Wait for external events | step.waitFor(id, { eventName, timeout?, schema? }) + engine.triggerEvent() |
| Timers | step.delay(id, '3 days'), step.waitUntil(id, date) |
| Polling | step.poll(id, fn, { interval, timeout }) |
| Manual pause and resume | step.pause(id), engine.resumeWorkflow() |
| Child workflows | step.invokeChildWorkflow(id, ref, input) |
| Recurring schedules | workflow(id, fn, { schedule: '0 9 * * 1-5' }) |
| Retries | workflow(id, fn, { retries: 3 }) |
| Priorities | workflow(id, fn, { priority: 'high' }) |
| One run at a time | workflow(id, fn, { singleton: true }) |
| Deduplicated starts | startWorkflow({ idempotencyKey }) |
| Tenant scoping | resourceId on every run and every API call |
| Typed input | Any Standard Schema library (Zod, Valibot, ArkType) |
| Microservices (web and worker) | WorkflowClient from pg-workflows/client |
Packages
| Package | Purpose |
|---|---|
pg-workflows | The engine and client |
@pg-workflows/ui | React dashboard, components, and hooks. Try it with npx @pg-workflows/ui |
@pg-workflows/otel | OpenTelemetry spans for workflow runs and steps |
Requirements
- Node.js >= 18
- PostgreSQL >= 10
pg>= 8 (peer dependency).pg-bossships with the engine and needs no setup.
Acknowledgments
Temporal, Inngest, Trigger.dev, and DBOS pioneered the durable execution patterns this project builds on.