Configuration
Environment variables, database objects, retries, and requirements.
Environment variables
The engine reads these at startup. All are optional.
| Variable | Default | Description |
|---|---|---|
WORKFLOW_RUN_WORKERS | 3 | Number of concurrent workers each WorkflowEngine runs in-process. Each worker handles one run execution at a time. |
WORKFLOW_RUN_EXPIRE_IN_SECONDS | 300 | Maximum time for a single handler execution. An execution that runs longer is failed and retried. Override per call with options.expireInSeconds on startWorkflow, resumeWorkflow, and triggerEvent. |
WORKFLOW_RUN_HEARTBEAT_SECONDS | 30 | How often workers report that an execution is alive. If a worker process dies, its run is detected and retried after roughly this interval plus 60 seconds, instead of waiting for the full expiry. Minimum 10. |
The engine does not read DATABASE_URL. Pass the connection string or a pg.Pool to the constructor:
import { WorkflowEngine } from 'pg-workflows'
const engine = new WorkflowEngine({
connectionString: process.env.DATABASE_URL ?? 'postgres://postgres:postgres@localhost:5432/postgres',
})Database objects
engine.start() runs migrations and creates:
| Object | Purpose |
|---|---|
public.workflow_runs | One row per run: status, input, output, error, and the timeline of step results. |
workflow_runs.resource_id index | Lookups by resource ID. |
workflow_runs.idempotency_key unique partial index | Idempotent starts. |
Unique partial index on workflow_id for pending and running singleton runs | Singleton workflows. |
pgboss_v12_pgworkflow schema | pg-boss job queue tables. The schema is isolated so it does not collide with another pg-boss installation in the same database. |
Retries
Retries are scheduled by pg-boss with exponential backoff: 2^retryCount seconds (about 1s, 2s, 4s, 8s), with up to ±50% jitter. A failed attempt includes a thrown error, an execution that passes WORKFLOW_RUN_EXPIRE_IN_SECONDS, and a worker that stops sending heartbeats. When the last attempt fails, the run is marked failed. See Retries and timeouts.
Dependencies
pgis a peer dependency. Install it alongsidepg-workflows.pg-bossis a regular dependency. It is installed with the engine and needs no setup. To use your own pg-boss configuration, pass abossinstance to theWorkflowEngineorWorkflowClientconstructor.
Requirements
- Node.js >= 18
- PostgreSQL >= 10
pg>= 8- A Standard Schema library (Zod, Valibot, ArkType) if you use
inputSchema