pgflow (Workflow Engine for Supabase) | News

pgflow 0.17.1: Private Step Queues and Anonymous Telemetry

Fri, 18 Sep 2026 00:00:00 GMT

0.17.0 shipped the queue identity work below; 0.17.1 adds anonymous telemetry to the same feature set. If you are upgrading from 0.16.x, this article covers the whole 0.17.x line.

pgflow now persists the physical queue identity of every step and task. pgflow.steps and pgflow.step_tasks gain a queue_name column that stores the canonical route, snapshotted when the task is created and never rewritten. A queued task’s message identity is (queue_name, message_id) instead of message_id alone - PGMQ message ids are queue-scoped, so the same id in two different queues can no longer be mistaken for the same message. Existing flows use queue_mode = 'flow' and retain lower(flow_slug). Wrap a new flow with withStepQueues() to use queue_mode = 'step': each step receives a generated private queue.

Read the data model for what is stored, and the update guide for the full 0.16.0 → 0.17.0 procedure.

pgflow.start_tasks() now requires the queue_name argument. The released three-argument form and the NULL default are gone: the database migration drops the old overload, and startTasks() on IPgflowClient/PgflowSqlClient requires the queue argument in TypeScript too. The argument is the task’s canonical persisted route - lower(flow_slug) in flow mode or the generated step route in step mode. Step-mode direct callers also pass the exact step_slug. pgflow’s own workers poll and claim through that route, so existing flows keep working unchanged, including queues that PGMQ still lists with an older mixed-case spelling - but custom code that calls start_tasks()/startTasks() directly must pass the canonical route explicitly; passing the polled mixed-case spelling of an upgraded queue matches nothing.

There is no rolling mixed-version upgrade. Old workers cannot claim tasks against the new schema; new workers cannot run against the old schema. Stop and drain everything, apply the migration, then deploy matching packages, workers, and explicit-queue callers together.

What changes

Queue identity snapshots. Every step records its route in steps.queue_name; every task copies it at creation (step_tasks.queue_name). Dispatch, claims, visibility, completion, retries, skip/cancel cascades, late callbacks, stalled recovery, and pruning all address the queue through the stored snapshot.
Private step queues. withStepQueues() derives one route for each step. Start one EdgeWorker entry point per selected stepSlug; each worker polls and claims only its own route.
Queue-scoped message identity. (queue_name, message_id) is unique per queue where message_id is set; message_id alone stays nullable. Message ids cross the JavaScript boundary as exact decimal strings (they can exceed the safe integer range).
Provisioning safeguards. Two flows can no longer address the same normalized default queue, and steps in one flow cannot differ only by case. A listed PGMQ queue with a colliding normalized name is rejected before a new flow is created, pgflow.flows is unique on lower(flow_slug), and pgflow.steps is unique on (flow_slug, lower(step_slug)) - including direct SQL creation.
Legacy mixed-case queues keep working. Queues created by earlier releases keep their original pgmq spelling. PGMQ’s public message API normalizes names, so pgflow addresses them by the stored canonical name directly - no per-message queue listing. Only queue deletion resolves the original spelling through pgmq.list_queues() (PGMQ drops queue metadata by exact listed name), rejecting an ambiguous match before any destructive work; the pruning helper’s archive walk derives table names from the canonical route (pgmq.format_table_name() lowercases it).
Optional pruning helper updated. The manually installed pgflow.prune_data_older_than() snippet cleans messages through task snapshots and archive tables through persisted routes. Replace an installed copy; adapt customized copies yourself.

Maintenance upgrade from 0.16.0

The ordered procedure with the exact SQL lives in the update guide. In short: update packages and copy migrations in advance, pause new producers, gracefully drain in-flight work while the old schema is present (waiting for running handlers to finish - not for queues to empty; queued tasks and messages are retained), stop every worker including HTTP re-invocation and long-running processes, quiesce maintenance/recovery/definition writers, apply the transactional migration through Supabase’s migration runner (against the production database - --linked or --db-url, not the local default), replace the pruning helper if installed, deploy the matching package set, then resume maintenance, workers, and producers in that order - restoring the exact worker enabled states recorded before the window.

The migration backfills existing steps and tasks with lower(flow_slug) and queue_mode = 'flow' - including tasks whose message_id is NULL - and fails atomically on conflicting data (flows differing only by slug case, case-only duplicate step slugs, invalid leading or trailing underscore or __ slugs, duplicate (queue_name, message_id) pairs, queue names beyond PGMQ’s 47-character limit). A failed migration leaves the database unchanged; resolve conflicts manually and re-run it. After a successful migration, old workers cannot simply restart. No queues or messages are migrated or recreated, and flow slug casing is untouched.

Anonymous telemetry

pgflow now includes anonymous, opt-out usage telemetry so development can be guided by real usage instead of guesses. Once per day your database summarizes yesterday’s activity into coarse buckets - active or not, versions running, run and worker counts, flow shapes, feature adoption - and sends one small JSON document. Nothing identifying ever leaves your database: no slugs, names, IDs, inputs, outputs, errors, or addresses.

You can inspect the exact bytes of every past report with select * from pgflow_telemetry.sent_reports, preview any day with pgflow_telemetry.preview(), and disable it permanently with one line:

select pgflow_telemetry.disable();

Read the full details - what is collected, what is never collected, where data lives and for how long - in the telemetry reference.

pgflow 0.16.0: Startup-Only Flow Compilation

Mon, 07 Sep 2026 00:00:00 GMT

This release makes worker startup the only supported way to deploy a flow. Every flow worker compiles or verifies its imported definition in the database before it registers itself and starts polling. A failed compilation registers nothing — no worker function is tracked, no worker row appears, and existing registrations stay untouched.

Read Startup Compilation for how deployment works now, and Versioning Flows for when a flow needs a new slug.

This release removes features that existing projects may still use:

the pgflow compile command and scripts or CI jobs that call it;
compileFlow() and migration-based flow deployment;
compareFlowShapes() from @pgflow/dsl;
ControlPlane, including the ControlPlane export, deployed supabase/functions/pgflow, and its [functions.pgflow] configuration;
FlowWorkerConfig.compilation, including compilation: false and allowDataLoss;
pgflow.ensure_flow_compiled(text, jsonb, boolean).

Do not apply the database migration while old workers are running. Stop and drain them first, update all pgflow packages and worker code together, remove the legacy configuration, apply the migration, then deploy the new workers. Old workers cannot start after the migration.

What is removed

