The Postgres World is a production-ready backend for self-hosted deployments. It uses PostgreSQL for durable storage and graphile-worker for reliable job processing.

Use the Postgres World when you need to deploy workflows on your own infrastructure outside of Vercel - such as a Docker container, Kubernetes cluster, or any cloud that supports long-running servers.

Install the Postgres World package in your workflow project:

Configure the required environment variables to use the world and point it to your PostgreSQL database:

WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"

Run the migration script to create the necessary tables in your database. Ensure WORKFLOW_POSTGRES_URL is set when running this command:

npx workflow-postgres-setup

To subscribe to the graphile-worker queue, your workflow app needs to start the world on server start. Here are examples for a few frameworks:

Use the workflow CLI to inspect workflows stored in PostgreSQL:

# Set your database URL
export WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"

# List workflow runs
npx workflow inspect runs --backend @workflow/world-postgres

# Launch the web UI
npx workflow web --backend @workflow/world-postgres

If WORKFLOW_POSTGRES_URL is not set, the CLI defaults to postgres://world:world@localhost:5432/world.

Learn more in the Observability documentation.

All configuration options can be set via environment variables or programmatically via createWorld().

WORKFLOW_POSTGRES_URL (required)

PostgreSQL connection string. Falls back to DATABASE_URL if not set.

Default: postgres://world:world@localhost:5432/world

WORKFLOW_POSTGRES_JOB_PREFIX

Prefix for graphile-worker queue job names. Useful when sharing a database between multiple applications.

WORKFLOW_POSTGRES_WORKER_CONCURRENCY

Number of concurrent workers polling for jobs. Default: 50.

This value also bounds how many parent→child workflow polls can be in flight simultaneously. Every await childRun.returnValue inside a workflow holds a worker slot until the child run terminates — if you expect recursive or highly-fanned-out parent/child workflows, raise this ceiling above the peak number of concurrent polls. With the default of 50, the included fibonacciWorkflow e2e test (fib(6), ~24 concurrent polls at peak) passes; deeper recursion or larger fanouts need a correspondingly larger setting.

WORKFLOW_POSTGRES_MAX_POOL_SIZE

Maximum size of the internal pg.Pool used when createWorld() constructs the pool. Default: 10

For higher worker concurrency, Graphile Worker recommends setting maxPoolSize to 10 or queueConcurrency + 2, whichever is larger.

Programmatic configuration

import { createWorld } from "@workflow/world-postgres";

const world = createWorld({
  connectionString: "postgres://user:password@host:5432/database",
  jobPrefix: "myapp_",
  queueConcurrency: 50,
  maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
});

The Postgres World uses PostgreSQL as a durable backend:

• Storage - Workflow runs, events, steps, and hooks are stored in PostgreSQL tables
• Job Queue - graphile-worker handles reliable job processing with retries
• Streaming - PostgreSQL NOTIFY/LISTEN enables real-time event distribution

This architecture ensures workflows survive application restarts with all state reliably persisted. For implementation details, see the source code.

Deploy your application to any cloud that supports long-running servers:

• Docker containers
• Kubernetes clusters
• Virtual machines
• Platform-as-a-Service providers (Railway, Render, Fly.io, etc.)

Ensure your deployment has:

1. Network access to your PostgreSQL database
2. Environment variables configured correctly
3. The start() function called on server initialization

• Requires long-running process - Must call start() on server initialization; not compatible with serverless platforms
• PostgreSQL infrastructure - Requires a PostgreSQL database (self-hosted or managed)
• Not compatible with Vercel - Use the Vercel World for Vercel deployments

For local development, use the Local World which requires no external services.