@quickback-dev/cli 0.57.1 → 0.58.1
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/check.d.ts +24 -0
- package/dist/commands/check.d.ts.map +1 -0
- package/dist/commands/check.js +111 -0
- package/dist/commands/check.js.map +1 -0
- package/dist/commands/migrate.d.ts +13 -0
- package/dist/commands/migrate.d.ts.map +1 -1
- package/dist/commands/migrate.js +232 -0
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrate.test.js +109 -0
- package/dist/commands/migrate.test.js.map +1 -1
- package/dist/docs/content.js +70 -70
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +8 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.js +2 -2
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +11 -4
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +71 -8
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +40 -0
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/docs/changelog.md +42 -1
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +46 -2
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +1 -1
- package/dist/skill/docs/compiler/cloud-compiler/index.md +60 -4
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +4 -1
- package/dist/skill/docs/compiler/definitions/access.md +16 -12
- package/dist/skill/docs/compiler/definitions/actions.md +53 -52
- package/dist/skill/docs/compiler/definitions/changesets.md +74 -7
- package/dist/skill/docs/compiler/definitions/concepts.md +1 -1
- package/dist/skill/docs/compiler/definitions/encryption.md +11 -5
- package/dist/skill/docs/compiler/definitions/masking.md +23 -6
- package/dist/skill/docs/compiler/definitions/permissions.md +22 -23
- package/dist/skill/docs/compiler/definitions/read.md +26 -7
- package/dist/skill/docs/compiler/definitions/schema.md +48 -4
- package/dist/skill/docs/compiler/definitions/sealed-protocol.md +7 -3
- package/dist/skill/docs/compiler/index.md +7 -4
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +43 -15
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +17 -5
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +17 -8
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +2 -2
- package/dist/skill/docs/stack/cms/index.md +5 -2
- package/dist/skill/docs/stack/schedules/index.md +46 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +42 -1
- package/src/skill/docs/compiler/cloud-compiler/cli.md +46 -2
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +1 -1
- package/src/skill/docs/compiler/cloud-compiler/index.md +60 -4
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +4 -1
- package/src/skill/docs/compiler/definitions/access.md +16 -12
- package/src/skill/docs/compiler/definitions/actions.md +53 -52
- package/src/skill/docs/compiler/definitions/changesets.md +74 -7
- package/src/skill/docs/compiler/definitions/concepts.md +1 -1
- package/src/skill/docs/compiler/definitions/encryption.md +11 -5
- package/src/skill/docs/compiler/definitions/masking.md +23 -6
- package/src/skill/docs/compiler/definitions/permissions.md +22 -23
- package/src/skill/docs/compiler/definitions/read.md +26 -7
- package/src/skill/docs/compiler/definitions/schema.md +48 -4
- package/src/skill/docs/compiler/definitions/sealed-protocol.md +7 -3
- package/src/skill/docs/compiler/index.md +7 -4
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +43 -15
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +17 -5
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +17 -8
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +2 -2
- package/src/skill/docs/stack/cms/index.md +5 -2
- package/src/skill/docs/stack/schedules/index.md +46 -0
|
@@ -46,7 +46,7 @@ Ciphertext cannot be queried, so encrypted columns are **excluded from every que
|
|
|
46
46
|
- Never an `embeddings.fields` source (embedding a value ships its plaintext to the model)
|
|
47
47
|
- The table must carry a `q.scope('organization')` column — keys are per-organization
|
|
48
48
|
- Text-shaped columns only (v1)
|
|
49
|
-
- Database provider must be **Cloudflare D1** or **Neon over HTTP
|
|
49
|
+
- Database provider must be **Cloudflare D1** or **Neon over HTTP/Hyperdrive**. The deprecated Neon WebSocket mode and providers without the key-table plumbing are compile-time refusals, never silently-plaintext output. On Neon, `org_data_keys` lives in the `app` Postgres schema with org-scoped row-level security: a request-scoped connection can read and lazily create exactly its own organization's wrapped-key row; rotation and crypto-shredding are service-role operations.
|
|
50
50
|
|
|
51
51
|
Encrypted columns **may** appear in view projections and responses — they decrypt through the generated prepare path. Masking composes on top as defense-in-depth.
|
|
52
52
|
|
|
@@ -170,12 +170,18 @@ Sealed values are opaque references at rest, so they're fenced off from every su
|
|
|
170
170
|
- The table **must** carry a `q.scope('organization')` column — keys are per-scope.
|
|
171
171
|
- Reading a sealed column server-side is a **type error**: the column is branded `$type<SealedValue>()`, an opaque non-string, so `db.select()` on it won't typecheck. The server's structural inability to read it is enforced by `tsc`, not convention.
|
|
172
172
|
- Sealed projects **force-enable** KV-backed JWT revocation (so a revoked reader's in-flight reveal token dies); a project with sealed columns and no KV binding **fails to compile**.
|
|
173
|
-
- Database provider must be **Cloudflare D1** or **Neon over HTTP**
|
|
173
|
+
- Database provider must be **Cloudflare D1** or **Neon over HTTP/Hyperdrive** — anything else fails to compile. On Neon, the seal/vault tables carry **deny-all row-level security for request connections**: only the worker-internal service-role lane (the generated `/seal/v1` routes, `ctx.seal`, and the sealed write chokepoint) can touch them, and every one of those queries is still explicitly organization-scoped.
|
|
174
174
|
|
|
175
175
|
## What this tier does and doesn't claim
|
|
176
176
|
|
|
177
|
-
The sealed tier protects against **full Worker compromise** — leaked secrets, malicious or buggy server code, a coerced operator. All of them get ciphertext; the keys to read it never exist server-side.
|
|
177
|
+
The sealed tier protects against **full Worker compromise** — leaked secrets, malicious or buggy server code, a coerced operator. All of them get ciphertext; the keys to read it never exist server-side. Its operating model is explicit:
|
|
178
178
|
|
|
179
|
-
- **A reveal needs a real second factor.** The vault passphrase (or passkey) is separate from login and never leaves the client.
|
|
179
|
+
- **A reveal needs a real second factor.** The vault passphrase (or passkey) is separate from login and never leaves the client.
|
|
180
|
+
- **Recovery is opt-in and zero-knowledge.** A key admin can enroll a scope key wrapped under a client-held recovery code through `/seal/v1/recovery/enroll`; `/recovery/use` returns only that opaque wrapped blob. If no recovery is enrolled and every reader loses their factor, the data is unrecoverable by design.
|
|
181
|
+
- **Rotation includes re-granting.** `/rotate` versions the scope key and returns the live-reader worklist and public keys so the key-admin client can wrap and grant the new private key without exposing it to the server.
|
|
180
182
|
- **No server-side processing.** Your actions can't read, mask, search, or index a sealed value — it's plaintext only in a client that just revealed it. If the server needs to process the field, you want the envelope tier instead.
|
|
181
|
-
- **Passkey
|
|
183
|
+
- **Passkey rollout check.** The server verification path and nonce-bound
|
|
184
|
+
WebAuthn contract are implemented; before enabling it for a production
|
|
185
|
+
hostname, run the ceremony with that deployment's real browser,
|
|
186
|
+
authenticator, RP ID, and origin. The passphrase lane is fully round-trip
|
|
187
|
+
tested.
|
|
@@ -141,9 +141,16 @@ show: {
|
|
|
141
141
|
|
|
142
142
|
The `'owner'` condition compares against the owner column declared via `q.scope('owner')` (or auto-detected from a `userId` / `ownerId` column). If no owner scope is present, it falls back to `createdBy`.
|
|
143
143
|
|
|
144
|
-
### Relationship-
|
|
144
|
+
### Relationship-aware field projection
|
|
145
145
|
|
|
146
|
-
|
|
146
|
+
For relationship-specific field visibility, use a named view gated by the
|
|
147
|
+
relationship role. The relationship resolver runs once at the access layer and
|
|
148
|
+
the view projects only the fields that caller may receive.
|
|
149
|
+
|
|
150
|
+
Quickback deliberately does not run per-row database lookups from
|
|
151
|
+
`masking.<field>.show`: doing so would turn list masking into an N+1 query
|
|
152
|
+
pipeline. A relationship-backed `show.roles` entry is therefore a clear
|
|
153
|
+
compile-time refusal, never a silently ignored condition or a broader grant.
|
|
147
154
|
|
|
148
155
|
### Named gates in masking
|
|
149
156
|
|
|
@@ -153,12 +160,14 @@ Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }
|
|
|
153
160
|
- A gate carrying a **`record:`** predicate is a **compile error** — masking cannot evaluate record conditions, so the record dimension would be silently dropped.
|
|
154
161
|
- A gate carrying **firewall lanes** is a **compile error** — masking has no firewall array to satisfy, so the gate's row lanes would silently not apply. Reference a who-only rule (or inline the roles) in `show:`, and stamp the firewall gate on the resource's `firewall:` instead.
|
|
155
162
|
|
|
156
|
-
**
|
|
163
|
+
**Supported patterns**, depending on intent:
|
|
157
164
|
|
|
158
165
|
- **Gate on BA roles only**: keep masking simple and put the relationship check at the access layer instead — `read.views.<v>.access: { roles: ['guest'] }` returns a curated field projection that excludes the sensitive column entirely for non-staff callers, without involving masking.
|
|
159
166
|
- **Move the field into a view that's gated by the relationship-role at access**: same pattern — column-level security via field projection rather than per-row masking.
|
|
160
167
|
|
|
161
|
-
|
|
168
|
+
The schema slot remains reserved for a future batched async-mask pipeline, so
|
|
169
|
+
adding that execution mode will not require changing the surrounding masking
|
|
170
|
+
shape.
|
|
162
171
|
|
|
163
172
|
## Query Gate (filter / sort / search)
|
|
164
173
|
|
|
@@ -205,7 +214,9 @@ read: {
|
|
|
205
214
|
},
|
|
206
215
|
```
|
|
207
216
|
|
|
208
|
-
`query`
|
|
217
|
+
`query` is the unified replacement for the legacy per-capability masking flags
|
|
218
|
+
(`filterable`, `searchable`, `sortable`). If an older definition still uses
|
|
219
|
+
one, the compiler stops with the exact migration to the single role gate.
|
|
209
220
|
|
|
210
221
|
## Egress protection
|
|
211
222
|
|
|
@@ -237,7 +248,13 @@ masking: {
|
|
|
237
248
|
}
|
|
238
249
|
```
|
|
239
250
|
|
|
240
|
-
`egress` defaults to `'block'` (fail-closed).
|
|
251
|
+
`egress` defaults to `'block'` (fail-closed). The action scan is an
|
|
252
|
+
accident-prevention layer: it catches direct `record.col` → sink flows without
|
|
253
|
+
pretending to be a whole-program information-flow proof. Aliased values,
|
|
254
|
+
whole-row spreads, and values re-fetched through `db.select()` remain ordinary
|
|
255
|
+
application code. Pair masking with the [encryption
|
|
256
|
+
pillar](/compiler/definitions/encryption) whenever the field needs a
|
|
257
|
+
cryptographic boundary at rest or from the server itself.
|
|
241
258
|
|
|
242
259
|
## Complete Example
|
|
243
260
|
|
|
@@ -86,29 +86,28 @@ permission is just the named, reusable spelling.
|
|
|
86
86
|
See [Firewall — named permissions](/compiler/definitions/firewall#named-permissions-permission)
|
|
87
87
|
for how the arm sits inside a firewall.
|
|
88
88
|
|
|
89
|
-
##
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
`read.access` / `crud.*.access
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
are now shipped and **are** firewall-pushable — see
|
|
89
|
+
## Firewall-pushable permission rules
|
|
90
|
+
|
|
91
|
+
A firewall permission compiles all the way down to a SQL `WHERE` expression.
|
|
92
|
+
The production-ready subset includes relationship leaves, composed
|
|
93
|
+
`{ permissionRef }` leaves, and FK-traversal arrows under `anyOf` / `allOf`.
|
|
94
|
+
Those rules run in the database alongside the rest of the row firewall.
|
|
95
|
+
|
|
96
|
+
Two expression shapes belong at a different enforcement site, and the compiler
|
|
97
|
+
routes you there with a build error instead of weakening the policy:
|
|
98
|
+
|
|
99
|
+
- **Claim checks.** `{ role }`, `{ scopeRole }`, and `{ pseudoRole }` are
|
|
100
|
+
decided from verified request claims rather than row subqueries. Put them on
|
|
101
|
+
`read.access` / `crud.*.access`, then keep the permission focused on row
|
|
102
|
+
reachability.
|
|
103
|
+
- **Negated SQL relationships.** `not` over a relationship site is refused
|
|
104
|
+
because nullable `NOT IN (subquery)` semantics create the classic null trap.
|
|
105
|
+
Express the positive relationship set or enforce the exclusion at a runtime
|
|
106
|
+
access site.
|
|
107
|
+
|
|
108
|
+
The wider DSL remains available for permission definitions and future
|
|
109
|
+
enforcement sites, while every firewall reference is checked for SQL
|
|
110
|
+
pushability today. FK-traversal arrows are firewall-pushable; see
|
|
112
111
|
[Arrows](/compiler/definitions/arrows).
|
|
113
112
|
|
|
114
113
|
The compile-time analyzer flags permissions that can never be satisfied,
|
|
@@ -212,13 +212,32 @@ export default defineTable(balanceSnapshots, {
|
|
|
212
212
|
|
|
213
213
|
## Aggregate Reads
|
|
214
214
|
|
|
215
|
-
Reading a parent **with** its owned relations
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
(
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
215
|
+
Reading a parent **with** its owned relations rides contract-v2 `?include=`,
|
|
216
|
+
which accepts two kinds of tokens in the same `read.include` allowlist:
|
|
217
|
+
|
|
218
|
+
- **FK columns** (`?include=vendorId`) — forward embeds: the target rows the
|
|
219
|
+
source row points at.
|
|
220
|
+
- **`owns` relation names** (`?include=reactions`) — the phase-2 aggregate
|
|
221
|
+
reader: the changeset root's owned **child rows**, pivoting on the root PK
|
|
222
|
+
and matching the child's declared `fk` column.
|
|
223
|
+
|
|
224
|
+
```typescript
|
|
225
|
+
export default defineTable(notes, {
|
|
226
|
+
owns: { reactions: { table: 'noteReactions', fk: 'noteId' } },
|
|
227
|
+
read: {
|
|
228
|
+
access: { roles: ['member', 'admin'] },
|
|
229
|
+
include: ['reactions'], // ?include=reactions embeds the children
|
|
230
|
+
},
|
|
231
|
+
});
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Both kinds land in the top-level `included` map keyed by the include token,
|
|
235
|
+
then row PK, and both inherit the **target's full security surface** — its
|
|
236
|
+
`read.access` (pre-record-evaluable only, compile-enforced), its firewall
|
|
237
|
+
(ANDed into the child fetch on the caller-claims handle), and its masking.
|
|
238
|
+
`fields[<token>]` sparse projections apply identically. The aggregate-changeset
|
|
239
|
+
write surface ([changesets](/compiler/definitions/changesets)) still returns
|
|
240
|
+
the **root row only** — read the aggregate back with `?include=<relation>`.
|
|
222
241
|
|
|
223
242
|
## See Also
|
|
224
243
|
|
|
@@ -352,11 +352,22 @@ These internal tables still participate in the database schema and migrations
|
|
|
352
352
|
|
|
353
353
|
The compiler automatically injects the four **[audit fields](#audit-fields)** (`createdAt`/`createdBy`/`modifiedAt`/`modifiedBy`), the soft-delete pair (`deletedAt`/`deletedBy`, when soft delete is enabled), and **`organizationId`** into child/junction tables when the parent feature is org-scoped. This ensures cascade soft deletes and scoped queries work correctly without manual column definitions.
|
|
354
354
|
|
|
355
|
-
>
|
|
355
|
+
> **Route keys are handled automatically**
|
|
356
356
|
>
|
|
357
|
-
>
|
|
357
|
+
> Quickback gives every route-backed table one stable key. `compiler.injectId`
|
|
358
|
+
> defaults to `'auto'`: a table without a primary key receives an `id` whose
|
|
359
|
+
> generation strategy follows `providers.database.config.generateId`.
|
|
358
360
|
>
|
|
359
|
-
>
|
|
361
|
+
> For a greenfield table with a non-`id` or compound primary key, the compiler
|
|
362
|
+
> preserves that domain uniqueness as a unique index and adds the route `id`.
|
|
363
|
+
> For an already-deployed table where changing the primary key needs a migration,
|
|
364
|
+
> the compile stops with migration guidance instead of emitting broken routes.
|
|
365
|
+
>
|
|
366
|
+
> Use `q.id()` when you want the key visible in authored source. Set
|
|
367
|
+
> `compiler.injectId: false` only when deliberately retaining a custom
|
|
368
|
+
> single-column route key; Quickback resolves that key through schema metadata.
|
|
369
|
+
> Internal `// @quickback-internal` junction tables can keep compound keys because
|
|
370
|
+
> they do not expose CRUD routes.
|
|
360
371
|
|
|
361
372
|
|
|
362
373
|
## Audit Fields
|
|
@@ -502,6 +513,38 @@ await db.update(records)
|
|
|
502
513
|
|
|
503
514
|
You don't set `deletedBy` yourself; the wrapper pairs it with the `deletedAt` signal.
|
|
504
515
|
|
|
516
|
+
### Retention and permanent erasure
|
|
517
|
+
|
|
518
|
+
Soft delete is the recoverable default, not a fixed data-retention policy.
|
|
519
|
+
Quickback leaves the retention window in application code because legal holds,
|
|
520
|
+
customer contracts, and record classes rarely share one universal timer.
|
|
521
|
+
|
|
522
|
+
The platform provides the pieces for an explicit policy:
|
|
523
|
+
|
|
524
|
+
- **Immediate permanent deletion** — configure
|
|
525
|
+
`delete: { mode: 'hard', batch: { mode: 'hard' } }`. Generated hard-delete
|
|
526
|
+
routes record the deletion in the security audit pipeline before removing the
|
|
527
|
+
row.
|
|
528
|
+
- **Time-based purging** — declare a
|
|
529
|
+
[`defineSchedule`](/stack/schedules#retention-and-purge-jobs) job that
|
|
530
|
+
hard-deletes rows whose `deletedAt` is older than your policy cutoff. The
|
|
531
|
+
scheduler emits the Worker cron trigger and runs the same code on D1 or
|
|
532
|
+
Neon.
|
|
533
|
+
- **Aggregate deletion** — use database foreign keys with
|
|
534
|
+
`onDelete: 'cascade'` for same-database ownership, and orchestrate
|
|
535
|
+
cross-database records, R2 objects, and external systems from an explicit
|
|
536
|
+
offboarding action or queued job.
|
|
537
|
+
- **Encrypted data** — envelope-encrypted fields support per-organization
|
|
538
|
+
crypto-shredding by deleting the wrapped DEK. Sealed deployments should
|
|
539
|
+
include their vault grants, recovery records, and key versions in the same
|
|
540
|
+
reviewed offboarding workflow.
|
|
541
|
+
|
|
542
|
+
That makes retention ordinary, version-controlled business logic rather than a
|
|
543
|
+
global platform timer that might erase the wrong class of record. It also keeps
|
|
544
|
+
the compliance claim honest: the schedule and erasure workflow implement your
|
|
545
|
+
policy; enabling soft delete alone does not assert GDPR, HIPAA, or SOC 2
|
|
546
|
+
compliance.
|
|
547
|
+
|
|
505
548
|
### Protected system fields
|
|
506
549
|
|
|
507
550
|
The audit and soft-delete columns are always protected from client input, even with `guards: false`:
|
|
@@ -773,7 +816,8 @@ export const jobs = pgTable('jobs', {
|
|
|
773
816
|
| Feature | SQLite | PostgreSQL |
|
|
774
817
|
|---------|--------|------------|
|
|
775
818
|
| Boolean | `integer({ mode: 'boolean' })` | `boolean()` |
|
|
776
|
-
| JSON | `text({ mode: 'json' })` | `jsonb()` or `json()` |
|
|
819
|
+
| JSON | `text({ mode: 'json' })` with D1 JSON functions and `->` / `->>` operators | `jsonb()` or `json()` with PostgreSQL JSON indexing |
|
|
820
|
+
| Arrays | Relational child rows or JSON arrays (`json_each`) | Native arrays, relational rows, or JSONB |
|
|
777
821
|
| Auto-increment | `integer().primaryKey()` | `serial()` |
|
|
778
822
|
| UUID | `text()` | `uuid()` |
|
|
779
823
|
|
|
@@ -336,11 +336,15 @@ val plaintext = seal.reveal(session, scope, vaultItemId) /
|
|
|
336
336
|
|
|
337
337
|
Passkey reveal is the same call as `revealWithPasskey(…, getAssertion)`, where `getAssertion(nonce)` runs the platform WebAuthn ceremony with `challenge = nonce`. Full details, the transport contract, and the conformance harness live in [`apps/seal-sdk/README`](https://github.com/paulstenhouse/quickback-compiler/tree/main/apps/seal-sdk). The SDKs are versioned **with** the compiler in the same repo, so the wire format never drifts from the server you're talking to.
|
|
338
338
|
|
|
339
|
-
##
|
|
339
|
+
## Current lifecycle boundary
|
|
340
340
|
|
|
341
|
-
|
|
341
|
+
The protocol already includes versioned rotation, a reader re-grant worklist,
|
|
342
|
+
grant requests, and recovery-code escrow. Two management conveniences remain
|
|
343
|
+
outside the current contract:
|
|
342
344
|
|
|
343
345
|
- **Content-key re-encryption on rotation** — `/rotate` versions the scope key and re-grants *readers*, and older key versions stay readable, so nothing breaks. But existing sealed *values* keep their content keys wrapped to the old scope key until a client re-seals them; there's no bulk re-encrypt-and-crypto-shred-the-old-version flow yet.
|
|
344
346
|
- **Audience grants beyond reveal** — `vault_grant` audience reveals are honored at `/reveal`/`/key`, but there's no first-class management surface yet.
|
|
345
347
|
|
|
346
|
-
|
|
348
|
+
Neither is required for ordinary seal, reveal, grant, revoke, recovery, or key
|
|
349
|
+
rotation flows. Future management routes can be added under the versioned
|
|
350
|
+
protocol without changing the `qbseal:1` wire format.
|
|
@@ -28,7 +28,7 @@ quickback/
|
|
|
28
28
|
|
|
29
29
|
## The target: Hono on Cloudflare
|
|
30
30
|
|
|
31
|
-
[Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for SQLite
|
|
31
|
+
[Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for managed SQLite or **Neon** for PostgreSQL over HTTP or Hyperdrive.
|
|
32
32
|
|
|
33
33
|
```typescript
|
|
34
34
|
providers: {
|
|
@@ -44,11 +44,14 @@ providers: {
|
|
|
44
44
|
- **[Configuration](/compiler/config)** — `quickback.config.ts`, providers, domains, bindings
|
|
45
45
|
- **[Getting Started](/compiler/getting-started)** — Templates and full examples
|
|
46
46
|
|
|
47
|
-
## The
|
|
47
|
+
## The compiler and the CLI
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
`quickback compile` uses the zero-setup hosted compiler by default. Teams with
|
|
50
|
+
restricted-source or build-availability requirements can run the same compiler
|
|
51
|
+
image locally and point the CLI at it:
|
|
50
52
|
|
|
51
|
-
- **[
|
|
53
|
+
- **[Hosted and local compilation](/compiler/cloud-compiler)** — one compiler,
|
|
54
|
+
identical generated output, two operational trust boundaries
|
|
52
55
|
- **[Claude Code Skill](/compiler/claude-code-skill)** — AI-powered authoring assistance
|
|
53
56
|
|
|
54
57
|
## Development workflow
|
|
@@ -1,15 +1,20 @@
|
|
|
1
1
|
# D1 Database
|
|
2
2
|
|
|
3
|
-
Cloudflare D1 is
|
|
3
|
+
Cloudflare D1 is managed, serverless SQLite on Cloudflare's network. It is
|
|
4
|
+
Quickback's zero-configuration default for Cloudflare deployments and a strong
|
|
5
|
+
fit for CRUD-heavy SaaS products, content catalogs, internal tools, and
|
|
6
|
+
workflows that benefit from simple operations.
|
|
4
7
|
|
|
5
8
|
## What is D1?
|
|
6
9
|
|
|
7
10
|
D1 is Cloudflare's serverless SQL database built on SQLite:
|
|
8
11
|
|
|
9
|
-
- **
|
|
10
|
-
|
|
11
|
-
- **
|
|
12
|
-
- **
|
|
12
|
+
- **Cloudflare-native** — queried directly from your Worker with no public
|
|
13
|
+
connection string
|
|
14
|
+
- **SQLite SQL** — including D1's supported FTS5, JSON, and math extensions
|
|
15
|
+
- **Zero connection management** — no pool or database server to operate
|
|
16
|
+
- **Managed durability** — built-in disaster recovery, with global read
|
|
17
|
+
replication available through D1 Sessions when a workload needs it
|
|
13
18
|
|
|
14
19
|
## Multi-Database Pattern
|
|
15
20
|
|
|
@@ -234,13 +239,36 @@ The `withFirewall` helper:
|
|
|
234
239
|
3. **Avoid raw SQL** - Raw SQL bypasses application security; use Drizzle ORM
|
|
235
240
|
4. **Review custom code** - Manual routes should be code-reviewed for security
|
|
236
241
|
|
|
237
|
-
##
|
|
238
|
-
|
|
239
|
-
D1 is
|
|
240
|
-
|
|
241
|
-
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
-
|
|
245
|
-
|
|
246
|
-
|
|
242
|
+
## Choose by workload, not by a limitations checklist
|
|
243
|
+
|
|
244
|
+
D1 is more capable than a simple `LIKE`-only store. Cloudflare documents
|
|
245
|
+
[FTS5 full-text search and the JSON
|
|
246
|
+
extension](https://developers.cloudflare.com/d1/sql-api/sql-statements/), and
|
|
247
|
+
D1 supports JSON path extraction, mutation, `->` / `->>` operators, and array
|
|
248
|
+
expansion through
|
|
249
|
+
[`json_each`](https://developers.cloudflare.com/d1/sql-api/query-json/).
|
|
250
|
+
SQLite also supports CTEs and window functions. The important distinction is
|
|
251
|
+
whether your application wants SQLite's model or PostgreSQL's ecosystem.
|
|
252
|
+
|
|
253
|
+
| Need | D1 approach | Choose Neon/Postgres when… |
|
|
254
|
+
|---|---|---|
|
|
255
|
+
| Generated Quickback search | The generated `?search` API uses allowlisted `LIKE` semantics; custom actions can use FTS5 | Search is built around PostgreSQL `tsvector`, language dictionaries, GIN indexes, or an existing Postgres search design |
|
|
256
|
+
| 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 |
|
|
257
|
+
| 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 |
|
|
258
|
+
| 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 |
|
|
259
|
+
| IDs | `q.id()` uses Quickback's provider-driven generation; SQLite `INTEGER PRIMARY KEY` is also available through Drizzle interop | Native UUID/identity types and database-side defaults are a design requirement |
|
|
260
|
+
| Write profile | A D1 database processes queries serially and is excellent for modest, short writes | The app needs sustained concurrent writes or interactive multi-step transactions |
|
|
261
|
+
|
|
262
|
+
The practical rule is simple:
|
|
263
|
+
|
|
264
|
+
- Start with **D1** for conventional application data, low operational
|
|
265
|
+
overhead, and Cloudflare-native deployment.
|
|
266
|
+
- Start with **Neon/Postgres** when advanced SQL and data types are part of the
|
|
267
|
+
product architecture—not as a workaround after launch. Neon HTTP remains the
|
|
268
|
+
lightweight Cloudflare path; add Hyperdrive only when the application needs
|
|
269
|
+
interactive transactions or connection pooling.
|
|
270
|
+
|
|
271
|
+
Keep Cloudflare's current [D1 platform
|
|
272
|
+
limits](https://developers.cloudflare.com/d1/platform/limits/) in capacity
|
|
273
|
+
planning. Quickback supports both providers, so choosing Postgres for an
|
|
274
|
+
advanced application is a first-class architecture choice.
|
|
@@ -1,13 +1,25 @@
|
|
|
1
1
|
# Database
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Quickback treats D1 and Neon/Postgres as first-class database targets. Choose
|
|
4
|
+
from the application's data model and query profile; the same Quickback
|
|
5
|
+
security definitions compile to either provider.
|
|
4
6
|
|
|
5
7
|
## Providers
|
|
6
8
|
|
|
7
|
-
| Provider | Best
|
|
8
|
-
|
|
9
|
-
| [Cloudflare D1](/compiler/targets/hono-api/database/d1) |
|
|
10
|
-
| [Neon](/compiler/targets/hono-api/database/neon) |
|
|
9
|
+
| Provider | Best for | Why choose it |
|
|
10
|
+
|----------|----------|---------------|
|
|
11
|
+
| [Cloudflare D1](/compiler/targets/hono-api/database/d1) | CRUD-heavy SaaS, content catalogs, internal tools, straightforward workflows | Managed SQLite, no connection strings or pooling, Cloudflare-native operations, FTS5 and JSON functions when needed |
|
|
12
|
+
| [Neon](/compiler/targets/hono-api/database/neon) | Data-intensive products and apps designed around PostgreSQL | Native JSONB/arrays, `tsvector` + GIN, PostGIS/extensions, database RLS, advanced indexing and interactive transactions through Hyperdrive |
|
|
13
|
+
|
|
14
|
+
## Quick decision
|
|
15
|
+
|
|
16
|
+
- Pick **D1** when simple operations and a low-ops Cloudflare deployment are the
|
|
17
|
+
priority.
|
|
18
|
+
- Pick **Neon/Postgres** up front when advanced search, rich data types,
|
|
19
|
+
sustained concurrent writes, Postgres extensions, or database-level RLS are
|
|
20
|
+
product requirements.
|
|
21
|
+
- Hyperdrive is optional: Neon HTTP is the lightweight default on Cloudflare;
|
|
22
|
+
Hyperdrive is the full-featured lane for interactive transactions.
|
|
11
23
|
|
|
12
24
|
## Getting Started
|
|
13
25
|
|
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
# Neon
|
|
2
2
|
|
|
3
|
-
Neon provides serverless PostgreSQL
|
|
3
|
+
Neon provides serverless PostgreSQL for Cloudflare Workers. Choose it when the
|
|
4
|
+
application is designed around PostgreSQL: native JSONB and arrays, `tsvector`
|
|
5
|
+
with GIN indexes, PostGIS or other extensions, sustained concurrent writes, or
|
|
6
|
+
database-level Row Level Security alongside the generated Hono API. D1 also
|
|
7
|
+
supports JSON functions and FTS5; Neon is the choice when the **PostgreSQL
|
|
8
|
+
implementation and ecosystem** are the requirement.
|
|
4
9
|
|
|
5
10
|
## Why Neon
|
|
6
11
|
|
|
@@ -722,15 +727,17 @@ precedent — so there is no separate `WEBHOOKS_DB` binding.
|
|
|
722
727
|
## Encryption on Neon
|
|
723
728
|
|
|
724
729
|
The encryption pillar — `.encrypted()` (envelope) and `.sealed()` /
|
|
725
|
-
`q.vaultRef()` (sealed) columns — is supported on Neon over HTTP
|
|
730
|
+
`q.vaultRef()` (sealed) columns — is supported on Neon over HTTP and
|
|
731
|
+
Hyperdrive. The
|
|
726
732
|
`org_data_keys` and seal-vault tables fold into the single journaled migration
|
|
727
733
|
set, and the encryption RLS section rides the journaled RLS migration:
|
|
728
734
|
`org_data_keys` gets org-scoped RLS (the envelope DEK path needs caller claims),
|
|
729
735
|
and the vault spine is locked to service-role-only. The seal chokepoints
|
|
730
736
|
acquire `createServiceDb`.
|
|
731
737
|
|
|
732
|
-
|
|
733
|
-
|
|
738
|
+
The deprecated Node/Bun WebSocket mode is a fail-closed compile error for both
|
|
739
|
+
tiers because it cannot provide the request-scoped and service-role handles the
|
|
740
|
+
key tables require.
|
|
734
741
|
|
|
735
742
|
## Batch transactions
|
|
736
743
|
|
|
@@ -782,7 +789,7 @@ export default defineAction({
|
|
|
782
789
|
|
|
783
790
|
Note the `tx.select()…for("update")` form: Drizzle's relational query API
|
|
784
791
|
(`tx.query.<table>.findFirst`) is [blocked on the scoped
|
|
785
|
-
`db`/`tx`](/compiler/definitions/actions#relational-
|
|
792
|
+
`db`/`tx`](/compiler/definitions/actions#scoped-relational-query-safety)
|
|
786
793
|
because the tenant firewall can't be injected into relational queries. The
|
|
787
794
|
select builder gives you the same row lock with scope conditions applied
|
|
788
795
|
automatically.
|
|
@@ -948,10 +955,12 @@ automatically.
|
|
|
948
955
|
| Factor | Neon | D1 |
|
|
949
956
|
|--------|------|-----|
|
|
950
957
|
| SQL dialect | PostgreSQL | SQLite |
|
|
958
|
+
| Search | `tsvector`, language dictionaries, GIN indexes | FTS5 in custom SQL; generated Quickback `?search` uses `LIKE` |
|
|
959
|
+
| Structured data | Native JSONB, arrays, rich Postgres types | JSON text with JSON path/operators; relational or JSON arrays |
|
|
951
960
|
| Security model | RLS + application-layer | Application-layer only |
|
|
952
|
-
|
|
|
953
|
-
|
|
|
954
|
-
| Best for |
|
|
961
|
+
| Transactions | HTTP batches; interactive transactions with Hyperdrive | Atomic statements/batches within D1's SQLite execution model |
|
|
962
|
+
| Operations | Neon HTTP is lightweight; Hyperdrive is optional for pooling/interactive transactions | No connection strings or pooling |
|
|
963
|
+
| Best for | Postgres-native, data-intensive, or high-concurrency applications | Cloudflare-native CRUD and conventional application workloads |
|
|
955
964
|
|
|
956
965
|
## See also
|
|
957
966
|
|
|
@@ -14,9 +14,9 @@ The generated API returns structured error responses with consistent fields acro
|
|
|
14
14
|
| `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
|
|
15
15
|
| `404` | Not Found | Record doesn't exist (or firewall blocked with `errorMode: 'hide'`) |
|
|
16
16
|
| `409` | Conflict | Unique constraint hit, or a duplicate [`Idempotency-Key`](/stack/api-contract#idempotency-key) still in flight |
|
|
17
|
-
| `412` | Precondition Failed | [
|
|
17
|
+
| `412` | Precondition Failed | `If-Match` revision mismatch — [changesets](/compiler/definitions/changesets) and plain single-record `PATCH`/`PUT`/`DELETE` |
|
|
18
18
|
| `422` | Unprocessable | `Idempotency-Key` reused with a different request or principal |
|
|
19
|
-
| `428` | Precondition Required | `If-Match` sent where no revision
|
|
19
|
+
| `428` | Precondition Required | `If-Match` sent where it can't anchor: no revision column, a batch endpoint (single-resource precondition), or the POST changeset variant |
|
|
20
20
|
| `429` | Too Many Requests | Rate limit exceeded |
|
|
21
21
|
| `500` | Internal Error | Uncaught throw — generic body, full error server-side |
|
|
22
22
|
|
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
# Quickback CMS
|
|
2
2
|
|
|
3
|
-
> **Early Access**
|
|
3
|
+
> **Available in Early Access**
|
|
4
4
|
>
|
|
5
|
-
> The Quickback CMS is
|
|
5
|
+
> The Quickback CMS is available today for any Quickback-compiled API that emits
|
|
6
|
+
> a schema registry. Core schema-driven CRUD, views, actions, access, and masking
|
|
7
|
+
> workflows are ready to use. The CMS is evolving quickly, so review release notes
|
|
8
|
+
> when upgrading projects that depend on customized admin workflows.
|
|
6
9
|
|
|
7
10
|
|
|
8
11
|
# Quickback CMS
|
|
@@ -72,6 +72,52 @@ execute: async ({ db, withInternalContext }) => {
|
|
|
72
72
|
|
|
73
73
|
`withInternalContext` builds a context with `internal: true` and `userId: "system:cron-<name>"`, so audited writes made through it are attributable to the schedule (e.g. `system:cron-sweepDigests`) and can reach `roles: ['INTERNAL']`-gated rows. Reach for it whenever the schedule legitimately operates across tenants.
|
|
74
74
|
|
|
75
|
+
## Retention and purge jobs
|
|
76
|
+
|
|
77
|
+
Retention is a strong fit for schedules because the cutoff stays in your
|
|
78
|
+
version-controlled business logic. This example permanently removes records
|
|
79
|
+
90 days after they were soft-deleted:
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
// quickback/services/schedules/purgeDeletedRecords.ts
|
|
83
|
+
import { and, isNotNull, lt } from "drizzle-orm";
|
|
84
|
+
import { defineSchedule } from "quickback";
|
|
85
|
+
import { records } from "../../features/records/records";
|
|
86
|
+
|
|
87
|
+
const RETENTION_DAYS = 90;
|
|
88
|
+
|
|
89
|
+
export default defineSchedule({
|
|
90
|
+
name: "purgeDeletedRecords",
|
|
91
|
+
cron: "0 2 * * *",
|
|
92
|
+
description: "Permanently remove records after the recovery window",
|
|
93
|
+
execute: async ({ db, scheduledTime }) => {
|
|
94
|
+
const cutoff = new Date(
|
|
95
|
+
scheduledTime - RETENTION_DAYS * 24 * 60 * 60 * 1000,
|
|
96
|
+
);
|
|
97
|
+
|
|
98
|
+
await db
|
|
99
|
+
.delete(records)
|
|
100
|
+
.where(and(
|
|
101
|
+
isNotNull(records.deletedAt),
|
|
102
|
+
lt(records.deletedAt, cutoff),
|
|
103
|
+
));
|
|
104
|
+
},
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The schedule's plain `db` is intentionally unscoped so a maintenance job can
|
|
109
|
+
operate across tenants and can see rows hidden by the normal
|
|
110
|
+
`deletedAt IS NULL` firewall. Keep the cutoff predicate explicit, process large
|
|
111
|
+
sets in bounded batches, and add the audit/metrics your retention policy
|
|
112
|
+
requires. Use an on-demand admin action or queue workflow for subject- or
|
|
113
|
+
organization-level erasure that also needs to remove R2 objects, auth records,
|
|
114
|
+
or external-provider data.
|
|
115
|
+
|
|
116
|
+
See [Schema → Retention and permanent
|
|
117
|
+
erasure](/compiler/definitions/schema#retention-and-permanent-erasure) for the
|
|
118
|
+
full policy pattern, including hard-delete routes, cascades, and encrypted
|
|
119
|
+
data.
|
|
120
|
+
|
|
75
121
|
## Failure isolation
|
|
76
122
|
|
|
77
123
|
The generated `scheduled()` dispatcher runs every schedule whose cron matches `event.cron` concurrently (`Promise.all`), and each handler's errors are caught individually — one failing schedule logs `[Cron] Schedule error` and the others still run to completion. A cron with no registered handler logs `[Cron] No schedule registered` and returns.
|