diff --git a/pkgs/cli/README.md b/pkgs/cli/README.md index c29f9eaf1..82e9d7e3c 100644 --- a/pkgs/cli/README.md +++ b/pkgs/cli/README.md @@ -16,7 +16,6 @@ This package provides essential tools for setting up, managing, and deploying pg ## Prerequisites - Supabase CLI v2.50.3 or higher -- Deno v2.1.x or higher (for flow compilation) - Local Supabase project initialized ## Installation @@ -70,8 +69,8 @@ npx pgflow@latest compile my_flow Options: -- `--deno-json ` - Path to custom deno.json configuration file - `--supabase-path ` - Path to custom Supabase directory +- `--control-plane-url ` - ControlPlane URL (default: `http://127.0.0.1:54321/functions/v1/pgflow`) The compiler will: diff --git a/pkgs/cli/src/commands/compile/index.ts b/pkgs/cli/src/commands/compile/index.ts index 994842b0a..c48a528e7 100644 --- a/pkgs/cli/src/commands/compile/index.ts +++ b/pkgs/cli/src/commands/compile/index.ts @@ -98,23 +98,10 @@ export default (program: Command) => { new Option('--secret-key [key]', 'Supabase anon/service_role key') .hideHelp() ) - .option( - '--deno-json ', - '[DEPRECATED] No longer used. Will be removed in v1.0' - ) .action(async (flowSlug, options) => { intro('pgflow - Compile Flow to SQL'); try { - // Show deprecation warning for --deno-json - if (options.denoJson) { - log.warn( - 'The --deno-json flag is deprecated and no longer used.\n' + - 'Flow compilation now happens via HTTP, not local Deno.\n' + - 'This flag will be removed in v1.0' - ); - } - // Validate Supabase path let supabasePath: string; if (options.supabasePath) { diff --git a/pkgs/website/astro.config.mjs b/pkgs/website/astro.config.mjs index 2e71facc3..adbfc0b20 100644 --- a/pkgs/website/astro.config.mjs +++ b/pkgs/website/astro.config.mjs @@ -168,7 +168,6 @@ export default defineConfig({ 'get-started/installation', 'get-started/flows/quickstart', 'get-started/flows/create-flow', - 'get-started/flows/compile-flow', 'get-started/flows/run-flow', 'concepts/how-pgflow-works', 'concepts/data-model', diff --git a/pkgs/website/redirects.config.mjs b/pkgs/website/redirects.config.mjs index b30f31912..765639f95 100644 --- a/pkgs/website/redirects.config.mjs +++ b/pkgs/website/redirects.config.mjs @@ -49,7 +49,8 @@ export const redirects = { '/getting-started/': '/get-started/installation/', '/getting-started/install-pgflow/': '/get-started/installation/', '/getting-started/create-first-flow/': '/get-started/flows/create-flow/', - '/getting-started/compile-to-sql/': '/get-started/flows/compile-flow/', + '/getting-started/compile-to-sql/': '/get-started/flows/quickstart/', + '/get-started/flows/compile-flow/': '/get-started/flows/quickstart/', '/getting-started/run-flow/': '/get-started/flows/run-flow/', '/getting-started/configuration/': '/reference/configuration/', '/getting-started/update-pgflow/': '/deploy/update-pgflow/', diff --git a/pkgs/website/src/components/PageFrame.astro b/pkgs/website/src/components/PageFrame.astro index 61ca3e40e..2010d11f9 100644 --- a/pkgs/website/src/components/PageFrame.astro +++ b/pkgs/website/src/components/PageFrame.astro @@ -63,7 +63,7 @@ const showFooter = isLandingPage || isAuthorPage;
  • Installation
  • Create Flow
    • -
  • Compile Flow
    • +
  • Quickstart
  • Run Flow
  • Project Status
  • FAQ
    • diff --git a/pkgs/website/src/content/docs/build/version-flows.mdx b/pkgs/website/src/content/docs/build/version-flows.mdx index 378fc1511..7d4b52ea9 100644 --- a/pkgs/website/src/content/docs/build/version-flows.mdx +++ b/pkgs/website/src/content/docs/build/version-flows.mdx @@ -68,7 +68,7 @@ Put the new flow in its own file with a versioned slug. 2. **Compile it** - [Compile the new flow to SQL](/get-started/flows/compile-flow/) which generates a migration file: + Compile the new flow to SQL to generate a migration file: ```bash frame="none" npx pgflow@latest compile greetUserV2 diff --git a/pkgs/website/src/content/docs/concepts/compilation.mdx b/pkgs/website/src/content/docs/concepts/compilation.mdx index 63caaaf20..015239754 100644 --- a/pkgs/website/src/content/docs/concepts/compilation.mdx +++ b/pkgs/website/src/content/docs/concepts/compilation.mdx @@ -67,6 +67,13 @@ This architecture provides several benefits: **Simpler CLI** - The CLI is a lightweight Node.js package that makes HTTP requests, rather than needing to bundle the entire compilation infrastructure. + + ## Adding New Flows To make a flow available for compilation: diff --git a/pkgs/website/src/content/docs/deploy/supabase/deploy-first-flow.mdx b/pkgs/website/src/content/docs/deploy/supabase/deploy-first-flow.mdx index c812a3182..e4d039b08 100644 --- a/pkgs/website/src/content/docs/deploy/supabase/deploy-first-flow.mdx +++ b/pkgs/website/src/content/docs/deploy/supabase/deploy-first-flow.mdx @@ -19,6 +19,11 @@ Before deploying to production: - You have a Supabase project (free or paid tier) + + ## Get Your Database Connection String Your workers need to connect to the production database: diff --git a/pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx b/pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx deleted file mode 100644 index ef87b40a2..000000000 --- a/pkgs/website/src/content/docs/get-started/flows/compile-flow.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Compile flow to SQL -description: Learn how to compile your flow definition to SQL and apply it to your database -sidebar: - order: 30 ---- - -import { Aside, Steps } from "@astrojs/starlight/components"; - -Now that we've defined our flow and registered it, we need to compile it to SQL and apply it to your database. - - - - - -1. ### Start edge functions - - Open a terminal and start the edge functions server: - - ```bash frame="none" - npx supabase functions serve - ``` - - - -2. ### Compile the flow - - In a **separate terminal**, run the compile command with the flow slug: - - ```bash frame="none" - npx pgflow@latest compile greetUser - ``` - - - - You should see output like this: - - ``` - Successfully compiled flow to SQL - Migration file created: supabase/migrations/20250505120000_create_greetUser_flow.sql - ``` - -3. ### Examine the generated SQL (optional) - - Let's look at what got generated: - - ```bash frame="none" - cat supabase/migrations/*_create_greetUser_flow.sql - ``` - - The generated SQL looks like this: - - ```sql - SELECT pgflow.create_flow('greetUser'); - SELECT pgflow.add_step('greetUser', 'fullName'); - SELECT pgflow.add_step('greetUser', 'greeting', ARRAY['fullName']); - ``` - - :::tip[Step Configuration] - This is a simple example showing basic step registration. Steps can also be configured with retry behavior, timeouts, and delays. See [Step Execution Options](/reference/configuration/step-execution/) for all available configuration options. - ::: - -4. ### Apply the migration - - Apply the migration to register the flow in your database: - - ```bash frame="none" - npx supabase migrations up - ``` - - You should see: - - ``` - Applying migration 20250505120000_create_greetUser_flow.sql...done - ``` - - - -:::note[How compilation works] -The compile command sends an HTTP request to your local `pgflow` edge function, which compiles the TypeScript and returns SQL. This approach uses the same Deno runtime as production, ensuring consistency. - -
    -Learn more - -When you run `pgflow compile greetUser`: - -1. The CLI sends a request to `http://127.0.0.1:54321/functions/v1/pgflow/flows/greetUser` -2. The ControlPlane edge function looks up the flow in its registry -3. It compiles the flow to SQL using `@pgflow/dsl` -4. The CLI receives the SQL and writes it to a migration file - -See [Compilation](/concepts/compilation/) for more details. -
    -::: - -## Troubleshooting - -### "Could not connect to ControlPlane" - -Make sure edge functions are running: - -```bash frame="none" -npx supabase functions serve -``` - -### "Flow not found" - -The flow is not registered in `index.ts`. Make sure you: - -1. Imported your flow in `supabase/functions/pgflow/index.ts` -2. Added it to the `ControlPlane.serve([...])` array - -:::note[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](/build/delete-flows/) (development only) or use [versioning](/build/version-flows/). - -
    -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. -
    -::: diff --git a/pkgs/website/src/content/docs/get-started/flows/quickstart.mdx b/pkgs/website/src/content/docs/get-started/flows/quickstart.mdx index afa737214..3df7a2323 100644 --- a/pkgs/website/src/content/docs/get-started/flows/quickstart.mdx +++ b/pkgs/website/src/content/docs/get-started/flows/quickstart.mdx @@ -119,6 +119,20 @@ Want to modify the flow structure? Flows are immutable once registered - this pr **In production:** Create a [versioned flow](/build/version-flows/) (e.g., `greetUserV2`) to preserve history. +## Troubleshooting + +### "Could not connect to ControlPlane" + +Make sure edge functions are running: + +```bash frame="none" +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 diff --git a/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx b/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx index 30a88c27c..4ce1a1adf 100644 --- a/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx +++ b/pkgs/website/src/content/docs/get-started/flows/run-flow.mdx @@ -17,8 +17,9 @@ If you used `pgflow install`, the `greet-user-worker` is already scaffolded. You diff --git a/pkgs/website/src/content/docs/get-started/installation.mdx b/pkgs/website/src/content/docs/get-started/installation.mdx index 88f9d10bc..24304d70e 100644 --- a/pkgs/website/src/content/docs/get-started/installation.mdx +++ b/pkgs/website/src/content/docs/get-started/installation.mdx @@ -30,10 +30,17 @@ If you haven't installed the CLI yet or need to upgrade, see Supabase's [install ``` Want to understand what's happening? See the [manual installation guide](/reference/manual-installation/). diff --git a/pkgs/website/src/content/docs/news/pgflow-0-9-0-control-plane-and-http-based-compilation.mdx b/pkgs/website/src/content/docs/news/pgflow-0-9-0-control-plane-and-http-based-compilation.mdx index 556854e21..6d92d89b7 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-9-0-control-plane-and-http-based-compilation.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-9-0-control-plane-and-http-based-compilation.mdx @@ -46,7 +46,7 @@ pgflow compile path/to/my_flow.ts --deno-json supabase/functions/deno.json pgflow compile my_flow ``` -The `--deno-json` flag is deprecated and will be removed in v1.0. +The `--deno-json` flag has been removed.