Manual Installation

This guide explains how to manually set up pgflow and Edge Worker without using the automatic installer. While we recommend using the pgflow install command for most users, this manual approach can be helpful in certain scenarios:

When you need more control over the installation process
When troubleshooting installation issues
When integrating with custom deployment pipelines
When you want to understand what happens behind the scenes

Manual Installation Steps

1. Install migration files

To manually install the required migration files:

Download the latest release

Go to the pgflow GitHub releases page
Download the source code zip file for the latest release
Extract the downloaded zip file
Create your migrations directory if it doesn’t exist: mkdir -p supabase/migrations

Copy the migration files

Copy files from the extracted archive’s pkgs/core/supabase/migrations/*.sql to your project’s supabase/migrations/ folder.

Apply the migrations

After copying the migration files, apply them:

npx supabase migration up

2. Create environment file

Edge Worker needs environment variables for database connection and logging.

Create a .env file in your supabase/functions directory with the following content:

# Database connection string for Edge Worker and pgflow
EDGE_WORKER_DB_URL="postgresql://postgres.pooler-dev:postgres@pooler:6543/postgres"

# Log level (options: debug, info, warn, error)
EDGE_WORKER_LOG_LEVEL="info"

3. Setup Connection Pool

Modify the db.pooler section in your supabase/config.toml file to enable pooler and make sure that db.pool_mode is set to "transaction".

[db.pooler]
enabled = false
enabled = true
# Port to use for the local connection pooler.
port = 54329
# Specifies when a server connection can be reused by other clients.
# Configure one of the supported pooler modes: `transaction`, `session`.
pool_mode = "transaction"
# How many server connections to allow per user/database pair.
default_pool_size = 20
# Maximum number of client connections allowed.
max_client_conn = 100

4. Setup Edge Runtime policy

Change the Edge Runtime policy to per_worker to enable Background Tasks (see more in Testing background tasks locally).

[edge_runtime]
enabled = true
# Configure one of the supported request policies: `oneshot`, `per_worker`.
# Use `oneshot` for hot reload, or `per_worker` for load testing.
policy = "oneshot"
policy = "per_worker"
# Port to attach the Chrome inspector for debugging edge functions.
inspector_port = 8083

5. Restart Supabase

To apply the changes, restart Supabase:

npx supabase stop
npx supabase start

What gets installed

When following these steps, the installation sets up:

worker schema with tables for worker management and message queuing
pgflow schema with tables for workflows and execution state
SQL functions for worker lifecycle management and workflow operations

The same migrations and configuration are used for both Edge Worker and pgflow, as pgflow builds on top of Edge Worker’s functionality.

What’s the difference?

The manual installation process essentially performs the same steps as the automatic pgflow install command, but gives you direct control over each step. The automatic installer:

Detects your Supabase project directory
Updates your config.toml file
Copies the migration files
Creates the environment file
Provides helpful feedback during installation

If you encounter any issues with the automatic installer, this manual approach can help you identify and fix specific problems in your setup.

Verifying your installation

After completing the installation, verify it by running these queries:

-- Verify worker schema
SELECT * FROM pgflow.workers LIMIT 1;

-- Verify pgflow schema
SELECT * FROM pgflow.flows LIMIT 1;

If these queries run without errors (they may return no rows, which is expected for a fresh installation), your installation was successful and you can proceed to using the features.