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

Prerequisites

• Supabase CLI version 2.0.2 or higher (check with supabase -v)
• A local Supabase project set up
• Basic understanding of Supabase configuration

Manual Installation Steps

1. Install migration files

To manually install the required migration files:

Download the latest release

1. Go to the pgflow GitHub releases page
2. Download the source code zip file for the latest release
3. Extract the downloaded zip file
4. 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

Note

The installation process is exactly the same whether you’re using Edge Worker or pgflow, as pgflow builds on top of Edge Worker and the migration files include everything needed for both.

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"

Special Characters in Passwords

If your database password contains special characters (@, &, :, etc.), you must URL-encode them to avoid authentication errors. See our DB Connection URLs guide for detailed instructions.

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

Transaction Mode

Edge Worker requires transaction mode connection because of Edge Function early termination. This will change in the future.

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:

• pgflow schema with tables for flows, execution state, and worker management
• pgmq schema for message queuing
• SQL functions for worker lifecycle management and flow 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:

1. Detects your Supabase project directory
2. Updates your config.toml file
3. Copies the migration files
4. Creates the environment file
5. 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.