Setting up pgblame with Supabase

A 5-minute walkthrough for Supabase users.

1. Enable pg_stat_statements

Supabase has it available but not always enabled by default.

• Open your Supabase project's dashboard.
• Navigate to Database → Extensions.
• Search for pg_stat_statements.
• Toggle it on.

Alternatively, via SQL editor: CREATE EXTENSION IF NOT EXISTS pg_stat_statements; while connected as postgres.

2. Create a read-only role for pgblame

Don't give the agent your superuser credentials. Run this in the SQL editor:

-- Create the role
CREATE ROLE pgblame_reader WITH LOGIN PASSWORD '<choose-something-strong>';

-- Read pg_stat_statements (safe: no app data is exposed)
GRANT pg_read_all_stats TO pgblame_reader;

-- Allow it to connect
GRANT CONNECT ON DATABASE postgres TO pgblame_reader;

If you'd like to be even more restrictive, you can revoke its access to the public schema:

REVOKE ALL ON SCHEMA public FROM pgblame_reader;

It still works — pgblame only needs pg_stat_statements, which pg_read_all_stats covers.

3. Get the connection string

In Supabase: Settings → Database → Connection string. Use the Session Mode connection (not the transaction-mode pooler):

postgresql://pgblame_reader:<password>@db.<ref>.supabase.co:5432/postgres?sslmode=require

4. Get a project token from pgblame

In your pgblame dashboard:

• Click New project.
• Name it (e.g. "myapp-prod").
• The wizard runs a connection test against your Postgres, then issues a one-time token like pgb_xxxxxxxx. Copy it now; it's shown once.

5. Run the agent

docker run -d \
  --name pgblame-agent \
  --restart unless-stopped \
  -e PGBLAME_DATABASE_URL="postgresql://pgblame_reader:...@db.xxx.supabase.co:5432/postgres?sslmode=require" \
  -e PGBLAME_TOKEN="pgb_xxxxxxxx" \
  -v pgblame-data:/var/lib/pgblame \
  ghcr.io/liberzon/pgblame-agent:latest

It'll start sending data within 60–120 seconds (the first tick is a baseline; the second emits deltas).

6. Wire deploy webhooks

You probably deploy via Vercel or Railway. See:

• Vercel webhook setup
• Railway webhook setup

Troubleshooting