Skip to content

compilation.mdx

Latest commit

 

History

History
92 lines (63 loc) · 3.89 KB

compilation.mdx

File metadata and controls

92 lines (63 loc) · 3.89 KB
title Compilation
description How pgflow compiles TypeScript flows to SQL via HTTP
sidebar
order
25

import { Aside } from "@astrojs/starlight/components";

pgflow compiles TypeScript flow definitions to SQL migrations via an HTTP-based architecture. This design eliminates the need for a local Deno installation and ensures compilation uses the same runtime as production.

How It Works

When you run pgflow compile greetUser, the following happens:

┌─────────────┐     HTTP GET      ┌─────────────────────┐
│  pgflow CLI │ ─────────────────>│  ControlPlane Edge  │
│             │                   │      Function       │
│             │                   │                     │
│             │     SQL Array     │  1. Look up flow    │
│             │ <─────────────────│  2. Call compileFlow│
│             │                   │  3. Return SQL      │
│             │                   └─────────────────────┘
│  4. Write   │
│  migration  │
└─────────────┘

  1. CLI sends request - The compile command sends an HTTP GET request to: http://127.0.0.1:54321/functions/v1/pgflow/flows/{slug}

  2. ControlPlane looks up flow - The edge function has a registry of flows (from your index.ts). It finds the flow by slug.

  3. Compilation happens in Deno - The ControlPlane calls compileFlow() from @pgflow/dsl, which extracts the flow structure and generates SQL.

  4. SQL returned to CLI - The response contains an array of SQL statements.

  5. CLI writes migration - The CLI joins the SQL and writes it to supabase/migrations/{timestamp}_create_{slug}_flow.sql.

The ControlPlane Edge Function

The pgflow edge function is created during installation and serves as your project's ControlPlane:

import { ControlPlane } from '@pgflow/edge-worker';
import * as flows from '../../flows/index.ts';

ControlPlane.serve(flows);

The ControlPlane:

  • Registers flows by slug in an in-memory registry
  • Exposes the /flows/:slug endpoint for compilation
  • Returns 404 if a flow slug is not found in the registry
  • Returns 500 with error details if compilation fails

Why HTTP-Based Compilation?

This architecture provides several benefits:

No local Deno required - Users don't need Deno installed on their machine. The Supabase Edge Functions runtime handles everything.

Same runtime as production - Flows are compiled using the exact same Deno environment they'll run in, eliminating "works on my machine" issues.

Consistent dependency resolution - The deno.json import map in your edge function ensures consistent package versions.

Simpler CLI - The CLI is a lightweight Node.js package that makes HTTP requests, rather than needing to bundle the entire compilation infrastructure.

The ControlPlane is currently used for local development compilation only. In future releases, it will be deployed to production for auto-compilation features where workers verify and compile flows at startup. For now, only deploy your worker functions to production.

Adding New Flows

To make a flow available for compilation:

  1. Create the flow definition in supabase/flows/
  2. Export it from supabase/flows/index.ts

The ControlPlane automatically picks up all flows exported from your flows/index.ts.

When running `supabase functions serve`, code changes are detected automatically and the ControlPlane reloads with your new flows.

API Reference

For detailed HTTP endpoint documentation, see ControlPlane API Reference.