Coordination

How N instances of your app avoid double-firing a schedule — single, advisoryLock, and cluster exactly-once strategies.

When more than one instance of your app is running, each one's self timer wants to fire the same schedule at the same instant. Coordination is the gate that decides which instance actually runs it. It's an app-wide setting:

// apps/api/app.config.ts
scheduling: { coordination: 'advisoryLock' }

The job definition never mentions coordination — you can move from one box to a fleet without touching a *.cron.tsx file.

The three strategies

Strategy Exactly-once across instances? Needs Use when
single No — every instance fires nothing One process: PM2 single instance, a single container, local dev
advisoryLock One claim winner per firing bucket Shared SQL database with primary-key constraints Multiple instances sharing one authoritative claim store
cluster Shard owner fires PostgreSQL, MySQL, MariaDB or SQL Server or a direct remote Turso primary with a cluster runner Schedules use the same cluster infrastructure as workflows

Default: single on memory, SQLite, local Turso and embedded Turso replicas; advisoryLock on PostgreSQL, MySQL, MariaDB, SQL Server and direct remote Turso primaries. Both boot paths use the resolved connection capability.

single

No gate. The instance's timer fires, the handler runs. Zero coordination overhead.

This is correct only if exactly one instance runs the schedule. Two single instances = two firings. That's not a bug to work around — it's the contract. If you scale past one instance, switch to advisoryLock.

advisoryLock

Explicit scheduling: { coordination: 'advisoryLock' } also works with SQLite and Turso in both voltro dev and compiled production startup. It uses the primary-key constraint of _voltro_schedule_claims; local and embedded connections still default to single, while a direct remote primary defaults to advisoryLock. Memory falls back to single. This setting does not enable distributed workflow runners for SQLite, and separate local database files do not coordinate with each other. Replicas must arbitrate claims in the same authoritative database; independent embedded copies are not a shared claim gate.

The portable multi-instance strategy uses a shared SQL claim table, without Redis, an orchestrator or leader election.

How it works. Each firing computes a deterministic key, <name>@<iso-second> (e.g. dailyDigest@2026-05-28T09:00:00), from the cron-derived scheduledAt — not Date.now(), so every replica computes the identical key regardless of clock skew within the firing window. The bucket is second-precision (YYYY-MM-DDTHH:MM:SS, 19 chars), so a 6-field cron like */10 * * * * * gets a distinct key for every firing instant within a minute. Every replica races to INSERT that key into _voltro_schedule_claims. The table's primary key makes exactly one INSERT win; the rest hit the conflict and stand down.

replica A ─┐                          ┌─ INSERT dailyDigest@…09:00  → wins, runs
replica B ─┼─ same bucket, same key ─┤
replica C ─┘                          └─ PK conflict → stands down (no run row)
  • Self-expiring. The key includes the firing instant, so a crashed winner doesn't block the next firing — the next firing instant is a new key.
  • A claim does not outlive its bucket. When a replica wins a claim it deletes that schedule's own older rows in the same pass, so the table's steady-state size is a small multiple of the number of schedules rather than a function of uptime. How far back it prunes scales with how far apart that caller's buckets are — a cron keeps roughly an hour of predecessors, a 250 ms coordinated task about a minute. The grace exists because deleting a claim too early is a double fire: a replica that is running late must still find the row that says its bucket was taken.
  • Swept, on the scale it fills — on every dialect. _voltro_schedule_claims gets a retention policy on both boot paths: rows older than 24 hours by claimedAt are deleted, tunable with VOLTRO_SCHEDULE_CLAIMS_TTL_HOURS. The announcement at boot names it (retention: N policy(ies) armed). 24 h rather than the 30 days the framework's history tables get, because this is a lock ledger — a claim row answers a question about one firing instant, and nothing reads yesterday's. One row per (schedule, second-bucket) adds up faster than people expect: a deployment with a handful of sub-minute schedules measured 1 557 rows/hour, which a 30-day window would have let reach a million before the first row aged out. If you raise it, the number to reason about is the longest a replica may be paused and still be trusted not to re-fire a bucket it already lost. The sweep is the backstop, not the main bound — it is what cleans up after a schedule you renamed or deleted, which the per-schedule prune above can never revisit. (Through 0.32.0 the whole sweep was registered behind a postgres-only gate, so on the other four dialects it never ran and the boot said nothing about it. Fixed in 0.33.0.)
  • Looked up by primary key. The existence check the coordinator runs before its INSERT is a single-row read on id, which is the claim key — so the table's size does not enter the firing path.
  • Pool-safe. Unlike a session-level pg_advisory_lock (tied to a connection a pool may reassign), a claims row is durable and connection-independent.
  • Fail-closed. If the claims table is unreachable, the coordinator logs a warning and declines to fire rather than risk a double-fire. A missing run is recoverable via backfill; a double-fire (two charge emails) often isn't.

