@quickback-dev/cli 0.72.9 → 0.72.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +8 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/db-explain.d.ts +67 -0
- package/dist/commands/db-explain.d.ts.map +1 -0
- package/dist/commands/db-explain.js +141 -0
- package/dist/commands/db-explain.js.map +1 -0
- package/dist/commands/db-export.d.ts +34 -0
- package/dist/commands/db-export.d.ts.map +1 -0
- package/dist/commands/db-export.js +250 -0
- package/dist/commands/db-export.js.map +1 -0
- package/dist/commands/db-insights.d.ts +60 -0
- package/dist/commands/db-insights.d.ts.map +1 -0
- package/dist/commands/db-insights.js +106 -0
- package/dist/commands/db-insights.js.map +1 -0
- package/dist/commands/db-recovery.d.ts +98 -0
- package/dist/commands/db-recovery.d.ts.map +1 -0
- package/dist/commands/db-recovery.js +558 -0
- package/dist/commands/db-recovery.js.map +1 -0
- package/dist/commands/db-target.d.ts +27 -0
- package/dist/commands/db-target.d.ts.map +1 -0
- package/dist/commands/db-target.js +83 -0
- package/dist/commands/db-target.js.map +1 -0
- package/dist/commands/db.d.ts +3 -0
- package/dist/commands/db.d.ts.map +1 -0
- package/dist/commands/db.js +43 -0
- package/dist/commands/db.js.map +1 -0
- package/dist/commands/effects.d.ts +8 -0
- package/dist/commands/effects.d.ts.map +1 -0
- package/dist/commands/effects.js +48 -0
- package/dist/commands/effects.js.map +1 -0
- package/dist/commands/platform-budget.d.ts +143 -0
- package/dist/commands/platform-budget.d.ts.map +1 -0
- package/dist/commands/platform-budget.js +619 -0
- package/dist/commands/platform-budget.js.map +1 -0
- package/dist/commands/preview.d.ts +57 -0
- package/dist/commands/preview.d.ts.map +1 -0
- package/dist/commands/preview.js +268 -0
- package/dist/commands/preview.js.map +1 -0
- package/dist/commands/search.d.ts +20 -0
- package/dist/commands/search.d.ts.map +1 -0
- package/dist/commands/search.js +133 -0
- package/dist/commands/search.js.map +1 -0
- package/dist/index.js +35 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +4 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
- package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
- package/dist/lib/cloudflare-spend-policies.js +289 -0
- package/dist/lib/cloudflare-spend-policies.js.map +1 -0
- package/dist/lib/compiler-stubs.d.ts +2 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +2 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/d1-fingerprint.d.ts +8 -0
- package/dist/lib/d1-fingerprint.d.ts.map +1 -0
- package/dist/lib/d1-fingerprint.js +113 -0
- package/dist/lib/d1-fingerprint.js.map +1 -0
- package/dist/lib/file-loader.d.ts +12 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +27 -1
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts +6 -5
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +24 -12
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
- package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/search.js +160 -0
- package/dist/lib/migrations/postprocessors/search.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +7 -0
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +3 -0
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +1 -1
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +1 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/preview-lifecycle.d.ts +139 -0
- package/dist/lib/preview-lifecycle.d.ts.map +1 -0
- package/dist/lib/preview-lifecycle.js +429 -0
- package/dist/lib/preview-lifecycle.js.map +1 -0
- package/dist/lib/preview.d.ts +146 -0
- package/dist/lib/preview.d.ts.map +1 -0
- package/dist/lib/preview.js +417 -0
- package/dist/lib/preview.js.map +1 -0
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +4 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/SKILL.md +9 -3
- package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/dist/skill/docs/api/batch-operations.md +19 -0
- package/dist/skill/docs/api/caching.md +17 -0
- package/dist/skill/docs/api/crud.md +9 -0
- package/dist/skill/docs/api/errors.md +31 -2
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/changelog/index.md +1 -0
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/bindings.md +177 -1
- package/dist/skill/docs/configure/cloudflare-access.md +43 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/providers.md +5 -0
- package/dist/skill/docs/configure/tenant-databases.md +627 -14
- package/dist/skill/docs/define/access.md +26 -0
- package/dist/skill/docs/define/actions/defining.md +7 -1
- package/dist/skill/docs/define/actions/index.md +5 -0
- package/dist/skill/docs/define/actions/scoped-db.md +127 -1
- package/dist/skill/docs/define/authoring-basics.md +92 -0
- package/dist/skill/docs/define/changesets.md +8 -0
- package/dist/skill/docs/define/encryption.md +48 -2
- package/dist/skill/docs/define/feature.md +17 -2
- package/dist/skill/docs/define/guards.md +11 -3
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/invariants.md +321 -0
- package/dist/skill/docs/define/issue-tracker-example.md +225 -0
- package/dist/skill/docs/define/masking.md +3 -3
- package/dist/skill/docs/define/rate-limit.md +63 -22
- package/dist/skill/docs/define/read.md +332 -5
- package/dist/skill/docs/define/relationships.md +10 -0
- package/dist/skill/docs/define/schema.md +137 -10
- package/dist/skill/docs/define/scopes.md +1 -0
- package/dist/skill/docs/define/transitions.md +9 -0
- package/dist/skill/docs/define/triggers.md +127 -1
- package/dist/skill/docs/platform/api-contract/index.md +35 -4
- package/dist/skill/docs/platform/auth/api-keys.md +26 -3
- package/dist/skill/docs/platform/auth/index.md +5 -2
- package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +73 -1
- package/dist/skill/docs/platform/database/durable-effects.md +224 -0
- package/dist/skill/docs/platform/database/read-replication.md +9 -0
- package/dist/skill/docs/platform/database/recovery.md +292 -0
- package/dist/skill/docs/platform/database/using-d1.md +152 -2
- package/dist/skill/docs/platform/index.md +1 -0
- package/dist/skill/docs/platform/operations/budgets.md +224 -0
- package/dist/skill/docs/platform/queues/handlers.md +1 -0
- package/dist/skill/docs/platform/queues/index.md +18 -0
- package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
- package/dist/skill/docs/platform/storage/using-r2.md +13 -0
- package/dist/skill/docs/platform/vector/embeddings.md +28 -4
- package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/dist/skill/docs/platform/workflows/index.md +385 -0
- package/dist/skill/docs/start/deploy-browser.md +51 -0
- package/dist/skill/docs/start/deploy.md +97 -1
- package/dist/skill/docs/tooling/cli.md +117 -0
- package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/dist/skill/docs/ui/account/customization.md +4 -0
- package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
- package/package.json +1 -1
- package/src/skill/SKILL.md +9 -3
- package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/src/skill/docs/api/batch-operations.md +19 -0
- package/src/skill/docs/api/caching.md +17 -0
- package/src/skill/docs/api/crud.md +9 -0
- package/src/skill/docs/api/errors.md +31 -2
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/changelog/index.md +1 -0
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/bindings.md +177 -1
- package/src/skill/docs/configure/cloudflare-access.md +43 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/providers.md +5 -0
- package/src/skill/docs/configure/tenant-databases.md +627 -14
- package/src/skill/docs/define/access.md +26 -0
- package/src/skill/docs/define/actions/defining.md +7 -1
- package/src/skill/docs/define/actions/index.md +5 -0
- package/src/skill/docs/define/actions/scoped-db.md +127 -1
- package/src/skill/docs/define/authoring-basics.md +92 -0
- package/src/skill/docs/define/changesets.md +8 -0
- package/src/skill/docs/define/encryption.md +48 -2
- package/src/skill/docs/define/feature.md +17 -2
- package/src/skill/docs/define/guards.md +11 -3
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/invariants.md +321 -0
- package/src/skill/docs/define/issue-tracker-example.md +225 -0
- package/src/skill/docs/define/masking.md +3 -3
- package/src/skill/docs/define/rate-limit.md +63 -22
- package/src/skill/docs/define/read.md +332 -5
- package/src/skill/docs/define/relationships.md +10 -0
- package/src/skill/docs/define/schema.md +137 -10
- package/src/skill/docs/define/scopes.md +1 -0
- package/src/skill/docs/define/transitions.md +9 -0
- package/src/skill/docs/define/triggers.md +127 -1
- package/src/skill/docs/platform/api-contract/index.md +35 -4
- package/src/skill/docs/platform/auth/api-keys.md +26 -3
- package/src/skill/docs/platform/auth/index.md +5 -2
- package/src/skill/docs/platform/auth/plugins/index.md +1 -1
- package/src/skill/docs/platform/database/d1.md +73 -1
- package/src/skill/docs/platform/database/durable-effects.md +224 -0
- package/src/skill/docs/platform/database/read-replication.md +9 -0
- package/src/skill/docs/platform/database/recovery.md +292 -0
- package/src/skill/docs/platform/database/using-d1.md +152 -2
- package/src/skill/docs/platform/index.md +1 -0
- package/src/skill/docs/platform/operations/budgets.md +224 -0
- package/src/skill/docs/platform/queues/handlers.md +1 -0
- package/src/skill/docs/platform/queues/index.md +18 -0
- package/src/skill/docs/platform/realtime/table-changes.md +1 -0
- package/src/skill/docs/platform/storage/using-r2.md +13 -0
- package/src/skill/docs/platform/vector/embeddings.md +28 -4
- package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/src/skill/docs/platform/workflows/index.md +385 -0
- package/src/skill/docs/start/deploy-browser.md +51 -0
- package/src/skill/docs/start/deploy.md +97 -1
- package/src/skill/docs/tooling/cli.md +117 -0
- package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/src/skill/docs/ui/account/customization.md +4 -0
- package/src/skill/docs/ui/admin/record-layouts.md +3 -3
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# Durable effects
|
|
2
|
+
|
|
3
|
+
An after-commit hook or `effects.enqueue` runs **after** the write commits. If
|
|
4
|
+
the Worker dies between the commit and the send, the effect is lost. Durable
|
|
5
|
+
effects close that gap on Cloudflare D1: each effect is written as an intent
|
|
6
|
+
row inside the **same native D1 batch** as the business writes. The intent
|
|
7
|
+
exists if and only if the writes committed.
|
|
8
|
+
|
|
9
|
+
A dispatcher then delivers each intent to a queue **at least once**. A
|
|
10
|
+
per-deployment control Durable Object keeps receipts and a restore
|
|
11
|
+
generation. A D1 restore cannot roll those back.
|
|
12
|
+
|
|
13
|
+
Durable effects do **not** make an external side effect happen exactly once.
|
|
14
|
+
Queue acceptance is not consumer completion. Consumers must be idempotent.
|
|
15
|
+
|
|
16
|
+
## Enable
|
|
17
|
+
|
|
18
|
+
{/* doc-compile: skip — config fragment; the full defineConfig wrapper is shown in /configure. */}
|
|
19
|
+
```typescript
|
|
20
|
+
database: defineDatabase("cloudflare-d1", {
|
|
21
|
+
additionalQueues: [{ name: "my-app-comms", binding: "COMMS_QUEUE" }],
|
|
22
|
+
durableEffects: { enabled: true },
|
|
23
|
+
}),
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
| Option | Default | Meaning |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| `enabled` | — | Required, explicit opt-in. |
|
|
29
|
+
| `maxAttempts` | `8` | Failed queue sends before an intent becomes a **dead** entry (1–100). |
|
|
30
|
+
| `sweepCron` | `* * * * *` | Cron for the dispatcher sweep. It runs alongside your own [schedules](/platform/schedules). |
|
|
31
|
+
| `workflowQueue` | the only queue | The queue that carries [workflow](/platform/workflows) start, event and control intents. Required when a project with workflows has more than one queue. |
|
|
32
|
+
|
|
33
|
+
The compiler refuses the option unless the provider is `cloudflare-d1` on the
|
|
34
|
+
Cloudflare runtime and a queue is configured. It never falls back to
|
|
35
|
+
best-effort delivery. Enabling it adds:
|
|
36
|
+
|
|
37
|
+
- the `_quickback_effects` table to the features database (both migration owners);
|
|
38
|
+
- the `QB_CONTROL` Durable Object binding (class `QuickbackControl`, SQLite-backed, migration tag `qb-do-QuickbackControl`);
|
|
39
|
+
- the `sweepCron` trigger and a `scheduled()` export;
|
|
40
|
+
- consumer admission in the generated queue consumer.
|
|
41
|
+
|
|
42
|
+
[`readCache`](/define/read#workers-cache) deploys the same control object
|
|
43
|
+
without durable effects, so deployments that enabled it earlier keep the class.
|
|
44
|
+
The read cache no longer calls it: its data epoch is a per-write token that a
|
|
45
|
+
restore cannot reuse. It never creates a second control object.
|
|
46
|
+
|
|
47
|
+
## Record an effect
|
|
48
|
+
|
|
49
|
+
Pass `effects` to an atomic [`db.batch`](/define/actions/scoped-db#atomic-d1-batches-and-concurrency):
|
|
50
|
+
|
|
51
|
+
{/* doc-compile: skip — illustrative action fragment; orders is an application table. */}
|
|
52
|
+
```ts
|
|
53
|
+
const id = crypto.randomUUID();
|
|
54
|
+
await db.batch([db.insert(orders).values({ id, total: input.total })], {
|
|
55
|
+
effects: [{
|
|
56
|
+
key: `order-placed:${id}`,
|
|
57
|
+
queue: "COMMS_QUEUE",
|
|
58
|
+
message: { type: "order.placed", orderId: id },
|
|
59
|
+
}],
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
- `queue` must be a configured queue binding. The action helper types it as a union of those bindings.
|
|
64
|
+
- `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.
|
|
65
|
+
- A batch may carry up to 50 effects. Their keys must be unique within the batch.
|
|
66
|
+
- Choose identifiers **before** the batch. A message cannot refer to results the batch produces.
|
|
67
|
+
|
|
68
|
+
Validation runs before preparation, so an invalid effect never reaches the
|
|
69
|
+
database (`DURABLE_EFFECT_INVALID`, 400). The batch then asks the control object
|
|
70
|
+
whether the deployment is open, and for its current generation. A fenced
|
|
71
|
+
deployment rejects the write with `DEPLOYMENT_FENCED` (503). An unreachable
|
|
72
|
+
control object rejects it with `EFFECTS_CONTROL_UNAVAILABLE` (503). Both happen
|
|
73
|
+
before submission, so `details.committed` is `false`. A batch without `effects`
|
|
74
|
+
never contacts the control object.
|
|
75
|
+
|
|
76
|
+
### Identity and duplicates
|
|
77
|
+
|
|
78
|
+
An effect's ID is a hash of the deployment, the D1 binding, the principal, the
|
|
79
|
+
active organization and your `key`. Retrying the same operation produces the
|
|
80
|
+
same ID. The intent table's primary key then **rolls back the whole batch**, so
|
|
81
|
+
the business write cannot silently happen twice. The error is
|
|
82
|
+
`DURABLE_EFFECT_CONFLICT` (409, `details.committed: false`). Another principal or
|
|
83
|
+
organization using the same key creates a different effect.
|
|
84
|
+
|
|
85
|
+
### Outcomes
|
|
86
|
+
|
|
87
|
+
Effects use the [transaction outcome table](/define/actions/scoped-db#transaction-outcomes-and-recovery) unchanged:
|
|
88
|
+
|
|
89
|
+
| Batch outcome | Intents |
|
|
90
|
+
|---|---|
|
|
91
|
+
| Rejected before submission | None written. |
|
|
92
|
+
| Definitive rollback (`committed: false`) | None. They roll back with the writes. |
|
|
93
|
+
| Outcome unknown (`committed: null`) | Unknown, like the writes. If the backend committed, the sweep delivers them. A timeout is not rollback evidence. |
|
|
94
|
+
| Committed, hooks failed (`committed: true`) | Committed. They are delivered. |
|
|
95
|
+
|
|
96
|
+
Durable effects are available to request-scoped actions. A handle without a
|
|
97
|
+
request runtime, such as a cron or queue handle, rejects `effects`. Existing
|
|
98
|
+
`afterCommit` hooks and `effects.enqueue` keep their best-effort semantics.
|
|
99
|
+
|
|
100
|
+
## Delivery
|
|
101
|
+
|
|
102
|
+
After a commit, the request starts delivery of its own intents through
|
|
103
|
+
`waitUntil`. The scheduled sweep is the guarantee:
|
|
104
|
+
|
|
105
|
+
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.
|
|
106
|
+
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.
|
|
107
|
+
3. **Send** a versioned envelope:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{ "__qbEffect": { "v": 1, "app": "…", "binding": "DB", "id": "…", "generation": 1,
|
|
111
|
+
"hash": "…", "attempt": 1, "org": "…", "principal": "…" },
|
|
112
|
+
"message": { "type": "order.placed", "orderId": "…" } }
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
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**.
|
|
116
|
+
|
|
117
|
+
If the control object is unreachable, dispatch fails closed: the lease is
|
|
118
|
+
released without consuming an attempt, and the intent stays durable. Errors
|
|
119
|
+
are stored only as a class name, such as `send:Error`. Message bodies are never
|
|
120
|
+
logged.
|
|
121
|
+
|
|
122
|
+
## Consumers
|
|
123
|
+
|
|
124
|
+
The generated queue consumer checks every message carrying `__qbEffect`
|
|
125
|
+
**before** any handler runs. It verifies the payload hash, then asks the control
|
|
126
|
+
object for admission (`admitConsume`):
|
|
127
|
+
|
|
128
|
+
| Admission | Action |
|
|
129
|
+
|---|---|
|
|
130
|
+
| `run` | The handler receives the unwrapped `message`. Its `ack()` / `retry()` settle a consume receipt (`completed` / `failed`) **before** the platform acknowledgement. |
|
|
131
|
+
| `duplicate` | A completed receipt exists. The message is acknowledged without running. |
|
|
132
|
+
| `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. |
|
|
133
|
+
| `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. |
|
|
134
|
+
|
|
135
|
+
A missing completion receipt is not proof that nothing happened. A redelivery
|
|
136
|
+
after a crash runs again. Make database writes idempotent, for example by
|
|
137
|
+
deriving keys from `orderId`. Pass a provider idempotency key to external APIs.
|
|
138
|
+
A consumer outside this Worker does not perform admission. It is an
|
|
139
|
+
uncontrolled reconciliation boundary.
|
|
140
|
+
|
|
141
|
+
## Operational control contract
|
|
142
|
+
|
|
143
|
+
`QuickbackControl` is one SQLite-backed Durable Object per deployment
|
|
144
|
+
(`idFromName('quickback-control')`). It lives outside the features database, so
|
|
145
|
+
a D1 restore never rewinds it. It is **RPC only**: no fetch handler and no route
|
|
146
|
+
of its own. With [D1 recovery](/platform/database/recovery) enabled, operators
|
|
147
|
+
reach it through the signed operator bridge.
|
|
148
|
+
Each method is one storage transaction. All methods take the D1 binding name
|
|
149
|
+
first, and each binding is independent.
|
|
150
|
+
|
|
151
|
+
| Method | Returns | Contract |
|
|
152
|
+
|---|---|---|
|
|
153
|
+
| `state(binding)` | `{ generation, mode, attemptingDispatches, startedConsumes, quiescent }` | `generation` starts at 1 and only increases. Consumers such as caches key on it. |
|
|
154
|
+
| `beginDispatch(binding, { id, generation, hash })` | `{ ok: true, attempt }` or `{ ok: false, reason: 'fenced' \| 'stale' \| 'accepted' }` | Registers an attempt before a send. |
|
|
155
|
+
| `settleDispatch(binding, { id, attempt, outcome })` | `boolean` | `accepted` \| `failed`. Only the latest attempt can settle. |
|
|
156
|
+
| `admitConsume(binding, { id, generation, hash })` | `run` / `duplicate` / `quarantined` / `retry` | Consumer admission permit. |
|
|
157
|
+
| `settleConsume(binding, { id, attempt, outcome })` | `boolean` | `completed` \| `failed`. |
|
|
158
|
+
| `receipts(binding, ids)` | `{ [id]: { dispatch?, dispatchGeneration?, consume? } }` | Non-rewound receipts, up to 500 IDs per call. |
|
|
159
|
+
| `quarantine` / `quarantined(binding, limit?)` | — | Record and list quarantined deliveries. |
|
|
160
|
+
| `fence(binding)` | state | Stops new effect-bearing writes, dispatches and consumer runs. |
|
|
161
|
+
| `drain(binding)` | state | `quiescent` only when no receipt is unsettled. Lease expiry never counts as quiescence. |
|
|
162
|
+
| `resolveUnknown(binding, { id, dispatch?, consume? })` | receipt | Explicit operator resolution of an unsettled receipt. |
|
|
163
|
+
| `rotateGeneration(binding)` | state | Requires a fenced, quiescent binding. Adds 1. |
|
|
164
|
+
| `resume(binding)` | state | Reopens admission. |
|
|
165
|
+
| `admission(bindings)` | `{ [binding]: { mode, generation } }` | One transaction for several bindings; the source of the recovery admission cache. |
|
|
166
|
+
| `claimNonce(nonce, expiresAt)` | `boolean` | Single-use operator request nonces. |
|
|
167
|
+
| `operation(id)` / `advanceOperation(id, { digest, from, to, detail })` | record / `{ ok, operation }` | Compare-and-set recovery operation stages with an appended history. |
|
|
168
|
+
|
|
169
|
+
With recovery enabled, `state` also reports `admissionClearAt`. That is the fence
|
|
170
|
+
time plus the 35-second admission window. `quiescent` stays false until it
|
|
171
|
+
passes, and `rotateGeneration` waits for it.
|
|
172
|
+
|
|
173
|
+
Receipts are kept indefinitely. Retention must cover the supported restore
|
|
174
|
+
horizon plus the outstanding delivery lifetime. Pruning earlier is not
|
|
175
|
+
supported.
|
|
176
|
+
|
|
177
|
+
### Recovery fence
|
|
178
|
+
|
|
179
|
+
`quickback db restore-apply` runs this protocol for you, with fenced admission
|
|
180
|
+
of every D1 write. See [D1 recovery](/platform/database/recovery). Without
|
|
181
|
+
recovery enabled, the fence only stops effect-bearing writes. The protocol for
|
|
182
|
+
restoring the features database:
|
|
183
|
+
|
|
184
|
+
1. `fence` the binding.
|
|
185
|
+
2. `drain` until `quiescent`. Resolve stuck receipts explicitly with `resolveUnknown`.
|
|
186
|
+
3. Restore the D1 database.
|
|
187
|
+
4. `rotateGeneration`.
|
|
188
|
+
5. Call `reconcileRestoredEffects(env, { reissuePending })`. It handles every non-terminal intent from an older generation:
|
|
189
|
+
- an `accepted` receipt marks the intent accepted, and it is not resent;
|
|
190
|
+
- any other receipt means the outcome is uncertain, so the intent is quarantined;
|
|
191
|
+
- an intent that was never dispatched is quarantined, or reissued in the new generation with the **same ID** when `reissuePending` is set.
|
|
192
|
+
6. `resume`.
|
|
193
|
+
|
|
194
|
+
Work accepted before the restore cannot execute against restored data. A
|
|
195
|
+
restored older-generation row is quarantined at dispatch. A pre-restore message
|
|
196
|
+
delivered after reopening is quarantined at consume.
|
|
197
|
+
|
|
198
|
+
## Dead and quarantined entries
|
|
199
|
+
|
|
200
|
+
Rows are inspectable in the features database:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
wrangler d1 execute <features-db> --remote --command \
|
|
204
|
+
"SELECT id, state, attempts, last_error, queue, created_at FROM _quickback_effects WHERE state IN ('dead','quarantined')"
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
With [D1 recovery](/platform/database/recovery) enabled, the operator path is
|
|
208
|
+
`quickback effects list | replay | resolve | reconcile`. It runs through the
|
|
209
|
+
signed operator bridge. To retry an entry, call
|
|
210
|
+
`replayDurableEffect(env, id, { confirmHash })` from
|
|
211
|
+
`src/lib/durable-effects.ts`. `confirmHash` must equal the row's `payload_hash`.
|
|
212
|
+
The replay keeps the same ID and uses the current generation. It refuses an
|
|
213
|
+
effect the queue already accepted. If the previous outcome is unknown, the
|
|
214
|
+
replay also requires `reconciled: 'not-delivered'`, which is recorded on the
|
|
215
|
+
receipt. Without recovery, expose it only through an operator-only action. The
|
|
216
|
+
compiler emits no application route for it.
|
|
217
|
+
|
|
218
|
+
## Limits
|
|
219
|
+
|
|
220
|
+
- 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.
|
|
221
|
+
- Writing an effect costs one control call per batch. Batches without effects are unaffected.
|
|
222
|
+
- Accepted intent rows are retained. Prune old `accepted` rows yourself if the table grows.
|
|
223
|
+
- Queue and cron handlers cannot record durable effects yet. [Workflow](/platform/workflows) steps can: their `db` carries the runtime.
|
|
224
|
+
- [Workflows](/platform/workflows) build on durable effects. Every start, event and control is an intent in the same batch as its registry row.
|
|
@@ -250,8 +250,17 @@ With [`queryTimeoutMs`](/platform/database/using-d1#backend-stalls) set, the
|
|
|
250
250
|
deadline wraps the session as well — a replica that takes too long to catch up
|
|
251
251
|
to a bookmark answers `503 DB_TIMEOUT` like any other slow read.
|
|
252
252
|
|
|
253
|
+
## Query diagnostics
|
|
254
|
+
|
|
255
|
+
With [query diagnostics](/platform/database/using-d1#sampled-query-diagnostics)
|
|
256
|
+
on, the observation layer sits in the same wrapper chain as the deadline,
|
|
257
|
+
outside the session adapter. Sampled events report `region` and `primary`
|
|
258
|
+
whenever D1 returns them. Diagnostics never probe a replica, retry a statement
|
|
259
|
+
or change bookmarks or the primary-fallback policy.
|
|
260
|
+
|
|
253
261
|
## Related
|
|
254
262
|
|
|
255
263
|
- [Using D1](/platform/database/using-d1) — queries, dual-DB mode, backend stalls
|
|
256
264
|
- [Database options](/configure/providers#database-options) — every `defineDatabase("cloudflare-d1")` option
|
|
257
265
|
- [Cloudflare: Global read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/)
|
|
266
|
+
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
# D1 recovery
|
|
2
|
+
|
|
3
|
+
Restoring a D1 database on its own is dangerous. It can rewind idempotency
|
|
4
|
+
records, resurrect queue messages that were already delivered, and leave old
|
|
5
|
+
writers committing into the restored data. Fenced recovery makes restore an
|
|
6
|
+
operation the deployment takes part in. Traffic stays out until the schema,
|
|
7
|
+
derived state and external-effect reconciliation are confirmed.
|
|
8
|
+
|
|
9
|
+
Each database is an **independent restore point**. Cloudflare has no atomic
|
|
10
|
+
restore across `AUTH_DB`, `DB` and other stores. A restore of several bindings
|
|
11
|
+
is an ordered saga with per-binding results. It never guarantees consistency
|
|
12
|
+
between those databases.
|
|
13
|
+
|
|
14
|
+
## Enable
|
|
15
|
+
|
|
16
|
+
{/* doc-compile: skip — config fragment; the full defineConfig wrapper is shown in /configure. */}
|
|
17
|
+
```typescript
|
|
18
|
+
database: defineDatabase("cloudflare-d1", {
|
|
19
|
+
recovery: { enabled: true }, // operatorKey defaults to QB_RECOVERY_OPERATOR_KEY
|
|
20
|
+
// recovery: { enabled: true, operatorKey: { env: "OPS_RECOVERY_KEY" } },
|
|
21
|
+
}),
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Then set the operator key as a Worker secret (32 or more characters) for each
|
|
25
|
+
target:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
openssl rand -hex 32 | npx wrangler secret put QB_RECOVERY_OPERATOR_KEY --env production
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The compiler accepts the option only for `cloudflare-d1` on the Cloudflare
|
|
32
|
+
runtime. Enabling it adds:
|
|
33
|
+
|
|
34
|
+
- the per-deployment `QuickbackControl` Durable Object (`QB_CONTROL`). This is the same object as [durable effects](/platform/database/durable-effects). There is never a second control object;
|
|
35
|
+
- write admission on **every D1 binding** the Worker receives (auth, features, files, webhooks, audit);
|
|
36
|
+
- an admission check on HTTP, queue, cron and inbound-email entry points;
|
|
37
|
+
- the signed operator bridge at `POST /__quickback/operator`.
|
|
38
|
+
|
|
39
|
+
Without the secret, the bridge answers `503 RECOVERY_OPERATOR_DISABLED`. It
|
|
40
|
+
never falls back to another credential.
|
|
41
|
+
|
|
42
|
+
## How writes are admitted
|
|
43
|
+
|
|
44
|
+
Each isolate keeps one observation of `{ mode, generation }` per D1 binding
|
|
45
|
+
from the control object. The observation is refreshed at most every 5 seconds
|
|
46
|
+
and stamped with the Worker clock taken **before** the call.
|
|
47
|
+
|
|
48
|
+
Every statement that is not provably read-only (`SELECT`, `VALUES`,
|
|
49
|
+
`EXPLAIN`, a read `PRAGMA`) goes to D1 as a native batch. That includes
|
|
50
|
+
statements behind Drizzle, Better Auth and the generated runtime. The batch
|
|
51
|
+
starts with one assertion:
|
|
52
|
+
|
|
53
|
+
```sql
|
|
54
|
+
SELECT CASE WHEN ?1 >= now_ms - 30000 THEN 1 ELSE <raise> END -- ?1 = observation time
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- **Fenced binding**: refused before submission with `DEPLOYMENT_FENCED` (503, `committed: false`).
|
|
58
|
+
- **Stale observation**: D1 itself rejects the assertion, so the whole batch rolls back with `RECOVERY_ADMISSION_EXPIRED` (503, `committed: false`). This holds however long the request ran, and whether the invocation crashed or the Worker clock lagged.
|
|
59
|
+
- **Control object unreachable**: an observation younger than 25 seconds is still used. After that, writes fail closed with `RECOVERY_CONTROL_UNAVAILABLE` (503).
|
|
60
|
+
|
|
61
|
+
`fence` records its time. `drain` reports `quiescent` only once **35 seconds**
|
|
62
|
+
have passed since the fence (the 30-second window plus 5 seconds of clock-skew
|
|
63
|
+
margin) and no plan-037 receipt is still unsettled. Every observation that said
|
|
64
|
+
"open" was taken before the fence, so no write admitted under it can commit
|
|
65
|
+
after that point. No permit is held. A crashed Worker leaves nothing to release
|
|
66
|
+
and nothing to wait for: its admission simply expires inside D1.
|
|
67
|
+
|
|
68
|
+
**Cost.** A write gets no extra round trip: the assertion reads no table and
|
|
69
|
+
travels in the same D1 batch. A single statement becomes a two-statement batch.
|
|
70
|
+
Each isolate makes one control-object call per 5 seconds while it serves
|
|
71
|
+
traffic. Reads are unchanged. Latency and availability on a deployed account
|
|
72
|
+
have not been measured yet. The control object is a hard dependency for
|
|
73
|
+
traffic: it is a single Durable Object per deployment.
|
|
74
|
+
|
|
75
|
+
`exec()` cannot carry the assertion, so it is refused on guarded bindings. Use
|
|
76
|
+
`prepare()` or `batch()`. Writes through `.raw()` come back from the batched
|
|
77
|
+
result in object-key order. Duplicate column names in a write's `RETURNING`
|
|
78
|
+
clause are not preserved.
|
|
79
|
+
|
|
80
|
+
### Entry points while fenced
|
|
81
|
+
|
|
82
|
+
| Entry | While any binding is fenced |
|
|
83
|
+
|---|---|
|
|
84
|
+
| HTTP | `503 DEPLOYMENT_FENCED` with `Retry-After: 30`, for reads and writes, before auth or database middleware |
|
|
85
|
+
| Queue consumer | the batch is retried after 30 seconds; no handler runs |
|
|
86
|
+
| Cron | the run is skipped and logged |
|
|
87
|
+
| Inbound email | rejected with a maintenance reason |
|
|
88
|
+
|
|
89
|
+
A response that took longer than 30 seconds re-checks before release. If the
|
|
90
|
+
deployment was fenced, or its generation changed meanwhile, the response is
|
|
91
|
+
withheld with `503 RECOVERY_GENERATION_CHANGED`. Every response carries
|
|
92
|
+
`x-quickback-generation`, the sum of the per-binding generations. With
|
|
93
|
+
[read replication](/platform/database/read-replication), a client that sends
|
|
94
|
+
`x-quickback-generation` along with its bookmark has the bookmark dropped when
|
|
95
|
+
the generation differs. A bookmark from before a restore can then never point
|
|
96
|
+
past it. A bookmark sent without the header behaves as before: the wait is
|
|
97
|
+
bounded by `bookmarkWaitMs`.
|
|
98
|
+
|
|
99
|
+
### What is not covered
|
|
100
|
+
|
|
101
|
+
The guarantee covers generated entry points only. These are **unmanaged
|
|
102
|
+
writers**, which you must stop and reconcile yourself:
|
|
103
|
+
|
|
104
|
+
- Durable Object classes, which receive the raw `env`. The restore plan lists every class except `QuickbackControl` and `Broadcaster`, and refuses to plan until each is declared with `--writers-stopped`;
|
|
105
|
+
- Workflows, also listed by the plan;
|
|
106
|
+
- custom Workers, scripts or external clients that use the database through the API, and `wrangler d1 execute`;
|
|
107
|
+
- consumers outside this Worker, which receive effect envelopes without admission.
|
|
108
|
+
|
|
109
|
+
Streaming response bodies continue after release and are not re-checked.
|
|
110
|
+
|
|
111
|
+
## Restore
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# 1. Read-only plan. Resolves the timestamp to an immutable bookmark per binding.
|
|
115
|
+
quickback db restore-plan --env production --url https://api.example.com \
|
|
116
|
+
--binding DB --timestamp 2026-11-18T10:00:00Z --out restore.json
|
|
117
|
+
# …or pin the exact bookmarks a checkpoint recorded:
|
|
118
|
+
# --checkpoint checkpoint.json (instead of --timestamp)
|
|
119
|
+
|
|
120
|
+
# 2. Review restore.json, then apply with the exact digest it printed.
|
|
121
|
+
QB_RECOVERY_OPERATOR_KEY=… quickback db restore-apply restore.json --confirm <plan-digest>
|
|
122
|
+
|
|
123
|
+
# 3. Reopen with the resume digest that apply printed after verification.
|
|
124
|
+
quickback db restore-resume --operation r-… --plan restore.json --confirm <resume-digest>
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The plan records:
|
|
128
|
+
|
|
129
|
+
- the target: account, logical environment, Wrangler environment, Worker and URL;
|
|
130
|
+
- each binding's database ID, current bookmark, target bookmark and timestamp;
|
|
131
|
+
- the local migration manifest hash;
|
|
132
|
+
- the control contract version and current generations;
|
|
133
|
+
- the enabled recovery hooks (versioned);
|
|
134
|
+
- the unmanaged writers you declared stopped.
|
|
135
|
+
|
|
136
|
+
**A timestamp is not an exact point.** Time Travel restores to "any minute":
|
|
137
|
+
a timestamp resolves to the latest bookmark the platform recorded at or before
|
|
138
|
+
it, which can be minutes older than the timestamp. Writes committed shortly
|
|
139
|
+
before the timestamp can be lost. In a live drill, every timestamp from 9 s to
|
|
140
|
+
35 s after a burst of writes resolved to the bookmark from before the burst. To
|
|
141
|
+
restore an exact point, take a [checkpoint](#checkpoints) when you have one and
|
|
142
|
+
plan with `--checkpoint`. The plan refuses a checkpoint that was edited, or that
|
|
143
|
+
has no bookmark for a selected binding's database.
|
|
144
|
+
|
|
145
|
+
The plan contains no rows and no credentials. Its digest is the SHA-256 of the
|
|
146
|
+
canonical document. Repeat `--binding` to restore several databases as an
|
|
147
|
+
ordered saga.
|
|
148
|
+
|
|
149
|
+
`restore-apply` rereads the target identity, the Worker's recovery contract and
|
|
150
|
+
the local migrations, and refuses if anything changed since review. The
|
|
151
|
+
operation ID comes from the plan digest. Each stage is a compare-and-set in the
|
|
152
|
+
control object, outside every restored database, and appended to its history:
|
|
153
|
+
|
|
154
|
+
| Stage | Work |
|
|
155
|
+
|---|---|
|
|
156
|
+
| `planned` | operation recorded |
|
|
157
|
+
| `fenced` | `fence` each binding |
|
|
158
|
+
| `drained` | poll `drain` until quiescent (`--drain-timeout`, default 120 s). Unsettled effect receipts stop here: resolve them with `quickback effects resolve` |
|
|
159
|
+
| `prior-bookmarks-recorded` | current bookmarks captured: the undo point |
|
|
160
|
+
| `restoring` | each binding is marked `unknown`, then restored by bookmark (`wrangler d1 time-travel restore --json`). The returned undo bookmark is recorded at once |
|
|
161
|
+
| `restored` | every binding restored |
|
|
162
|
+
| `reconciling` | `rotateGeneration` per binding (idempotent across crashes), then `reconcileRestoredEffects` on the effects binding |
|
|
163
|
+
| `verified` | the checks below passed; a resume digest is recorded |
|
|
164
|
+
| `resumed` | `resume` each binding (only via `restore-resume`) |
|
|
165
|
+
|
|
166
|
+
Running `restore-apply` again with the same plan **continues from the recorded
|
|
167
|
+
stage**. It never starts a second blind restore.
|
|
168
|
+
|
|
169
|
+
- **Lost acknowledgement.** If a restore call fails or returns no usable acknowledgement, the binding stays `unknown`. Completion is never inferred from a changed bookmark. Rerun with `--retry-unknown`: restoring to the same immutable bookmark under the fence is safe.
|
|
170
|
+
- **Partial success.** With several bindings, finished ones stay `restored`, and the run stops with the fence held.
|
|
171
|
+
- **Failure.** Every failure leaves the fence held. `restore-status --operation <id> --url …` shows the stage, history, per-binding restore results, recorded bookmarks, rotation, effect counts and verification.
|
|
172
|
+
|
|
173
|
+
### Verification
|
|
174
|
+
|
|
175
|
+
`restore-verify restore.json` runs the same checks under maintenance through the
|
|
176
|
+
bridge. They are bounded and read-only:
|
|
177
|
+
|
|
178
|
+
- `PRAGMA quick_check` reports `ok`;
|
|
179
|
+
- the restored `d1_migrations` list equals the deployed Worker's migrations exactly. If not, the restored schema is incompatible: apply a separately reviewed migration or deployment, then verify again. Migrations are never rolled back automatically;
|
|
180
|
+
- the generation was rotated;
|
|
181
|
+
- no durable effect from an older generation is left unreconciled;
|
|
182
|
+
- no virtual tables exist unless the `search` recovery hook is registered. That hook belongs to plan 038, full-text search, and is not registered yet, so a database with FTS tables does not reopen.
|
|
183
|
+
|
|
184
|
+
Two failed verifications stop the operation until you pass
|
|
185
|
+
`--acknowledge-failures`. `restore-resume` reruns verification and recomputes
|
|
186
|
+
the digest. Any change since verification refuses the reopen. That includes a
|
|
187
|
+
moved generation, a schema change or a reconciled effect.
|
|
188
|
+
|
|
189
|
+
### Recovery hooks
|
|
190
|
+
|
|
191
|
+
| Hook | Covers |
|
|
192
|
+
|---|---|
|
|
193
|
+
| `admission` | the fence and drain above |
|
|
194
|
+
| `generation-rotation` | the non-rewound generation. Old effect envelopes become stale. The [read cache](/define/read#the-data-epoch) does not depend on it: its epoch token is restore-safe on its own |
|
|
195
|
+
| `effects-reconcile` | an intent with an `accepted` receipt is marked accepted and **not resent**. An uncertain one is quarantined. A never-dispatched one is quarantined, or reissued in the new generation with `--reissue-pending` at plan time |
|
|
196
|
+
| `search` | not registered (plan 038). Virtual tables block verification |
|
|
197
|
+
|
|
198
|
+
### Undo
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
quickback db restore-undo-plan --operation r-… --plan restore.json --out undo.json
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
This builds a **new** reviewed plan whose targets are the bookmarks captured at
|
|
205
|
+
`prior-bookmarks-recorded`. Apply it like any plan. It is another fenced saga.
|
|
206
|
+
It does not reverse external effects that ran in between.
|
|
207
|
+
|
|
208
|
+
### Checkpoints
|
|
209
|
+
|
|
210
|
+
`quickback db checkpoint --env production --binding DB [--binding AUTH_DB] --out checkpoint.json`
|
|
211
|
+
records each binding's current bookmark and migration manifest. It is an
|
|
212
|
+
inventory of exact points to plan against (`restore-plan --checkpoint`), not a portable backup. Time Travel
|
|
213
|
+
retention depends on your plan and backend. The CLI does not assume a horizon.
|
|
214
|
+
A bookmark the platform no longer has fails with `RECOVERY_BOOKMARK_UNAVAILABLE`.
|
|
215
|
+
|
|
216
|
+
## Exports
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
quickback db export-plan --env production --binding DB --format d1 \
|
|
220
|
+
--directory /secure/exports --out export.json
|
|
221
|
+
quickback db export-apply export.json --confirm <digest>
|
|
222
|
+
quickback db export-verify /secure/exports/<file>.sql.receipt.json
|
|
223
|
+
quickback db export-status export.json
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
| Format | Contains | Restorable into D1 |
|
|
227
|
+
|---|---|---|
|
|
228
|
+
| `d1` | ordinary tables (whole database or `--table`) | yes |
|
|
229
|
+
| `sqlite3_cli_only` | the whole database, including virtual tables (Wrangler `--compatibility sqlite3_cli_only`) | **no**, an analysis artifact only |
|
|
230
|
+
|
|
231
|
+
`export-plan` inventories tables, including virtual tables and FTS shadow
|
|
232
|
+
tables, without exporting data. A `d1` export of a database with virtual tables
|
|
233
|
+
is refused unless you select ordinary tables with `--table`. Tables are never
|
|
234
|
+
omitted silently. After importing such an export, rebuild the search state.
|
|
235
|
+
|
|
236
|
+
`export-apply`:
|
|
237
|
+
|
|
238
|
+
1. Rechecks the digest, the target and the directory.
|
|
239
|
+
2. Records each binding's bookmark.
|
|
240
|
+
3. Runs `wrangler d1 export` into an exclusively created `.partial` file.
|
|
241
|
+
4. Verifies the size, SHA-256, format and the planned tables.
|
|
242
|
+
5. Renames the file atomically and writes a receipt.
|
|
243
|
+
|
|
244
|
+
The directory must be an absolute real path, with no symlink, outside every
|
|
245
|
+
Git worktree. It is created with mode `0700`. Files and receipts get `0600`.
|
|
246
|
+
Receipts hold hashes, sizes, bookmarks and table names, never rows, SQL or
|
|
247
|
+
signed URLs. Wrangler output is never echoed.
|
|
248
|
+
|
|
249
|
+
An interrupted or failed export stays `.partial` and cannot verify. Rerun with
|
|
250
|
+
`--restart` to discard it. Repeated bindings are exported independently, each
|
|
251
|
+
at its own bookmark. Exports offer no cross-database snapshot, upload, Git
|
|
252
|
+
attachment or retention deletion.
|
|
253
|
+
|
|
254
|
+
A remote D1 export can make the database briefly unavailable to queries.
|
|
255
|
+
Export does not fence. Run it in a quiet period, or fence first.
|
|
256
|
+
|
|
257
|
+
## Operator bridge
|
|
258
|
+
|
|
259
|
+
The CLI signs every request with the operator key from **its own process
|
|
260
|
+
environment**. Plan files never contain the key. The signed string covers the
|
|
261
|
+
method, the exact origin and path, a millisecond timestamp, a single-use nonce
|
|
262
|
+
and the SHA-256 of the body:
|
|
263
|
+
|
|
264
|
+
```text
|
|
265
|
+
QBOP1\nPOST\nhttps://api.example.com/__quickback/operator\n<timestamp>\n<nonce>\n<body-sha256>
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
The Worker checks it before any auth or database middleware.
|
|
269
|
+
|
|
270
|
+
- Timestamps more than 5 minutes off are refused.
|
|
271
|
+
- Nonces are claimed in the control object, so a replay is refused.
|
|
272
|
+
- A request signed for another origin fails. Use a different key per target.
|
|
273
|
+
- Session cookies, API keys and other application credentials cannot reach any operation.
|
|
274
|
+
|
|
275
|
+
The bridge also carries the plan-037 operator path:
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
quickback effects state --url https://api.example.com [--binding DB]
|
|
279
|
+
quickback effects list --url https://api.example.com --state quarantined|dead|pending
|
|
280
|
+
quickback effects replay <id> --url https://api.example.com --confirm-hash <payload_hash> [--reconciled not-delivered]
|
|
281
|
+
quickback effects resolve <id> --url https://api.example.com --binding DB --dispatch accepted|failed
|
|
282
|
+
quickback effects reconcile --url https://api.example.com [--reissue-pending]
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
`list` returns IDs, states, attempts, error classes and payload hashes. It
|
|
286
|
+
never returns payloads.
|
|
287
|
+
|
|
288
|
+
## Limits
|
|
289
|
+
|
|
290
|
+
- The admission window is fixed: 30 seconds plus 5 seconds of skew. A single D1 batch that starts executing later than that after its observation fails and must be retried.
|
|
291
|
+
- A deployed-account drill has not been run yet. Before relying on this in production, rehearse export, verify, restore and resume against a disposable staging database, and keep the receipts.
|
|
292
|
+
- Tenant Durable Object recovery is separate. See [Tenancy](/configure/tenancy).
|