Durable effects
Record queue effects in the same D1 transaction as the writes, deliver them at least once with leases and receipts, and fence them across restores.
An after-commit hook or effects.enqueue runs after the write commits. If
the Worker dies between the commit and the send, the effect is lost. Durable
effects close that gap on Cloudflare D1: each effect is written as an intent
row inside the same native D1 batch as the business writes. The intent
exists if and only if the writes committed.
A dispatcher then delivers each intent to a queue at least once. A per-deployment control Durable Object keeps receipts and a restore generation. A D1 restore cannot roll those back.
Durable effects do not make an external side effect happen exactly once. Queue acceptance is not consumer completion. Consumers must be idempotent.
Enable
database: defineDatabase("cloudflare-d1", {
additionalQueues: [{ name: "my-app-comms", binding: "COMMS_QUEUE" }],
durableEffects: { enabled: true },
}),| Option | Default | Meaning |
|---|---|---|
enabled | — | Required, explicit opt-in. |
maxAttempts | 8 | Failed queue sends before an intent becomes a dead entry (1–100). |
sweepCron | * * * * * | Cron for the dispatcher sweep. It runs alongside your own schedules. |
workflowQueue | the only queue | The queue that carries workflow start, event and control intents. Required when a project with workflows has more than one queue. |
The compiler refuses the option unless the provider is cloudflare-d1 on the
Cloudflare runtime and a queue is configured. It never falls back to
best-effort delivery. Enabling it adds:
- the
_quickback_effectstable to the features database (both migration owners); - the
QB_CONTROLDurable Object binding (classQuickbackControl, SQLite-backed, migration tagqb-do-QuickbackControl); - the
sweepCrontrigger and ascheduled()export; - consumer admission in the generated queue consumer.
readCache deploys the same control object
without durable effects, so deployments that enabled it earlier keep the class.
The read cache no longer calls it: its data epoch is a per-write token that a
restore cannot reuse. It never creates a second control object.
Record an effect
Pass effects to an atomic db.batch:
const id = crypto.randomUUID();
await db.batch([db.insert(orders).values({ id, total: input.total })], {
effects: [{
key: `order-placed:${id}`,
queue: "COMMS_QUEUE",
message: { type: "order.placed", orderId: id },
}],
});queuemust be a configured queue binding. The action helper types it as a union of those bindings.messageis a plain JSON object with a stringtype, used for consumer routing. It is at most 64 KiB of canonical JSON. Dates, class instances, functions,undefined, non-finite numbers and the reserved__qbEffectfield are rejected.- A batch may carry up to 50 effects. Their keys must be unique within the batch.
- Choose identifiers before the batch. A message cannot refer to results the batch produces.
Validation runs before preparation, so an invalid effect never reaches the
database (DURABLE_EFFECT_INVALID, 400). The batch then asks the control object
whether the deployment is open, and for its current generation. A fenced
deployment rejects the write with DEPLOYMENT_FENCED (503). An unreachable
control object rejects it with EFFECTS_CONTROL_UNAVAILABLE (503). Both happen
before submission, so details.committed is false. A batch without effects
never contacts the control object.
Identity and duplicates
An effect's ID is a hash of the deployment, the D1 binding, the principal, the
active organization and your key. Retrying the same operation produces the
same ID. The intent table's primary key then rolls back the whole batch, so
the business write cannot silently happen twice. The error is
DURABLE_EFFECT_CONFLICT (409, details.committed: false). Another principal or
organization using the same key creates a different effect.
Outcomes
Effects use the transaction outcome table unchanged:
| Batch outcome | Intents |
|---|---|
| Rejected before submission | None written. |
Definitive rollback (committed: false) | None. They roll back with the writes. |
Outcome unknown (committed: null) | Unknown, like the writes. If the backend committed, the sweep delivers them. A timeout is not rollback evidence. |
Committed, hooks failed (committed: true) | Committed. They are delivered. |
Durable effects are available to request-scoped actions. A handle without a
request runtime, such as a cron or queue handle, rejects effects. Existing
afterCommit hooks and effects.enqueue keep their best-effort semantics.
Delivery
After a commit, the request starts delivery of its own intents through
waitUntil. The scheduled sweep is the guarantee:
-
Claim. One conditional
UPDATEleases due rows for 60 seconds. Overlapping sweepers can never both own a row. Every later transition checks the lease owner. -
Register. Before sending, the dispatcher records an attempt with the control object (
beginDispatch). A fenced binding releases the lease. A stale generation quarantines the row. An already-accepted receipt marks the row accepted without resending. -
Send a versioned envelope:
{ "__qbEffect": { "v": 1, "app": "…", "binding": "DB", "id": "…", "generation": 1, "hash": "…", "attempt": 1, "org": "…", "principal": "…" }, "message": { "type": "order.placed", "orderId": "…" } } -
Settle. Queue acceptance settles the receipt as
acceptedand marks the row. A failed send backs off exponentially, from 30 seconds up to an hour. AftermaxAttemptsfailures the row becomesdead. If the worker dies after sending, the lease expires and the next sweep sends again with the same effect ID.
If the control object is unreachable, dispatch fails closed: the lease is
released without consuming an attempt, and the intent stays durable. Errors
are stored only as a class name, such as send:Error. Message bodies are never
logged.
Consumers
The generated queue consumer checks every message carrying __qbEffect
before any handler runs. It verifies the payload hash, then asks the control
object for admission (admitConsume):
| Admission | Action |
|---|---|
run | The handler receives the unwrapped message. Its ack() / retry() settle a consume receipt (completed / failed) before the platform acknowledgement. |
duplicate | A completed receipt exists. The message is acknowledged without running. |
quarantined | Unknown ID, tampered payload, malformed envelope or stale generation. A quarantine record is persisted, then the message is acknowledged. It never runs or retries forever. |
retry | The binding is fenced, another delivery is still running (15-minute window), or the control object is unreachable. The message is retried after 30 seconds. |
A missing completion receipt is not proof that nothing happened. A redelivery
after a crash runs again. Make database writes idempotent, for example by
deriving keys from orderId. Pass a provider idempotency key to external APIs.
A consumer outside this Worker does not perform admission. It is an
uncontrolled reconciliation boundary.
Operational control contract
QuickbackControl is one SQLite-backed Durable Object per deployment
(idFromName('quickback-control')). It lives outside the features database, so
a D1 restore never rewinds it. It is RPC only: no fetch handler and no route
of its own. With D1 recovery enabled, operators
reach it through the signed operator bridge.
Each method is one storage transaction. All methods take the D1 binding name
first, and each binding is independent.
| Method | Returns | Contract |
|---|---|---|
state(binding) | { generation, mode, attemptingDispatches, startedConsumes, quiescent } | generation starts at 1 and only increases. Consumers such as caches key on it. |
beginDispatch(binding, { id, generation, hash }) | { ok: true, attempt } or { ok: false, reason: 'fenced' | 'stale' | 'accepted' } | Registers an attempt before a send. |
settleDispatch(binding, { id, attempt, outcome }) | boolean | accepted | failed. Only the latest attempt can settle. |
admitConsume(binding, { id, generation, hash }) | run / duplicate / quarantined / retry | Consumer admission permit. |
settleConsume(binding, { id, attempt, outcome }) | boolean | completed | failed. |
receipts(binding, ids) | { [id]: { dispatch?, dispatchGeneration?, consume? } } | Non-rewound receipts, up to 500 IDs per call. |
quarantine / quarantined(binding, limit?) | — | Record and list quarantined deliveries. |
fence(binding) | state | Stops new effect-bearing writes, dispatches and consumer runs. |
drain(binding) | state | quiescent only when no receipt is unsettled. Lease expiry never counts as quiescence. |
resolveUnknown(binding, { id, dispatch?, consume? }) | receipt | Explicit operator resolution of an unsettled receipt. |
rotateGeneration(binding) | state | Requires a fenced, quiescent binding. Adds 1. |
resume(binding) | state | Reopens admission. |
admission(bindings) | { [binding]: { mode, generation } } | One transaction for several bindings; the source of the recovery admission cache. |
claimNonce(nonce, expiresAt) | boolean | Single-use operator request nonces. |
operation(id) / advanceOperation(id, { digest, from, to, detail }) | record / { ok, operation } | Compare-and-set recovery operation stages with an appended history. |
With recovery enabled, state also reports admissionClearAt. That is the fence
time plus the 35-second admission window. quiescent stays false until it
passes, and rotateGeneration waits for it.
Receipts are kept indefinitely. Retention must cover the supported restore horizon plus the outstanding delivery lifetime. Pruning earlier is not supported.
Recovery fence
quickback db restore-apply runs this protocol for you, with fenced admission
of every D1 write. See D1 recovery. Without
recovery enabled, the fence only stops effect-bearing writes. The protocol for
restoring the features database:
fencethe binding.drainuntilquiescent. Resolve stuck receipts explicitly withresolveUnknown.- Restore the D1 database.
rotateGeneration.- Call
reconcileRestoredEffects(env, { reissuePending }). It handles every non-terminal intent from an older generation:- an
acceptedreceipt marks the intent accepted, and it is not resent; - any other receipt means the outcome is uncertain, so the intent is quarantined;
- an intent that was never dispatched is quarantined, or reissued in the new generation with the same ID when
reissuePendingis set.
- an
resume.
Work accepted before the restore cannot execute against restored data. A restored older-generation row is quarantined at dispatch. A pre-restore message delivered after reopening is quarantined at consume.
Dead and quarantined entries
Rows are inspectable in the features database:
wrangler d1 execute <features-db> --remote --command \
"SELECT id, state, attempts, last_error, queue, created_at FROM _quickback_effects WHERE state IN ('dead','quarantined')"With D1 recovery enabled, the operator path is
quickback effects list | replay | resolve | reconcile. It runs through the
signed operator bridge. To retry an entry, call
replayDurableEffect(env, id, { confirmHash }) from
src/lib/durable-effects.ts. confirmHash must equal the row's payload_hash.
The replay keeps the same ID and uses the current generation. It refuses an
effect the queue already accepted. If the previous outcome is unknown, the
replay also requires reconciled: 'not-delivered', which is recorded on the
receipt. Without recovery, expose it only through an operator-only action. The
compiler emits no application route for it.
Limits
- One control object per deployment serializes admission, dispatch and consume calls: about one write admission, two dispatch calls and two consume calls per effect. Throughput and latency on a deployed account are not yet measured.
- Writing an effect costs one control call per batch. Batches without effects are unaffected.
- Accepted intent rows are retained. Prune old
acceptedrows yourself if the table grows. - Queue and cron handlers cannot record durable effects yet. Workflow steps can: their
dbcarries the runtime. - Workflows build on durable effects. Every start, event and control is an intent in the same batch as its registry row.
Read replication
Serve reads from D1's regional replicas with the Sessions API — one config flag, one response header, sequential consistency per client.
D1 recovery
Fence every D1 write, restore databases by Time Travel bookmark, reconcile durable effects, verify, and reopen — as a reviewed, resumable operation. Plus protected exports.