PgFlow: Elixir vs Supabase (TypeScript/Deno)

Both implementations share the same base PostgreSQL schema and SQL orchestration layer. They can run side-by-side against the same database.

Architecture

Flow Definition

TypeScript — fluent builder with method chaining:

const flow = new Flow<{ orderId: number }>({ slug: 'process_order' })
  .step({ slug: 'validate' }, (input) => ({ valid: true }))
  .step({ slug: 'charge', dependsOn: ['validate'] }, (deps) => ({ charged: true }))
  .map({ slug: 'notify' }, (item) => ({ sent: true }))

Elixir — macro DSL:

defmodule ProcessOrder do
  use PgFlow.Flow
  @flow queue: :process_order, max_attempts: 3

  step :validate do
    fn input, _ctx -> %{valid: true} end
  end

  step :charge, depends_on: [:validate] do
    fn deps, _ctx -> %{charged: true} end
  end

  map :notify do
    fn item, _ctx -> %{sent: true} end
  end
end

Both compile to identical SQL: pgflow.create_flow() + pgflow.add_step().

Step Types

Step/Flow Options

Handler Context

Both lazy-load flow input to avoid unnecessary DB queries for non-root steps.

Worker Model

TypeScript: Stateless Edge Functions

Supabase Edge Function (triggered per batch)
  → register worker → heartbeat → processBatch → exit
  → Horizontal scaling via multiple function instances
  → Worker deprecation via is_deprecated flag
  → ensure_workers() pings functions via pg_cron

Elixir: Long-Running OTP GenServers

PgFlow.Supervisor (rest_for_one)
├── Task.Supervisor
├── Signal.Notify (when signal_strategy: :notify)
├── WorkerSupervisor (dynamic)
│   └── Worker.Server (one per flow/job)
├── StalledTaskRecovery
└── :flow_starter (one-shot registration)

Polling Protocol

Both use the same two-phase protocol:

1. Reserve messages from pgmq (makes them invisible)
2. pgflow.start_tasks() — atomically claim tasks, return details
3. Execute handler
4. pgflow.complete_task() or pgflow.fail_task()

Difference in phase 1:

TypeScript uses blocking read_with_poll because stateless edge functions have no event loop to schedule polls — the database must do the waiting. Elixir workers are long-running GenServers where Process.send_after provides native scheduling, so pgmq.read() returns instantly and the connection goes back to the Ecto pool. This avoids holding DB connections idle and enables adaptive backoff with cancellable timers (NOTIFY or completion events can wake the worker immediately).

Note that read_with_poll is not truly push-based — PostgreSQL runs an internal poll loop at pollIntervalMs (default 200ms) inside the blocking call:

Deno worker                    PostgreSQL
   |                              |
   |---- read_with_poll() ------->|
   |     (connection held)        |-- SELECT FROM q_* ... nothing
   |                              |-- wait 200ms
   |                              |-- SELECT FROM q_* ... nothing
   |                              |-- wait 200ms
   |                              |-- SELECT FROM q_* ... MESSAGE!
   |<--- [message] ---------------|

The real question is where the poll loop lives and what tradeoffs that creates:

Feature Comparison

Shared SQL Core

Both call the same PostgreSQL functions:

Database schema (7 tables): flows, steps, deps (definition) + runs, step_states, step_tasks, workers (runtime).

Schema Divergences

The Elixir implementation adds the following extensions that are not present in the upstream TypeScript/Deno project:

These additions are backward-compatible: existing flow records default to flow_type = 'flow', and extension functions don't modify core pgflow tables. TypeScript workers can safely ignore them.

Compilation

TypeScript: CLI sends HTTP request to ControlPlane edge function, which extracts the flow shape and generates SQL. Written to supabase/migrations/.

Elixir: mix pgflow.gen.flow_migration MyFlow reads __pgflow_definition__/0 at compile time and generates an Ecto migration with the same SQL calls. Also compiles flows at worker startup via FlowCompiler.