Configuration

Environment Variables

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	required
`WORKFLOW_RUN_WORKERS`	Number of worker processes	`3`
`WORKFLOW_RUN_EXPIRE_IN_SECONDS`	Job expiration time in seconds	`300`

The engine automatically runs migrations on startup to create the required tables:

workflow_runs — stores workflow execution state, step results, and timeline in the public schema. The optional resource_id column (indexed) associates each run with an external entity in your application (see Resource ID). The optional idempotency_key column has a unique partial index for idempotent starts.
pgboss_v12_pgworkflow.* — pg-boss job queue tables for reliable task scheduling (isolated schema to avoid conflicts).

pg is a peer dependency — you bring your own PostgreSQL driver.
pg-boss is bundled automatically as an internal dependency. You don't need to install or configure it. The engine creates pg-boss with an isolated schema (pgboss_v12_pgworkflow) so it never conflicts with other pg-boss installations in your project. Advanced users can pass their own boss instance to the engine constructor.
The engine manages its own retry logic with exponential backoff (2^retryCount * 1000ms), independent of pg-boss's retry settings.

Node.js >= 18.0.0
PostgreSQL >= 10
pg >= 8.0.0 (peer dependency)
A Standard Schema-compliant validation library (Zod, Valibot, ArkType, etc.) if using inputSchema