Postgres

The Postgres World is a production-ready backend for self-hosted deployments. It uses PostgreSQL for durable storage and pg-boss 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.

Installation

Install the Postgres World package in your workflow project:

npm install @workflow/world-postgres

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

Starting the World

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

export async function register() {
  if (process.env.NEXT_RUNTIME !== "edge") {
    const { getWorld } = await import("workflow/runtime");
    await getWorld().start?.();
  }
}

import type { ServerInit } from "@sveltejs/kit";

export const init: ServerInit = async () => {
  const { getWorld } = await import("workflow/runtime");
  await getWorld().start?.();
};

import { defineNitroPlugin } from "nitro/~internal/runtime/plugin";

export default defineNitroPlugin(async () => {
  const { getWorld } = await import("workflow/runtime");
  await getWorld().start?.();
});

import { defineNitroConfig } from "nitropack";

export default defineNitroConfig({
  modules: ["workflow/nitro"],
  plugins: ["plugins/start-pg-world.ts"],
});

Observability

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.

Testing & Performance

Configuration

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 pg-boss queue job names. Useful when sharing a database between multiple applications.

WORKFLOW_POSTGRES_WORKER_CONCURRENCY

Number of concurrent workers polling for jobs. Default: 10

Programmatic configuration

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

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

How It Works

The Postgres World uses PostgreSQL as a durable backend:

• Storage - Workflow runs, events, steps, and hooks are stored in PostgreSQL tables
• Job Queue - pg-boss 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.

Deployment

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

Limitations

• 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.