@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.
Files changed (210) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +8 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/db-explain.d.ts +67 -0
  5. package/dist/commands/db-explain.d.ts.map +1 -0
  6. package/dist/commands/db-explain.js +141 -0
  7. package/dist/commands/db-explain.js.map +1 -0
  8. package/dist/commands/db-export.d.ts +34 -0
  9. package/dist/commands/db-export.d.ts.map +1 -0
  10. package/dist/commands/db-export.js +250 -0
  11. package/dist/commands/db-export.js.map +1 -0
  12. package/dist/commands/db-insights.d.ts +60 -0
  13. package/dist/commands/db-insights.d.ts.map +1 -0
  14. package/dist/commands/db-insights.js +106 -0
  15. package/dist/commands/db-insights.js.map +1 -0
  16. package/dist/commands/db-recovery.d.ts +98 -0
  17. package/dist/commands/db-recovery.d.ts.map +1 -0
  18. package/dist/commands/db-recovery.js +558 -0
  19. package/dist/commands/db-recovery.js.map +1 -0
  20. package/dist/commands/db-target.d.ts +27 -0
  21. package/dist/commands/db-target.d.ts.map +1 -0
  22. package/dist/commands/db-target.js +83 -0
  23. package/dist/commands/db-target.js.map +1 -0
  24. package/dist/commands/db.d.ts +3 -0
  25. package/dist/commands/db.d.ts.map +1 -0
  26. package/dist/commands/db.js +43 -0
  27. package/dist/commands/db.js.map +1 -0
  28. package/dist/commands/effects.d.ts +8 -0
  29. package/dist/commands/effects.d.ts.map +1 -0
  30. package/dist/commands/effects.js +48 -0
  31. package/dist/commands/effects.js.map +1 -0
  32. package/dist/commands/platform-budget.d.ts +143 -0
  33. package/dist/commands/platform-budget.d.ts.map +1 -0
  34. package/dist/commands/platform-budget.js +619 -0
  35. package/dist/commands/platform-budget.js.map +1 -0
  36. package/dist/commands/preview.d.ts +57 -0
  37. package/dist/commands/preview.d.ts.map +1 -0
  38. package/dist/commands/preview.js +268 -0
  39. package/dist/commands/preview.js.map +1 -0
  40. package/dist/commands/search.d.ts +20 -0
  41. package/dist/commands/search.d.ts.map +1 -0
  42. package/dist/commands/search.js +133 -0
  43. package/dist/commands/search.js.map +1 -0
  44. package/dist/index.js +35 -1
  45. package/dist/index.js.map +1 -1
  46. package/dist/lib/api-client.d.ts +4 -0
  47. package/dist/lib/api-client.d.ts.map +1 -1
  48. package/dist/lib/api-client.js.map +1 -1
  49. package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
  50. package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
  51. package/dist/lib/cloudflare-spend-policies.js +289 -0
  52. package/dist/lib/cloudflare-spend-policies.js.map +1 -0
  53. package/dist/lib/compiler-stubs.d.ts +2 -0
  54. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  55. package/dist/lib/compiler-stubs.js +2 -0
  56. package/dist/lib/compiler-stubs.js.map +1 -1
  57. package/dist/lib/d1-fingerprint.d.ts +8 -0
  58. package/dist/lib/d1-fingerprint.d.ts.map +1 -0
  59. package/dist/lib/d1-fingerprint.js +113 -0
  60. package/dist/lib/d1-fingerprint.js.map +1 -0
  61. package/dist/lib/file-loader.d.ts +12 -0
  62. package/dist/lib/file-loader.d.ts.map +1 -1
  63. package/dist/lib/file-loader.js +27 -1
  64. package/dist/lib/file-loader.js.map +1 -1
  65. package/dist/lib/migrations/plan.js +3 -0
  66. package/dist/lib/migrations/plan.js.map +1 -1
  67. package/dist/lib/migrations/postprocessors/index.d.ts +6 -5
  68. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  69. package/dist/lib/migrations/postprocessors/index.js +24 -12
  70. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  71. package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
  72. package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
  73. package/dist/lib/migrations/postprocessors/search.js +160 -0
  74. package/dist/lib/migrations/postprocessors/search.js.map +1 -0
  75. package/dist/lib/migrations/prior-state.d.ts +7 -0
  76. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  77. package/dist/lib/migrations/prior-state.js +3 -0
  78. package/dist/lib/migrations/prior-state.js.map +1 -1
  79. package/dist/lib/migrations/types.d.ts +1 -1
  80. package/dist/lib/migrations/types.d.ts.map +1 -1
  81. package/dist/lib/migrations/types.js +1 -0
  82. package/dist/lib/migrations/types.js.map +1 -1
  83. package/dist/lib/preview-lifecycle.d.ts +139 -0
  84. package/dist/lib/preview-lifecycle.d.ts.map +1 -0
  85. package/dist/lib/preview-lifecycle.js +429 -0
  86. package/dist/lib/preview-lifecycle.js.map +1 -0
  87. package/dist/lib/preview.d.ts +146 -0
  88. package/dist/lib/preview.d.ts.map +1 -0
  89. package/dist/lib/preview.js +417 -0
  90. package/dist/lib/preview.js.map +1 -0
  91. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  92. package/dist/lib/wrangler-resources.js +4 -2
  93. package/dist/lib/wrangler-resources.js.map +1 -1
  94. package/dist/skill/SKILL.md +9 -3
  95. package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
  96. package/dist/skill/docs/api/batch-operations.md +19 -0
  97. package/dist/skill/docs/api/caching.md +17 -0
  98. package/dist/skill/docs/api/crud.md +9 -0
  99. package/dist/skill/docs/api/errors.md +31 -2
  100. package/dist/skill/docs/api/query-params.md +6 -0
  101. package/dist/skill/docs/changelog/index.md +1 -0
  102. package/dist/skill/docs/configure/agents.md +1 -1
  103. package/dist/skill/docs/configure/bindings.md +177 -1
  104. package/dist/skill/docs/configure/cloudflare-access.md +43 -0
  105. package/dist/skill/docs/configure/domains.md +1 -1
  106. package/dist/skill/docs/configure/providers.md +5 -0
  107. package/dist/skill/docs/configure/tenant-databases.md +627 -14
  108. package/dist/skill/docs/define/access.md +26 -0
  109. package/dist/skill/docs/define/actions/defining.md +7 -1
  110. package/dist/skill/docs/define/actions/index.md +5 -0
  111. package/dist/skill/docs/define/actions/scoped-db.md +127 -1
  112. package/dist/skill/docs/define/authoring-basics.md +92 -0
  113. package/dist/skill/docs/define/changesets.md +8 -0
  114. package/dist/skill/docs/define/encryption.md +48 -2
  115. package/dist/skill/docs/define/feature.md +17 -2
  116. package/dist/skill/docs/define/guards.md +11 -3
  117. package/dist/skill/docs/define/index.md +1 -1
  118. package/dist/skill/docs/define/invariants.md +321 -0
  119. package/dist/skill/docs/define/issue-tracker-example.md +225 -0
  120. package/dist/skill/docs/define/masking.md +3 -3
  121. package/dist/skill/docs/define/rate-limit.md +63 -22
  122. package/dist/skill/docs/define/read.md +332 -5
  123. package/dist/skill/docs/define/relationships.md +10 -0
  124. package/dist/skill/docs/define/schema.md +137 -10
  125. package/dist/skill/docs/define/scopes.md +1 -0
  126. package/dist/skill/docs/define/transitions.md +9 -0
  127. package/dist/skill/docs/define/triggers.md +127 -1
  128. package/dist/skill/docs/platform/api-contract/index.md +35 -4
  129. package/dist/skill/docs/platform/auth/api-keys.md +26 -3
  130. package/dist/skill/docs/platform/auth/index.md +5 -2
  131. package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
  132. package/dist/skill/docs/platform/database/d1.md +73 -1
  133. package/dist/skill/docs/platform/database/durable-effects.md +224 -0
  134. package/dist/skill/docs/platform/database/read-replication.md +9 -0
  135. package/dist/skill/docs/platform/database/recovery.md +292 -0
  136. package/dist/skill/docs/platform/database/using-d1.md +152 -2
  137. package/dist/skill/docs/platform/index.md +1 -0
  138. package/dist/skill/docs/platform/operations/budgets.md +224 -0
  139. package/dist/skill/docs/platform/queues/handlers.md +1 -0
  140. package/dist/skill/docs/platform/queues/index.md +18 -0
  141. package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
  142. package/dist/skill/docs/platform/storage/using-r2.md +13 -0
  143. package/dist/skill/docs/platform/vector/embeddings.md +28 -4
  144. package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
  145. package/dist/skill/docs/platform/workflows/index.md +385 -0
  146. package/dist/skill/docs/start/deploy-browser.md +51 -0
  147. package/dist/skill/docs/start/deploy.md +97 -1
  148. package/dist/skill/docs/tooling/cli.md +117 -0
  149. package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
  150. package/dist/skill/docs/ui/account/customization.md +4 -0
  151. package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
  152. package/package.json +1 -1
  153. package/src/skill/SKILL.md +9 -3
  154. package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
  155. package/src/skill/docs/api/batch-operations.md +19 -0
  156. package/src/skill/docs/api/caching.md +17 -0
  157. package/src/skill/docs/api/crud.md +9 -0
  158. package/src/skill/docs/api/errors.md +31 -2
  159. package/src/skill/docs/api/query-params.md +6 -0
  160. package/src/skill/docs/changelog/index.md +1 -0
  161. package/src/skill/docs/configure/agents.md +1 -1
  162. package/src/skill/docs/configure/bindings.md +177 -1
  163. package/src/skill/docs/configure/cloudflare-access.md +43 -0
  164. package/src/skill/docs/configure/domains.md +1 -1
  165. package/src/skill/docs/configure/providers.md +5 -0
  166. package/src/skill/docs/configure/tenant-databases.md +627 -14
  167. package/src/skill/docs/define/access.md +26 -0
  168. package/src/skill/docs/define/actions/defining.md +7 -1
  169. package/src/skill/docs/define/actions/index.md +5 -0
  170. package/src/skill/docs/define/actions/scoped-db.md +127 -1
  171. package/src/skill/docs/define/authoring-basics.md +92 -0
  172. package/src/skill/docs/define/changesets.md +8 -0
  173. package/src/skill/docs/define/encryption.md +48 -2
  174. package/src/skill/docs/define/feature.md +17 -2
  175. package/src/skill/docs/define/guards.md +11 -3
  176. package/src/skill/docs/define/index.md +1 -1
  177. package/src/skill/docs/define/invariants.md +321 -0
  178. package/src/skill/docs/define/issue-tracker-example.md +225 -0
  179. package/src/skill/docs/define/masking.md +3 -3
  180. package/src/skill/docs/define/rate-limit.md +63 -22
  181. package/src/skill/docs/define/read.md +332 -5
  182. package/src/skill/docs/define/relationships.md +10 -0
  183. package/src/skill/docs/define/schema.md +137 -10
  184. package/src/skill/docs/define/scopes.md +1 -0
  185. package/src/skill/docs/define/transitions.md +9 -0
  186. package/src/skill/docs/define/triggers.md +127 -1
  187. package/src/skill/docs/platform/api-contract/index.md +35 -4
  188. package/src/skill/docs/platform/auth/api-keys.md +26 -3
  189. package/src/skill/docs/platform/auth/index.md +5 -2
  190. package/src/skill/docs/platform/auth/plugins/index.md +1 -1
  191. package/src/skill/docs/platform/database/d1.md +73 -1
  192. package/src/skill/docs/platform/database/durable-effects.md +224 -0
  193. package/src/skill/docs/platform/database/read-replication.md +9 -0
  194. package/src/skill/docs/platform/database/recovery.md +292 -0
  195. package/src/skill/docs/platform/database/using-d1.md +152 -2
  196. package/src/skill/docs/platform/index.md +1 -0
  197. package/src/skill/docs/platform/operations/budgets.md +224 -0
  198. package/src/skill/docs/platform/queues/handlers.md +1 -0
  199. package/src/skill/docs/platform/queues/index.md +18 -0
  200. package/src/skill/docs/platform/realtime/table-changes.md +1 -0
  201. package/src/skill/docs/platform/storage/using-r2.md +13 -0
  202. package/src/skill/docs/platform/vector/embeddings.md +28 -4
  203. package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
  204. package/src/skill/docs/platform/workflows/index.md +385 -0
  205. package/src/skill/docs/start/deploy-browser.md +51 -0
  206. package/src/skill/docs/start/deploy.md +97 -1
  207. package/src/skill/docs/tooling/cli.md +117 -0
  208. package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
  209. package/src/skill/docs/ui/account/customization.md +4 -0
  210. 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).