compileFlow() and compareFlowShapes() from @pgflow/dsl — SQL text generation and the TypeScript comparator are gone. Shape comparison lives only in PostgreSQL (_compare_flow_shapes()).
ControlPlane — the HTTP SQL-compiler edge function, its export from @pgflow/edge-worker, and the supabase/functions/pgflow/ folder the installer used to create.
The pgflow compile CLI command.
The FlowWorkerConfig.compilation option in all its forms (false, {}, { allowDataLoss: true }). Stale properties in already-deployed JavaScript are ignored.
The production data-loss path: pgflow.ensure_flow_compiled(text, jsonb, boolean). The database migration drops this overload, so production can no longer authorize destructive recompilation. Local development keeps automatic destructive recompilation for same-slug mismatches (hot reload).

Upgrading HTTP worker functions

For each HTTP worker function:

Record its exact worker_functions.enabled value.
Set enabled = false, deprecate its workers, and wait for heartbeats and in-flight tasks to drain by following Update Deployed Flows.
Update pgflow, @pgflow/core, @pgflow/dsl, @pgflow/client, and @pgflow/edge-worker to the same version.
Run npx pgflow@latest install, review the copied migration, and apply it while old workers remain stopped.
Deploy workers that import their complete flow definitions.
Restore each recorded enabled value and check a fresh heartbeat.

Upgrading process workers

Stop the processes and external supervisors before applying the migration. Update the packages and database, then restart the supervisors.

Remove legacy project files and configuration

rm -rf supabase/functions/pgflow
npx supabase@latest functions delete pgflow --project-ref your-project-ref

your-project-ref is your Supabase project reference. The remote delete command is required only when the ControlPlane function was deployed.

Also remove any [functions.pgflow] block from supabase/config.toml, every pgflow compile script or CI step, and every worker compilation property. Keep existing generated flow migration files as immutable migration history — do not delete or rewrite migrations that a database already applied.

pgflow 0.15.1: Reliable Task Finalization and Recovery

Fri, 04 Sep 2026 00:00:00 GMT

This patch release hardens the task lifecycle. Tasks now reach a terminal state on every completion path, stalled-task recovery uses the right timeout, claimed tasks keep their queue visibility before handlers run, and npm install pgflow works again on Windows.

Tasks Under Skipped Steps

When a step was skipped via whenExhausted: 'skip' or 'skip-cascade' (or skipped by a cascade), sibling task rows stayed queued or started forever. The step was skipped, but its task rows never ended. This was reported in #638.

Task rows under a skipped step are now terminalized as skipped. Two ordering details make this safe:

Tasks are terminalized before their queue messages are archived, preserving the task-before-queue lock order.
start_tasks only returns rows it actually claimed, so workers no longer execute tasks that a concurrent skip already marked skipped.

Tasks on Failed Runs

When a run failed, unfinished task rows on that run stayed active. A late step callback or the stalled-task recovery job could then “finish” a task after its run had already failed. This was reported in #645.

Unfinished tasks are now marked cancelled when their run fails, and late callbacks and stalled recovery can no longer revive them.

Stalled-Task Recovery Uses the Step Timeout

Stalled tasks were requeued only after their flow timeout expired, so recovery for a short step inside a long flow waited far longer than necessary. This was reported in #621.

Requeue now uses the effective step timeout: the step timeout when set, otherwise the flow timeout.

Claim Visibility Before Handlers Run

start_tasks() claimed tasks but applied the PGMQ visibility extension in a way PostgreSQL could skip, so a claimed task sometimes kept only the initial read visibility. A handler that ran longer than that window made the queue message visible again, so a second worker could pick up the same task. This was reported in #656.

The visibility update is now structurally required (a referenced CTE instead of an unreferenced SELECT CTE), so every claimed task keeps the effective timeout (coalesce(step timeout, flow timeout) + 2) before handlers run, and a visibility-update failure rolls back the whole claim.

Windows Install Fixed

The CLI package’s postinstall script ran chmod on its bin file, which broke npm install pgflow on Windows. This was reported in #610.

The postinstall script is gone. npm sets the executable bit for bin files automatically, so a plain npm install pgflow works on Windows again.

Automatic Repair of Existing Data

The single consolidated migration 20260904095427_pgflow_task_lifecycle_hardening repairs existing task rows in the same order:

Active task rows (queued/started) under skipped steps become skipped.
Remaining active task rows on failed runs become cancelled.

Completed and genuinely failed tasks keep their outcomes, and all history fields are preserved. No manual action is required.

To pick up these fixes, follow Update pgflow.

pgflow 0.15.0: Standalone Workers with Node and Bun

Tue, 18 Aug 2026 00:00:00 GMT

pgflow workers are no longer tied to Supabase Edge Functions. This release publishes @pgflow/edge-worker to npm and adds a process runtime that runs workers as long-lived Node or Bun processes — on Railway, Fly.io, Docker, or any VM.

Run a worker with Node or Bun

Install the package with your package manager of choice, set your connection variables, and start a worker script:

npm add @pgflow/edge-worker
pnpm add @pgflow/edge-worker
bun add @pgflow/edge-worker

worker.ts

import { EdgeWorker } from '@pgflow/edge-worker';
import { ProcessOrders } from './flows/process-orders.js';

await EdgeWorker.start(ProcessOrders);

Process workers handle SIGTERM, SIGINT, and SIGQUIT with graceful drain: tasks finish, the worker is marked stopped, and connections close before exit.

See the Node/Bun Process Workers guide for deployment recipes and configuration.

Already using pgflow? 0.15.0 ships a database migration — follow Update pgflow before deploying process workers.

Supabase Edge Function improvements

Edge Function workers also got lifecycle hardening in this release:

Bounded shutdown. Shutdown finishes within a five-second deadline; PostgreSQL connections are force-closed if it expires.
Serialized startup. Concurrent requests share one startup; none observe a half-started worker.
Retry backoff. Persistent database failures back off exponentially (100 ms to 5 s) instead of hot-looping.

pgflow 0.14.0: Conditional Step Execution

Wed, 18 Mar 2026 00:00:00 GMT

pgflow 0.14.0 introduces conditional step execution - run steps based on input patterns and handle failures gracefully without failing the entire workflow.

Highlights

if / ifNot - Skip steps based on JSON containment patterns
whenUnmet - Control behavior when conditions aren’t met (fail, skip, skip-cascade)
whenExhausted - Handle step failures gracefully after all retries fail
Type-safe - TypeScript tracks which dependencies may be undefined

Pattern Matching with `if` / `ifNot`

Use if to run a step only when input contains a pattern:

.step({
  slug: 'premiumFeature',
  if: { plan: 'premium' },
  whenUnmet: 'skip',
}, handler)

Use ifNot to run a step only when input does NOT contain a pattern:

.step({
  slug: 'trialReminder',
  ifNot: { plan: 'premium' },
  whenUnmet: 'skip',
}, handler)

JSON Containment Semantics

Patterns use PostgreSQL’s @> containment operator. Your pattern only needs the fields you care about:

