Skip to content
pgflow (Workflow Engine for Supabase)
News

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.

What is compilation?

Section titled “What is compilation?”

pgflow compiles your TypeScript flow definition into SQL migrations that register the flow in your database.

  1. Analyze TypeScript flow definition
  2. Extract steps, dependencies, and options
  3. Generate SQL registration commands
  4. Create migration file

The runtime executes flows based on their database representation, not the TypeScript code directly.

  1. Compile the flow to SQL

    Section titled “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 “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 “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 this:

    Applying migration 20250505120000_create_greet_user_flow.sql...done