Skip to content

# Compile flow to SQL

Now that we’ve defined our flow, we need to register it in the database. pgflow provides a CLI tool that compiles your TypeScript flow definition into SQL migrations that can be applied to your Supabase database.

Not production ready

pgflow is currently in Alpha stage and not yet production ready.

## What is compilation?

Section titled “What is compilation?”

The pgflow compilation process:

1. Analyzes your TypeScript flow definition
2. Extracts information about steps, dependencies, and options
3. Generates SQL commands that register the flow and its structure in your database
4. Creates a migration file that can be applied to your database

This is an essential step because pgflow’s runtime executes flows based on their database representation, not the TypeScript code directly.

Prerequisites

Before continuing, make sure you have:

- Completed the flow definition from the previous step
- The Supabase CLI installed and configured
- Deno version 1.45.2 (required for flow compilation)

### 1. Compile the flow to SQL

Section titled “1. Compile the flow to SQL”

Run the pgflow compile command, pointing to your flow definition file:

    npx pgflow@latest compile supabase/functions/_flows/greet_user.ts

This will:

- Parse your TypeScript flow definition
- Extract the flow structure, step dependencies, and configuration
- Generate SQL commands to register the flow in the database
- Create a timestamped migration file in your Supabase migrations folder

You should see output like this:

    ✓ Successfully compiled flow to SQL✓ Migration file created: supabase/migrations/20250505120000_create_greet_user_flow.sql

### 2. Examine the generated SQL

Section titled “2. Examine the generated SQL”

Let’s look at what got generated. Open the migration file in your editor:

    cat supabase/migrations/*_create_greet_user_flow.sql

The migration file contains SQL commands that:

1. Create the flow definition
2. Add each step with its configuration
3. Define dependencies between steps

The generated SQL looks like this:

    SELECT pgflow.create_flow('greet_user');SELECT pgflow.add_step('greet_user', 'full_name');SELECT pgflow.add_step('greet_user', 'greeting', ARRAY['full_name']);

This SQL representation is what the pgflow runtime system uses to execute your workflow.

### 3. Apply the migration

Section titled “3. Apply the migration”

Now that we have the SQL migration, we need to apply it to our database:

    npx supabase migrations up

This will execute the SQL migration and register your flow definition in the database.

If successful, you should see output like:

    Applying migration 20250505120000_create_greet_user_flow.sql...done

Flow definitions are immutable

Once a flow is registered in the database, its structure cannot be modified. To change a flow, you can either delete it (development only) or use versioning.

Why immutability matters

What does immutability mean?

Once a flow is registered, you cannot modify its structure - no adding/removing steps, changing dependencies, or renaming steps.

Why this protects production:

- Running workflows continue safely through deployments
- Historical runs remain intact with their original structure
- Flows behave consistently from start to finish
- Complete audit trails are preserved

This ensures your production workflows are stable, predictable, and never break mid-execution.