Input	Pattern	Match?
`{ plan: 'premium', name: 'Alice' }`	`{ plan: 'premium' }`	Yes
`{ plan: 'free' }`	`{ plan: 'premium' }`	No
`{ user: { role: 'admin', name: 'Bob' } }`	`{ user: { role: 'admin' } }`	Yes
`{ tags: ['urgent', 'support'] }`	`{ tags: ['urgent'] }`	Yes

See Pattern Matching for complete semantics.

Behavior Modes

The whenUnmet option controls what happens when a condition isn’t met:

Mode	Step	Dependents	Run
`fail`	Fails	Not executed	Fails
`skip`	Skipped	Receive `undefined`	Continues
`skip-cascade`	Skipped	All skipped	Continues

// Skip entire feature branch if condition not met
.step({
  slug: 'loadPremiumData',
  if: { plan: 'premium' },
  whenUnmet: 'skip-cascade',
}, handler)

See Skip Modes for detailed guidance on choosing modes.

Graceful Failure Handling

The new whenExhausted option controls what happens after all retries fail:

.step({
  slug: 'sendWelcomeEmail',
  dependsOn: ['createAccount'],
  maxAttempts: 3,
  whenExhausted: 'skip',  // Continue even if email fails
}, handler)

Use whenExhausted: 'skip' for non-critical steps like notifications, analytics, or enrichment that shouldn’t block the main workflow.

See Graceful Failure for patterns.

Type Safety

pgflow’s type system tracks which steps may be skipped:

.step({
  slug: 'processResults',
  dependsOn: ['optionalEnrichment'],
}, async (input) => {
  // TypeScript knows this may be undefined
  if (input.optionalEnrichment) {
    return processWithEnrichment(input.optionalEnrichment);
  }
  return processBasic(input.run);
})

With skip-cascade, dependent types remain required - if the step runs, the dependency is guaranteed.

Migration

This release includes schema changes. After upgrading, run:

npx pgflow@latest install

Then apply the new migration:

npx supabase db push

See Install pgflow for upgrade details.

Learn More

Conditional Steps Overview - Introduction to the feature
Pattern Matching - JSON containment patterns
Skip Modes - Detailed mode comparison
Graceful Failure - Handling failures with whenExhausted
Examples - AI/LLM patterns like query routing and RAG fallback

pgflow 0.13.3: Authentication Fix for ensure_workers and EdgeWorker

Tue, 03 Feb 2026 00:00:00 GMT

This release fixes a critical authentication issue where ensure_workers() fails to start Edge Workers due to key format mismatches, resulting in 401 Unauthorized errors. This resolves GitHub issue #603.

The Problem

Supabase stores the service role key in different formats depending on where you access it:

In Vault (used by ensure_workers): JWT format starting with eyJhbG...
In Edge Functions (SUPABASE_SERVICE_ROLE_KEY env var): Internal format starting with sb_secret_...

When ensure_workers sends an HTTP request to trigger a worker, it includes the JWT-format key from vault in the Authorization header. However, the Edge Worker validates this against SUPABASE_SERVICE_ROLE_KEY, which contains the sb_secret_... format. Since these strings don’t match, authentication fails with a 401 error.

The Solution

We’ve introduced PGFLOW_AUTH_SECRET - a user-controlled authentication secret that bypasses the format mismatch entirely:

Store your custom secret in vault as pgflow_auth_secret
Set the same value as PGFLOW_AUTH_SECRET in your Edge Function secrets
Both sides now use the identical string for authentication

How to Update

Update your pgflow installation and configure the new authentication secret:

Update your packages and migrations following the update guide

Set pgflow_auth_secret in vault (same value you’ll use in step 3):

SELECT vault.create_secret('your-secret-value', 'pgflow_auth_secret');

Set PGFLOW_AUTH_SECRET in your Edge Function secrets with the same value

See the Configure Secrets documentation for detailed setup instructions.

Backward Compatibility

For backwards compatibility, pgflow falls back to the legacy secrets if PGFLOW_AUTH_SECRET is not configured:

Database side: Falls back to supabase_service_role_key in vault
Edge Function side: Falls back to SUPABASE_SERVICE_ROLE_KEY env var

Existing deployments will continue to work without immediate changes, though we strongly recommend migrating to PGFLOW_AUTH_SECRET to avoid the format mismatch issues.

pgflow 0.13.2: Stalled Task Recovery and Config Fixes

Mon, 12 Jan 2026 00:00:00 GMT

This patch release fixes two issues: tasks getting stuck when workers crash, and the maxPgConnections config being ignored.

Stalled Tasks Automatic Recovery

The Problem

When a worker crashes or is terminated unexpectedly, tasks can get stuck in started status indefinitely. These “stalled” tasks never complete and block flow progress. This was reported in #586.

The Solution

A new pgflow.requeue_stalled_tasks() function automatically detects and recovers stalled tasks:

Runs via cron job every 15 seconds
Identifies tasks stuck in started status beyond their timeout + 30s buffer
Requeues them back to queued status (up to 3 times)
After 3 requeue attempts, archives the message and marks task with permanently_stalled_at timestamp for manual investigation

The cron job is set up automatically via migration. For more details, see the Troubleshooting Stalled Tasks guide.

Visibility Timeout Increase

Default visibility timeout increased from 2s to 5s to reduce the likelihood of tasks appearing stalled during normal processing delays.

Did This Affect You?

Run this query to check if you had stalled tasks before upgrading:

SELECT count(*)
FROM pgflow.step_tasks
WHERE status = 'started'
  AND started_at < now() - interval '5 minutes';

If you see results, those tasks will now be automatically recovered.

To find tasks that exceeded the max requeue limit (for manual investigation):

SELECT r.run_id, r.flow_slug, st.step_slug, st.requeued_count, st.permanently_stalled_at
FROM pgflow.step_tasks st
JOIN pgflow.runs r ON r.run_id = st.run_id
WHERE st.permanently_stalled_at IS NOT NULL;

Connection Config Fix

The Bug

The maxPgConnections configuration option was being ignored when passed to createFlowWorker().

The Fix

The config is now properly passed through the connection chain with a default of 4 connections.

Credits

Thanks to matz for reporting issue #586!

pgflow 0.13.1: CLI Fix + Step Output Storage for Conditional Execution

Sat, 03 Jan 2026 00:00:00 GMT

pgflow 0.13.1 fixes a compatibility issue with recent Supabase CLI versions and introduces atomic step output storage for 2x faster Map chains.

Supabase CLI Compatibility Fix

If local development stopped working after a Supabase CLI update, this release fixes it.

