@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
|
@@ -42,11 +42,28 @@ export default feature('jobs', {
|
|
|
42
42
|
});
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
Type inference still works — `typeof import('./jobs').default.$infer` gives you the row type. Action files
|
|
45
|
+
Type inference still works — `typeof import('./jobs').default.$infer` gives you the row type. Action files should normally import both `defineAction` and the table from the generated per-feature helper (`../.quickback/define-action`), which re-exports the table typed with the generated schema. See [Actions](/define/actions).
|
|
46
|
+
|
|
47
|
+
### Import paths by authoring context
|
|
48
|
+
|
|
49
|
+
| File doing the import | Preferred import |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `features/projects/issues.ts`, FK to its sibling | `import projects from "./projects"` |
|
|
52
|
+
| `features/projects/actions/assign.ts`, primary-table action | `import { defineAction, projects, issues } from "../.quickback/define-action"` |
|
|
53
|
+
| `features/projects/actions/issues/assign.ts`, sibling-table action | `import { defineAction } from "../../.quickback/define-action.issues"`; import tables from `../../.quickback/define-action` |
|
|
54
|
+
| Table FK to another feature | `import people from "../people/people"` |
|
|
55
|
+
| Action using another feature's table | Import the named table from that feature's generated helper, e.g. `import { people } from "../../people/.quickback/define-action"` from a flat `projects/actions/` file |
|
|
56
|
+
|
|
57
|
+
The primary helper re-exports **all tables in its feature**. A sibling-bound
|
|
58
|
+
helper `define-action.<table>` binds `record` and `whereRecord` to that sibling
|
|
59
|
+
for correctly typed mutations. Use it for `defineAction` in sibling actions;
|
|
60
|
+
import all table values from the primary helper. Direct named table imports from `feature()` files remain supported in
|
|
61
|
+
actions; prefer the helper for generated managed-column types. Relative paths
|
|
62
|
+
are measured from the importing file, not from the feature root.
|
|
46
63
|
|
|
47
64
|
## q.table() + defineTable() — the expanded form
|
|
48
65
|
|
|
49
|
-
This is what `feature()` compiles into.
|
|
66
|
+
This is what `feature()` compiles into. Use this when you need direct control of the table declaration. A named import from a `feature()` file is also supported by `quickback check` and the build; a named import alone does not require switching to this form.
|
|
50
67
|
|
|
51
68
|
```typescript
|
|
52
69
|
// quickback/features/jobs/jobs.ts
|
|
@@ -66,10 +83,10 @@ export const jobs = q.table('jobs', {
|
|
|
66
83
|
|
|
67
84
|
export default defineTable(jobs, {
|
|
68
85
|
guards: { /* ... */ },
|
|
69
|
-
read: {
|
|
70
|
-
create: {
|
|
71
|
-
update: {
|
|
72
|
-
delete: {
|
|
86
|
+
read: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
|
|
87
|
+
create: { access: { roles: ["owner", "hiring-manager"] } },
|
|
88
|
+
update: { access: { roles: ["owner", "hiring-manager"] } },
|
|
89
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
73
90
|
});
|
|
74
91
|
|
|
75
92
|
export type Job = typeof jobs.$infer;
|
|
@@ -104,8 +121,41 @@ If `stageId` is null, the match is not required. The compiler rejects unknown
|
|
|
104
121
|
columns or an unresolved target table. This is opt-in: some visible records
|
|
105
122
|
may legitimately link across projects.
|
|
106
123
|
|
|
124
|
+
**Null-safe matches.** When "no project" is a value both rows can share, add
|
|
125
|
+
`nulls: 'equal'`. The comparison becomes null-safe (SQLite `IS`, Postgres
|
|
126
|
+
`IS NOT DISTINCT FROM`): a line with no project may point at a receipt with no
|
|
127
|
+
project, and a line with a project may not point at one without (or the other
|
|
128
|
+
way round).
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
receiptId: q.text().required().references(() => receipts.id, {
|
|
132
|
+
match: { source: 'projectId', target: 'projectId', nulls: 'equal' },
|
|
133
|
+
}),
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The default, `nulls: 'distinct'`, is the strict rule above.
|
|
137
|
+
|
|
138
|
+
**Several rules on one FK.** `match` also takes a list, and every rule must
|
|
139
|
+
hold. A payment allocation that must carry its bill allocation's bill **and**
|
|
140
|
+
its project (or no project):
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
billAllocationId: q.text().optional().references(() => billAllocations.id, {
|
|
144
|
+
match: [
|
|
145
|
+
{ source: 'billId', target: 'billId' },
|
|
146
|
+
{ source: 'projectId', target: 'projectId', nulls: 'equal' },
|
|
147
|
+
],
|
|
148
|
+
}),
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
A row with two optional FKs that must each agree with it, such as a credit
|
|
152
|
+
application tied to either a bill or a vendor credit, declares one `match` on
|
|
153
|
+
each FK. Whichever FK is set is checked.
|
|
154
|
+
|
|
107
155
|
The compiler emits database triggers for inserts and updates of the source
|
|
108
|
-
row, and for changes to the target's parent column
|
|
156
|
+
row, and for changes to the target's parent column (one pair per rule). They
|
|
157
|
+
are emitted the same way on a shared database and inside each
|
|
158
|
+
[tenant database](/configure/tenant-databases). Use the Quickback API for
|
|
109
159
|
client writes; the triggers backstop generated CRUD, batch writes, changesets,
|
|
110
160
|
and actions at the database boundary. Updating `projectId` while
|
|
111
161
|
leaving `stageId` unchanged still checks the resulting pair. A mismatch returns
|
|
@@ -115,6 +165,23 @@ check existing rows for mismatches before rollout. The ordinary target
|
|
|
115
165
|
[firewall check](/define/firewall#foreign-key-referential-checks) remains in
|
|
116
166
|
place for generated CRUD writes.
|
|
117
167
|
|
|
168
|
+
### Require the referenced row's state
|
|
169
|
+
|
|
170
|
+
`match` compares a column on both rows. To require something of the
|
|
171
|
+
referenced row itself (its kind, or that it isn't archived), add `requires`.
|
|
172
|
+
The database checks it from both sides: a source write that points at a
|
|
173
|
+
failing row is refused, and so is a target update that would break a live
|
|
174
|
+
reference.
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
itemLineId: q.text().required().references(() => itemLines.id, {
|
|
178
|
+
requires: { kind: 'reimbursable' },
|
|
179
|
+
}),
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
See [Invariants → requires](/define/invariants#requires-on-references) for the
|
|
183
|
+
condition syntax and the per-rule `when` form.
|
|
184
|
+
|
|
118
185
|
> **Never FK Better Auth tables**
|
|
119
186
|
>
|
|
120
187
|
> `.references(() => users.id)` (or `user`, `organization`, `member`, `session`) on a feature column is illegal. Those tables live in `AUTH_DB`; your features live in `DB`. SQLite cannot FK across D1 databases, and drizzle-kit fails generating features migrations:
|
|
@@ -213,6 +280,52 @@ The schema must be written inline from `z` and literals, because the compiler co
|
|
|
213
280
|
- using `z` anywhere else in the table file
|
|
214
281
|
- importing anything from `zod` other than `{ z }`
|
|
215
282
|
|
|
283
|
+
#### Indexed JSON projections (SQLite)
|
|
284
|
+
|
|
285
|
+
Use `projections` in the second argument of `q.json(schema, options)` to index a stored scalar inside a typed JSON value. It is supported on `cloudflare-d1`, including organization databases in SQLite Durable Objects. The alias is a query name: it does not add a physical column, a response property, or a field clients can write.
|
|
286
|
+
|
|
287
|
+
```typescript title="quickback/features/companies/companies.ts"
|
|
288
|
+
import { feature, q } from "@quickback/compiler";
|
|
289
|
+
import { z } from "zod";
|
|
290
|
+
|
|
291
|
+
export default feature("companies", {
|
|
292
|
+
columns: {
|
|
293
|
+
id: q.id(),
|
|
294
|
+
organizationId: q.scope("organization"),
|
|
295
|
+
metadata: q.json(z.object({
|
|
296
|
+
company: z.object({ industry: z.string().nullable() }).optional(),
|
|
297
|
+
score: z.number().optional(),
|
|
298
|
+
}), {
|
|
299
|
+
projections: {
|
|
300
|
+
industry: {
|
|
301
|
+
path: ["company", "industry"],
|
|
302
|
+
filterable: "in",
|
|
303
|
+
sortable: true,
|
|
304
|
+
index: { prefix: ["organizationId"] },
|
|
305
|
+
},
|
|
306
|
+
score: { path: ["score"], filterable: "range", sortable: true },
|
|
307
|
+
},
|
|
308
|
+
}).optional(),
|
|
309
|
+
...q.audit(),
|
|
310
|
+
...q.softDelete(),
|
|
311
|
+
},
|
|
312
|
+
guards: { createable: ["metadata"], updatable: ["metadata"] },
|
|
313
|
+
read: { access: { roles: ["member"] } },
|
|
314
|
+
create: { access: { roles: ["member"] } },
|
|
315
|
+
update: { access: { roles: ["member"] } },
|
|
316
|
+
});
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
The same column options work in `q.table()` with `defineTable()`. The compiler infers `string`, `number` or `boolean` from the inline Zod schema. Optional and nullable properties are supported. `filterable: "eq"` enables equality and `.ne`; `"in"` adds `.in`; numeric `"range"` adds `.gt`, `.gte`, `.lt` and `.lte`. Declare at least one of `filterable` or `sortable: true`. A view can narrow these capabilities with `query.filterable` and `query.sortable`.
|
|
320
|
+
|
|
321
|
+
Paths must be nonempty literal arrays of property names made of ASCII letters, digits and underscores, beginning with a letter or underscore. Arrays, wildcards, objects, arbitrary SQL/JSONPath, dynamic options and ambiguous unions are rejected. Aliases begin with a letter, use the same alphabet, and must be unique across the table's JSON columns; physical column names, SQL column names, pagination controls and JavaScript prototype names are reserved. Table, source and prefix SQL identifiers use that safe property-name alphabet too. `sqlName` is supported within that restriction.
|
|
322
|
+
|
|
323
|
+
A projection cannot read an effectively masked, encrypted, sealed or write-only column, even if some roles can reveal that column. A `keys` entry with `derivedFrom` is also unavailable: it is computed after the SQL read. Stored organizer and platform keys can be indexed; their write authority is unchanged.
|
|
324
|
+
|
|
325
|
+
`index.prefix` names distinct physical scalar columns, in index order. It cannot name another projection or a JSON, array, encrypted or secret column. Each alias owns one non-unique expression index; no `id` suffix is added automatically. Sorting requires a non-null unique physical `id` column and uses the existing `id` tie-breaker in the query. Index names are bounded and derived from the SQL table, SQL source column and alias. Path/type/prefix edits replace that index; alias edits drop the old identity and create the new one. Existing rows need no application backfill, but building an index scans the table and consumes storage. Validate large tenant upgrades against your runtime budget before release.
|
|
326
|
+
|
|
327
|
+
Missing paths, JSON null, malformed legacy JSON, wrong scalar types, arrays/objects and non-finite numbers index as SQL NULL. No scalar coercion occurs. In particular a string `"2"` does not match a numeric projection. SQL comparison semantics apply: `.ne` does not select NULLs. See [JSON projection queries](/define/read#json-projection-queries) for pagination and API restrictions.
|
|
328
|
+
|
|
216
329
|
#### Per-key write authority (`keys`)
|
|
217
330
|
|
|
218
331
|
`createable` and `updatable` decide whether a client may write a column. One JSON column can mix keys a project member may change with keys only a platform operator may change (entitlements, plan features, feature flags). The second argument of `q.json(schema, opts)` can declare a tier for each key:
|
|
@@ -251,6 +364,7 @@ export default feature("projects", {
|
|
|
251
364
|
| Option | Meaning |
|
|
252
365
|
|--------|---------|
|
|
253
366
|
| `sqlName` | SQL column name. The legacy positional form `q.json(schema, "col")` still works. |
|
|
367
|
+
| `projections.<alias>` | Indexed scalar query alias; see [Indexed JSON projections](#indexed-json-projections-sqlite). |
|
|
254
368
|
| `keys.<key>.tier` | `"organizer"` (the default): an ordinary key. `"platform"`: see below. |
|
|
255
369
|
| `keys.<key>.derivedFrom` | The key is computed from another table and never stored. Requires `tier: "platform"` and a `z.boolean()` property. |
|
|
256
370
|
|
|
@@ -437,6 +551,11 @@ r2Key: q.storageKey({
|
|
|
437
551
|
placeholder before `{uuid}`. Each placeholder fills a whole path segment.
|
|
438
552
|
- **Deleted with the row.** A hard delete through the generated routes or the
|
|
439
553
|
action `db` deletes the object too.
|
|
554
|
+
- **Tenant tables** (`tenancy.isolation: 'durable-object'`) need
|
|
555
|
+
`tenancy.bridges.files`. The object reserves keys and records deletes. The
|
|
556
|
+
edge signs, verifies and deletes. A tenant upload stays `pending` until
|
|
557
|
+
`db.finalizeUpload` (or its grant's expiry) verifies it. See
|
|
558
|
+
[Tenant databases → Managed files](/configure/tenant-databases#managed-files).
|
|
440
559
|
|
|
441
560
|
The column takes `.required()`, `.optional()`, `.unique()` and `.index()`.
|
|
442
561
|
Other modifiers fail the compile. The template rules, the error codes, and the
|
|
@@ -641,9 +760,9 @@ export default defineTable(jobs, {
|
|
|
641
760
|
createable: ["title", "department", "status", "salaryMin", "salaryMax"],
|
|
642
761
|
updatable: ["title", "department", "status"],
|
|
643
762
|
},
|
|
644
|
-
create: {
|
|
645
|
-
update: {
|
|
646
|
-
delete: {
|
|
763
|
+
create: { access: { roles: ["owner", "hiring-manager"] } },
|
|
764
|
+
update: { access: { roles: ["owner", "hiring-manager"] } },
|
|
765
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
647
766
|
});
|
|
648
767
|
|
|
649
768
|
export type Job = typeof jobs.$inferSelect;
|
|
@@ -1320,6 +1439,14 @@ A self-reference is a normal FK everywhere else:
|
|
|
1320
1439
|
- A batch create checks parents that exist **before** the batch. A record
|
|
1321
1440
|
can't name a sibling from the same batch as its parent; create the parent
|
|
1322
1441
|
first.
|
|
1442
|
+
- **No generated soft-delete cascade.** The generated DELETE route's
|
|
1443
|
+
soft-delete cascade reaches child rows in *other* tables only; it never
|
|
1444
|
+
follows a self-reference, so children stay live when their parent is
|
|
1445
|
+
soft-deleted. To take subtasks
|
|
1446
|
+
with their parent, declare an `afterUpdate` trigger on the soft-delete
|
|
1447
|
+
transition (it runs on every write path, not only the generated DELETE
|
|
1448
|
+
route); [Triggers → Soft-delete mapping](/define/triggers#soft-delete-mapping)
|
|
1449
|
+
has one that reaches every descendant.
|
|
1323
1450
|
|
|
1324
1451
|
The legacy resource-level `references: { vendorId: "contact" }` map can override
|
|
1325
1452
|
schema-registry target metadata for an alias, but it does not create a database
|
|
@@ -108,6 +108,7 @@ export default feature('guests', {
|
|
|
108
108
|
email: { type: 'email', show: { roles: ['admin', 'scope:event:organizer'] } }, // hidden from the driver
|
|
109
109
|
},
|
|
110
110
|
read: {
|
|
111
|
+
access: { roles: ['admin', 'scope:event:organizer'] }, // full rows: staff only
|
|
111
112
|
views: {
|
|
112
113
|
manifest: {
|
|
113
114
|
fields: ['id', 'nameAtInvite', 'shuttleId', 'pickupLocation'],
|
|
@@ -26,6 +26,15 @@ declared transitions with hand-written per-verb actions: you lose the
|
|
|
26
26
|
generated routes, the `guards.protected` integration, and the CMS
|
|
27
27
|
affordances.
|
|
28
28
|
|
|
29
|
+
A transition's `from` and `guard` are checked by the generated action. To
|
|
30
|
+
hold a state at the **database**, so that no action, batch or raw write can
|
|
31
|
+
undo it, pair transitions with [invariants](/define/invariants):
|
|
32
|
+
`frozen: { when: { status: 'posted' } }` stops a posted row changing,
|
|
33
|
+
`lockedBy` locks its child rows, and `restrict` with
|
|
34
|
+
`blocks: { enter: { status: 'withdrawn' } }` refuses entering a state while
|
|
35
|
+
other rows still point at the row (an existence check on the transition,
|
|
36
|
+
enforced by the database).
|
|
37
|
+
|
|
29
38
|
## Two lines per state change
|
|
30
39
|
|
|
31
40
|
```typescript
|
|
@@ -74,6 +74,89 @@ export default feature('invoices', {
|
|
|
74
74
|
|
|
75
75
|
Events: `beforeInsert`, `afterInsert`, `beforeUpdate`, `afterUpdate`, `beforeDelete`, `afterDelete`. Each event takes an array of named triggers; names must be unique per event.
|
|
76
76
|
|
|
77
|
+
## Awaited preparation (`prepare: true`)
|
|
78
|
+
|
|
79
|
+
On D1 with `changes.counter: true`, a before-handler can prepare a write using
|
|
80
|
+
scoped database reads and the stored row. Declare `prepare: true`; ordinary
|
|
81
|
+
before-handlers keep their synchronous, pending-values contract.
|
|
82
|
+
|
|
83
|
+
```typescript
|
|
84
|
+
triggers: {
|
|
85
|
+
beforeUpdate: [{
|
|
86
|
+
name: 'calculateTotal',
|
|
87
|
+
prepare: true,
|
|
88
|
+
handler: async ({ row, old, values, db, ctx }) => {
|
|
89
|
+
// row is the stored row merged with the pending values.
|
|
90
|
+
// old is the stored row; values contains only the pending patch.
|
|
91
|
+
if (row.quantity < 1) throw new Error('quantity must be positive');
|
|
92
|
+
return { total: row.unitPrice * row.quantity };
|
|
93
|
+
},
|
|
94
|
+
}],
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Preparation runs once when the builder is awaited or passed to `db.batch`.
|
|
99
|
+
The runtime captures the organization's revision **before** loading the stored
|
|
100
|
+
row or running the handler. It executes the resulting mutation and revision
|
|
101
|
+
assertion in one native D1 batch. A concurrent change rejects the whole write
|
|
102
|
+
with `STALE_REVISION` (409), including ordinary CRUD writes. Retry by building a
|
|
103
|
+
new operation and reading fresh state. Awaiting the same prepared builder again
|
|
104
|
+
reuses its result.
|
|
105
|
+
|
|
106
|
+
The handler receives the authenticated `ctx`, the pending `values`, and merged
|
|
107
|
+
`row`. Update and delete handlers also receive `old`. Its `db` allows scoped
|
|
108
|
+
SELECT queries; writes, raw SQL execution, transactions, and batches are refused.
|
|
109
|
+
Return a partial object to derive fields or throw to reject. Scope and audit
|
|
110
|
+
fields are stamped by the write wrappers after preparation. Keep preparation
|
|
111
|
+
free of external side effects: a revision conflict can reject the eventual write.
|
|
112
|
+
|
|
113
|
+
This first version supports one inserted row or exactly one visible row for an
|
|
114
|
+
update/delete, with `values`/`set`, `where`, and optional `returning`. Bulk writes,
|
|
115
|
+
upserts, SQL-expression patches, direct executor methods, and precompiled
|
|
116
|
+
statements fail explicitly. Use individual builders inside `db.batch` for several
|
|
117
|
+
inserts. Lookups see committed data, so a child whose parent is created in that
|
|
118
|
+
same batch needs its derived values supplied by the action and checked by a SQL
|
|
119
|
+
invariant trigger at commit.
|
|
120
|
+
|
|
121
|
+
Prepared handlers run through the generated database wrappers; raw SQL still
|
|
122
|
+
bypasses JavaScript handlers. Use SQL triggers for invariants that must cover raw
|
|
123
|
+
imports. `prepare` cannot be combined with `async` or `withOld`; `async` remains
|
|
124
|
+
reserved for queued after-handlers.
|
|
125
|
+
|
|
126
|
+
## Scoped integer sequences
|
|
127
|
+
|
|
128
|
+
D1 tables can declare a persistent sequence for invoice numbers, journal
|
|
129
|
+
references, or other integers allocated within an organization:
|
|
130
|
+
|
|
131
|
+
```typescript
|
|
132
|
+
sequence: { field: 'number', scope: ['organizationId'], start: 1 },
|
|
133
|
+
unique: [{ columns: ['organizationId', 'number'] }],
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Declare `number` as `q.int().required()`. Every scope field must be required,
|
|
137
|
+
and the scope must include a `q.scope('organization')` column. The compiler
|
|
138
|
+
requires a non-partial unique constraint on the scope fields plus the number.
|
|
139
|
+
The field is server-managed: callers omit it, and explicit values are refused.
|
|
140
|
+
|
|
141
|
+
The generated insert computes the next number inside its SQL statement. A
|
|
142
|
+
database trigger validates and advances the compiler-owned
|
|
143
|
+
`_quickback_sequences` record atomically. `returning()` includes the assigned
|
|
144
|
+
number. Several individual inserts in a native `db.batch` receive consecutive
|
|
145
|
+
numbers; a failed batch rolls back both rows and sequence advancement. Deleting
|
|
146
|
+
a row does not make its number available again. When enabling a sequence on an
|
|
147
|
+
existing table, allocation starts above its current maximum.
|
|
148
|
+
|
|
149
|
+
Numbers and scope fields cannot change after insertion, including through raw
|
|
150
|
+
SQL. Integer overflow beyond JavaScript's safe range is rejected. Use one row
|
|
151
|
+
per INSERT statement; multi-row VALUES and upserts are explicitly unsupported.
|
|
152
|
+
This version supports D1 only. Raw SQL inserts must supply the exact next number
|
|
153
|
+
and are checked by the same database trigger.
|
|
154
|
+
|
|
155
|
+
With [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases#change-signals-sequences-and-changesets),
|
|
156
|
+
a sequenced tenant table keeps `_quickback_sequences` in each organization's
|
|
157
|
+
Durable Object, with the same rules: each organization counts from its own
|
|
158
|
+
`start`, and a tenant `db.batch` is one object transaction.
|
|
159
|
+
|
|
77
160
|
## SQL triggers (`sql:`)
|
|
78
161
|
|
|
79
162
|
The compiler owns the object names and ships the DDL in a journaled
|
|
@@ -234,6 +317,31 @@ raw-SQL hard deletes are still covered. `*Update` events get the inverse
|
|
|
234
317
|
guard, so a soft delete fires delete triggers exactly once and never
|
|
235
318
|
double-fires as an update.
|
|
236
319
|
|
|
320
|
+
One exception: an `*Update` trigger whose own `when:` requires the transition
|
|
321
|
+
(both `NEW."deleted_at" IS NOT NULL` and `OLD."deleted_at" IS NULL` as top-level
|
|
322
|
+
`AND` terms) is meant to run on it, and keeps its `when:` unchanged. Use this
|
|
323
|
+
when a soft-delete trigger needs `NEW` — an `afterDelete` body cannot use it,
|
|
324
|
+
because its hard-delete variant has only `OLD`:
|
|
325
|
+
|
|
326
|
+
```ts
|
|
327
|
+
afterUpdate: [
|
|
328
|
+
{
|
|
329
|
+
name: "cascadeSoftDeleteToSubtasks",
|
|
330
|
+
when: `NEW."deleted_at" IS NOT NULL AND OLD."deleted_at" IS NULL`,
|
|
331
|
+
sql: `UPDATE "tasks" SET "deleted_at" = NEW."deleted_at", "deleted_by" = NEW."deleted_by"
|
|
332
|
+
WHERE "deleted_at" IS NULL AND "id" IN (SELECT "id" FROM (
|
|
333
|
+
WITH RECURSIVE "sub"("id") AS (
|
|
334
|
+
SELECT "id" FROM "tasks" WHERE "parent_id" = NEW."id"
|
|
335
|
+
UNION SELECT "t"."id" FROM "tasks" "t" JOIN "sub" ON "t"."parent_id" = "sub"."id"
|
|
336
|
+
) SELECT "id" FROM "sub"));`,
|
|
337
|
+
},
|
|
338
|
+
],
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
This trigger cannot re-fire for the rows it updates (see [Recursion](#recursion)),
|
|
342
|
+
so it would reach only direct children. The recursive CTE soft-deletes
|
|
343
|
+
every descendant in one statement.
|
|
344
|
+
|
|
237
345
|
Identical on both dialects. On Postgres the two delete variants are two
|
|
238
346
|
functions, not one, because the transition trigger fires on `UPDATE` and
|
|
239
347
|
returns `NEW` while the hard-delete one returns `OLD`.
|
|
@@ -396,9 +504,22 @@ insert type when a `sql:` body assigns it (`NEW."project_id" := …`) or a
|
|
|
396
504
|
|
|
397
505
|
## Choosing a lane
|
|
398
506
|
|
|
507
|
+
Most rejection triggers are one of a handful of shapes. Declare those as
|
|
508
|
+
[invariants](/define/invariants) rather than hand-writing the SQL: the
|
|
509
|
+
compiler emits the triggers, keeps them in step with the columns, and returns
|
|
510
|
+
a stable code.
|
|
511
|
+
|
|
399
512
|
| Need | Use |
|
|
400
513
|
|---|---|
|
|
401
|
-
|
|
|
514
|
+
| Rows are never deleted (by anything, cascades included) | [`invariants.permanent`](/define/invariants#permanent) |
|
|
515
|
+
| Rows never change after insert, except a one-time stamp | [`invariants.appendOnly`](/define/invariants#appendonly) |
|
|
516
|
+
| A row (or some columns) can't change once in a state, or ever | [`invariants.frozen`](/define/invariants#frozen) |
|
|
517
|
+
| Child rows are locked while the parent is posted / sent / void | [`invariants.lockedBy`](/define/invariants#lockedby) |
|
|
518
|
+
| A referenced row must have a kind or state | [`.references(…, { requires })`](/define/invariants#requires-on-references) |
|
|
519
|
+
| No delete, change or state entry while referenced | [`invariants.restrict`](/define/invariants#restrict) |
|
|
520
|
+
| A column kept equal to an aggregate of child rows | [`invariants.derived`](/define/invariants#derived) |
|
|
521
|
+
| A parent's lines balance when each write commits | [`invariants.balanced`](/define/invariants#balanced) |
|
|
522
|
+
| Any other invariant that must hold universally (raw SQL included) | `sql:` with `RAISE(ABORT)` (D1) / `RAISE EXCEPTION` (Postgres) |
|
|
402
523
|
| Denormalized columns, counters, tombstones | `sql:` |
|
|
403
524
|
| Validation/derivation with application logic | `before*` `handler:` |
|
|
404
525
|
| Side-effects after a write (notify, write related rows) | `after*` `handler:` |
|
|
@@ -473,6 +594,11 @@ feature](/configure/tenant-databases#platform-queues) the message goes through
|
|
|
473
594
|
the tenant object's outbox before the response instead, with `tenantId` and
|
|
474
595
|
`dedupeKey` stamped by the edge.
|
|
475
596
|
|
|
597
|
+
`afterCommit` hooks and `effects.enqueue` are best-effort: a Worker that dies
|
|
598
|
+
after the commit loses them. For a queue message that must commit with the
|
|
599
|
+
write, use [durable effects](/platform/database/durable-effects): pass
|
|
600
|
+
`effects` to an atomic `db.batch` on D1.
|
|
601
|
+
|
|
476
602
|
Effects enqueued by an `execute` that later throws are dropped. The context
|
|
477
603
|
also carries `now` — one ISO timestamp per invocation; prefer it over
|
|
478
604
|
`new Date().toISOString()`. See [Column types](/define/schema#decimals-dates-64-bit-integers-and-arrays) for
|
|
@@ -72,20 +72,47 @@ column the caller may sort by but not see ([query params](/api/query-params)).
|
|
|
72
72
|
## Idempotency-Key
|
|
73
73
|
|
|
74
74
|
Any `POST`/`PATCH`/`PUT`/`DELETE` may carry an `Idempotency-Key` header (a
|
|
75
|
-
caller-generated UUID, ≤ 255 chars)
|
|
75
|
+
caller-generated UUID, ≤ 255 chars) for response replay and duplicate detection:
|
|
76
76
|
|
|
77
77
|
- First request **claims** the key (the claim is the concurrency lock) and
|
|
78
78
|
caches the response.
|
|
79
79
|
- A retry with the same key replays the cached response byte-identically with
|
|
80
80
|
`Idempotency-Replayed: true`.
|
|
81
81
|
- A concurrent duplicate gets `409 IDEMPOTENCY_IN_PROGRESS`.
|
|
82
|
-
- Reusing a key for a *different* request (method/path) is a
|
|
82
|
+
- Reusing a key for a *different* request (method/path, exact body bytes, query, content type or active organization) is a
|
|
83
83
|
`422 IDEMPOTENCY_KEY_REUSED`.
|
|
84
|
-
-
|
|
84
|
+
- Ordinary replay-cache keys expire after **24 hours**; 5xx, `Set-Cookie` and
|
|
85
85
|
`Cache-Control: no-store` responses release the lock instead of caching. A
|
|
86
86
|
`no-store` response (a grant code, a token) is never stored for any caller,
|
|
87
87
|
so a retry re-runs the handler rather than replaying a secret.
|
|
88
88
|
|
|
89
|
+
**D1 atomic batches keep durable operation receipts.** When a request carrying
|
|
90
|
+
an `Idempotency-Key` executes scoped `db.batch`, Quickback persists an attempt
|
|
91
|
+
marker before submission and a commit marker in the same atomic batch as your
|
|
92
|
+
writes. After submission, errors, timeouts, `no-store` and cookie responses
|
|
93
|
+
cannot release the key for re-execution. A completed, replayable response is replayed as
|
|
94
|
+
usual. A caught timeout is not a completed batch: even if the handler returns
|
|
95
|
+
2xx/4xx, Quickback keeps the unknown receipt pending. If the batch committed but its response was lost (including an after-hook
|
|
96
|
+
failure), retries return `409 IDEMPOTENCY_COMMITTED` with the key as a receipt
|
|
97
|
+
reference. This does not report that failed hooks succeeded and does not expose
|
|
98
|
+
internal result rows. If submission has an unresolved outcome, retries return
|
|
99
|
+
`409 IDEMPOTENCY_OUTCOME_UNKNOWN`; they never execute the operation again.
|
|
100
|
+
|
|
101
|
+
Atomic operation receipts do not expire or participate in stale-claim takeover.
|
|
102
|
+
An unresolved attempt requires operator reconciliation against application data;
|
|
103
|
+
Quickback does not currently provide an automatic reconciliation endpoint. Do
|
|
104
|
+
not submit a new key to work around an unknown outcome. One request claim can
|
|
105
|
+
commit one guarded batch; compose the operation's writes into that batch.
|
|
106
|
+
For financial operations, require callers to persist and reuse the same key.
|
|
107
|
+
Only acknowledged SQL rollback permits clearing an atomic attempt for retry.
|
|
108
|
+
If cleanup fails, the receipt stays fenced. `DB_BATCH_POST_COMMIT_FAILED` is a
|
|
109
|
+
500 Problem with `details.committed: true`; `DB_BATCH_OUTCOME_UNKNOWN` has
|
|
110
|
+
`details.committed: null`. Neither permits automatic mutation retries. See the
|
|
111
|
+
[five transaction outcomes](/define/actions/scoped-db#transaction-outcomes-and-recovery).
|
|
112
|
+
|
|
113
|
+
Requests without the header retain atomicity but do not receive this replay
|
|
114
|
+
protection. Legacy cache rows without a request fingerprint are refused on reuse.
|
|
115
|
+
|
|
89
116
|
The key is per **request**. For "this client-side record exists exactly
|
|
90
117
|
once" across sessions and devices, store a per-**row** token instead — see
|
|
91
118
|
[Row-token idempotency](/api/crud#row-token-idempotency).
|
|
@@ -96,7 +123,11 @@ principal, or a legacy row with no principal — is refused with a `422`
|
|
|
96
123
|
Problem: the cached response body is **never served to a foreign
|
|
97
124
|
principal**, and nothing beyond the `422` itself leaks. The comparison runs
|
|
98
125
|
before the stale-claim takeover, so a foreign caller can neither read nor
|
|
99
|
-
overwrite your claim.
|
|
126
|
+
overwrite your claim. Scope fingerprints encode sorted name/subject tuples, so
|
|
127
|
+
delimiter characters in a subject cannot impersonate another scope set. Existing
|
|
128
|
+
claims using the older delimiter encoding fail closed on collision; no old
|
|
129
|
+
response is reinterpreted under the new encoding. Ordinary unmarked cache rows
|
|
130
|
+
may be reused after their 24-hour expiry, with the old body cleared atomically.
|
|
100
131
|
|
|
101
132
|
**Unauthenticated requests carrying the header are rejected (400)** — an
|
|
102
133
|
anonymous caller has no principal to bind the claim to. Better Auth's own
|
|
@@ -79,17 +79,40 @@ Scopes are stored in metadata rather than Better Auth's `permissions` field beca
|
|
|
79
79
|
|
|
80
80
|
## Key prefix
|
|
81
81
|
|
|
82
|
-
New keys
|
|
82
|
+
New keys read `<identifier>_<environment>_<random>`, so a key says which project and which environment it belongs to in logs and secret scanners:
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
my_app_live_0b1fee88…
|
|
86
|
+
my_app_staging_7c2d41aa…
|
|
87
|
+
my_app_dev_3e90b5d1…
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The identifier defaults to the project name, slugged (`my-app` → `my_app_`). The environment segment is chosen at runtime:
|
|
91
|
+
|
|
92
|
+
| Worker | Segment |
|
|
93
|
+
|--------|---------|
|
|
94
|
+
| Named environment `production`, `prod`, or `live` | `live_` |
|
|
95
|
+
| Any other named environment | its own name — `staging_`, `dev_`, `pr-12_` |
|
|
96
|
+
| No named environments, `BETTER_AUTH_URL` on `localhost` / `127.0.0.1` / `[::1]` | `dev_` |
|
|
97
|
+
| No named environments, any other `BETTER_AUTH_URL` | `live_` |
|
|
98
|
+
|
|
99
|
+
Every named environment runs the same bundle, so when the `apiKey` plugin is on the compiler stamps `QUICKBACK_ENVIRONMENT = "<name>"` into each target's vars; the Worker reads it to pick the segment.
|
|
100
|
+
|
|
101
|
+
An environment name that can't be a segment fails the compile: other than `production`, `prod` and `live`, each name must be letters, digits and `-` only. `_` is refused because it would blur the `<identifier>_<environment>_` boundaries — rename `qa_east` to `qa-east`.
|
|
102
|
+
|
|
103
|
+
Override the identifier with the object form of the plugin:
|
|
83
104
|
|
|
84
105
|
```ts
|
|
85
106
|
auth: defineAuth("better-auth", {
|
|
86
107
|
plugins: {
|
|
87
|
-
apiKey: { prefix: "
|
|
108
|
+
apiKey: { prefix: "acme_" },
|
|
88
109
|
},
|
|
89
110
|
}),
|
|
90
111
|
```
|
|
91
112
|
|
|
92
|
-
|
|
113
|
+
`prefix` is the identifier only — the environment segment is always appended (`acme_live_…`). It must be 1–32 characters of `A-Z a-z 0-9 _ -`, ending in `_` or `-`; anything else fails the compile.
|
|
114
|
+
|
|
115
|
+
The prefix is display-only — Better Auth hashes the whole key — so keys created before it (unprefixed, or `my_app_<random>` without an environment segment) keep verifying. `Authorization: Bearer` recognition matches the identifier, so every environment's keys and older `my_app_` keys are all accepted there.
|
|
93
116
|
|
|
94
117
|
## Banned owners
|
|
95
118
|
|
|
@@ -131,5 +131,8 @@ report every table as missing.
|
|
|
131
131
|
|
|
132
132
|
The bundled Account UI uses `signIn.social` and `linkSocial` for generic OAuth
|
|
133
133
|
providers, including Cloudflare. Their callback is
|
|
134
|
-
`/auth/v1/
|
|
135
|
-
|
|
134
|
+
`/auth/v1/callback/cloudflare` on Better Auth 1.7. Register the full URL on
|
|
135
|
+
your Cloudflare OAuth client (for example,
|
|
136
|
+
`https://api.example.com/auth/v1/callback/cloudflare`). Earlier versions used
|
|
137
|
+
`/auth/v1/oauth2/callback/cloudflare`; add the current callback when upgrading.
|
|
138
|
+
Cloudflare rejects sign-in before consent if the exact redirect URI is absent.
|
|
@@ -302,7 +302,7 @@ Sending `x-api-key` together with a session cookie or an `Authorization` header
|
|
|
302
302
|
|
|
303
303
|
These need a real session (cookie or session-token bearer). Under `/auth/v1/*` a key authenticates only `GET /auth/v1/get-session`; every other Better Auth endpoint ignores `x-api-key`, so a leaked key cannot mint JWTs, manage keys, or act on organizations. See [API Keys](/platform/auth/api-keys).
|
|
304
304
|
|
|
305
|
-
Keys can carry organization context via `metadata.organizationId` — when set, the auth middleware looks up the user's role in that org and populates `ctx.roles` accordingly, so a single key inherits the same firewall + access scope as the user who created it. `metadata.scopes` narrows a key to named resources and read/write — see [API Keys → Scopes](/platform/auth/api-keys#scopes). New keys carry a project prefix (`
|
|
305
|
+
Keys can carry organization context via `metadata.organizationId` — when set, the auth middleware looks up the user's role in that org and populates `ctx.roles` accordingly, so a single key inherits the same firewall + access scope as the user who created it. `metadata.scopes` narrows a key to named resources and read/write — see [API Keys → Scopes](/platform/auth/api-keys#scopes). New keys carry a project and environment prefix (`my_app_live_…` / `my_app_staging_…`; [Key prefix](/platform/auth/api-keys#key-prefix)), a banned owner's keys stop working, and each key is rate limited.
|
|
306
306
|
|
|
307
307
|
### OAuth Provider (MCP-ready)
|
|
308
308
|
|
|
@@ -592,6 +592,78 @@ The `withFirewall` helper:
|
|
|
592
592
|
3. **Avoid raw SQL** - Raw SQL bypasses application security; use Drizzle ORM
|
|
593
593
|
4. **Review custom code** - Manual routes should be code-reviewed for security
|
|
594
594
|
|
|
595
|
+
## Full-text search (`read.search`)
|
|
596
|
+
|
|
597
|
+
[`read.search`](/define/read#full-text-search-readsearch) gives a resource an
|
|
598
|
+
FTS5 index in the same database as its table — the features D1, or each
|
|
599
|
+
organization's SQLite Durable Object for tenant tables.
|
|
600
|
+
|
|
601
|
+
**What the compiler owns.** An external-content FTS5 virtual table named
|
|
602
|
+
`__qb_fts_<table>_<generation>` (internal; never a public identifier) and three
|
|
603
|
+
maintenance triggers. The generation changes when the indexed columns or
|
|
604
|
+
tokenizer change; weights are query-time only and never migrate.
|
|
605
|
+
|
|
606
|
+
**Migrations (features D1).** The `append-search` step (CLI or hosted
|
|
607
|
+
compiler — the same rules) appends `NNNN_quickback_search_<hash>.sql` after
|
|
608
|
+
the schema and trigger migrations:
|
|
609
|
+
|
|
610
|
+
- It drops every index object this or any earlier search migration owned
|
|
611
|
+
(read from the `-- quickback:search-object` manifest lines — FTS5 shadow
|
|
612
|
+
tables go with their virtual table), creates the current generation, runs
|
|
613
|
+
`'rebuild'` from the table and `'integrity-check'` against it, then creates
|
|
614
|
+
the triggers. One migration, one transaction.
|
|
615
|
+
- When a new schema migration in the same build alters, drops, renames or
|
|
616
|
+
rebuilds an indexed table, the owned triggers are dropped at the top of
|
|
617
|
+
that new migration (SQLite would otherwise keep a trigger referencing a
|
|
618
|
+
dropped column and fail every later write) and a fresh search migration
|
|
619
|
+
follows it, because drizzle's table rebuild changes rowids and drops
|
|
620
|
+
triggers. Applied SQL is never edited.
|
|
621
|
+
- The CLI tells the compiler when your history contains a search migration,
|
|
622
|
+
so removing the last `read.search` still retires the owned objects. An
|
|
623
|
+
older CLI rejects the `append-search` step instead of skipping it — upgrade
|
|
624
|
+
the CLI.
|
|
625
|
+
|
|
626
|
+
**Tenant objects.** The same statements install by content hash when an
|
|
627
|
+
object wakes, and are forced after any applied migration and after a dump
|
|
628
|
+
restore (restored rows are reloaded without triggers, so the old index is
|
|
629
|
+
discarded and rebuilt and verified before the object serves). Point-in-time
|
|
630
|
+
recovery restores the index together with the rows; a different index
|
|
631
|
+
generation is rebuilt on the next wake.
|
|
632
|
+
|
|
633
|
+
**Rebuilding by hand.** The index can always be re-derived from the table:
|
|
634
|
+
|
|
635
|
+
```sql
|
|
636
|
+
INSERT INTO "__qb_fts_<table>_<generation>"("__qb_fts_<table>_<generation>") VALUES('rebuild');
|
|
637
|
+
INSERT INTO "__qb_fts_<table>_<generation>"("__qb_fts_<table>_<generation>", rank) VALUES('integrity-check', 1);
|
|
638
|
+
```
|
|
639
|
+
|
|
640
|
+
The exact statements for your build are listed in each search migration's
|
|
641
|
+
manifest and in the compile output (`meta.searchIndexMigration.rebuild`).
|
|
642
|
+
[`quickback search status` / `rebuild`](/tooling/cli#check-and-rebuild-search-indexes)
|
|
643
|
+
runs exactly these statements against a target with `wrangler d1 execute`.
|
|
644
|
+
After a D1 Time Travel restore, check the index and rebuild it if needed before
|
|
645
|
+
re-enabling search traffic.
|
|
646
|
+
|
|
647
|
+
**Limits and costs.**
|
|
648
|
+
|
|
649
|
+
- The rebuild runs inside the migration. Very large tables can exceed D1's
|
|
650
|
+
per-query limits; a resumable, checkpointed backfill is not implemented
|
|
651
|
+
yet — split the migration or rebuild during a maintenance window.
|
|
652
|
+
- Every insert/update of an indexed field also writes the index (in a local
|
|
653
|
+
5,000-row benchmark the index added roughly 0.4× the table's size and
|
|
654
|
+
made inserts of ~200-character rows about 25× slower; measure your own
|
|
655
|
+
workload).
|
|
656
|
+
- `INSERT OR REPLACE` / `REPLACE` conflict resolution deletes the old row
|
|
657
|
+
without firing delete triggers, leaving a stale index entry. Use an upsert
|
|
658
|
+
(`ON CONFLICT … DO UPDATE`), which the generated API already does, or
|
|
659
|
+
rebuild afterwards.
|
|
660
|
+
- A standard `wrangler d1 export` refuses databases with virtual tables.
|
|
661
|
+
`wrangler d1 export --compatibility sqlite3_cli_only` includes them, but that
|
|
662
|
+
dump targets the SQLite CLI and cannot be imported back into D1
|
|
663
|
+
([Cloudflare docs](https://developers.cloudflare.com/d1/best-practices/import-export-data/)).
|
|
664
|
+
For a D1-importable export, drop the search tables first and rebuild them
|
|
665
|
+
afterwards — the index is derived from the table, so nothing is lost.
|
|
666
|
+
|
|
595
667
|
## Choose by workload, not by a limitations checklist
|
|
596
668
|
|
|
597
669
|
D1 is more capable than a simple `LIKE`-only store. Cloudflare documents
|
|
@@ -605,7 +677,7 @@ whether your application wants SQLite's model or PostgreSQL's ecosystem.
|
|
|
605
677
|
|
|
606
678
|
| Need | D1 approach | Choose Neon/Postgres when… |
|
|
607
679
|
|---|---|---|
|
|
608
|
-
| Generated Quickback search | The generated `?search` API uses allowlisted `LIKE` semantics;
|
|
680
|
+
| Generated Quickback search | The generated `?search` API uses allowlisted `LIKE` semantics by default; declare [`read.search`](#full-text-search-readsearch) for generated FTS5 token matching | Search is built around PostgreSQL `tsvector`, language dictionaries, GIN indexes, or an existing Postgres search design |
|
|
609
681
|
| Structured JSON | JSON is stored as text with D1's JSON functions and path operators | You need native `jsonb`, GIN indexing, or extensive JSONB query/update operators |
|
|
610
682
|
| Booleans and arrays | Drizzle maps booleans to SQLite integers; arrays can be modeled relationally or stored/queryable as JSON | Native PostgreSQL booleans/arrays are part of the schema contract |
|
|
611
683
|
| Reporting and aggregation | SQLite CTEs, window functions, joins, and aggregates cover conventional reports | You need Postgres extensions, materialized views, specialized indexes, or a Postgres analytics ecosystem |
|