@quickback-dev/cli 0.70.27 → 0.70.38
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/codex/AGENTS.md +290 -0
- package/dist/commands/build.d.ts +12 -0
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +69 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/codex.d.ts +16 -0
- package/dist/commands/codex.d.ts.map +1 -0
- package/dist/commands/codex.js +159 -0
- package/dist/commands/codex.js.map +1 -0
- package/dist/commands/compile.d.ts +62 -0
- package/dist/commands/compile.d.ts.map +1 -0
- package/dist/commands/compile.js +830 -0
- package/dist/commands/compile.js.map +1 -0
- package/dist/commands/compile.test.d.ts.map +1 -0
- package/dist/commands/deploy.d.ts +9 -0
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +20 -2
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/init.d.ts +6 -0
- package/dist/commands/init.d.ts.map +1 -0
- package/dist/commands/init.js +405 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/migrate-data.d.ts +12 -0
- package/dist/commands/migrate-data.d.ts.map +1 -0
- package/dist/commands/migrate-data.js +134 -0
- package/dist/commands/migrate-data.js.map +1 -0
- package/dist/commands/migrate.d.ts.map +1 -1
- package/dist/commands/migrate.js +11 -0
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrate.test.d.ts.map +1 -0
- package/dist/commands/migrations.test.d.ts.map +1 -0
- package/dist/commands/push.test.d.ts.map +1 -0
- package/dist/commands/schema.test.d.ts.map +1 -0
- package/dist/commands/secrets.d.ts +27 -0
- package/dist/commands/secrets.d.ts.map +1 -0
- package/dist/commands/secrets.js +186 -0
- package/dist/commands/secrets.js.map +1 -0
- package/dist/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +672 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/docs/index.test.d.ts.map +1 -0
- package/dist/index.js +23 -3
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +87 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -0
- package/dist/lib/access-manifest-diff.js +331 -0
- package/dist/lib/access-manifest-diff.js.map +1 -0
- package/dist/lib/action-harvest.test.d.ts.map +1 -0
- package/dist/lib/api-client.test.d.ts.map +1 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +3 -0
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/artifact-routing.test.d.ts.map +1 -0
- package/dist/lib/auth.test.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
- package/dist/lib/compiler-floor.test.d.ts.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/config-id-splice.test.d.ts.map +1 -0
- package/dist/lib/config-sync.test.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.test.d.ts.map +1 -0
- package/dist/lib/copy-source-apps.test.d.ts.map +1 -0
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +1 -0
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +1 -0
- package/dist/lib/file-loader.d.ts +6 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +17 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.d.ts.map +1 -0
- package/dist/lib/file-writer.test.d.ts.map +1 -0
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +1 -0
- package/dist/lib/migrations/drizzle.test.d.ts.map +1 -0
- package/dist/lib/migrations/executor.test.d.ts.map +1 -0
- package/dist/lib/migrations/inventory.test.d.ts.map +1 -0
- package/dist/lib/migrations/lock.test.d.ts.map +1 -0
- package/dist/lib/migrations/paths.test.d.ts.map +1 -0
- package/dist/lib/migrations/plan.test.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +1 -0
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +1 -0
- package/dist/lib/migrations/staging.test.d.ts.map +1 -0
- package/dist/lib/neon-canary.test.d.ts.map +1 -0
- package/dist/lib/neon-target.test.d.ts.map +1 -0
- package/dist/lib/neon.test.d.ts.map +1 -0
- package/dist/lib/ops-manifest.d.ts +76 -0
- package/dist/lib/ops-manifest.d.ts.map +1 -0
- package/dist/lib/ops-manifest.js +94 -0
- package/dist/lib/ops-manifest.js.map +1 -0
- package/dist/lib/prepare-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
- package/dist/lib/release-and-pin.d.ts +34 -0
- package/dist/lib/release-and-pin.d.ts.map +1 -0
- package/dist/lib/release-and-pin.js +71 -0
- package/dist/lib/release-and-pin.js.map +1 -0
- package/dist/lib/schema-sync/index.test.d.ts.map +1 -0
- package/dist/lib/shell.d.ts +4 -1
- package/dist/lib/shell.d.ts.map +1 -1
- package/dist/lib/shell.js +8 -3
- package/dist/lib/shell.js.map +1 -1
- package/dist/lib/shell.test.d.ts.map +1 -0
- package/dist/lib/sweep-stale.d.ts +25 -0
- package/dist/lib/sweep-stale.d.ts.map +1 -0
- package/dist/lib/sweep-stale.js +179 -0
- package/dist/lib/sweep-stale.js.map +1 -0
- package/dist/lib/sweep-stale.test.d.ts.map +1 -0
- package/dist/lib/wrangler-resources.test.d.ts.map +1 -0
- package/dist/skill/docs/api/actions.md +2 -0
- package/dist/skill/docs/api/batch-operations.md +18 -4
- package/dist/skill/docs/api/crud.md +62 -0
- package/dist/skill/docs/api/errors.md +17 -2
- package/dist/skill/docs/configure/auth.md +49 -2
- package/dist/skill/docs/configure/bindings.md +15 -0
- package/dist/skill/docs/configure/domains.md +4 -0
- package/dist/skill/docs/configure/index.md +29 -11
- package/dist/skill/docs/configure/providers.md +1 -0
- package/dist/skill/docs/configure/tenancy.md +117 -0
- package/dist/skill/docs/define/access.md +19 -0
- package/dist/skill/docs/define/actions/access.md +76 -0
- package/dist/skill/docs/define/actions/defining.md +156 -1
- package/dist/skill/docs/define/actions/scoped-db.md +236 -9
- package/dist/skill/docs/define/areas.md +46 -0
- package/dist/skill/docs/define/authz-roles.md +10 -0
- package/dist/skill/docs/define/diagnostics.md +263 -0
- package/dist/skill/docs/define/encryption.md +34 -2
- package/dist/skill/docs/define/guards.md +13 -0
- package/dist/skill/docs/define/masking.md +77 -3
- package/dist/skill/docs/define/rate-limit.md +3 -3
- package/dist/skill/docs/define/schema.md +148 -7
- package/dist/skill/docs/define/scopes.md +79 -0
- package/dist/skill/docs/define/sealed-protocol.md +111 -9
- package/dist/skill/docs/define/transitions.md +39 -0
- package/dist/skill/docs/define/views.md +77 -3
- package/dist/skill/docs/platform/api-contract/index.md +4 -0
- package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/dist/skill/docs/platform/auth/using-auth.md +6 -0
- package/dist/skill/docs/platform/database/d1.md +47 -0
- package/dist/skill/docs/platform/database/data-migrations.md +109 -0
- package/dist/skill/docs/platform/database/index.md +1 -0
- package/dist/skill/docs/platform/database/read-replication.md +257 -0
- package/dist/skill/docs/platform/database/using-d1.md +2 -1
- package/dist/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/dist/skill/docs/platform/push/index.md +2 -0
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/dist/skill/docs/platform/storage/using-r2.md +135 -19
- package/dist/skill/docs/start/deploy.md +38 -0
- package/dist/skill/docs/tooling/cli.md +120 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/dist/skill/docs/tooling/output.md +70 -2
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +2 -0
- package/src/skill/docs/api/batch-operations.md +18 -4
- package/src/skill/docs/api/crud.md +62 -0
- package/src/skill/docs/api/errors.md +17 -2
- package/src/skill/docs/configure/auth.md +49 -2
- package/src/skill/docs/configure/bindings.md +15 -0
- package/src/skill/docs/configure/domains.md +4 -0
- package/src/skill/docs/configure/index.md +29 -11
- package/src/skill/docs/configure/providers.md +1 -0
- package/src/skill/docs/configure/tenancy.md +117 -0
- package/src/skill/docs/define/access.md +19 -0
- package/src/skill/docs/define/actions/access.md +76 -0
- package/src/skill/docs/define/actions/defining.md +156 -1
- package/src/skill/docs/define/actions/scoped-db.md +236 -9
- package/src/skill/docs/define/areas.md +46 -0
- package/src/skill/docs/define/authz-roles.md +10 -0
- package/src/skill/docs/define/diagnostics.md +263 -0
- package/src/skill/docs/define/encryption.md +34 -2
- package/src/skill/docs/define/guards.md +13 -0
- package/src/skill/docs/define/masking.md +77 -3
- package/src/skill/docs/define/rate-limit.md +3 -3
- package/src/skill/docs/define/schema.md +148 -7
- package/src/skill/docs/define/scopes.md +79 -0
- package/src/skill/docs/define/sealed-protocol.md +111 -9
- package/src/skill/docs/define/transitions.md +39 -0
- package/src/skill/docs/define/views.md +77 -3
- package/src/skill/docs/platform/api-contract/index.md +4 -0
- package/src/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/src/skill/docs/platform/auth/using-auth.md +6 -0
- package/src/skill/docs/platform/database/d1.md +47 -0
- package/src/skill/docs/platform/database/data-migrations.md +109 -0
- package/src/skill/docs/platform/database/index.md +1 -0
- package/src/skill/docs/platform/database/read-replication.md +257 -0
- package/src/skill/docs/platform/database/using-d1.md +2 -1
- package/src/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/src/skill/docs/platform/push/index.md +2 -0
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/src/skill/docs/platform/storage/using-r2.md +135 -19
- package/src/skill/docs/start/deploy.md +38 -0
- package/src/skill/docs/tooling/cli.md +120 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/src/skill/docs/tooling/output.md +70 -2
|
@@ -84,6 +84,10 @@ caller-generated UUID, ≤ 255 chars) to make the write safe to retry:
|
|
|
84
84
|
- Keys expire after **24 hours** (Stripe semantics); 5xx and `Set-Cookie`
|
|
85
85
|
responses release the lock instead of caching.
|
|
86
86
|
|
|
87
|
+
The key is per **request**. For "this client-side record exists exactly
|
|
88
|
+
once" across sessions and devices, store a per-**row** token instead — see
|
|
89
|
+
[Row-token idempotency](/api/crud#row-token-idempotency).
|
|
90
|
+
|
|
87
91
|
**Claims are bound to the calling principal.** A replay from a different
|
|
88
92
|
principal — another user, another scope subject, a delegated machine
|
|
89
93
|
principal, or a legacy row with no principal — is refused with a `422`
|
|
@@ -125,6 +125,8 @@ There is no same-second gap: markers are epoch milliseconds (written `m<ms>`), t
|
|
|
125
125
|
Revocation stamps are written **automatically** on:
|
|
126
126
|
|
|
127
127
|
- user ban
|
|
128
|
+
- the target of the admin plugin's `/admin/set-role`, `/admin/remove-user`, `/admin/update-user`, and `/admin/revoke-user-sessions`
|
|
129
|
+
- every [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound) write (ban, role change, account deletion)
|
|
128
130
|
- org-member removal and member role change (Better Auth `organizationHooks`)
|
|
129
131
|
- `UPDATE` / `DELETE` of scope-conferring relationship rows
|
|
130
132
|
|
|
@@ -80,16 +80,17 @@ const esc = (v: string) =>
|
|
|
80
80
|
.replace(/"/g, '"').replace(/'/g, ''');
|
|
81
81
|
|
|
82
82
|
export default function welcomeTemplate({ otp, name, appName, appUrl }: Input) {
|
|
83
|
-
|
|
83
|
+
// Plain text: TEMPLATE_UNESCAPED skips names containing `text`, `subject`, or `plain`.
|
|
84
|
+
const greetingText = name ? `Hi ${name},` : "Hi,";
|
|
84
85
|
return {
|
|
85
86
|
subject: `Welcome to ${appName} — set your password`,
|
|
86
87
|
html: `
|
|
87
88
|
<h1>Welcome to ${esc(appName)}</h1>
|
|
88
|
-
<p>${esc(
|
|
89
|
+
<p>${esc(greetingText)} your account is ready. Use this code to set your password and sign in:</p>
|
|
89
90
|
<p style="font-size:32px;letter-spacing:8px"><b>${esc(otp)}</b></p>
|
|
90
91
|
<p>Visit <a href="${esc(appUrl)}/set-password">${esc(appUrl)}/set-password</a> to finish setup.</p>
|
|
91
92
|
`,
|
|
92
|
-
text: `${
|
|
93
|
+
text: `${greetingText}\n\nYour ${appName} code: ${otp}\n\nFinish setup at ${appUrl}/set-password`,
|
|
93
94
|
};
|
|
94
95
|
}
|
|
95
96
|
```
|
|
@@ -114,6 +114,12 @@ export default defineConfig({
|
|
|
114
114
|
- The column set is fixed. Sessions, accounts and credentials are never returned.
|
|
115
115
|
- `roles` is required, and the organization plugin must be enabled — otherwise the compile fails.
|
|
116
116
|
|
|
117
|
+
## Changing users from actions — `ctx.auth`
|
|
118
|
+
|
|
119
|
+
Action code that bans a user, changes a member's role, deletes an account, or lists an organization's members uses `ctx.auth` — typed, bound to the caller's active organization, written through Better Auth's adapter, and stamping the `qbrev:user` [revocation entry](/configure/auth#revocationcheck-none--kv--token-revocation-strategy) so outstanding JWTs die. Never write the auth tables through `authDb`. Full reference: [`ctx.auth`](/define/actions/scoped-db#ctxauth--better-auth-users-and-members-org-bound).
|
|
120
|
+
|
|
121
|
+
Rows addressed to an email before the account exists (invitations, guest lists) can be linked automatically when the account verifies that email: [`auth.claims`](/configure/auth#authclaims--link-rows-to-the-account-that-verifies-their-email).
|
|
122
|
+
|
|
117
123
|
## Related
|
|
118
124
|
|
|
119
125
|
- [Auth Overview](/platform/auth) — Setup and configuration
|
|
@@ -225,6 +225,53 @@ binding name unchanged across environments; only the stateful identifiers —
|
|
|
225
225
|
`database_id`, queue names, bucket names (and optionally `database_name`) —
|
|
226
226
|
are per-environment.
|
|
227
227
|
|
|
228
|
+
### Inheriting from another target (`extends`)
|
|
229
|
+
|
|
230
|
+
A staging target is usually production with different identities. Instead of
|
|
231
|
+
copying production's block, extend it and list only what differs:
|
|
232
|
+
|
|
233
|
+
{/* doc-compile: skip — excerpt of the `environments` block; `production` is the entry shown above. */}
|
|
234
|
+
```typescript title="quickback/quickback.config.ts"
|
|
235
|
+
environments: {
|
|
236
|
+
production: { /* … as above … */ },
|
|
237
|
+
staging: {
|
|
238
|
+
extends: "production",
|
|
239
|
+
name: "my-app-staging",
|
|
240
|
+
domain: "api-staging.example.com",
|
|
241
|
+
worker: {
|
|
242
|
+
env: "staging",
|
|
243
|
+
vars: { BETTER_AUTH_URL: "https://api-staging.example.com" },
|
|
244
|
+
bindings: {
|
|
245
|
+
d1: {
|
|
246
|
+
auth: { databaseId: "…" },
|
|
247
|
+
features: { databaseId: "…" },
|
|
248
|
+
},
|
|
249
|
+
},
|
|
250
|
+
},
|
|
251
|
+
},
|
|
252
|
+
},
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
The compiler resolves `extends` before anything else reads the config. The
|
|
256
|
+
validator, the `[env.*]` emitter, the hostname resolver, and the ops manifest
|
|
257
|
+
all see one complete target, so the generated `[env.staging]` stanza is as
|
|
258
|
+
complete as a hand-written one. The rules:
|
|
259
|
+
|
|
260
|
+
- **Objects merge key by key, arrays and scalars replace.** In the example,
|
|
261
|
+
`worker.vars` keeps production's other vars and overrides
|
|
262
|
+
`BETTER_AUTH_URL`. `requiredSecrets`, `workersDev`, `previewUrls`,
|
|
263
|
+
`placement` and the email binding are inherited unchanged.
|
|
264
|
+
- **Identity and state are never inherited.** `name`, `domain` / `domains`,
|
|
265
|
+
`filesWorker`, `branch`, `worker.env`, and the stateful bindings `d1`, `kv`,
|
|
266
|
+
`hyperdrive`, `queues`, `r2Buckets` and `rateLimits` must be restated. If
|
|
267
|
+
any were inherited, a staging deploy would run on production's script,
|
|
268
|
+
hostnames, or data. If one is missing, the usual per-target errors name it
|
|
269
|
+
(for example, *must declare bindings.d1.features.databaseId*). When
|
|
270
|
+
production gains a new database role, every child that has not restated it
|
|
271
|
+
fails the compile, so a staging target cannot silently drift.
|
|
272
|
+
- **Chains are allowed. A cycle or an unknown parent is a compile error** that
|
|
273
|
+
names the chain (`staging → preview → staging`).
|
|
274
|
+
|
|
228
275
|
### Queues and R2 buckets per target
|
|
229
276
|
|
|
230
277
|
Queue names and R2 bucket names are stateful, so repeating the primary value
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Data Migrations
|
|
2
|
+
|
|
3
|
+
Schema migrations change the **shape** of your tables, and Drizzle generates
|
|
4
|
+
them for you. Data migrations change the **rows**: a backfill, a repair, a
|
|
5
|
+
one-time move. You write them as ordinary TypeScript under
|
|
6
|
+
`quickback/migrations/data/`, and `quickback migrate data` runs them inside the
|
|
7
|
+
deployed Worker for one environment.
|
|
8
|
+
|
|
9
|
+
```ts title="quickback/migrations/data/2026-10-21-archive-stale-drafts.ts"
|
|
10
|
+
import { defineDataMigration } from "@quickback/compiler";
|
|
11
|
+
import { and, eq, isNull } from "drizzle-orm";
|
|
12
|
+
import { projects } from "../../db/schema";
|
|
13
|
+
|
|
14
|
+
export default defineDataMigration({
|
|
15
|
+
id: "2026-10-21-archive-stale-drafts",
|
|
16
|
+
databases: ["DB"],
|
|
17
|
+
description: "Archive draft projects that never got a budget",
|
|
18
|
+
async run({ db, dryRun, log }) {
|
|
19
|
+
const stale = await db
|
|
20
|
+
.select({ id: projects.id })
|
|
21
|
+
.from(projects)
|
|
22
|
+
.where(and(eq(projects.status, "draft"), isNull(projects.budget)));
|
|
23
|
+
log(`${stale.length} stale draft project(s)`);
|
|
24
|
+
if (dryRun) return;
|
|
25
|
+
for (const row of stale) {
|
|
26
|
+
await db.update(projects).set({ status: "archived" }).where(eq(projects.id, row.id));
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
});
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Declare who may run them. There is no default role:
|
|
33
|
+
|
|
34
|
+
{/* doc-compile: skip — excerpt of the top-level `dataMigrations` key; the rest of `defineConfig` is unchanged. */}
|
|
35
|
+
```ts title="quickback/quickback.config.ts"
|
|
36
|
+
dataMigrations: {
|
|
37
|
+
access: { userRole: ["sysadmin"] },
|
|
38
|
+
},
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Then deploy and run:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
quickback deploy --env staging
|
|
45
|
+
quickback migrate data --env staging # dry run: logs, writes nothing
|
|
46
|
+
quickback migrate data --env staging --apply # writes, records the id
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## The definition
|
|
50
|
+
|
|
51
|
+
| Field | |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `id` | Ledger key, as a string literal. It runs once per environment. Ids run in sorted order, so start them with a date. |
|
|
54
|
+
| `databases` | Database bindings the migration touches (`["DB"]`). `db` is the first one, and `dbs[binding]` gives each. On D1 with split databases, the auth binding (`AUTH_DB`) is also allowed. |
|
|
55
|
+
| `description` | Shown by `quickback migrate data`. |
|
|
56
|
+
| `run({ db, dbs, env, dryRun, log })` | The work. `log()` lines (up to 500) go to the CLI and the ledger row. |
|
|
57
|
+
|
|
58
|
+
The compiler reads `id` and `databases` statically. A computed id, an unknown
|
|
59
|
+
binding, a duplicate id, or a missing `run` is a compile error that names the
|
|
60
|
+
file. From `@quickback/compiler` you may import only `defineDataMigration` (and
|
|
61
|
+
types). Relative imports resolve against the generated tree the same way they
|
|
62
|
+
do in action files, so `../../db/schema` is the generated schema barrel.
|
|
63
|
+
|
|
64
|
+
## Guarantees
|
|
65
|
+
|
|
66
|
+
- **Dry run by default.** Without `--apply`, the runner calls
|
|
67
|
+
`run({ dryRun: true })`, and every write method on the handle (`insert`,
|
|
68
|
+
`update`, `delete`, `batch`, `run`, `execute`, `transaction`) throws. A
|
|
69
|
+
migration that forgets to check `dryRun` fails loudly instead of writing.
|
|
70
|
+
- **Once per environment.** Each target's features database has its own
|
|
71
|
+
`_qb_data_migrations` ledger. Before `run` starts, `--apply` claims the id
|
|
72
|
+
with a single conflict-free `INSERT`, so two concurrent applies cannot both
|
|
73
|
+
run. An applied id answers `409 DATA_MIGRATION_ALREADY_APPLIED`.
|
|
74
|
+
- **Failures are recorded and retryable.** A thrown error marks the row
|
|
75
|
+
`failed`, with the message and log. The next `quickback migrate data` re-runs
|
|
76
|
+
it.
|
|
77
|
+
- **No implied transaction.** D1 has no transactions across statements, so
|
|
78
|
+
write migrations that are safe to re-run after a partial failure. Select
|
|
79
|
+
what still needs changing, as in the example above.
|
|
80
|
+
- **Audited.** When the project has the audit wrapper, writes are stamped
|
|
81
|
+
`system:data-migration-<id>`, and the ledger row records the operator's
|
|
82
|
+
user id. With [release stamping](/start/deploy#release-stamps) on, it also
|
|
83
|
+
records the release that applied the migration.
|
|
84
|
+
|
|
85
|
+
## Why it runs in the Worker
|
|
86
|
+
|
|
87
|
+
The runner is a route the compiler mounts at
|
|
88
|
+
`/api/v1/system/data-migrations`, gated to `dataMigrations.access.userRole`.
|
|
89
|
+
It is not a local script, and it is not a separate Wrangler entrypoint. The
|
|
90
|
+
Worker is the one place where both database families are reachable through the
|
|
91
|
+
bindings the app itself uses. Code outside a Worker cannot run JavaScript
|
|
92
|
+
against a D1 binding, and a Postgres database behind Hyperdrive is only
|
|
93
|
+
reachable from inside the Worker. The runner uses the same service handle as
|
|
94
|
+
cron and queue handlers: `drizzle(env.DB)` on D1, and the service-role
|
|
95
|
+
`createServiceDb(env)` on Neon and PlanetScale, where the ledger lives in the
|
|
96
|
+
`app` schema behind a service-role-only RLS policy. Your machine needs only an
|
|
97
|
+
operator's bearer token, never database credentials.
|
|
98
|
+
|
|
99
|
+
Each request must finish within the Worker's request limits. Split very large
|
|
100
|
+
backfills into several migrations, or make one resumable: a failed run can be
|
|
101
|
+
re-applied, and it picks up whatever rows still match.
|
|
102
|
+
|
|
103
|
+
## The CLI
|
|
104
|
+
|
|
105
|
+
`quickback migrate data` finds the route and each target's API hostname in
|
|
106
|
+
`reports/ops.manifest.json`. See the
|
|
107
|
+
[CLI reference](/tooling/cli#run-data-migrations) for every flag. It refuses
|
|
108
|
+
to run when the deployed Worker does not know a migration the build declares,
|
|
109
|
+
because that means the current build is not deployed yet.
|
|
@@ -29,5 +29,6 @@ security definitions compile to either provider.
|
|
|
29
29
|
|
|
30
30
|
- **[D1 Setup](/platform/database/d1)** — Bindings, wrangler config, migrations
|
|
31
31
|
- **[Using D1](/platform/database/using-d1)** — Drizzle queries, dual-DB mode, schema patterns
|
|
32
|
+
- **[Read replication](/platform/database/read-replication)** — Serve reads from D1's regional replicas with the Sessions API
|
|
32
33
|
- **[Neon](/platform/database/neon)** — Serverless Postgres setup and usage
|
|
33
34
|
- **[PlanetScale Postgres](/platform/database/planetscale-postgres)** — Roles, connection usernames, the cache-disabled Hyperdrive binding
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# Read replication
|
|
2
|
+
|
|
3
|
+
Cloudflare D1 can keep read-only copies of a database in every region
|
|
4
|
+
(ENAM, WNAM, WEUR, EEUR, APAC, OC) at no extra cost. Replicas only serve
|
|
5
|
+
queries made through the [D1 Sessions
|
|
6
|
+
API](https://developers.cloudflare.com/d1/best-practices/read-replication/);
|
|
7
|
+
plain binding queries always go to the primary. `readReplication` makes the
|
|
8
|
+
generated API use that session for every request-scoped feature read.
|
|
9
|
+
|
|
10
|
+
```typescript
|
|
11
|
+
// quickback.config.ts
|
|
12
|
+
database: defineDatabase("cloudflare-d1", {
|
|
13
|
+
readReplication: true,
|
|
14
|
+
}),
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Then enable replication on the features database itself — **Settings →
|
|
18
|
+
Enable Read Replication** in the D1 dashboard, or `PUT` the database with
|
|
19
|
+
`{ "read_replication": { "mode": "auto" } }` through the REST API. The
|
|
20
|
+
compiler never flips that switch. The generated code is correct either way:
|
|
21
|
+
without replicas every session runs on the primary, so turning the flag on
|
|
22
|
+
first and replication on later is safe.
|
|
23
|
+
|
|
24
|
+
D1 only. Postgres providers reject the option; Neon's read replicas are a
|
|
25
|
+
connection-string concern.
|
|
26
|
+
|
|
27
|
+
## What the generated API does
|
|
28
|
+
|
|
29
|
+
Each request's `db` handle runs on a D1 session. The session constraint is
|
|
30
|
+
chosen by method:
|
|
31
|
+
|
|
32
|
+
| Request | Session starts | Why |
|
|
33
|
+
|---------|----------------|-----|
|
|
34
|
+
| `GET` / `HEAD` carrying the bookmark header | at that bookmark | The client continues its own session: monotonic reads, read-your-writes |
|
|
35
|
+
| `GET` / `HEAD` without the header | `first-unconstrained` | Nearest replica — the common case for a fresh page load |
|
|
36
|
+
| Everything else (`POST`, `PATCH`, `PUT`, `DELETE`, actions, batch) | `first-primary` | Writes go to the primary anyway; starting there keeps a handler's reads after its own write fresh |
|
|
37
|
+
|
|
38
|
+
Every response carries the session's bookmark:
|
|
39
|
+
|
|
40
|
+
```http
|
|
41
|
+
HTTP/1.1 200 OK
|
|
42
|
+
x-d1-bookmark: 0000007b-0000b26e-00001538-0c3e87bb37b3db5cc52eedb93cd3b96b
|
|
43
|
+
x-d1-served-by: WEUR;primary=false
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
A client that sends the bookmark back on its next `GET` gets sequential
|
|
47
|
+
consistency across requests: it never reads an older version of the database
|
|
48
|
+
than the one it last saw, and it sees its own writes. A client that ignores
|
|
49
|
+
the header gets eventual consistency on reads only — the same thing any
|
|
50
|
+
replicated database gives an un-sessioned reader — and still gets fresh
|
|
51
|
+
reads inside every write. All three headers (`x-d1-bookmark`,
|
|
52
|
+
`x-d1-served-by`, `x-d1-fallback`) are CORS-exposed so browser code can read
|
|
53
|
+
them.
|
|
54
|
+
|
|
55
|
+
`x-d1-served-by` is for verifying a rollout: it is set only when D1 reports
|
|
56
|
+
where the session ran (`meta.served_by_region` / `served_by_primary`). D1
|
|
57
|
+
attaches that to `all()` / `run()` / `batch()` results on remote databases and
|
|
58
|
+
never under `wrangler dev` — and not to `raw()`, which is how Drizzle runs most
|
|
59
|
+
selects, so a read-only request often carries no `x-d1-served-by` even in
|
|
60
|
+
production.
|
|
61
|
+
|
|
62
|
+
### Echo the bookmark from your client
|
|
63
|
+
|
|
64
|
+
{/* doc-compile: skip — client-side fetch wrapper; `API` is the app's base URL, not a compiler symbol. */}
|
|
65
|
+
```typescript
|
|
66
|
+
let bookmark: string | null = null;
|
|
67
|
+
|
|
68
|
+
async function api(path: string, init: RequestInit = {}) {
|
|
69
|
+
const headers = new Headers(init.headers);
|
|
70
|
+
if (bookmark) headers.set("x-d1-bookmark", bookmark);
|
|
71
|
+
const res = await fetch(`${API}${path}`, { ...init, headers, credentials: "include" });
|
|
72
|
+
bookmark = res.headers.get("x-d1-bookmark") ?? bookmark;
|
|
73
|
+
return res;
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
One variable per browser tab or app session is enough. Sending a bookmark
|
|
78
|
+
from a different session is harmless: D1 only guarantees the new session is
|
|
79
|
+
at least as fresh as the bookmark.
|
|
80
|
+
|
|
81
|
+
Only a well-formed bookmark (three 8-hex groups and a hash group, as D1
|
|
82
|
+
issues them) continues a session. Any other header value is ignored and the request starts
|
|
83
|
+
`first-unconstrained`, so a stale or hand-edited header can never fail a
|
|
84
|
+
query.
|
|
85
|
+
|
|
86
|
+
### Rename the header
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
readReplication: { header: "x-bookmark" },
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The name must be a valid HTTP header token. It is matched case-insensitively
|
|
93
|
+
on the way in and emitted lowercase.
|
|
94
|
+
|
|
95
|
+
### Replica → primary fallback
|
|
96
|
+
|
|
97
|
+
A replica may not have the row another user wrote a moment ago, so a `GET`
|
|
98
|
+
for it can come back not-found from the replica even though the primary has
|
|
99
|
+
it. The generated worker retries those reads once on the primary:
|
|
100
|
+
|
|
101
|
+
| First response (`GET` / `HEAD` only) | Retried on the primary? |
|
|
102
|
+
|----------------------------|--------------------------|
|
|
103
|
+
| `404`, or `403 FIREWALL_NOT_FOUND` (the firewall's default `errorMode: 'reveal'` answer for a row it cannot see) | Yes, once |
|
|
104
|
+
| a read continued from a client bookmark whose replica did not catch up within `bookmarkWaitMs` (below) | Yes, once — whatever the handler answered |
|
|
105
|
+
| any `5xx`, including `503 DB_TIMEOUT` | Yes, once |
|
|
106
|
+
| anything else (`2xx`, `304`, other `4xx`) | No |
|
|
107
|
+
| any status, when the session started `first-primary` or D1 reported the primary served it | No |
|
|
108
|
+
| any status under `wrangler dev` (D1 never reports where it served) | No |
|
|
109
|
+
|
|
110
|
+
The retried response carries `x-d1-fallback: primary`, the primary session's
|
|
111
|
+
bookmark, and the first attempt's `x-request-id`:
|
|
112
|
+
|
|
113
|
+
```http
|
|
114
|
+
HTTP/1.1 200 OK
|
|
115
|
+
x-d1-fallback: primary
|
|
116
|
+
x-d1-bookmark: 0000007b-0000b26f-00000002-9b1d0e4a2f7c4c1e8d3a6b5f0c2e7d91
|
|
117
|
+
x-request-id: 3f0c…
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Details worth knowing:
|
|
121
|
+
|
|
122
|
+
- **One retry, never a loop.** The retry is marked inside the worker (an
|
|
123
|
+
object identity, not a header), so no client can trigger or suppress it,
|
|
124
|
+
and a retried request is never retried again.
|
|
125
|
+
- **The whole request runs twice.** The worker re-dispatches the request
|
|
126
|
+
through every middleware; Hono middleware cannot re-run downstream
|
|
127
|
+
handlers on its own. The retry does not count against the CRUD rate
|
|
128
|
+
limiter a second time; a custom `GET` action's own rate limit does count
|
|
129
|
+
both passes. Error logs from the first pass are kept — that is how you see
|
|
130
|
+
replica errors.
|
|
131
|
+
- **Genuine not-founds pay twice.** A `GET` for a row that exists nowhere
|
|
132
|
+
costs a replica read and a primary read. That is bounded at 2×.
|
|
133
|
+
- **Only not-found and errors.** A stale list (`200` with yesterday's rows)
|
|
134
|
+
is not detected; echo the bookmark, and adopt the bookmark from realtime
|
|
135
|
+
frames (below), to avoid it.
|
|
136
|
+
- **When D1 says nothing.** Drizzle's selects return no `served_by` metadata,
|
|
137
|
+
so after a not-found or 5xx with none, the worker asks D1 once per isolate
|
|
138
|
+
(`select 1`) whether it reports `served_by` at all. Remote D1 does;
|
|
139
|
+
`wrangler dev` does not, so local development never retries.
|
|
140
|
+
|
|
141
|
+
### Bounding the wait for a bookmark
|
|
142
|
+
|
|
143
|
+
A `GET` that carries a bookmark starts its session at that bookmark, and D1
|
|
144
|
+
holds the first query until the replica has caught up to it. Cloudflare
|
|
145
|
+
documents no bound on replica lag, so without a cap that wait lasts until
|
|
146
|
+
[`queryTimeoutMs`](/platform/database/using-d1#backend-stalls) fires — seconds,
|
|
147
|
+
with the fallback only after.
|
|
148
|
+
|
|
149
|
+
`bookmarkWaitMs` caps it. When the session's first statement has not completed
|
|
150
|
+
within that many milliseconds, the read is abandoned and re-served from the
|
|
151
|
+
primary (`x-d1-fallback: primary`) — never stale, and never more than about
|
|
152
|
+
`bookmarkWaitMs` slower than going to the primary directly:
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
database: defineDatabase("cloudflare-d1", {
|
|
156
|
+
queryTimeoutMs: 5000,
|
|
157
|
+
readReplication: { bookmarkWaitMs: 300 }, // the default
|
|
158
|
+
}),
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
- **Default 300 ms**, clamped to `queryTimeoutMs` when that is lower. An
|
|
162
|
+
explicit value must be a positive integer no larger than `queryTimeoutMs`.
|
|
163
|
+
- **Only bookmark reads.** `first-unconstrained` reads (no bookmark) and
|
|
164
|
+
everything on the primary keep the normal `queryTimeoutMs`.
|
|
165
|
+
- **Only the first statement.** Once one statement on the session has
|
|
166
|
+
answered, the replica is at least at the bookmark; later statements in the
|
|
167
|
+
same request are bounded by `queryTimeoutMs` alone. The cap covers every
|
|
168
|
+
statement form, including the `raw()` reads Drizzle uses for selects and
|
|
169
|
+
`batch()`.
|
|
170
|
+
- **No client-visible error.** The abandoned replica read never reaches the
|
|
171
|
+
client when the primary answers; if the primary retry also fails, the
|
|
172
|
+
client gets that failure (`503 DB_TIMEOUT` and so on) as usual. The worker
|
|
173
|
+
logs a `D1_REPLICA_WAIT` warning (plus the first pass's error line) each
|
|
174
|
+
time, so you can count them in Workers Logs.
|
|
175
|
+
|
|
176
|
+
**Tuning.** Set it a little above your observed p95 replica lag. Too low and
|
|
177
|
+
reads that would have been served by a replica a moment later go to the
|
|
178
|
+
primary instead (correct, just slower and more primary load); too high and a
|
|
179
|
+
lagging replica costs that much latency before the fallback. Count
|
|
180
|
+
`D1_REPLICA_WAIT` events and `x-d1-fallback` responses to judge it.
|
|
181
|
+
|
|
182
|
+
### Realtime frames carry the writer's bookmark
|
|
183
|
+
|
|
184
|
+
A client that refetches over HTTP when a realtime frame arrives holds its
|
|
185
|
+
*own* bookmark, which predates the write that caused the frame — so the
|
|
186
|
+
refetch can land on a replica that has not seen that write yet. With
|
|
187
|
+
`readReplication` on and [realtime](/platform/realtime) enabled, every
|
|
188
|
+
`postgres_changes`, `broadcast` and `view_changes` frame sent while handling a
|
|
189
|
+
request carries that request's D1 bookmark, read when the frame is sent (after
|
|
190
|
+
the write; frames sent from `waitUntil` after the response included):
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"specversion": "1.0",
|
|
195
|
+
"type": "dev.quickback.my-app.projects.insert",
|
|
196
|
+
"qbframe": "postgres_changes",
|
|
197
|
+
"qbd1bookmark": "0000007b-0000b26f-00000002-9b1d0e4a2f7c4c1e8d3a6b5f0c2e7d91",
|
|
198
|
+
"data": { "table": "projects", "eventType": "INSERT", "new": { "id": "prj_…" } }
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`qbd1bookmark` is a CloudEvents extension attribute, named like the other
|
|
203
|
+
`qb*` attributes (CloudEvents requires lowercase alphanumeric names). It is
|
|
204
|
+
absent on frames sent outside a request — schedules, queues, email handlers,
|
|
205
|
+
Durable Objects — and on projects without `readReplication`. It is never row
|
|
206
|
+
data: masking and audience targeting are unchanged.
|
|
207
|
+
|
|
208
|
+
On any frame carrying `qbd1bookmark`, set your stored bookmark to the
|
|
209
|
+
lexicographic max of the two before refetching. D1 bookmarks sort
|
|
210
|
+
oldest-to-newest as plain strings:
|
|
211
|
+
|
|
212
|
+
{/* doc-compile: skip — client-side frame handler; `bookmark` is the same variable as the fetch wrapper above. */}
|
|
213
|
+
```typescript
|
|
214
|
+
socket.addEventListener("message", (event) => {
|
|
215
|
+
const frame = JSON.parse(event.data);
|
|
216
|
+
const theirs = frame.qbd1bookmark;
|
|
217
|
+
if (typeof theirs === "string" && (!bookmark || theirs > bookmark)) bookmark = theirs;
|
|
218
|
+
// …then refetch with api(), which sends the adopted bookmark.
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Server code can read the current request's bookmark the same way the realtime
|
|
223
|
+
helper does: `currentD1Bookmark()` from `src/db` returns it (or `null` outside
|
|
224
|
+
a request).
|
|
225
|
+
|
|
226
|
+
## What stays on the primary
|
|
227
|
+
|
|
228
|
+
Only the per-request features `db` rides the session. These keep their own
|
|
229
|
+
primary handles, exactly as before:
|
|
230
|
+
|
|
231
|
+
- the auth database (Better Auth's adapter and `c.get('authDb')`) — session
|
|
232
|
+
and membership rows must never be read from a lagging replica
|
|
233
|
+
- the audit and webhooks databases
|
|
234
|
+
- [schedules](/platform/schedules), [queues](/platform/queues) and
|
|
235
|
+
[email handlers](/platform/email) — no request, no client, no bookmark
|
|
236
|
+
- Durable Objects and anything that builds its own `drizzle(env.DB)`
|
|
237
|
+
|
|
238
|
+
A read that must be fresh regardless of the client — polling a payment
|
|
239
|
+
status, an OTP flow — belongs in an action or a non-`GET` route, which starts
|
|
240
|
+
on the primary.
|
|
241
|
+
|
|
242
|
+
## Replica lag
|
|
243
|
+
|
|
244
|
+
Replication is asynchronous and a `first-unconstrained` read may be
|
|
245
|
+
arbitrarily old. D1 bounds it per session, not globally: the session waits
|
|
246
|
+
until a replica has caught up to the bookmark you passed. That is why writes
|
|
247
|
+
start `first-primary` and why the bookmark is worth echoing.
|
|
248
|
+
|
|
249
|
+
With [`queryTimeoutMs`](/platform/database/using-d1#backend-stalls) set, the
|
|
250
|
+
deadline wraps the session as well — a replica that takes too long to catch up
|
|
251
|
+
to a bookmark answers `503 DB_TIMEOUT` like any other slow read.
|
|
252
|
+
|
|
253
|
+
## Related
|
|
254
|
+
|
|
255
|
+
- [Using D1](/platform/database/using-d1) — queries, dual-DB mode, backend stalls
|
|
256
|
+
- [Database options](/configure/providers#database-options) — every `defineDatabase("cloudflare-d1")` option
|
|
257
|
+
- [Cloudflare: Global read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/)
|
|
@@ -63,9 +63,10 @@ dashboard or `wrangler tail --format json` filter on `event = "DB_DEADLINE"`
|
|
|
63
63
|
and group by `binding` / `kind` to track stalls over time. The response the
|
|
64
64
|
client saw carries the same `binding` in `details`. Unset, nothing changes: no wrapper is emitted and queries are
|
|
65
65
|
unbounded, as before. The option is D1-only; Postgres drivers carry their own
|
|
66
|
-
statement timeouts. `
|
|
66
|
+
statement timeouts. With [`readReplication`](/platform/database/read-replication) on, the deadline wraps the request's D1 session too.
|
|
67
67
|
|
|
68
68
|
## Related
|
|
69
69
|
|
|
70
70
|
- [D1 Setup](/platform/database/d1) — Bindings and wrangler config
|
|
71
|
+
- [Read replication](/platform/database/read-replication) — Serve reads from regional replicas with the Sessions API
|
|
71
72
|
- [Schema](/define/schema) — Defining your database schema
|
|
@@ -95,6 +95,7 @@ the worker entry, and that same entry exports the `queue()` consumer.
|
|
|
95
95
|
```ts title="quickback/features/orders/actions/startCheckout.ts"
|
|
96
96
|
import { z } from "zod";
|
|
97
97
|
import { and, eq } from "drizzle-orm";
|
|
98
|
+
// quickback-allow ACTION_RAW_DB_WITHOUT_UNSAFE: the fulfilment webhook handler below has no caller to scope to
|
|
98
99
|
import { drizzle } from "drizzle-orm/d1";
|
|
99
100
|
import { defineAction, orders } from "../.quickback/define-action";
|
|
100
101
|
import { onWebhookEvent } from "../../../lib/webhooks";
|
|
@@ -151,6 +152,7 @@ onWebhookEvent("stripe:checkout.session.completed", async (ctx) => {
|
|
|
151
152
|
// session unpaid and settle later on async_payment_succeeded.
|
|
152
153
|
if (session.payment_status !== "paid") return;
|
|
153
154
|
|
|
155
|
+
// quickback-allow ACTION_RAW_DB_WITHOUT_UNSAFE: webhook handler, no principal — the WHERE pins the row
|
|
154
156
|
const db = drizzle(ctx.env.DB);
|
|
155
157
|
const marked = await db
|
|
156
158
|
.update(orders)
|
|
@@ -181,7 +183,10 @@ happens on Stripe's domain, and the next thing your Worker hears is the webhook.
|
|
|
181
183
|
> `ctx.env` instead — exactly as the bundled subscription handlers do. That
|
|
182
184
|
> client is **unfiltered**: the `where` clause is the only thing keeping the
|
|
183
185
|
> write on one row, which is why it matches on the id Stripe echoed back and on
|
|
184
|
-
> `status = "unpaid"`.
|
|
186
|
+
> `status = "unpaid"`. Because the handler lives in an action file, the raw
|
|
187
|
+
> client is a compile error (`ACTION_RAW_DB_WITHOUT_UNSAFE`) unless it is
|
|
188
|
+
> excused: the two `quickback-allow` comments name that decision and its reason
|
|
189
|
+
> ([Diagnostics → source codes](/define/diagnostics#source-codes)).
|
|
185
190
|
|
|
186
191
|
|
|
187
192
|
## Idempotency is not optional
|
|
@@ -171,6 +171,8 @@ Don't send a `tags` field — the server stamps it from the session and ignores
|
|
|
171
171
|
|
|
172
172
|
Sends ride the **after-commit effects phase**, so a rolled-back write never notifies anyone and `dryRun` sends nothing. Enqueue the fan-out from inside `execute`:
|
|
173
173
|
|
|
174
|
+
{/* doc-compile: skip — needs the `push` config from step 2, which declares the PUSH_FANOUT_QUEUE binding (without it ENV_UNDECLARED fires, correctly). The same action compiles with that config in tests/output-matrix/fixtures/push. */}
|
|
175
|
+
|
|
174
176
|
```typescript
|
|
175
177
|
// features/events/actions/publish.ts
|
|
176
178
|
import { z } from "zod";
|