Skip to content

# Compile API

The `compileFlow` function converts Flow objects into SQL statements that can be executed directly in PostgreSQL. Use this when you need to inspect the generated SQL or integrate flow compilation into custom tooling.

## Usage

Section titled “Usage”

Import `compileFlow` from `@pgflow/dsl` and pass it a Flow object:

    import { Flow, compileFlow } from '@pgflow/dsl';
    type Input = {  url: string;};
    const MyFlow = new Flow<Input>({  slug: 'my_flow',  maxAttempts: 3,  timeout: 60,})  .step({ slug: 'fetch' }, (input) => input.run.url)  .step({ slug: 'process', dependsOn: ['fetch'] }, (input) => ({    url: input.run.url,    content: input.fetch,  }));
    const statements = compileFlow(MyFlow);// Returns: string[]

Output (array of SQL statements):

    [  "SELECT pgflow.create_flow('my_flow', max_attempts => 3, timeout => 60);",  "SELECT pgflow.add_step('my_flow', 'fetch');",  "SELECT pgflow.add_step('my_flow', 'process', ARRAY['fetch']);"]

## Executing the SQL

Section titled “Executing the SQL”

The generated statements should be executed within a single transaction:

    import postgres from 'postgres';
    const sql = postgres('postgresql://...');const statements = compileFlow(MyFlow);
    await sql.begin(async (tx) => {  for (const statement of statements) {    await tx.unsafe(statement);  }});

Caution

Always execute the statements within a transaction to ensure the flow is either fully created or not created at all. This prevents partial flow definitions if an error occurs.

Note

The standard approach uses `pgflow compile` to generate migration files instead of executing SQL directly. Manual compilation is useful for debugging, custom tooling, or understanding the SQL layer.