From 65fbd11b22e1eb92c791bde3e2f3e95b312ed561 Mon Sep 17 00:00:00 2001 From: Wojtek Majewski Date: Fri, 26 Dec 2025 00:15:38 +0100 Subject: [PATCH] update docs --- ...auto-compilation-and-worker-management.mdx | 2 +- .../news/pgflow-0-11-0-compilation-config.mdx | 2 +- ...andler-signatures-for-flow-composition.mdx | 144 +++++++----------- ...a-map-steps-and-documentation-redesign.mdx | 2 +- ...q-version-conflict-with-supabase-1-5-1.mdx | 2 +- ...ng-realtime-broadcasts-for-step-events.mdx | 2 +- ...pabase-realtime-connection-reliability.mdx | 2 +- ...endencies-pgmq-1-5-0-and-postgresql-17.mdx | 2 +- ...ntrol-plane-and-http-based-compilation.mdx | 2 +- 9 files changed, 67 insertions(+), 93 deletions(-) diff --git a/pkgs/website/src/content/docs/news/pgflow-0-10-0-auto-compilation-and-worker-management.mdx b/pkgs/website/src/content/docs/news/pgflow-0-10-0-auto-compilation-and-worker-management.mdx index f05ee0a7c..0820fdfb6 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-10-0-auto-compilation-and-worker-management.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-10-0-auto-compilation-and-worker-management.mdx @@ -10,7 +10,7 @@ tags: - auto-compilation - worker-management - developer-experience -featured: true +featured: false --- import { Aside } from "@astrojs/starlight/components"; diff --git a/pkgs/website/src/content/docs/news/pgflow-0-11-0-compilation-config.mdx b/pkgs/website/src/content/docs/news/pgflow-0-11-0-compilation-config.mdx index 1823bc5ff..5d2fb6da1 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-11-0-compilation-config.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-11-0-compilation-config.mdx @@ -10,7 +10,7 @@ tags: - compilation - configuration - breaking-change -featured: true +featured: false --- import { Aside } from "@astrojs/starlight/components"; diff --git a/pkgs/website/src/content/docs/news/pgflow-0-12-0-simpler-handler-signatures-for-flow-composition.mdx b/pkgs/website/src/content/docs/news/pgflow-0-12-0-simpler-handler-signatures-for-flow-composition.mdx index fcc533ec9..50149b95d 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-12-0-simpler-handler-signatures-for-flow-composition.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-12-0-simpler-handler-signatures-for-flow-composition.mdx @@ -1,5 +1,5 @@ --- -draft: true +draft: false title: 'pgflow 0.12.0: Simpler Handler Signatures for Flow Composition' description: 'Breaking change: asymmetric handler signatures remove the run wrapper, enabling functional composition' date: 2025-12-24 @@ -18,17 +18,25 @@ pgflow 0.12.0 introduces asymmetric handler signatures - a breaking change that ## What Changed -Handler signatures are now asymmetric based on step type: +Handler signatures are now **asymmetric**. The `input.run` pattern no longer exists. -| Step Type | Before | After | -|-----------|--------|-------| -| Root step | `(input) => input.run.xxx` | `(flowInput, ctx) => flowInput.xxx` | -| Dependent step | `(input) => input.dep.xxx` | `(deps, ctx) => deps.dep.xxx` | -| Dependent (needs flowInput) | `(input) => input.run.xxx` | `async (deps, ctx) => (await ctx.flowInput).xxx` | -| Map step | `(item) => ...` | `async (item, ctx) => (await ctx.flowInput).xxx` | +```typescript del="input" del="input.run" del="input.dep" ins="flowInput" ins="deps" ins="async " ins="deps, ctx" ins="(await ctx.flowInput)" + +// Root steps +(input) => input.run.xxx +(flowInput) => flowInput.xxx + +// Dependent steps +(input) => input.dep.xxx +(deps) => deps.dep.xxx + +// Dependent needing flowInput +(input) => input.run.xxx +async (deps, ctx) => (await ctx.flowInput).xxx +``` ## Why This Change? @@ -49,74 +57,23 @@ const ChildFlow = new Flow<{ data: string }>() }); ``` -By removing the wrapper, outputs from one flow can now become inputs to another without transformation. - -## New Handler Signatures - -### Root Steps - -Root steps receive flow input directly as the first parameter: - -```typescript -// .step() - root -.step({ slug: 'init' }, (flowInput, ctx) => { - console.log(ctx.env.API_KEY); // Context still available - return { userId: flowInput.userId }; -}) - -// .array() - root (returns array for parallel processing) -.array({ slug: 'fetchAll' }, (flowInput, ctx) => { - return flowInput.urls; // Returns array directly -}) -``` - -### Dependent Steps +By removing the wrapper, outputs from one flow can become inputs to another without transformation. -Dependent steps receive only their dependencies as the first parameter. Access `flowInput` via context if needed (async): - -```typescript -// .step() - dependent (needs flowInput) - must be async -.step({ slug: 'process', dependsOn: ['init'] }, async (deps, ctx) => { - const flowInput = await ctx.flowInput; // Lazy-loaded, must await - const config = flowInput.config; - const data = deps.init.userId; // Dependencies directly - return { result: process(data, config) }; -}) - -// .step() - dependent (doesn't need flowInput - most common) -.step({ slug: 'save', dependsOn: ['process'] }, (deps) => { - return deps.process.result; // Just use deps -}) - -// .array() - dependent -.array({ slug: 'splitResults', dependsOn: ['process'] }, (deps, ctx) => { - return deps.process.items; // Returns array for parallel processing -}) -``` - -### Map Steps + -Map steps receive individual array elements. Access `flowInput` via context (async): +## Upgrading Your Flows -```typescript -// .map() - processes each array element (async if needs flowInput) -.map({ slug: 'processItem', array: 'fetchAll' }, async (item, ctx) => { - const flowInput = await ctx.flowInput; // Lazy-loaded, must await - return transform(item, flowInput.config); -}) -``` +Apply these patterns to update your handlers. The red/green highlights show exactly what changes. -## Upgrading Your Flows - ### Migration Patterns -Apply these transformations to your handlers: - -#### Root Steps (.step, .array) +#### Root Steps (same for `.step` and `.array`) ```typescript del="input" del="input.run" ins="flowInput" // BEFORE @@ -130,18 +87,6 @@ Apply these transformations to your handlers: }) ``` -```typescript del="input" del="input.run" ins="flowInput" -// BEFORE -.array({ slug: 'getUrls' }, (input) => { - return input.run.urls; -}) - -// AFTER -.array({ slug: 'getUrls' }, (flowInput) => { - return flowInput.urls; -}) -``` - #### Dependent Steps - Needing flowInput ```typescript del="input" del="input.run" del="input.init" ins="async" ins="deps, ctx" ins="await ctx.flowInput" ins="deps.init" @@ -175,15 +120,17 @@ Apply these transformations to your handlers: }) ``` -#### Map Steps - Accessing flowInput +#### Map Steps (no change needed if only using `item`) + +Most map steps just use `item` and need no changes. Only update if you need `flowInput`: ```typescript ins="async" ins="item, ctx" ins="await ctx.flowInput" -// BEFORE +// BEFORE (accessing flowInput) .map({ slug: 'transform', array: 'items' }, (item) => { return process(item); }) -// AFTER (if you need flowInput - must be async) +// AFTER (must be async to access flowInput) .map({ slug: 'transform', array: 'items' }, async (item, ctx) => { const flowInput = await ctx.flowInput; return process(item, flowInput.options); @@ -192,6 +139,16 @@ Apply these transformations to your handlers: ### Production Upgrade Guide +The upgrade requires careful coordination to avoid running old code against the new SQL schema. + + + 1. **Update handlers locally and test** @@ -223,19 +180,31 @@ Apply these transformations to your handlers: Deprecated workers finish their current task but won't call `start_tasks` again - so they won't be affected by the SQL changes. -4. **Apply database migration** +4. **Wait for workers to stop** + + Monitor workers until all have exited: + + ```sql + SELECT COUNT(*) FROM pgflow.workers + WHERE function_name = 'my-worker' + AND stopped_at IS NULL; + ``` + + Wait until this returns `0` before proceeding. + +5. **Apply database migration** ```bash frame="none" npx supabase db push ``` -5. **Deploy new workers** +6. **Deploy new workers** ```bash frame="none" npx supabase functions deploy my-worker ``` -6. **Enable worker functions** +7. **Enable worker functions** ```sql UPDATE pgflow.worker_functions @@ -247,6 +216,11 @@ Apply these transformations to your handlers: +## Other Fixes + +- Fixed `CONNECT_TIMEOUT` errors on Lovable.dev by switching to `jsr:@oscar6echo/postgres` fork +- Fixed `setTimeout` context binding issue in `@pgflow/client` for browser compatibility + --- Questions or issues? Join the [Discord community](https://discord.gg/pgflow) or [open a GitHub issue](https://github.com/pgflow-dev/pgflow/issues). diff --git a/pkgs/website/src/content/docs/news/pgflow-0-7-0-public-beta-map-steps-and-documentation-redesign.mdx b/pkgs/website/src/content/docs/news/pgflow-0-7-0-public-beta-map-steps-and-documentation-redesign.mdx index 1e7b293b9..f776a3209 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-7-0-public-beta-map-steps-and-documentation-redesign.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-7-0-public-beta-map-steps-and-documentation-redesign.mdx @@ -14,7 +14,7 @@ tags: - dsl - cli - client -featured: true +featured: false cover: alt: 'Cyberpunk workflow engine with glowing teal circuits processing parallel data streams' image: '../../../assets/cover-images/pgflow-0-7-0-public-beta-map-steps-and-documentation-redesign.png' diff --git a/pkgs/website/src/content/docs/news/pgflow-0-7-1-fix-pgmq-version-conflict-with-supabase-1-5-1.mdx b/pkgs/website/src/content/docs/news/pgflow-0-7-1-fix-pgmq-version-conflict-with-supabase-1-5-1.mdx index 04c499680..a6af17303 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-7-1-fix-pgmq-version-conflict-with-supabase-1-5-1.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-7-1-fix-pgmq-version-conflict-with-supabase-1-5-1.mdx @@ -9,7 +9,7 @@ tags: - bugfix - supabase - pgmq -featured: true +featured: false --- import { Aside } from "@astrojs/starlight/components"; diff --git a/pkgs/website/src/content/docs/news/pgflow-0-7-2-fix-missing-realtime-broadcasts-for-step-events.mdx b/pkgs/website/src/content/docs/news/pgflow-0-7-2-fix-missing-realtime-broadcasts-for-step-events.mdx index b459d13d0..02a42b4ae 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-7-2-fix-missing-realtime-broadcasts-for-step-events.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-7-2-fix-missing-realtime-broadcasts-for-step-events.mdx @@ -10,7 +10,7 @@ tags: - realtime - client - core -featured: true +featured: false --- import { Aside } from "@astrojs/starlight/components"; diff --git a/pkgs/website/src/content/docs/news/pgflow-0-7-3-improved-supabase-realtime-connection-reliability.mdx b/pkgs/website/src/content/docs/news/pgflow-0-7-3-improved-supabase-realtime-connection-reliability.mdx index bb589133e..3783d1108 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-7-3-improved-supabase-realtime-connection-reliability.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-7-3-improved-supabase-realtime-connection-reliability.mdx @@ -9,7 +9,7 @@ tags: - bugfix - realtime - client -featured: true +featured: false --- import { Aside } from "@astrojs/starlight/components"; diff --git a/pkgs/website/src/content/docs/news/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.mdx b/pkgs/website/src/content/docs/news/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.mdx index e7365542f..f8b8dc5ff 100644 --- a/pkgs/website/src/content/docs/news/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.mdx +++ b/pkgs/website/src/content/docs/news/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.mdx @@ -9,7 +9,7 @@ tags: - release - breaking-change - migration -featured: true +featured: false cover: alt: 'Cyberpunk hacker upgrading database dependencies on a glitchy terminal screen' image: '../../../assets/cover-images/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.png' 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 6d92d89b7..8dbfcbaca 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 @@ -9,7 +9,7 @@ tags: - release - control-plane - compilation -featured: true +featured: false --- import { Aside } from "@astrojs/starlight/components";