Quickback Docs

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 },
}),
OptionDefaultMeaning
enabled—Required, explicit opt-in.
maxAttempts8Failed queue sends before an intent becomes a dead entry (1–100).
sweepCron* * * * *Cron for the dispatcher sweep. It runs alongside your own schedules.
workflowQueuethe only queueThe 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_effects table to the features database (both migration owners);
  • the QB_CONTROL Durable Object binding (class QuickbackControl, SQLite-backed, migration tag qb-do-QuickbackControl);
  • the sweepCron trigger and a scheduled() 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 },
  }],
});
  • queue must be a configured queue binding. The action helper types it as a union of those bindings.
  • message is a plain JSON object with a string type, used for consumer routing. It is at most 64 KiB of canonical JSON. Dates, class instances, functions, undefined, non-finite numbers and the reserved __qbEffect field 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 outcomeIntents
Rejected before submissionNone 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:

  1. Claim. One conditional UPDATE leases due rows for 60 seconds. Overlapping sweepers can never both own a row. Every later transition checks the lease owner.

  2. 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.

  3. Send a versioned envelope:

    { "__qbEffect": { "v": 1, "app": "…", "binding": "DB", "id": "…", "generation": 1,
                       "hash": "…", "attempt": 1, "org": "…", "principal": "…" },
      "message": { "type": "order.placed", "orderId": "…" } }
  4. Settle. Queue acceptance settles the receipt as accepted and marks the row. A failed send backs off exponentially, from 30 seconds up to an hour. After maxAttempts failures the row becomes dead. 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):

AdmissionAction
runThe handler receives the unwrapped message. Its ack() / retry() settle a consume receipt (completed / failed) before the platform acknowledgement.
duplicateA completed receipt exists. The message is acknowledged without running.
quarantinedUnknown ID, tampered payload, malformed envelope or stale generation. A quarantine record is persisted, then the message is acknowledged. It never runs or retries forever.
retryThe 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.

MethodReturnsContract
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 })booleanaccepted | failed. Only the latest attempt can settle.
admitConsume(binding, { id, generation, hash })run / duplicate / quarantined / retryConsumer admission permit.
settleConsume(binding, { id, attempt, outcome })booleancompleted | 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)stateStops new effect-bearing writes, dispatches and consumer runs.
drain(binding)statequiescent only when no receipt is unsettled. Lease expiry never counts as quiescence.
resolveUnknown(binding, { id, dispatch?, consume? })receiptExplicit operator resolution of an unsettled receipt.
rotateGeneration(binding)stateRequires a fenced, quiescent binding. Adds 1.
resume(binding)stateReopens admission.
admission(bindings){ [binding]: { mode, generation } }One transaction for several bindings; the source of the recovery admission cache.
claimNonce(nonce, expiresAt)booleanSingle-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:

  1. fence the binding.
  2. drain until quiescent. Resolve stuck receipts explicitly with resolveUnknown.
  3. Restore the D1 database.
  4. rotateGeneration.
  5. Call reconcileRestoredEffects(env, { reissuePending }). It handles every non-terminal intent from an older generation:
    • an accepted receipt 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 reissuePending is set.
  6. 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 accepted rows yourself if the table grows.
  • Queue and cron handlers cannot record durable effects yet. Workflow steps can: their db carries the runtime.
  • Workflows build on durable effects. Every start, event and control is an intent in the same batch as its registry row.

On this page