@quickback-dev/cli 0.72.8 → 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 +2 -2
- package/dist/skill/docs/configure/index.md +2 -2
- package/dist/skill/docs/configure/providers.md +5 -0
- package/dist/skill/docs/configure/single-tenant.md +1 -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/auth/plugins/organization-defaults.md +37 -0
- package/dist/skill/docs/platform/auth/using-auth.md +2 -0
- 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 +6 -2
- package/dist/skill/docs/ui/account/environment-variables.md +7 -1
- package/dist/skill/docs/ui/account/features/admin.md +2 -2
- package/dist/skill/docs/ui/account/features/api-keys.md +1 -1
- package/dist/skill/docs/ui/account/features/index.md +10 -8
- package/dist/skill/docs/ui/account/features/organizations.md +19 -9
- package/dist/skill/docs/ui/account/features/passkeys.md +6 -2
- package/dist/skill/docs/ui/account/features/sessions.md +2 -2
- package/dist/skill/docs/ui/account/index.md +61 -30
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- package/dist/skill/docs/ui/admin/connecting.md +1 -1
- package/dist/skill/docs/ui/admin/index.md +1 -1
- 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 +2 -2
- package/src/skill/docs/configure/index.md +2 -2
- package/src/skill/docs/configure/providers.md +5 -0
- package/src/skill/docs/configure/single-tenant.md +1 -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/auth/plugins/organization-defaults.md +37 -0
- package/src/skill/docs/platform/auth/using-auth.md +2 -0
- 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 +6 -2
- package/src/skill/docs/ui/account/environment-variables.md +7 -1
- package/src/skill/docs/ui/account/features/admin.md +2 -2
- package/src/skill/docs/ui/account/features/api-keys.md +1 -1
- package/src/skill/docs/ui/account/features/index.md +10 -8
- package/src/skill/docs/ui/account/features/organizations.md +19 -9
- package/src/skill/docs/ui/account/features/passkeys.md +6 -2
- package/src/skill/docs/ui/account/features/sessions.md +2 -2
- package/src/skill/docs/ui/account/index.md +61 -30
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
- package/src/skill/docs/ui/admin/connecting.md +1 -1
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/record-layouts.md +3 -3
|
@@ -57,16 +57,166 @@ audit databases — races each statement against the deadline:
|
|
|
57
57
|
| Write (anything else, and any `batch` containing a write) | `500 DB_WRITE_OUTCOME_UNKNOWN` | Re-read the record, then decide. The statement was **not** cancelled on the backend and may still commit |
|
|
58
58
|
|
|
59
59
|
Each timeout also logs one structured line —
|
|
60
|
-
`{ level: "error", event: "DB_DEADLINE", binding, kind, ms,
|
|
61
|
-
truncated to 200 chars). Workers Logs indexes the JSON fields, so in the
|
|
60
|
+
`{ level: "error", event: "DB_DEADLINE", version: 1, binding, kind, ms, statements, fingerprint }`. `fingerprint` is the statement's [structural fingerprint](#fingerprints) (`null` for a multi-statement batch); SQL text and parameters are never logged. Workers Logs indexes the JSON fields, so in the
|
|
62
61
|
dashboard or `wrangler tail --format json` filter on `event = "DB_DEADLINE"`
|
|
63
62
|
and group by `binding` / `kind` to track stalls over time. The response the
|
|
64
63
|
client saw carries the same `binding` in `details`. Unset, nothing changes: no wrapper is emitted and queries are
|
|
65
64
|
unbounded, as before. The option is D1-only; Postgres drivers carry their own
|
|
66
65
|
statement timeouts. With [`readReplication`](/platform/database/read-replication) on, the deadline wraps the request's D1 session too.
|
|
67
66
|
|
|
67
|
+
## Sampled query diagnostics
|
|
68
|
+
|
|
69
|
+
D1 can return rows read/written, SQL execution time, retry attempts and replica
|
|
70
|
+
metadata for a statement. Turn on sampled observations in the D1 provider:
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import { defineDatabase } from '@quickback/compiler';
|
|
74
|
+
|
|
75
|
+
const database = defineDatabase('cloudflare-d1', {
|
|
76
|
+
diagnostics: { sampleRate: 0.01, slowMs: 100, rowsReadWarning: 10000 },
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
All three fields are required and unknown fields are a compile error.
|
|
81
|
+
`sampleRate` is between 0 and 1; `slowMs` and `rowsReadWarning` are finite and
|
|
82
|
+
nonnegative. They are your choices, not Cloudflare limits. `diagnostics` adds
|
|
83
|
+
no query deadline and changes no retry behavior. It also emits
|
|
84
|
+
`reports/d1-query-catalog.json`, which the [CLI commands](#explain-and-query-insights)
|
|
85
|
+
read. To get the catalog without runtime sampling, set `sampleRate: 0`.
|
|
86
|
+
|
|
87
|
+
### `D1_QUERY` events
|
|
88
|
+
|
|
89
|
+
Each sampled statement logs one JSON line:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{ "event": "D1_QUERY", "version": 1, "operation": "GET /api/v1/projects",
|
|
93
|
+
"binding": "DB", "method": "raw", "outcome": "success",
|
|
94
|
+
"fingerprint": "SELECT \"projects\" . \"id\" FROM \"projects\" WHERE ( \"projects\" . \"organization_id\" = ? AND \"projects\" . \"deleted_at\" IS NULL ) LIMIT ?",
|
|
95
|
+
"durationMs": 3.1, "metadataAvailable": false, "rowsRead": null, "rowsWritten": null,
|
|
96
|
+
"sqlDurationMs": null, "attempts": null, "region": null, "primary": null,
|
|
97
|
+
"batchIndex": null, "aggregate": false, "statementCount": null, "observedStatements": null,
|
|
98
|
+
"slow": false, "rowsReadWarning": null }
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
- **`operation`** is the request method plus the route pattern Hono matched
|
|
102
|
+
(`/api/v1/projects/:id`, never the concrete URL). It matches the `route` of an
|
|
103
|
+
entry in the catalog. It is `null` outside a request (cron, queue and email
|
|
104
|
+
runners).
|
|
105
|
+
- **Missing cost is `null`, not zero.** Drizzle runs SELECTs through `.raw()`,
|
|
106
|
+
which returns no D1 metadata, and `.first()` returns none either. Quickback
|
|
107
|
+
does not swap those calls or run a second query to measure them, so
|
|
108
|
+
`metadataAvailable: false` is the normal case for reads. Writes (`run`) and
|
|
109
|
+
native batches carry metadata.
|
|
110
|
+
- **`durationMs`** is the time measured in the Worker, including waiting and
|
|
111
|
+
transport. `sqlDurationMs` is D1's own execution time when it reports one.
|
|
112
|
+
- **Outcomes:** `success`, `error`, `timeout` (a read past
|
|
113
|
+
[`queryTimeoutMs`](#backend-stalls)), `write_outcome_unknown`
|
|
114
|
+
(a write past the deadline that may still commit) and `replica_wait_timeout`.
|
|
115
|
+
A statement that finishes after its deadline logs nothing more and is never
|
|
116
|
+
retried.
|
|
117
|
+
|
|
118
|
+
Sampling is decided once per request. The request's database middleware gives
|
|
119
|
+
every handle in that request one sampling decision and a shared budget of 20
|
|
120
|
+
events. Handles created outside a request, such as service jobs, get their own
|
|
121
|
+
20-event budget. A native batch logs one summary event (`aggregate: true`) that
|
|
122
|
+
holds the batch's duration. It also logs up to 19 per-statement events
|
|
123
|
+
(`batchIndex`) with cost but no duration. Never add the per-statement events to
|
|
124
|
+
the summary. `observedStatements` shows how many leading statements were
|
|
125
|
+
observed: a sampled prefix is not a full account. `exec`, `dump` and bindings
|
|
126
|
+
you call directly, outside the generated adapters, are not instrumented. A
|
|
127
|
+
failing log sink never changes a query's result.
|
|
128
|
+
|
|
129
|
+
### Fingerprints
|
|
130
|
+
|
|
131
|
+
A fingerprint is the statement reduced to its structure. It keeps:
|
|
132
|
+
|
|
133
|
+
- SQL keywords and a fixed list of SQLite functions;
|
|
134
|
+
- punctuation and operators;
|
|
135
|
+
- **compiler-known identifiers only**, which are the table and column names of
|
|
136
|
+
your generated Drizzle schema, double-quoted.
|
|
137
|
+
|
|
138
|
+
Every string, number, blob, parameter and comment becomes `?` or is dropped. Any
|
|
139
|
+
other name becomes the word `identifier`. SQL the tokenizer cannot classify is
|
|
140
|
+
`unclassified`: an unterminated quote, a second statement, an unknown character
|
|
141
|
+
or more than 16 KiB. That includes SQL that is not `SELECT`/`WITH`/`INSERT`/`UPDATE`/`DELETE`.
|
|
142
|
+
Fingerprints describe structure, and two queries with the same shape share one,
|
|
143
|
+
so they are not unique query IDs. SQL text, bound values, rows and errors never
|
|
144
|
+
appear in an event.
|
|
145
|
+
|
|
146
|
+
Because Drizzle quotes every identifier and binds every value, a fingerprint
|
|
147
|
+
of a generated query is valid SQL with `?` placeholders. That is what makes it
|
|
148
|
+
explainable.
|
|
149
|
+
|
|
150
|
+
### Explain and Query Insights
|
|
151
|
+
|
|
152
|
+
Both commands are read-only. They need `reports/d1-query-catalog.json` from a
|
|
153
|
+
build with `diagnostics` set.
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
# Plan the exact shape a route issued, against your local D1 (the default)
|
|
157
|
+
quickback db explain --binding DB \
|
|
158
|
+
--fingerprint 'SELECT "projects" . "id" FROM "projects" WHERE ( "projects" . "organization_id" = ? AND "projects" . "deleted_at" IS NULL ) LIMIT ?' \
|
|
159
|
+
--input ./explain-params.json # ["org_synthetic", 20]
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`db explain` plans a fingerprint you copied from a `D1_QUERY` event or from
|
|
163
|
+
`db insights`. The fingerprint is the production query builder's own output,
|
|
164
|
+
with the firewall predicates already in it. No second query builder exists that
|
|
165
|
+
could leave them out. The command accepts only a canonical `SELECT`
|
|
166
|
+
fingerprint whose names are all in the catalog. Literals, unknown names,
|
|
167
|
+
writes, comments and second statements are refused. It fills each `?` with your
|
|
168
|
+
synthetic `--input` values, which must be primitives, encoded as SQLite literals
|
|
169
|
+
(never pasted into the SQL). Then it runs one `EXPLAIN QUERY PLAN` through
|
|
170
|
+
`wrangler d1 execute`. For a remote plan, pass `--remote --env <target>`. The
|
|
171
|
+
target account and database are printed before anything runs, and there is no
|
|
172
|
+
remote fallback.
|
|
173
|
+
|
|
174
|
+
The output lists the plan rows, the indexes used, any full `SCAN` and any
|
|
175
|
+
`USE TEMP B-TREE` sort, with advice. A plan is the planner's estimate, not
|
|
176
|
+
measured cost. Read it next to sampled `rowsRead` and Query Insights.
|
|
177
|
+
Quickback's [automatic indexes](/define/schema) cover these columns:
|
|
178
|
+
|
|
179
|
+
- the tenant column, together with `deleted_at`;
|
|
180
|
+
- foreign keys;
|
|
181
|
+
- filter-like columns;
|
|
182
|
+
- view `sortable` columns.
|
|
183
|
+
|
|
184
|
+
Anything else is a manual index in the table's index callback. Quickback never
|
|
185
|
+
creates or migrates an index from diagnostics: index changes are advice only.
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
quickback db insights --env staging --binding DB --window 24h --sort reads --aggregate sum --limit 20 --json
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
`db insights` reads remote D1 Query Insights through the project's installed
|
|
192
|
+
Wrangler 4.x (`wrangler d1 insights`). It needs the following:
|
|
193
|
+
|
|
194
|
+
- an explicit `--binding`, with a real database ID and an explicit account ID
|
|
195
|
+
in the generated target;
|
|
196
|
+
- a Wrangler that you installed and authenticated yourself;
|
|
197
|
+
- an API token with **Account Analytics Read**.
|
|
198
|
+
|
|
199
|
+
The target identity is printed before Wrangler is called. An unknown binding
|
|
200
|
+
never widens to account-wide analytics. To ask for account-wide analytics, you
|
|
201
|
+
must say so: `--account <id> --all-databases`, without `--binding`. Query
|
|
202
|
+
strings are redacted to fingerprints using the catalog's identifiers before
|
|
203
|
+
anything is printed, so they match runtime fingerprints and feed straight into
|
|
204
|
+
`db explain`.
|
|
205
|
+
|
|
206
|
+
Results are top-N adaptive analytics, not account totals. Averages are
|
|
207
|
+
recomputed from sums and counts, and a zero count gives `null`. Wrangler
|
|
208
|
+
reports a missing sum or average as `0`, so a zero is not proof of zero cost.
|
|
209
|
+
The Wrangler command is experimental, so the CLI checks the shape of its
|
|
210
|
+
output. An unknown format, a permission failure or a failed command produces an
|
|
211
|
+
error code, never zero metrics or raw output.
|
|
212
|
+
|
|
213
|
+
References: [D1 return objects](https://developers.cloudflare.com/d1/worker-api/return-object/),
|
|
214
|
+
[index inspection](https://developers.cloudflare.com/d1/best-practices/use-indexes/),
|
|
215
|
+
[Query Insights](https://developers.cloudflare.com/d1/observability/metrics-analytics/#query-insights).
|
|
216
|
+
|
|
68
217
|
## Related
|
|
69
218
|
|
|
70
219
|
- [D1 Setup](/platform/database/d1) — Bindings and wrangler config
|
|
71
220
|
- [Read replication](/platform/database/read-replication) — Serve reads from regional replicas with the Sessions API
|
|
72
221
|
- [Schema](/define/schema) — Defining your database schema
|
|
222
|
+
- [CLI: D1 diagnostics](/tooling/cli#d1-diagnostics) — `quickback db explain` and `quickback db insights`
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
| [Realtime](/platform/realtime) | Durable Objects | WebSocket for live updates |
|
|
12
12
|
| [Queues](/platform/queues) | Cloudflare Queues | Background jobs, webhook delivery |
|
|
13
13
|
| [Schedules](/platform/schedules) | Cron Triggers | `defineSchedule` cron jobs, server-internal |
|
|
14
|
+
| [Workflows](/platform/workflows) | Cloudflare Workflows | `defineWorkflow` durable multi-step runs, actor authority re-checked per step |
|
|
14
15
|
| [Email](/platform/email) | Email Workers | `defineEmail` inbound handlers, server-internal |
|
|
15
16
|
| [Vector & AI](/platform/vector) | Workers AI | Embeddings, semantic search |
|
|
16
17
|
| [Webhooks](/platform/webhooks) | Hono + Queues | Signed inbound, retried outbound |
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# Account spend policies
|
|
2
|
+
|
|
3
|
+
`quickback platform budget` manages Cloudflare **spend policies**: email alerts
|
|
4
|
+
and spending limits for Workers and Durable Objects. It wraps the official
|
|
5
|
+
[`cf billing spend-policies`](https://developers.cloudflare.com/billing/manage/spend-management/cli/)
|
|
6
|
+
commands in a preview, review and apply workflow. Each change is checked
|
|
7
|
+
against the policy's version and recorded in a local receipt.
|
|
8
|
+
|
|
9
|
+
> These are **account-level platform controls**. Each policy covers one product
|
|
10
|
+
> (all Workers, or all Durable Objects) across one Cloudflare account. A policy
|
|
11
|
+
> cannot target one Worker, one Durable Object namespace or one tenant, so it is
|
|
12
|
+
> not a per-tenant quota. It is also not an invoice cap. Usage reporting and
|
|
13
|
+
> blocking take time, and some charges continue during a pause, so the invoice
|
|
14
|
+
> can exceed the threshold.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
## What Cloudflare supports
|
|
18
|
+
|
|
19
|
+
| Control | Supported here | Notes |
|
|
20
|
+
|---------|----------------|-------|
|
|
21
|
+
| Workers or Durable Objects email alert (`notification`) | Yes | Emails at 80% and 100% of the threshold. The product keeps running. |
|
|
22
|
+
| Workers or Durable Objects spending limit (`usage_block`) | Yes | Blocks the product's supported operations across the account. One enabled limit per product. |
|
|
23
|
+
| Account-wide budget alert | **No** | Dashboard only (**Billing → Billable Usage**). Cloudflare has no CLI or API for it, so a `budgetAlerts` key in the document is a validation error. |
|
|
24
|
+
| Current recorded spend | **No** | `cf` has no command that reads current spend. Plans and status show it as `unknown`, and show the latest 80% and 100% threshold events instead. |
|
|
25
|
+
|
|
26
|
+
Spend policies do **not** cover the Workers Paid subscription fee, Workers KV,
|
|
27
|
+
R2, D1, Queues, Workers AI, Vectorize or Durable Objects stored data.
|
|
28
|
+
|
|
29
|
+
A Workers limit can stop HTTP requests, cron triggers, queue consumers and other
|
|
30
|
+
invocations for every Worker on the account. A Durable Objects limit pauses
|
|
31
|
+
requests and operations. Existing WebSockets and some work in progress can
|
|
32
|
+
continue. See Cloudflare's notes on
|
|
33
|
+
[Workers](https://developers.cloudflare.com/workers/platform/spend-management/)
|
|
34
|
+
and [Durable Objects](https://developers.cloudflare.com/durable-objects/platform/spend-management/).
|
|
35
|
+
|
|
36
|
+
## Prerequisites
|
|
37
|
+
|
|
38
|
+
- The [`cf` CLI](https://developers.cloudflare.com/cf/get-started/), signed in
|
|
39
|
+
or with `CLOUDFLARE_API_TOKEN` set.
|
|
40
|
+
- **Account → Billing → Read** to run `status`, `plan` and `history`.
|
|
41
|
+
**Billing → Edit** to run `apply`. Cloudflare checks these permissions, not
|
|
42
|
+
Quickback.
|
|
43
|
+
|
|
44
|
+
## The account is always explicit
|
|
45
|
+
|
|
46
|
+
Every command needs `--account <id>`, or `--env <target>` to use that target's
|
|
47
|
+
`accountId` from `quickback.config.ts`. Quickback never takes the account from
|
|
48
|
+
your current `cf` or Wrangler login. The first line of output names the
|
|
49
|
+
account. Each `cf` call runs with `CLOUDFLARE_ACCOUNT_ID` set to that account,
|
|
50
|
+
which overrides any ambient value (Quickback prints a warning when it does).
|
|
51
|
+
Your global `cf` profile is not modified.
|
|
52
|
+
|
|
53
|
+
With `--env`, the plan also lists the other deployment targets on the same
|
|
54
|
+
account, because a limit stops all of them.
|
|
55
|
+
|
|
56
|
+
## The budget document
|
|
57
|
+
|
|
58
|
+
Policies are declared in a JSON file that operators own. It is kept apart from
|
|
59
|
+
`quickback.config.ts`, because one account can host several projects, and
|
|
60
|
+
`quickback build` and `quickback deploy` never apply account policies.
|
|
61
|
+
|
|
62
|
+
```json title="budget.json"
|
|
63
|
+
{
|
|
64
|
+
"version": 1,
|
|
65
|
+
"owner": "platform-ops",
|
|
66
|
+
"accountId": "0123456789abcdef0123456789abcdef",
|
|
67
|
+
"policies": [
|
|
68
|
+
{ "key": "workers-alert", "product": "workers", "action": "notification", "thresholdCents": 5000, "enabled": true, "email": "ops@example.com" }
|
|
69
|
+
]
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
This example sets an alert only. The amounts and addresses on this page are
|
|
74
|
+
illustrations, not recommendations. To add a limit, choose it deliberately:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{ "key": "objects-limit", "product": "durable_objects", "action": "usage_block", "thresholdCents": 10000, "enabled": true, "email": "ops@example.com" }
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
| Field | Rules |
|
|
81
|
+
|-------|-------|
|
|
82
|
+
| `owner` | Lowercase slug naming the team that owns these policies. It labels ownership. It does not grant permission. |
|
|
83
|
+
| `accountId` | 32 lowercase hex characters. Must equal `--account` or the `--env` target's account. |
|
|
84
|
+
| `key` | Unique lowercase slug. Quickback tracks ownership by `(account, owner, key)`, never by display name. |
|
|
85
|
+
| `product` | `workers` or `durable_objects`. No other product supports spend policies. |
|
|
86
|
+
| `action` | `notification` (alert) or `usage_block` (limit). |
|
|
87
|
+
| `thresholdCents` | Positive whole number of US cents (`5000` = $50). Zero, fractions and strings are rejected. |
|
|
88
|
+
| `enabled` | Required `true` or `false`. |
|
|
89
|
+
| `email` | One address. Required for alerts. A limit without one sends no email. |
|
|
90
|
+
| `name` | Optional display name (1–200 bytes). Defaults to `quickback <owner>/<key>`. |
|
|
91
|
+
| `adoptPolicyId` | Optional. Takes ownership of an existing policy, previewed in the plan like any other change. |
|
|
92
|
+
|
|
93
|
+
Unknown keys fail validation, and the CLI reports every problem at once. Never
|
|
94
|
+
put API tokens in this file.
|
|
95
|
+
|
|
96
|
+
## Plan, review, apply
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
quickback platform budget plan budget.json --out budget-plan.json --account 0123456789abcdef0123456789abcdef
|
|
100
|
+
quickback platform budget apply budget-plan.json --confirm <digest> --account 0123456789abcdef0123456789abcdef
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`plan` is read-only. It lists:
|
|
104
|
+
|
|
105
|
+
- every policy on the account, marked as owned or not owned;
|
|
106
|
+
- recorded spend as `unknown`;
|
|
107
|
+
- each operation, with before and after state, recipients, and its expected
|
|
108
|
+
policy version;
|
|
109
|
+
- consequences, such as "can block every Worker invocation as soon as
|
|
110
|
+
Cloudflare evaluates it", "lowers the threshold" or "lifts any block and
|
|
111
|
+
permits further spending";
|
|
112
|
+
- a SHA-256 digest of the whole plan file.
|
|
113
|
+
|
|
114
|
+
`plan` refuses to:
|
|
115
|
+
|
|
116
|
+
- create a second enabled limit for a product while a policy it does not own
|
|
117
|
+
is already one. Turn that policy off, or adopt it explicitly;
|
|
118
|
+
- change a policy's product;
|
|
119
|
+
- adopt a policy that is already owned.
|
|
120
|
+
|
|
121
|
+
When you remove an owned policy from the document, the plan turns it **off**
|
|
122
|
+
rather than deleting it.
|
|
123
|
+
|
|
124
|
+
`apply` checks the `--confirm` digest against the plan file, so a file edited
|
|
125
|
+
after review is refused. It then reads every policy again before changing
|
|
126
|
+
anything. A policy at a different version than the plan expected stops the
|
|
127
|
+
run: re-plan and review the new state. Quickback never merges changes made by
|
|
128
|
+
another operator. Each update resends the whole policy, as Cloudflare requires,
|
|
129
|
+
with `--if-match <version>`.
|
|
130
|
+
|
|
131
|
+
## Ownership and receipts
|
|
132
|
+
|
|
133
|
+
Operator state lives in `--state` (default `.quickback/platform-budget/`).
|
|
134
|
+
Files are written with mode `0600`:
|
|
135
|
+
|
|
136
|
+
- `ownership.json` maps `(account, owner, key)` to the policy id, the last
|
|
137
|
+
version Quickback saw, and a configuration hash. When a policy was changed
|
|
138
|
+
outside Quickback, the next plan says so.
|
|
139
|
+
- `receipts.jsonl` is append-only. Quickback writes an `intent` line before
|
|
140
|
+
each change and a `done` line after it, with the before and after state and
|
|
141
|
+
the version Cloudflare returned. If the `intent` write fails, nothing is sent
|
|
142
|
+
to Cloudflare. If the `done` write fails after Cloudflare accepted a change,
|
|
143
|
+
`apply` stops and names the policy and version.
|
|
144
|
+
|
|
145
|
+
Keep this directory somewhere durable and private. If several operators apply
|
|
146
|
+
changes, share it, for example in a private repository. Receipts contain
|
|
147
|
+
notification email addresses.
|
|
148
|
+
|
|
149
|
+
### Partial failure and resume
|
|
150
|
+
|
|
151
|
+
Each policy is changed separately, so partial success is possible. `apply`
|
|
152
|
+
lists the operations that completed, the one that failed, and those not yet
|
|
153
|
+
tried. To resume, run the same `apply` again. It skips operations that already
|
|
154
|
+
completed. If the failure was a version conflict (HTTP 412), re-plan instead.
|
|
155
|
+
|
|
156
|
+
If a create's response is lost, its outcome is unknown. On the next run,
|
|
157
|
+
`apply` looks for exactly one policy it does not own that matches the create.
|
|
158
|
+
If it finds one, it records it and does not create it again. If it finds more
|
|
159
|
+
than one, it stops. Check `history` before trying again.
|
|
160
|
+
|
|
161
|
+
## Rollback
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
quickback platform budget rollback-plan budget-plan.json --out rollback.json --account 0123456789abcdef0123456789abcdef
|
|
165
|
+
quickback platform budget apply rollback.json --confirm <digest> --account 0123456789abcdef0123456789abcdef
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Rollback does not clean up automatically. It builds a new plan for you to
|
|
169
|
+
review:
|
|
170
|
+
|
|
171
|
+
- a changed policy goes back to the full state recorded before it was changed;
|
|
172
|
+
- a created policy is turned off.
|
|
173
|
+
|
|
174
|
+
`rollback-plan` refuses if a policy changed after the original apply, rather
|
|
175
|
+
than overwriting that edit. It also refuses if the policy's ownership no longer
|
|
176
|
+
matches the receipt. Raising or turning off a limit permits further spending,
|
|
177
|
+
and the plan says so.
|
|
178
|
+
|
|
179
|
+
## Status and history
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
quickback platform budget status --account 0123456789abcdef0123456789abcdef --json
|
|
183
|
+
quickback platform budget history --account 0123456789abcdef0123456789abcdef
|
|
184
|
+
quickback platform budget history --account 0123456789abcdef0123456789abcdef --policy <policy-id>
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
`status` lists each policy, whether Quickback owns it, and its latest threshold
|
|
188
|
+
event. `history` with no `--policy` shows configuration changes across the
|
|
189
|
+
account: who made them, with before and after settings (`--cursor` pages, and
|
|
190
|
+
`--limit` accepts up to 100). With `--policy`, it shows that policy's threshold
|
|
191
|
+
events.
|
|
192
|
+
|
|
193
|
+
Keep these states apart:
|
|
194
|
+
|
|
195
|
+
- **Configuration.** Read-back after `apply` confirms the settings Cloudflare
|
|
196
|
+
stored.
|
|
197
|
+
- **Threshold events.** `approaching_limit` (80%) and `limit_reached` (100%)
|
|
198
|
+
record that Cloudflare evaluated the policy. They do not confirm that
|
|
199
|
+
blocking finished or that an email was delivered. If spend jumps past both
|
|
200
|
+
thresholds between evaluations, only the 100% email may arrive.
|
|
201
|
+
- **Enforcement.** An enabled policy is not proof that the product is running,
|
|
202
|
+
and `limit_reached` is not proof that it has stopped.
|
|
203
|
+
|
|
204
|
+
## After a prolonged Durable Objects block
|
|
205
|
+
|
|
206
|
+
When service returns, by raising the limit, turning it off or reaching the next
|
|
207
|
+
billing period:
|
|
208
|
+
|
|
209
|
+
1. Check `history --policy <id>` for when the limit was reached.
|
|
210
|
+
2. Durable Object alarms held for more than seven days during a pause can be
|
|
211
|
+
removed. Reconcile any job, schedule or retry that depends on an alarm, and
|
|
212
|
+
re-arm alarms from your application's own state.
|
|
213
|
+
3. Check queue consumers and cron-driven work for runs that were skipped while
|
|
214
|
+
Workers were blocked.
|
|
215
|
+
4. Clients holding WebSockets that stayed open may have missed events. Have
|
|
216
|
+
them resynchronize.
|
|
217
|
+
|
|
218
|
+
## Workload controls in `quickback.config.ts`
|
|
219
|
+
|
|
220
|
+
Spend policies are account-wide. To limit one Worker, set
|
|
221
|
+
`providers.runtime.config.limits.cpuMs` in the project config. It sets the CPU
|
|
222
|
+
time one invocation may use, emitted as `limits.cpu_ms` (see
|
|
223
|
+
[Runtime options](/configure/providers#runtime-options)). It stops runaway work
|
|
224
|
+
in a single request. It does not cap spend.
|
|
@@ -76,6 +76,7 @@ export default defineQueue<ProcessMaterialMessage>({
|
|
|
76
76
|
| `messageType` | `string` | Yes | Message type to match (e.g., `'process_material'`) |
|
|
77
77
|
| `description` | `string` | No | Human-readable description |
|
|
78
78
|
| `tenant` | `true` | No | Run inside the tenant object named by `message.tenantId` (`tenancy.isolation: 'durable-object'`). See [Tenant databases](/configure/tenant-databases#background-work). |
|
|
79
|
+
| `placement` | `'tenant'` \| `{ partition: '<kind>' }` | No | Which tenant object runs it: the organization object (`'tenant'`, the same as `tenant: true`) or a partition object of the project's partition kind, named by `message.tenantId` + `message.partitionKey`. Must be a literal; conflicts with `tenant: true`. See [Partition jobs](/configure/tenant-databases#partition-jobs). |
|
|
79
80
|
| `result` | `true` | No | A result job: called from edge code with `callTenantJob(env, tenantId, message, runId)`, which returns the handler's `result`. Needs `tenant: true` and `resultSchema`; never queued. See [Result jobs](/configure/tenant-databases#result-jobs). |
|
|
80
81
|
| `resultSchema` | `z.object(…)` | With `result` | Validates the returned `result` before it is recorded and returned (at most 256 KiB). `z.object` strips unknown keys; a strict object refuses them; passthrough / loose schemas fail the build. |
|
|
81
82
|
| `resultTtlSeconds` | number literal | No | Result jobs only: how long the object keeps a call's result so a repeated `runId` replays it. 60 to 604800 (7 days, the default); a short one suits read-only pulls such as exports. See [Result jobs](/configure/tenant-databases#result-jobs). |
|
|
@@ -12,6 +12,12 @@ The compiler auto-configures queues when certain features are enabled:
|
|
|
12
12
|
| Webhooks | `WEBHOOKS_QUEUE` | Async webhook delivery with retry |
|
|
13
13
|
| Custom | User-defined | Your own background processing |
|
|
14
14
|
|
|
15
|
+
On D1, [durable effects](/platform/database/durable-effects) write a queue
|
|
16
|
+
message's intent in the same transaction as the business writes. They deliver
|
|
17
|
+
it at least once, through a leased dispatcher and consumer admission.
|
|
18
|
+
[Workflows](/platform/workflows) use the same path: the generated consumer
|
|
19
|
+
routes `qb.workflow.*` intents to the workflow dispatcher.
|
|
20
|
+
|
|
15
21
|
## Queue Defaults
|
|
16
22
|
|
|
17
23
|
| Setting | Default |
|
|
@@ -34,11 +40,23 @@ database: defineDatabase("cloudflare-d1", {
|
|
|
34
40
|
maxBatchSize: 5,
|
|
35
41
|
maxBatchTimeout: 60,
|
|
36
42
|
maxRetries: 5,
|
|
43
|
+
maxConcurrency: 1, // optional: 1–250
|
|
44
|
+
deadLetterQueue: "my-app-processing-dead-letter", // optional
|
|
37
45
|
},
|
|
38
46
|
],
|
|
39
47
|
})
|
|
40
48
|
```
|
|
41
49
|
|
|
50
|
+
`maxConcurrency` (wrangler `max_concurrency`) caps concurrent consumer
|
|
51
|
+
invocations; `1` serializes the queue. `deadLetterQueue` (wrangler
|
|
52
|
+
`dead_letter_queue`) receives messages once `maxRetries` is exhausted; create
|
|
53
|
+
it with `wrangler queues create <name>`. Both are optional and go into the
|
|
54
|
+
queue's `[[queues.consumers]]` block. These are the same consumer settings
|
|
55
|
+
[`bindings.queueConsumers`](/configure/bindings) takes, and the ones to use for
|
|
56
|
+
a queue a [tenant database](/configure/tenant-databases#platform-queues) enqueues to:
|
|
57
|
+
tenant code can only send to the database queues (the primary queue and
|
|
58
|
+
`additionalQueues`).
|
|
59
|
+
|
|
42
60
|
## How It Works
|
|
43
61
|
|
|
44
62
|
All queues share a single Cloudflare Workers queue consumer. The consumer inspects each message's `type` field to dispatch to the correct handler:
|
|
@@ -52,6 +52,7 @@ The trade-off: any write in the organization changes the version, so unrelated w
|
|
|
52
52
|
|
|
53
53
|
- **Postgres:** the trigger functions are `SECURITY DEFINER`, owned by `quickback_owner`. The Worker role reads only its active organization's row, or any row on the service lane, and cannot write the table.
|
|
54
54
|
- **D1:** plain SQLite triggers in the features database.
|
|
55
|
+
- **Database per tenant** ([`tenancy.isolation: 'durable-object'`](/configure/tenant-databases#change-signals-sequences-and-changesets)): each organization's Durable Object holds its own counter, bumped by triggers on its tenant tables; tenant code reads it there. Broadcasts from tenant writes ride the object's outbox and the edge replays them, addressed to that organization.
|
|
55
56
|
- **Contention:** one row per organization serializes concurrent writes within that organization until each commits.
|
|
56
57
|
- **Providers:** `cloudflare-d1` and the Postgres providers. Elsewhere the compile fails.
|
|
57
58
|
|
|
@@ -203,6 +203,19 @@ another tenant's object never reaches that object.
|
|
|
203
203
|
hard delete there, call `deleteStorageObjects(env, table, deletedRows)` from
|
|
204
204
|
`src/lib/storage-keys`. It runs the same prefix check.
|
|
205
205
|
|
|
206
|
+
**Finalize.** `db.finalizeUpload(table, id)` loads the row through the firewall
|
|
207
|
+
and answers `{ status, key, uploadId }`. On the edge, `status` is `ready` when
|
|
208
|
+
the object exists and `pending` otherwise.
|
|
209
|
+
|
|
210
|
+
**Tenant tables.** With [database per tenant](/configure/tenant-databases), a
|
|
211
|
+
storage key on a tenant table runs through the tenant file bridge
|
|
212
|
+
(`tenancy.bridges.files`). Actions use the same calls. The object records the
|
|
213
|
+
reservation and every delete intent, and the edge signs, verifies, tombstones
|
|
214
|
+
and deletes. A tenant upload answers `status: 'pending'` and is readable only
|
|
215
|
+
after `db.finalizeUpload` verified its size and type. Keys are namespaced
|
|
216
|
+
`qbt/<project>/<environment>/<organization>/o/…` in the bucket. See
|
|
217
|
+
[Tenant databases → Managed files](/configure/tenant-databases#managed-files).
|
|
218
|
+
|
|
206
219
|
**What the compiler refuses** (each is a compile error):
|
|
207
220
|
|
|
208
221
|
| Code | Cause |
|
|
@@ -113,6 +113,30 @@ For content that doesn't live in a table (previews, external text), call the
|
|
|
113
113
|
search service's [`embed()`](/platform/vector/embeddings#generate-embeddings-directly)
|
|
114
114
|
from an action — it runs under that action's own access rules.
|
|
115
115
|
|
|
116
|
+
## Tenant Databases
|
|
117
|
+
|
|
118
|
+
With [database-per-tenant](/configure/tenant-databases)
|
|
119
|
+
(`tenancy.isolation: 'durable-object'`), a table placed in the organization's
|
|
120
|
+
Durable Object embeds through the **embeddings bridge** instead of the queue
|
|
121
|
+
above. Turn it on with `tenancy.bridges.embeddings: { enabled: true }`; without
|
|
122
|
+
it, `embeddings` on a tenant table is refused.
|
|
123
|
+
|
|
124
|
+
- The object records an index or delete intent in the write's own SQLite
|
|
125
|
+
transaction. The edge Worker, the only holder of `AI` and `VECTORIZE`, embeds
|
|
126
|
+
the text and stores an immutable vector id in the organization's Vectorize
|
|
127
|
+
namespace. A late result never replaces newer content.
|
|
128
|
+
- `GET /api/v1/<resource>?similar=<text>` is the semantic read. It returns only
|
|
129
|
+
rows whose current vector matched, through the resource's firewall, access,
|
|
130
|
+
masking and views. Scores and rejected candidates are never returned.
|
|
131
|
+
- Restore re-indexes in the new generation. Purge deletes the object's vectors
|
|
132
|
+
in bounded steps. Old-generation vectors never match a search.
|
|
133
|
+
- Tenant tables keep vectors only in Vectorize: `embeddingColumn` and
|
|
134
|
+
`metadata` are refused. Source fields must be plain columns. The table's
|
|
135
|
+
firewall must be the organization alone and its read access role-only.
|
|
136
|
+
|
|
137
|
+
See [Tenant databases → Embeddings](/configure/tenant-databases#embeddings) for
|
|
138
|
+
the full contract, models, limits and operator calls.
|
|
139
|
+
|
|
116
140
|
## Generated Files
|
|
117
141
|
|
|
118
142
|
When embeddings are configured, the compiler generates:
|
|
@@ -235,10 +259,10 @@ export default feature("jobs", {
|
|
|
235
259
|
...q.softDelete(),
|
|
236
260
|
},
|
|
237
261
|
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
238
|
-
read: {},
|
|
239
|
-
create: {},
|
|
240
|
-
update: {},
|
|
241
|
-
delete: {},
|
|
262
|
+
read: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
|
|
263
|
+
create: { access: { roles: ["owner", "hiring-manager"] } },
|
|
264
|
+
update: { access: { roles: ["owner", "hiring-manager"] } },
|
|
265
|
+
delete: { access: { roles: ["owner", "hiring-manager"] } },
|
|
242
266
|
});
|
|
243
267
|
```
|
|
244
268
|
|
|
@@ -74,6 +74,23 @@ const vector = await embeddings.jobSimilarity.embed("Text to embed");
|
|
|
74
74
|
// Returns: number[] (768 dimensions for bge-base)
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
+
## Semantic Reads on Tenant Tables
|
|
78
|
+
|
|
79
|
+
On a [tenant database](/configure/tenant-databases#embeddings) with the
|
|
80
|
+
embeddings bridge on, the collection route takes `?similar=`:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
curl "https://api.example.com/api/v1/notes?similar=quarterly%20travel%20budget&limit=10" \
|
|
84
|
+
-H "Authorization: Bearer $TOKEN"
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Results come best match first, through the table's firewall, access, masking
|
|
88
|
+
and views. Combine `?similar=` with ordinary filters (`?category=finance`).
|
|
89
|
+
`?search=`, `?total=`, aggregations and cursors are refused beside it. Pages
|
|
90
|
+
use `?offset=` and `?limit=`, up to `tenancy.bridges.embeddings.candidates`
|
|
91
|
+
results in all. Indexing is eventual: a row written a moment ago may not match
|
|
92
|
+
yet.
|
|
93
|
+
|
|
77
94
|
## Vectorize Queries
|
|
78
95
|
|
|
79
96
|
If your project uses a Vectorize index, you can query it directly for custom search logic:
|