Quickstart

See pgflow in action using the GreetUser flow scaffolded during installation.

Prerequisites

• Completed the pgflow installation
• Supabase running locally (npx supabase start)
• Migrations applied (npx supabase migrations up)

1. Start edge functions

   Open a terminal and start the edge functions server:

   npx supabase functions serve --no-verify-jwt

   About --no-verify-jwt

   The --no-verify-jwt flag disables JWT authentication for local development.

   Keep this terminal open.

2. Compile the flow

   In a new terminal, compile the GreetUser flow:

   npx pgflow@latest compile greetUser

   You should see:

   Successfully compiled flow to SQL
   Migration file created: supabase/migrations/..._create_greetUser_flow.sql

3. Apply the migration

   Apply the migration to register the flow in your database:

   npx supabase migrations up

   Want to modify this flow later?

   Once applied, flow structure is immutable. See Iterating on your flow below for the development workflow.

4. Start the worker

   Send an HTTP request to start the scaffolded worker:

   curl http://localhost:54321/functions/v1/greet-user-worker

   You should see worker activity in the edge functions terminal.

5. Trigger your first flow

   Open Supabase Studio (http://localhost:54323), go to the SQL Editor, and run:

   SELECT * FROM pgflow.start_flow(
     flow_slug => 'greetUser',
     input => '{"firstName": "Alice", "lastName": "Smith"}'::jsonb
   );

6. Check the result

   After a moment, query the run status:

   SELECT * FROM pgflow.runs
   WHERE flow_slug = 'greetUser'
   ORDER BY started_at DESC
   LIMIT 1;

   You should see status: completed with output:

   {"greeting": "Hello, Alice Smith!"}

What just happened?

Expand for details

1. Compilation converted your TypeScript flow to a SQL migration
2. Migration registered the flow structure in Postgres
3. Worker began polling for tasks on the greetUser queue
4. Steps executed in dependency order: fullName ran first, then greeting used its output

The GreetUser flow demonstrates the core pgflow pattern - steps with dependencies that pass data between them.

Iterating on your flow

Want to modify the flow structure? Flows are immutable once registered - this protects running workflows.

During development: Delete the flow and recompile. This removes all run data, so only use locally.

In production: Create a versioned flow (e.g., greetUserV2) to preserve history.

Troubleshooting

”Could not connect to ControlPlane”

Make sure edge functions are running:

npx supabase functions serve --no-verify-jwt

“Flow not found”

Register your flow in supabase/functions/pgflow/index.ts and restart the functions server.

Next steps

Understand the code Learn how the scaffolded GreetUser flow works

How pgflow works Understand the execution model behind the scenes

Iterate on flows Delete and recreate flows during development