pgflow now detects local development by checking the SUPABASE_URL environment variable. When running locally, Supabase CLI sets this to http://kong:8000 (the Docker-internal API gateway). This is more reliable than the previous key-based detection, which broke when Supabase CLI transitioned to new opaque API keys.

Step Output Storage

What Changed

Step outputs are now stored in step_states.output when a step completes, rather than being aggregated on-demand.

How It Worked Before

Previously, every time a downstream step needed its dependency’s output, pgflow ran an aggregation query:

SELECT jsonb_agg(output ORDER BY index)
FROM pgflow.step_tasks
WHERE run_id = $1 AND step_slug = $2

For a Map step with 500 items, this query scanned 500 rows. When another Map step depended on it with 500 tasks, that’s 500 tasks x 500 rows = 250,000 row scans.

Performance Gains

With outputs pre-stored, downstream tasks now read a single column instead of aggregating:

Benchmark	Before	After	Improvement
Start 500 tasks reading 500-element output	189s	87s	2.17x faster

The complexity dropped from O(N^2) to O(N) for Map-to-Map chains.

Simpler Manual Queries

Querying step outputs is now straightforward:

-- Get output for a specific step in a run
SELECT output
FROM pgflow.step_states
WHERE run_id = 'run-abc' AND step_slug = 'process';

-- Get all step outputs for a run
SELECT step_slug, output
FROM pgflow.step_states
WHERE run_id = 'run-abc';

No need to aggregate from step_tasks - the output is ready to use.

Migration Guide

This release includes a data migration that backfills step_states.output for existing completed steps.

Test locally with production data

Download a production backup and restore it locally to test the migration. See Restoring a downloaded backup in the Supabase docs, then run npx supabase db push to test the migration.
Record enabled worker functions

Before disabling, note which functions are currently enabled:
```
SELECT function_name FROM pgflow.worker_functions WHERE enabled = true;
```
Save this list - you’ll need it in step 7.

Disable all worker functions

UPDATE pgflow.worker_functions SET enabled = false;

Deprecate running workers

UPDATE pgflow.workers
SET deprecated_at = NOW()
WHERE deprecated_at IS NULL
  AND stopped_at IS NULL;

Wait for all workers to stop

SELECT COUNT(*) FROM pgflow.workers WHERE stopped_at IS NULL;

Wait until this returns 0.

Apply database migration
```
npx supabase db push
```

Deploy workers and re-enable

Deploy your workers and re-enable only the functions that were enabled before:

npx supabase functions deploy

UPDATE pgflow.worker_functions
SET enabled = true
WHERE function_name IN ('worker-1', 'worker-2');  -- from step 2

Looking Ahead

This change stores step outputs in a queryable location - a prerequisite for conditional execution. Future releases will use these stored outputs to evaluate conditions and skip steps dynamically.

Questions or issues? Join the Discord community or open a GitHub issue.

pgflow 0.12.0: Simpler Handler Signatures for Flow Composition

Wed, 24 Dec 2025 00:00:00 GMT

pgflow 0.12.0 introduces asymmetric handler signatures - a breaking change that removes the run wrapper from step inputs, enabling cleaner functional composition and preparing the foundation for subflows.

What Changed

Handler signatures are now asymmetric. The input.run pattern no longer exists.

// 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?

The previous run wrapper blocked functional composition:

// OLD: The run wrapper created type mismatches
// Root steps received: { run: flowInput }
// Dependent steps received: { run: flowInput, dep1: output1 }

// This meant subflows couldn't compose cleanly:
const ChildFlow = new Flow<{ data: string }>()
  .step({ slug: "process" }, (input) => {
    // Expected: input.data
    // Received: { run: parentInput, prep: { data: "..." } }
    // TYPE MISMATCH!
  });

By removing the wrapper, outputs from one flow can become inputs to another without transformation.

Upgrading Your Flows

Apply these patterns to update your handlers. The red/green highlights show exactly what changes.

Migration Patterns

Root Steps (same for `.step` and `.array`)

// BEFORE
.step({ slug: 'init' }, (input) => {
  return { userId: input.run.userId };
})

// AFTER
.step({ slug: 'init' }, (flowInput) => {
  return { userId: flowInput.userId };
})

Dependent Steps - Needing flowInput

// BEFORE
.step({ slug: 'process', dependsOn: ['init'] }, (input) => {
  const config = input.run.config;
  const data = input.init.data;
  return combine(data, config);
})

// AFTER (must be async)
.step({ slug: 'process', dependsOn: ['init'] }, async (deps, ctx) => {
  const flowInput = await ctx.flowInput;
  const config = flowInput.config;
  const data = deps.init.data;
  return combine(data, config);
})

Dependent Steps - Not Needing flowInput (Common Case)

// BEFORE
.step({ slug: 'save', dependsOn: ['process'] }, (input) => {
  return saveToDb(input.process.result);
})

// AFTER
.step({ slug: 'save', dependsOn: ['process'] }, (deps) => {
  return saveToDb(deps.process.result);
})

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:

// BEFORE (accessing flowInput)
.map({ slug: 'transform', array: 'items' }, (item) => {
  return process(item);
})

// 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);
})

Production Upgrade Guide

The upgrade requires careful coordination to avoid running old code against the new SQL schema.

Update handlers locally and test

Update all your flow handlers to the new signatures. Test locally:
```
npx supabase functions serve my-worker
```

Disable worker functions

Prevent cron from starting new workers with old code:

UPDATE pgflow.worker_functions
SET enabled = false
WHERE function_name = 'my-worker';

Deprecate existing workers
```
UPDATE pgflow.workers
SET deprecated_at = NOW()
WHERE function_name = 'my-worker'
  AND deprecated_at IS NULL;
```
Deprecated workers finish their current task but won’t call start_tasks again - so they won’t be affected by the SQL changes.

Wait for workers to stop

Monitor workers until all have exited:

SELECT COUNT(*) FROM pgflow.workers
WHERE function_name = 'my-worker'
  AND stopped_at IS NULL;

Wait until this returns 0 before proceeding.

Apply database migration
```
npx supabase db push
```
Deploy new workers
```
npx supabase functions deploy my-worker
```

Enable worker functions

UPDATE pgflow.worker_functions
SET enabled = true
WHERE function_name = 'my-worker';

The pgflow cron automatically starts new workers within seconds.

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 or open a GitHub issue.

pgflow 0.11.0: Compilation Configuration Overhaul

Fri, 12 Dec 2025 00:00:00 GMT

pgflow 0.11.0 introduces a redesigned compilation configuration system. The new compilation option provides clearer semantics and adds support for rapid iteration platforms like Lovable through the allowDataLoss flag.

Highlights

New compilation config - Grouped compilation options with clearer semantics
allowDataLoss option - Enable destructive recompilation in production for rapid iteration
Breaking change - ensureCompiledOnStartup removed in favor of compilation

