pgflow-dev · jumski · Nov 28, 2025
diff --git 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>` - Path to custom deno.json configuration file
 - `--supabase-path <path>` - Path to custom Supabase directory
+- `--control-plane-url <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
@@ -98,23 +98,10 @@ export default (program: Command) => {
       new Option('--secret-key [key]', 'Supabase anon/service_role key')
         .hideHelp()
     )
-    .option(
-      '--deno-json <denoJsonPath>',
-      '[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
@@ -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
@@ -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
@@ -63,7 +63,7 @@ const showFooter = isLandingPage || isAuthorPage;
         <ul>
           <li><a href="/get-started/installation/">Installation</a></li>
           <li><a href="/get-started/flows/create-flow/">Create Flow</a></li>
-          <li><a href="/get-started/flows/compile-flow/">Compile Flow</a></li>
+          <li><a href="/get-started/flows/quickstart/">Quickstart</a></li>
           <li><a href="/get-started/flows/run-flow/">Run Flow</a></li>
           <li><a href="/project-status/">Project Status</a></li>
           <li><a href="/get-started/faq/">FAQ</a></li>

diff --git 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
@@ -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.
 
+<Aside type="note" title="Production Deployment">
+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.
+</Aside>
+
 ## 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
@@ -19,6 +19,11 @@ Before deploying to production:
 - You have a Supabase project (free or paid tier)
 </Aside>
 
+<Aside type="note" title="ControlPlane Not Needed Yet">
+The `pgflow` ControlPlane function is for local compilation only.
+You do not need to deploy it to production yet - only deploy your worker functions.
+</Aside>
+
 ## 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
diff --git 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
 
 <CardGrid>

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
@@ -17,8 +17,9 @@ If you used `pgflow install`, the `greet-user-worker` is already scaffolded. You
 </Aside>
 
 <Aside type="caution" title="Prerequisites">
-Before starting, make sure you have completed:
-- [Compile flow to SQL](/get-started/flows/compile-flow/) guide
+Before starting, make sure you have:
+- Compiled your flow: `npx pgflow@latest compile <flowSlug>`
+- Applied migrations: `npx supabase migrations up`
 </Aside>
 
 <Steps>

diff --git 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
    ```
 
    <Aside type="note" title="What got installed?">
-   The installer creates:
-   - A `flows/` directory with an example `GreetUser` flow
-   - A `pgflow` Control Plane that handles flow compilation
-   - A `greet-user-worker` to run the example flow
+   <FileTree>
+   - supabase/
+     - flows/
+       - greet-user.ts (example flow)
+       - index.ts (exports)
+     - functions/
+       - pgflow/ (Control Plane for compilation)
+       - greet-user-worker/ (runs the example)
+     - migrations/
+       - ..._install_pgflow.sql
+   </FileTree>
    </Aside>
 
    Want to understand what's happening? See the [manual installation guide](/reference/manual-installation/).

diff --git a/...src/content/docs/news/pgflow-0-9-0-control-plane-and-http-based-compilation.mdx b/...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.
 
 <Aside type="tip" title="Need the Old Behavior?">
 If you need local Deno compilation, you can use the previous version:
@@ -90,16 +90,24 @@ export { GreetUser } from './greet-user.ts';
 export { MyOtherFlow } from './my-other-flow.ts';
 ```
 
-## Upgrading
+## Upgrading from v0.8.x
 
-Update your packages following the [Update pgflow guide](/deploy/update-pgflow/), then run:
+**Existing compiled flows continue to work** - no recompilation needed.
 
-```bash frame="none"
-npx pgflow@0.9.0 install
-```
+To compile **new flows** with v0.9.0:
 
-This creates the ControlPlane edge function at `supabase/functions/pgflow/`.
+1. Run `npx pgflow@0.9.0 install` to add the ControlPlane and `supabase/flows/` directory
+2. Create new flow files in `supabase/flows/`
+3. Export them from `supabase/flows/index.ts`
 
-<Aside type="caution" title="Register Your Flows">
-All existing flows must be added to the ControlPlane for compilation to work. See [Compilation](/concepts/compilation/) for details.
+<Aside type="note" title="Existing Flows">
+You don't need to move existing flow files. The new structure is only for
+flows you want to compile going forward. Move old flows only if you want
+consistency in your project structure.
 </Aside>
+
+### Removed: --deno-json flag
+
+The `--deno-json` flag has been removed. Compilation now uses the ControlPlane
+edge function instead of local Deno. If you used this flag in CI/CD scripts,
+update them to use the new compilation approach.