Losers don't write a run row — at scale that would be N−1 noise rows per firing. Only the winner's run appears in the dashboard, tagged wonLock.

If your app registers its own bound for a framework table, yours wins. registerRetention({ table, timeColumn, ttlMs }) from a startup outranks the framework's default for the same table — app > plugin > framework, and source defaults to 'app' so you do not have to pass anything. A real disagreement is reported at boot, on the line beside the policy that survived:

  ! _voltro_schedule_claims: two registrations — kept the app's 1h,
    dropped the framework's 24h. An app registration wins over a plugin's,
    and a plugin's over a framework default.

Through 0.32.0 this was a silent last-write-wins: a deployment's 1-hour bound was replaced one second later by the framework's default, the startup went on logging bounded to 1h at every boot, and it was found by counting rows. Note the direction — the loser is chosen by WHO registered, not by which TTL is narrower. "Narrower wins" would let a framework default we tighten in a later release silently start deleting your data faster than you asked for.

cluster

If you already run @effect/cluster (for workflows), schedules can ride the same sharding fabric. Each schedule becomes a ClusterCron singleton; the cluster assigns it to exactly one shard owner, and only that runner fires. The in-app self timer is not armed in this mode — the cluster owns the clock, so arming it too would double-fire.

Runs are tagged cluster. Coordination is handled by the cluster's shard assignment, so there's no claims table for cluster-mode schedules.

Caveat — sub-minute lag. A freshly started runner waits for shard assignment before the first firing (~10s observed on a cold runner). For minute-and-up cadences this is invisible. For "every second" it isn't — use self + single/advisoryLock for sub-minute work, or accept the warm-up.

Caveat — Postgres only. cluster (and advisoryLock) need Postgres. On a memory store they fall back to single with a boot warning:

scheduling.coordination=cluster needs store=postgres — falling back to single (dev/memory)

Choosing

Single process? ───────────────────────────────→ single
Multiple instances, no orchestrator? ──────────→ advisoryLock   (← the default on Postgres)
Already running @effect/cluster for workflows? → cluster
Letting k8s/EventBridge drive the clock? ──────→ trigger: 'external'  (the app claims each occurrence itself)

When the platform scheduler drives the firing (the external trigger), the run is still claimed before it starts, and the row is tagged external.

That is a correction of what this page used to say. It said the platform guarantees once-only, so coordination did not apply — and Kubernetes says the opposite in its own documentation: a CronJob may create a Job twice for one scheduled time, and a Job with a backoffLimit retries. The app therefore derives each firing's identity from the cron expression it declares (the arrival time is snapped back to the nearest occurrence) and claims that instant through the store, whatever coordination the deployment declares — including single, where the injected coordinator gates nothing, because the duplicate there does not come from a second replica but from the same platform delivering twice.

What each run records

Every firing writes a _voltro_schedule_runs row with a coordinationOutcome so you can see, after the fact, why this instance ran it:

coordinationOutcome Meaning
single No coordination — single-instance mode
wonLock Won the advisoryLock race
cluster Shard owner fires
external Driven by an outside scheduler hitting the trigger endpoint; the occurrence was claimed here

(lostLock firings are not recorded — see above.) The dashboard surfaces this per run; see the dashboard doc.

The run ledger uses a 30-day retention window, configurable with VOLTRO_SCHEDULE_RUNS_TTL_HOURS. A row is eligible only when scheduledAt and every non-null activity timestamp (firedAt, completedAt, heartbeatAt) are older than the cutoff. A freshly executed historical backfill therefore keeps its result for a full retention window, and a long-running handler remains protected while its heartbeat is recent. A queued row is never swept: under onOverlap: 'queue', it represents work still waiting in line. An abandoned running row can still age out after its last activity becomes old.

Custom registerRetention policies can declare activityColumns: ['updatedAt', 'completedAt'] to apply the same recent-activity protection. Null activity timestamps do not protect a row; the primary timeColumn cutoff and any where condition still apply. An app policy replaces the framework policy, so preserve the queued-row condition and activity columns when overriding schedule history retention. Conditional deletion rechecks eligibility after candidate selection; if that delete fails, the sweep does not fall back to unconditional per-ID deletion.

A missed row written by the boot catch-up goes through the same coordination gate as a firing. Every replica runs the catch-up and each one enumerates the same gap from the same ledger, so without the gate a five-slot gap on ten pods left fifty rows saying the same thing — and the wall of missed rows after a deploy is precisely the signal it exists to give you.