What’s New: The `compilation` Config

The compilation behavior is now controlled by a single compilation option:

// Default: auto-detect environment
EdgeWorker.start(MyFlow);

// Skip compilation (flows pre-compiled via CLI)
EdgeWorker.start(MyFlow, { compilation: false });

// Allow destructive recompile in production
EdgeWorker.start(MyFlow, { compilation: { allowDataLoss: true } });

When to Use Each Option

Option	Use Case
(not set)	Standard development and production - auto-detects environment
`compilation: false`	CI/CD pipelines with pre-compiled flows
`compilation: { allowDataLoss: true }`	Rapid iteration platforms (Lovable)

The `allowDataLoss` Option

The new allowDataLoss flag enables local-development behavior in production environments. When a flow shape mismatch is detected:

Deletes the existing flow and all its run data
Compiles the new flow from the TypeScript definition
Worker continues with the new schema

Target Use Case: Lovable and Similar Platforms

The allowDataLoss option was designed for platforms like Lovable where:

Flow definitions change frequently during development
Execution history doesn’t need to persist between iterations
Speed of iteration matters more than data durability
Users expect “just works” behavior without manual intervention

Breaking Changes

`ensureCompiledOnStartup` Removed

The ensureCompiledOnStartup option has been replaced by the new compilation config.

Before (0.10.x):

// Skip compilation
EdgeWorker.start(MyFlow, { ensureCompiledOnStartup: false });

// Enable compilation (default)
EdgeWorker.start(MyFlow, { ensureCompiledOnStartup: true });

After (0.11.0):

// Skip compilation
EdgeWorker.start(MyFlow, { compilation: false });

// Enable compilation (default) - just don't set the option
EdgeWorker.start(MyFlow);

Migration Guide

If you were using ensureCompiledOnStartup:

Old Config	New Config
`ensureCompiledOnStartup: true`	Remove (or use `compilation: {}`)
`ensureCompiledOnStartup: false`	`compilation: false`

Upgrade Now

Follow the standard Update pgflow guide to update packages and apply migrations.

Quick Migration

Update your packages:
```
npx pgflow@latest install
```
Find and replace in your worker files:
- ensureCompiledOnStartup: false → compilation: false
- ensureCompiledOnStartup: true → remove the option entirely
Apply database migrations:
```
supabase db push
```

pgflow 0.10.0: Auto-Compilation and Worker Management

Wed, 10 Dec 2025 00:00:00 GMT

pgflow 0.10.0 is a developer experience milestone. This release eliminates two of the biggest friction points in pgflow development: manual flow compilation and worker lifecycle management.

Highlights

Auto-compilation at startup - Workers verify and compile flows automatically
Intelligent worker management - Database-driven cron keeps workers running reliably
Beautiful local logging - Colored output with retry information and exponential backoff display

Auto-Compilation: Never Compile Manually Again

Previously, every flow change required running pgflow compile, dropping old flow data with ‘pgflow.delete_flow_and_data()’ and migrating database, all before you can test your flow. This release introduces automatic flow compilation and previous version deletion that happens when workers start.

How It Works

When a worker starts, it calls the new ensure_flow_compiled() function which:

Checks if the flow exists - If not, compiles it immediately
Compares flow shapes - Verifies the TypeScript definition matches the database
Auto-recompiles in development - Detects local Supabase and just deletes previous version and compiles new one
Fails safely in production - Returns an error instead of deleting/recompiling

Why This Matters

This achieves full watch-mode in local development:

Change your flow definition in TypeScript
Supabase detects the change and starts new function
Cron polls the function, starting new worker automatically
Flow is compiled and ready - no manual step required

And a convenient “deploy updated flow, no need for migrations” workflow on production:

Production worker only compiles new flows
Mismatches are caught immediately with clear error messages, worker refuses to start

Configuration

Auto-compilation is enabled by default. To opt out:

EdgeWorker.start(MyFlow, {
  ensureCompiledOnStartup: false,
});

Worker Management: Set It and Forget It

Managing worker lifecycles on hosted Supabase has been a pain point. Edge Functions have CPU time limits, worker contantly respanw themselves for continuos operation and to make it reliable one needed to setup a manual cron schedule.

pgflow 0.10.0 introduces built-in worker management that handles all of this automatically.

The Worker Management System

Each worker function (edge function having EdgeWorker.start()) is tracked in new pgflow.worker_functions table.

When you install 0.10.0 migrations, it will setup a new pgflow_ensure_workers cron job runs every second and:

Tracks registered workers from the worker_functions table
Detects dead workers - Uses heartbeats and stopped_at timestamps
Invokes workers when needed - Pings edge functions via HTTP to spawn new workers
Debounces intelligently - Prevents spawning too many workers simultaneously
Only invokes HTTP requests when needed, saving on invocations and egress.

Why This Matters

Before 0.10.0:

Set up manual pg_cron jobs with watchdog logic
Workers died and stayed dead until manually restarted
Risk of spawning too many workers under load

After 0.10.0:

Workers register themselves automatically
Dead workers are detected and replaced within seconds
Debouncing prevents worker storms
Graceful shutdown signals prevent false-positive restarts

Production Credentials

The worker management system uses Vault secrets to invoke edge functions:

supabase_service_role_key - For authentication
supabase_project_id - To build the function URL

Structured Logging: See What Matters

The new logging system adapts to your environment automatically.

Local Development (Fancy Format)

Features:

Colored icons (green checkmarks, red X, yellow retry arrows)
Worker-prefixed lines for multi-worker clarity
Flow/step paths for context
Retry countdown with exponential backoff calculation

Production (Simple Format)

[INFO] worker=analyze-website queue=pgflow_tasks flow=analyze_website status=verified worker_id=abc123
[VERBOSE] worker=analyze-website flow=analyze_website step=scrape status=completed duration_ms=127
[VERBOSE] worker=analyze-website flow=analyze_website step=analyze status=failed error="Rate limit" retry=1/3 retry_delay_s=5

Features:

Structured key=value format for log aggregators
Appropriate log levels (INFO, VERBOSE, DEBUG)
All context included for filtering and alerting

Configuration

The format is auto-detected based on environment, but you can override:

# Force fancy format in production (not recommended)
EDGE_WORKER_LOG_FORMAT=fancy

# Set log level explicitly
EDGE_WORKER_LOG_LEVEL=debug  # error < warn < info < verbose < debug

# Disable colors (respects NO_COLOR standard)
NO_COLOR=1

Breaking Changes

None. All new features are additive and existing workflows continue to work unchanged.

Upgrade Now

Follow the standard Update pgflow guide to update packages and apply migrations.

Remove Old Watchdog Cron Jobs

pgflow now sets up the pgflow_ensure_workers cron automatically during migration. If you previously set up manual cron jobs to keep workers running (from older documentation), remove them:

-- Check for old watchdog jobs
SELECT jobid, jobname, schedule, command
FROM cron.job
WHERE jobname LIKE '%watchdog%'
   OR command LIKE '%invoke%function%';

-- Remove old jobs (replace ID with actual jobid)
SELECT cron.unschedule(jobid) FROM cron.job WHERE jobname LIKE '%watchdog%';

Questions or issues? Open a GitHub issue or join the discussion on Discord.

pgflow 0.9.1: Unified Connection Configuration

Tue, 02 Dec 2025 00:00:00 GMT

This release unifies how the edge worker handles database connections - zero-config local development, a clear priority chain, and proper SSL support.

What’s New

connectionString now works (#469, #424) - The connectionString config option was being ignored. Now it works, enabling patterns like falling back to SUPABASE_DB_URL.
Pass raw postgres.js connection - Use config.sql to pass your own postgres.js instance with custom options (SSL, connection pooling, etc.).
Zero-config local dev - When local environment is detected (via known local dev keys), the worker automatically connects to the local transaction pooler. No environment variables needed.
Cleaner install - pgflow install no longer writes EDGE_WORKER_DB_URL to .env since local dev works without it.

Connection Priority

The edge worker now resolves database connections in this order:

config.sql - Full control with custom postgres instance
config.connectionString - Explicit URL in code
EDGE_WORKER_DB_URL - Environment variable
Local fallback - Auto-detected local Supabase pooler

If nothing is configured and local Supabase is not detected, the worker throws a clear error explaining the options.

New Documentation

The Supabase deployment guide has been revamped from a single page into a structured overview with dedicated pages for each topic:

Supabase Deployment Overview - Step-by-step guide structure
Database Connection - Overview of connection options
Preview Branches - Handling dynamic environments
Database SSL - Configuring SSL for external databases
Troubleshooting Connections - Common issues and solutions

Issues Addressed

#469 - connectionString config was being ignored
#424 - Simplified local development setup
Discussion #280 - Preview branch connection patterns

Thanks

This release was shaped by community feedback. Thanks to Nciso, mikz, ddlaws0n, and PixelEcho (Discord) for reporting issues, suggesting improvements, and helping improve the documentation.

pgflow 0.9.0: Control Plane and HTTP-Based Compilation

Fri, 28 Nov 2025 00:00:00 GMT

pgflow 0.9.0 introduces the ControlPlane edge function, enabling HTTP-based flow compilation without requiring a local Deno installation.

What Changed

The CLI no longer spawns Deno processes locally. Instead, compilation requests go through the ControlPlane edge function:

pgflow compile my_flow  -->  ControlPlane  -->  SQL migration

This simplifies the development setup and lays groundwork for future auto-compilation features where workers will verify and compile flows at startup without any CLI involvement.

Breaking Changes

Compile Command

The pgflow compile command now takes a flow slug instead of a file path:

Before (0.8.x):

pgflow compile path/to/my_flow.ts --deno-json supabase/functions/deno.json

After (0.9.0):

pgflow compile my_flow

The --deno-json flag has been removed.

New Install Experience

The installer now scaffolds a complete working setup:

npx pgflow@0.9.0 install

This creates:

supabase/flows/ - Directory for flow definitions with namespace imports
supabase/flows/greet-user.ts - Example GreetUser flow
supabase/functions/pgflow/ - Control Plane for compilation
supabase/functions/greet-user-worker/ - Example worker ready to run

The installer shows a clear summary and asks for a single confirmation before making changes.

Namespace Imports for Flows

ControlPlane now supports namespace imports, the recommended pattern:

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

ControlPlane.serve(flows);

Add flows by exporting from flows/index.ts:

export { GreetUser } from './greet-user.ts';
export { MyOtherFlow } from './my-other-flow.ts';

Upgrading from v0.8.x

Existing compiled flows continue to work - no recompilation needed.

To compile new flows with v0.9.0:

Run npx pgflow@0.9.0 install to add the ControlPlane and supabase/flows/ directory
Create new flow files in supabase/flows/
Export them from supabase/flows/index.ts

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.

pgflow 0.8.0: Modernizing Dependencies - pgmq 1.5.0 and PostgreSQL 17

Tue, 18 Nov 2025 00:00:00 GMT

pgflow 0.8.0 requires pgmq 1.5.0 or higher and PostgreSQL 17. This release removes the pgmq compatibility layer and prepares the foundation for upcoming flow auto-compilation features.

What’s Changing

pgflow 0.8.0 introduces breaking dependency changes:

pgmq version: Now requires 1.5.0 or higher (previously supported 1.4.x)
PostgreSQL version: Upgrades to PostgreSQL 17 (from 15)
Supabase CLI: Requires version 2.50.3 or higher (includes pgmq 1.5.0+)
Deno version: Now requires 2.1.x or higher (previously 1.45.x)

The migration will fail safely if these requirements are not met - no partial upgrades or corrupted state.

Background

This release skips backward compatibility entirely - pgflow 0.8.0 requires pgmq 1.5.0 from the start. Maintaining compatibility layers for older versions would accumulate technical debt that becomes harder to remove as the project matures.

Additionally, upcoming features like flow auto-compilation depend on infrastructure available only in newer Supabase versions (automatic edge function respawning in local development). Moving to pgmq 1.5.0 and PostgreSQL 17 unblocks these improvements.

Before You Upgrade

Check Your pgmq Version

Run this query to verify your current pgmq version:

SELECT extversion FROM pg_extension WHERE extname = 'pgmq';

You need version 1.5.0 or higher to upgrade to pgflow 0.8.0.

Check Your Deno Version

Verify your Deno installation meets the minimum requirement:

deno --version

You need Deno 2.1.x or higher (previously 1.45.x). If you need to upgrade, see the Deno installation guide.

Compatibility Check Built-In

The migration includes a pre-check that inspects the pgmq schema before making any changes. If pgmq 1.5.0 is not detected, the migration aborts with this error:

ERROR: INCOMPATIBLE PGMQ VERSION DETECTED

This migration requires pgmq 1.5.0 or higher.
The pgmq.message_record type is missing the "headers" column,
which indicates you are running pgmq < 1.5.0.

Action required:
  - Supabase: Ensure you are running a recent version that includes pgmq 1.5.0+
  - Self-hosted: Upgrade pgmq to version 1.5.0 or higher before running this migration

Migration aborted to prevent runtime failures.

This safety check prevents partial migrations and data corruption.

Migration Guide

Supabase Cloud Users

Supabase CLI version 2.50.3 or higher includes pgmq 1.5.0 by default.

Update your Supabase CLI if needed:

supabase -v  # Check current version
npm install -g supabase  # Update if below 2.50.3

Verify your pgmq version using the SQL query above
Run your migrations:
```
supabase db push
```

Self-Hosted Users

You must upgrade pgmq to 1.5.0+ before upgrading pgflow.

Check your current pgmq version
Upgrade pgmq to 1.5.0 or higher following the pgmq upgrade guide
Upgrade PostgreSQL to version 17 if not already running it
Run your pgflow migrations:
```
supabase db push
```

For questions or issues with the upgrade, visit the pgflow Discord or open a GitHub issue.

pgflow 0.7.3: Improved Supabase Realtime Connection Reliability

Mon, 17 Nov 2025 00:00:00 GMT

pgflow 0.7.3 introduces a configurable realtimeStabilizationDelayMs option that addresses a known Supabase Realtime limitation where backend routing isn’t fully established when the SUBSCRIBED event is emitted.

What’s New

The TypeScript client now includes a realtimeStabilizationDelayMs configuration option (default: 300ms) that adds a delay after subscribing to Realtime channels. This works around a known Supabase Realtime issue where messages sent immediately after subscription confirmation may be missed because backend routing takes additional time to fully establish.

When starting flows or retrieving runs, the client waits for this stabilization period after receiving the SUBSCRIBED event, ensuring that all subsequent realtime events are properly received.

Configuration

The default 300ms delay works reliably in most environments. If you experience missed events or connection issues, increase the delay to 400-500ms:

import { PgflowClient } from '@pgflow/client';

// Increase stabilization delay for unreliable connections
const pgflow = new PgflowClient(supabase, {
  realtimeStabilizationDelayMs: 400,
});

You can also disable the delay by setting it to 0, though this may cause missed events in some environments:

// Disable delay (may cause missed events)
const pgflow = new PgflowClient(supabase, {
  realtimeStabilizationDelayMs: 0,
});

See the TypeScript Client documentation and PgflowClient API reference for complete details.

Upgrading

Follow the update guide to upgrade your @pgflow/client dependency to 0.7.3.

Questions or issues? Join our Discord community or open an issue on GitHub.

pgflow 0.7.2: Fix Missing Realtime Broadcasts for Step Events

Tue, 04 Nov 2025 00:00:00 GMT

pgflow 0.7.2 fixes missing realtime broadcasts that prevented clients from receiving step:started and step:completed events. PostgreSQL’s query optimizer was eliminating CTEs containing realtime.send() calls because they weren’t referenced by subsequent operations.

What’s Fixed

step:started events now broadcast when steps begin executing
step:completed events now broadcast for empty map steps
step:completed events now broadcast for cascade completions
Client applySnapshot() methods added for proper initial state hydration without event emission

Additional Changes

Enhanced test coverage for realtime event lifecycles
Documentation updates for abort signal support and empty map step behavior

Upgrading

Questions or issues? Join our Discord community or open an issue on GitHub.

pgflow 0.7.1: Fix pgmq 1.5.1 Version Conflict on New Supabase Projects

Thu, 30 Oct 2025 00:00:00 GMT

pgflow 0.7.1 fixes installation failures on fresh Supabase projects caused by pgmq version mismatch.

The Bug

Installing pgflow on new Supabase projects failed with:

ERROR: extension "pgmq" has no installation script nor update path for version "1.4.4" (SQLSTATE 22023)
At statement: 2
CREATE EXTENSION IF NOT EXISTS "pgmq" WITH SCHEMA "pgmq" VERSION "1.4.4"

Why It Happened

Supabase upgraded to pgmq 1.5.1 in Postgres 17.6.1.016+ (supabase/postgres#1668). pgflow’s initial migration was pinned to version 1.4.4, which no longer exists in new Supabase instances.

The Fix

Removed the version constraint from pgmq extension creation. pgflow now uses whatever pgmq version Supabase provides (1.4.4, 1.5.1, or newer).

CREATE EXTENSION IF NOT EXISTS "pgmq" WITH SCHEMA "pgmq" VERSION "1.4.4";
CREATE EXTENSION IF NOT EXISTS "pgmq" WITH SCHEMA "pgmq";

Credits

Thanks to @kallebysantos for reporting this issue!

pgflow 0.7.0: Public Beta with Map Steps and Documentation Redesign

Sun, 19 Oct 2025 00:00:00 GMT

pgflow 0.7.0 is here - a major milestone that brings parallel array processing, production-ready stability, and a complete documentation redesign.

pgflow Enters Public Beta

pgflow has transitioned from alpha to public beta. Core functionality is stable and reliable, with early adopters already running pgflow in production environments.

This milestone reflects months of testing, bug fixes, and real-world usage feedback. The SQL Core, DSL, and Edge Worker components have proven robust across different workloads and deployment scenarios.

See the project status page for production recommendations and known limitations.

Map Steps

Map steps enable parallel array processing by automatically creating multiple tasks - one for each array element.

import { Flow } from '@pgflow/dsl/supabase';

const BatchProcessor = new Flow<string[]>({
  slug: 'batchProcessor',
  maxAttempts: 3,
})
  .map(
    { slug: 'processUrls' },
    async (url) => {
      // Each URL gets its own task with independent retry
      return await scrapeWebpage(url);
    }
  );

Why this matters:

When processing 100 URLs, if URL #47 fails, only that specific task retries - the other 99 continue processing. With a regular step, one failure would retry all 100 URLs.

This independent retry isolation makes flows more efficient and resilient. Each task has its own retry counter, timeout, and execution context.

Map steps handle edge cases automatically:

Empty arrays complete immediately without creating tasks
Type violations fail gracefully with stored output for debugging
Results maintain array order regardless of completion sequence

Learn more: Map Steps and Process Arrays in Parallel

Array Steps

The new .array() method provides compile-time type safety for array-returning handlers:

// Enforces array return type at compile time
flow.array({ slug: 'items' }, () => [1, 2, 3]);  // Valid

flow.array({ slug: 'invalid' }, () => 42);  // Compile error

Array steps are a semantic wrapper that makes intent clear and moves type errors from .map() to .array(). When a map step depends on a regular step that doesn’t return an array, the compiler catches it too - .array() just makes the error location more precise and the code intention explicit.

TypeScript Client - Now Fully Documented

The @pgflow/client package, initially released in v0.4.0 but never widely announced, now has complete documentation. This type-safe client powers the pgflow demo and provides both promise-based and event-based APIs for starting workflows and monitoring real-time progress from TypeScript environments (browsers, Node.js, Deno, React Native).

Features include type-safe flow management with automatic inference from flow definitions, real-time progress monitoring via Supabase broadcasts, and extensive test coverage.

Learn more: TypeScript Client Guide | @pgflow/client API Reference

Documentation Restructure and New Landing Page

The entire documentation has been reorganized from a feature-based structure to a user-journey-based structure, making it easier to find what you need at each stage of using pgflow.

Before	After

New documentation includes:

Build section - Guides for starting flows, organizing code, processing arrays, and managing versions
Deploy section - Production deployment guides for Supabase
Concepts - Understanding map steps, context object, data model, and architecture
@pgflow/client API Reference - Complete client library documentation

Redesigned Landing Page

The homepage has been completely rebuilt with animated DAG visualization, interactive before/after code comparisons, and streamlined messaging. Visit pgflow.dev to explore the new experience.

Developer Experience Improvements

Copy to Markdown on All Docs Pages - Every documentation page now includes contextual menu buttons to copy the page as markdown or open it directly in Claude Code or ChatGPT for context-aware assistance.

Additional improvements:

Full deno.json Support - pgflow compile now uses --config flag for complete deno.json support
Fixed config.toml Corruption - CLI no longer corrupts minimal config.toml files (thanks to @DecimalTurn)
Better Type Inference - Improved DSL type inference for .array() and .map() methods
Compile-time Duplicate Slug Detection - Prevents duplicate step slugs before deployment

Reliability Improvements

Enhanced Failure Handling - Automatic archival of queued messages when runs fail, with stored output for debugging
Fixed Data Pruning Bug - Resolved foreign key constraint issue preventing cleanup operations
Comprehensive integration tests for map steps and enhanced type testing infrastructure

Upgrading to 0.7.0

See the update guide for complete instructions.

Questions or issues with the upgrade? Join our Discord community or open an issue on GitHub.

pgflow 0.6.1: Worker Configuration in Handler Context

Fri, 05 Sep 2025 00:00:00 GMT

pgflow 0.6.1 adds workerConfig to the handler execution context, enabling intelligent decision-making based on worker configuration.

Worker Configuration in Context

Handlers now have access to the complete worker configuration through context.workerConfig (#200). This enables smarter handlers that can adapt their behavior based on retry limits, concurrency settings, timeouts, and other worker parameters.

async function sendEmail(input, context) {
  const isLastAttempt = context.rawMessage.read_ct >= context.workerConfig.retry.limit;

  if (isLastAttempt) {
    // Use fallback email service on final attempt
    return await sendWithFallbackProvider(input.to, input.subject, input.body);
  }

  // Use primary email service for regular attempts
  return await sendWithPrimaryProvider(input.to, input.subject, input.body);
}

See the context documentation for complete details on available configuration properties and additional examples.

Bug Fix

This release also fixes retry strategy validation to only enforce the 50-limit cap for exponential retry strategy, allowing higher limits for fixed strategy when needed (#199).

Updating to 0.6.1

Follow our update guide for step-by-step upgrade instructions.

pgflow 0.6.0: Worker Deprecation and Context Changes

Wed, 06 Aug 2025 00:00:00 GMT

pgflow 0.6.0 introduces worker deprecation for deployments without version overlap and simplifies the context object with breaking changes.

Worker Deprecation

Deploy new workers without version overlap. Deprecated workers stop accepting new tasks while finishing current work.

-- Deprecate old workers before starting new ones
UPDATE pgflow.workers
SET deprecated_at = NOW()
WHERE function_name = 'your-worker-name'
  AND deprecated_at IS NULL;

Workers detect deprecation within 5 seconds via heartbeat and gracefully stop polling. The deployment guide has been simplified with a single safe deployment sequence.

Breaking Context Changes

The context object is now cleaner and more consistent:

Before (0.5.x):

async function handler(input, context) {
  const { data } = await context.serviceSupabase
    .from('users')
    .select('*');
}

After (0.6.0):

async function handler(input, context) {
  const { data } = await context.supabase
    .from('users')
    .select('*');
}

Migration

Update context usage: context.serviceSupabase → context.supabase
Remove any context.anonSupabase usage
Use worker deprecation for smooth deployments

The service role client is now the primary Supabase interface, simplifying database operations in handler functions.

pgflow (Workflow Engine for Supabase) | News

pgflow 0.17.1: Private Step Queues and Anonymous Telemetry

What changes

Maintenance upgrade from 0.16.0

Anonymous telemetry

pgflow 0.16.0: Startup-Only Flow Compilation

What is removed

Upgrading HTTP worker functions

Upgrading process workers

Remove legacy project files and configuration

pgflow 0.15.1: Reliable Task Finalization and Recovery

Tasks Under Skipped Steps

Tasks on Failed Runs

Stalled-Task Recovery Uses the Step Timeout

Claim Visibility Before Handlers Run

Windows Install Fixed

Automatic Repair of Existing Data

pgflow 0.15.0: Standalone Workers with Node and Bun

Run a worker with Node or Bun

Supabase Edge Function improvements

pgflow 0.14.0: Conditional Step Execution

Highlights

Pattern Matching with if / ifNot

JSON Containment Semantics

Behavior Modes

Graceful Failure Handling

Type Safety

Migration

Learn More

pgflow 0.13.3: Authentication Fix for ensure_workers and EdgeWorker

The Problem

The Solution

How to Update

Backward Compatibility

pgflow 0.13.2: Stalled Task Recovery and Config Fixes

Stalled Tasks Automatic Recovery

The Problem

The Solution

Visibility Timeout Increase

Did This Affect You?

Connection Config Fix

The Bug

The Fix

Credits

pgflow 0.13.1: CLI Fix + Step Output Storage for Conditional Execution

Supabase CLI Compatibility Fix

Step Output Storage

What Changed

How It Worked Before

Performance Gains

Simpler Manual Queries

Migration Guide

Looking Ahead

pgflow 0.12.0: Simpler Handler Signatures for Flow Composition

What Changed

Why This Change?

Upgrading Your Flows

Migration Patterns

Root Steps (same for .step and .array)

Dependent Steps - Needing flowInput

Dependent Steps - Not Needing flowInput (Common Case)

Map Steps (no change needed if only using item)

Production Upgrade Guide

Other Fixes

pgflow 0.11.0: Compilation Configuration Overhaul

Highlights

What’s New: The compilation Config

When to Use Each Option

The allowDataLoss Option

Target Use Case: Lovable and Similar Platforms

Breaking Changes

ensureCompiledOnStartup Removed

Migration Guide

Upgrade Now

Quick Migration

pgflow 0.10.0: Auto-Compilation and Worker Management

Highlights

Auto-Compilation: Never Compile Manually Again

How It Works

Why This Matters

Pattern Matching with `if` / `ifNot`

Root Steps (same for `.step` and `.array`)

Map Steps (no change needed if only using `item`)

What’s New: The `compilation` Config

The `allowDataLoss` Option

`ensureCompiledOnStartup` Removed