@quickback-dev/cli 0.70.26 → 0.70.27

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/index.js CHANGED
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import pc from "picocolors";
12
12
  // Version injected at build time by scripts/inject-version.ts
13
- const CLI_VERSION = "0.70.26";
13
+ const CLI_VERSION = "0.70.27";
14
14
  function getPackageVersion() {
15
15
  return CLI_VERSION;
16
16
  }
@@ -132,6 +132,8 @@ single Postgres database with no bindings or split mode (see
132
132
  | `connectionMode` | `"auto" \| "http" \| "websocket" \| "hyperdrive"` | `"auto"` | How the generated runtime connects (`hyperdrive` enables interactive Postgres transactions on Workers) |
133
133
  | `hyperdrive.id` | `string` | — | Required Cloudflare Hyperdrive configuration ID when `connectionMode: "hyperdrive"` |
134
134
  | `hyperdrive.localConnectionString` | `string` | — | Optional local-only Postgres connection used by Wrangler dev |
135
+ | `hyperdrive.cached.id` | `string` | — | Second Hyperdrive config with query caching **on**, bound as `HYPERDRIVE_CACHED` and connecting as the read-only `quickback_reader` role. Required when any resource declares `read: { cache: "hyperdrive" }` — see [Cached public reads](/platform/database/neon#cached-public-reads-a-second-hyperdrive-binding) |
136
+ | `hyperdrive.cached.localConnectionString` | `string` | — | The reader role's local URL for Wrangler dev; required whenever `hyperdrive.localConnectionString` is set |
135
137
  | `pooled` | `boolean` | `true` | Use the pooled Neon connection string (recommended for Workers) |
136
138
  | `usePlurals` | `boolean` | `true` | Auth table names (`users`, `members`, …). **The D1 default is `false`** — a project moving from D1 must set `usePlurals: false` to keep `user`, `member`, … |
137
139
 
@@ -91,6 +91,12 @@ interface ReadConfig {
91
91
  // `firewall` block is used (the common case).
92
92
  firewall?: FirewallConfig;
93
93
 
94
+ // Serve reads through Cloudflare Hyperdrive's query cache (Postgres over
95
+ // Hyperdrive only). Public, tenant-free data: requires
96
+ // `firewall: { exception: true }`, a roles-only access admitting PUBLIC,
97
+ // and the HYPERDRIVE_CACHED binding. See Neon → Cached public reads.
98
+ cache?: "hyperdrive";
99
+
94
100
  // Pagination defaults for collection reads.
95
101
  pageSize?: number; // Default page size (default: 50)
96
102
  maxPageSize?: number; // Hard cap (default: 100)
@@ -103,7 +103,10 @@ and on `.returning()` alike. That's the type-level face of "the server is
103
103
  structurally unable to read it": at rest the column only ever holds a
104
104
  `{ __vaultRef }` marker, and the brand keeps action code from string-processing
105
105
  or hand-forwarding that marker. Sealed values leave the system exclusively
106
- through the `/seal/v1` reveal rails below. (Envelope `.encrypted()` columns are
106
+ through the `/seal/v1` reveal rails below. On D1 the column is emitted as
107
+ Drizzle JSON-mode text (`text(name, { mode: 'json' })`), so the marker is
108
+ stored as JSON and reads back as the `{ __vaultRef, vaultItemId }` object; the
109
+ SQL type stays `TEXT`. (Envelope `.encrypted()` columns are
107
110
  deliberately *not* branded — they type as `string` because the server can
108
111
  decrypt that tier; an action reading one gets `qbenc:` ciphertext.)
109
112
 
@@ -348,6 +348,92 @@ to your concurrency, not your statement count. Raise it later with
348
348
  suspend pays the compute start. Lengthen or disable autosuspend on the
349
349
  production branch.
350
350
 
351
+ ### Cached public reads: a second Hyperdrive binding
352
+
353
+ Hyperdrive's query cache keys on query text and parameters alone and never
354
+ invalidates on write, so it cannot sit under the claims-scoped `HYPERDRIVE`
355
+ binding. It can serve **public, tenant-free** data through a second binding
356
+ whose database role can see nothing else. Opt a resource in with
357
+ `read.cache`:
358
+
359
+ {/* doc-compile: skip — read.cache fails closed without hyperdrive.cached on the project config, which the doc harness's default project does not declare. */}
360
+ ```ts
361
+ // features/venues/venues.ts
362
+ import { q, defineTable } from "@quickback/compiler";
363
+
364
+ export const venues = q.table("venues", {
365
+ id: q.id(),
366
+ name: q.text().required(),
367
+ city: q.text().required(),
368
+ ...q.audit(),
369
+ ...q.softDelete(),
370
+ });
371
+
372
+ export default defineTable(venues, {
373
+ firewall: { exception: true },
374
+ read: {
375
+ access: { roles: ["PUBLIC"] },
376
+ cache: "hyperdrive",
377
+ },
378
+ });
379
+ ```
380
+
381
+ `GET /api/v1/venues`, `GET /api/v1/venues/:id` and its named views then read
382
+ through `HYPERDRIVE_CACHED` as `quickback_reader`, a role the security
383
+ migration creates with one privilege: `SELECT` on the tables that declared
384
+ `read.cache`, each with a `USING (true)` SELECT policy for that role. The
385
+ cache can only ever hold rows that role can read, so cache safety is
386
+ structural, not a property of any query. Everything else (writes, actions,
387
+ every other table) stays on `HYPERDRIVE`.
388
+
389
+ The compiler refuses `read.cache` unless all of these hold:
390
+
391
+ - Postgres over Hyperdrive on the Cloudflare runtime.
392
+ - `hyperdrive.cached: { id }` on the provider config, or
393
+ `bindings.hyperdrive.cached` on every named environment.
394
+ - `firewall: { exception: true }` — no tenant or owner row filter.
395
+ - `read.access` is a roles-only tree that admits `PUBLIC`. Record predicates,
396
+ relationship / permission arms, principals and function-form access are
397
+ rejected.
398
+ - No FK display columns and no `include` on the resource — the reader role
399
+ holds no grant on other tables.
400
+
401
+ Masking still applies per caller after the query. Reads can be stale for up
402
+ to the cached config's `max_age` (default 60 s, `--max-age` to change it;
403
+ `--swr` extends serving-while-revalidating). `Server-Timing` counts these
404
+ statements and the cached connection's open under `stmts` / `cold`.
405
+
406
+ Set it up once per database:
407
+
408
+ ```bash
409
+ # 1. The security migration created quickback_reader NOLOGIN; give it a login.
410
+ psql "$DATABASE_SETUP_URL" -c "ALTER ROLE quickback_reader LOGIN PASSWORD '<reader-password>';"
411
+
412
+ # 2. A second Hyperdrive config, caching ON, as that role.
413
+ npx wrangler hyperdrive create my-app-db-cached \
414
+ --max-age 60 \
415
+ --connection-string="postgresql://quickback_reader:<reader-password>@<endpoint>.<region>.aws.neon.tech/neondb?sslmode=require"
416
+ ```
417
+
418
+ ```ts
419
+ database: defineDatabase("neon", {
420
+ connectionMode: "hyperdrive",
421
+ hyperdrive: {
422
+ id: "<hyperdrive-config-id>",
423
+ cached: { id: "<cached-config-id>" },
424
+ },
425
+ }),
426
+ ```
427
+
428
+ With named environments, declare `bindings.hyperdrive.cached: { id }` on
429
+ every target; the `dev` target also needs
430
+ `cached.localConnectionString` (the reader role's local URL), as does the
431
+ provider-level `hyperdrive.cached` whenever `hyperdrive.localConnectionString`
432
+ is set — `wrangler dev` connects the cached binding as `quickback_reader`,
433
+ and the `quickback` role's URL reads nothing through it. The emitted
434
+ `createCachedDb(env)` is read-only by construction: a write or a
435
+ `db.transaction()` on it throws before reaching the database.
436
+
351
437
  For local `wrangler dev` without named environments, set
352
438
  `providers.database.config.hyperdrive.localConnectionString` to a local or
353
439
  development-only Postgres URL. With named environments, put it on the target
@@ -206,6 +206,13 @@ project sets neither. The rest of the tuning notes — the session cookie cache
206
206
  and connection limits — are on
207
207
  [Neon → Tuning the Worker for Hyperdrive](/platform/database/neon#tuning-the-worker-for-hyperdrive).
208
208
 
209
+ Public, tenant-free resources can opt into Hyperdrive's query cache with
210
+ `read: { cache: "hyperdrive" }` through a second binding and the read-only
211
+ `quickback_reader` role — see
212
+ [Cached public reads](/platform/database/neon#cached-public-reads-a-second-hyperdrive-binding).
213
+ On PlanetScale the reader's connection username is the role name plus the
214
+ branch id, `quickback_reader.<branch_id>`, like the other roles.
215
+
209
216
  ## What is shared with Neon, and what is not
210
217
 
211
218
  Shared — read the Neon page for the detail, it is the same generated output:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.70.26",
3
+ "version": "0.70.27",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -132,6 +132,8 @@ single Postgres database with no bindings or split mode (see
132
132
  | `connectionMode` | `"auto" \| "http" \| "websocket" \| "hyperdrive"` | `"auto"` | How the generated runtime connects (`hyperdrive` enables interactive Postgres transactions on Workers) |
133
133
  | `hyperdrive.id` | `string` | — | Required Cloudflare Hyperdrive configuration ID when `connectionMode: "hyperdrive"` |
134
134
  | `hyperdrive.localConnectionString` | `string` | — | Optional local-only Postgres connection used by Wrangler dev |
135
+ | `hyperdrive.cached.id` | `string` | — | Second Hyperdrive config with query caching **on**, bound as `HYPERDRIVE_CACHED` and connecting as the read-only `quickback_reader` role. Required when any resource declares `read: { cache: "hyperdrive" }` — see [Cached public reads](/platform/database/neon#cached-public-reads-a-second-hyperdrive-binding) |
136
+ | `hyperdrive.cached.localConnectionString` | `string` | — | The reader role's local URL for Wrangler dev; required whenever `hyperdrive.localConnectionString` is set |
135
137
  | `pooled` | `boolean` | `true` | Use the pooled Neon connection string (recommended for Workers) |
136
138
  | `usePlurals` | `boolean` | `true` | Auth table names (`users`, `members`, …). **The D1 default is `false`** — a project moving from D1 must set `usePlurals: false` to keep `user`, `member`, … |
137
139
 
@@ -91,6 +91,12 @@ interface ReadConfig {
91
91
  // `firewall` block is used (the common case).
92
92
  firewall?: FirewallConfig;
93
93
 
94
+ // Serve reads through Cloudflare Hyperdrive's query cache (Postgres over
95
+ // Hyperdrive only). Public, tenant-free data: requires
96
+ // `firewall: { exception: true }`, a roles-only access admitting PUBLIC,
97
+ // and the HYPERDRIVE_CACHED binding. See Neon → Cached public reads.
98
+ cache?: "hyperdrive";
99
+
94
100
  // Pagination defaults for collection reads.
95
101
  pageSize?: number; // Default page size (default: 50)
96
102
  maxPageSize?: number; // Hard cap (default: 100)
@@ -103,7 +103,10 @@ and on `.returning()` alike. That's the type-level face of "the server is
103
103
  structurally unable to read it": at rest the column only ever holds a
104
104
  `{ __vaultRef }` marker, and the brand keeps action code from string-processing
105
105
  or hand-forwarding that marker. Sealed values leave the system exclusively
106
- through the `/seal/v1` reveal rails below. (Envelope `.encrypted()` columns are
106
+ through the `/seal/v1` reveal rails below. On D1 the column is emitted as
107
+ Drizzle JSON-mode text (`text(name, { mode: 'json' })`), so the marker is
108
+ stored as JSON and reads back as the `{ __vaultRef, vaultItemId }` object; the
109
+ SQL type stays `TEXT`. (Envelope `.encrypted()` columns are
107
110
  deliberately *not* branded — they type as `string` because the server can
108
111
  decrypt that tier; an action reading one gets `qbenc:` ciphertext.)
109
112
 
@@ -348,6 +348,92 @@ to your concurrency, not your statement count. Raise it later with
348
348
  suspend pays the compute start. Lengthen or disable autosuspend on the
349
349
  production branch.
350
350
 
351
+ ### Cached public reads: a second Hyperdrive binding
352
+
353
+ Hyperdrive's query cache keys on query text and parameters alone and never
354
+ invalidates on write, so it cannot sit under the claims-scoped `HYPERDRIVE`
355
+ binding. It can serve **public, tenant-free** data through a second binding
356
+ whose database role can see nothing else. Opt a resource in with
357
+ `read.cache`:
358
+
359
+ {/* doc-compile: skip — read.cache fails closed without hyperdrive.cached on the project config, which the doc harness's default project does not declare. */}
360
+ ```ts
361
+ // features/venues/venues.ts
362
+ import { q, defineTable } from "@quickback/compiler";
363
+
364
+ export const venues = q.table("venues", {
365
+ id: q.id(),
366
+ name: q.text().required(),
367
+ city: q.text().required(),
368
+ ...q.audit(),
369
+ ...q.softDelete(),
370
+ });
371
+
372
+ export default defineTable(venues, {
373
+ firewall: { exception: true },
374
+ read: {
375
+ access: { roles: ["PUBLIC"] },
376
+ cache: "hyperdrive",
377
+ },
378
+ });
379
+ ```
380
+
381
+ `GET /api/v1/venues`, `GET /api/v1/venues/:id` and its named views then read
382
+ through `HYPERDRIVE_CACHED` as `quickback_reader`, a role the security
383
+ migration creates with one privilege: `SELECT` on the tables that declared
384
+ `read.cache`, each with a `USING (true)` SELECT policy for that role. The
385
+ cache can only ever hold rows that role can read, so cache safety is
386
+ structural, not a property of any query. Everything else (writes, actions,
387
+ every other table) stays on `HYPERDRIVE`.
388
+
389
+ The compiler refuses `read.cache` unless all of these hold:
390
+
391
+ - Postgres over Hyperdrive on the Cloudflare runtime.
392
+ - `hyperdrive.cached: { id }` on the provider config, or
393
+ `bindings.hyperdrive.cached` on every named environment.
394
+ - `firewall: { exception: true }` — no tenant or owner row filter.
395
+ - `read.access` is a roles-only tree that admits `PUBLIC`. Record predicates,
396
+ relationship / permission arms, principals and function-form access are
397
+ rejected.
398
+ - No FK display columns and no `include` on the resource — the reader role
399
+ holds no grant on other tables.
400
+
401
+ Masking still applies per caller after the query. Reads can be stale for up
402
+ to the cached config's `max_age` (default 60 s, `--max-age` to change it;
403
+ `--swr` extends serving-while-revalidating). `Server-Timing` counts these
404
+ statements and the cached connection's open under `stmts` / `cold`.
405
+
406
+ Set it up once per database:
407
+
408
+ ```bash
409
+ # 1. The security migration created quickback_reader NOLOGIN; give it a login.
410
+ psql "$DATABASE_SETUP_URL" -c "ALTER ROLE quickback_reader LOGIN PASSWORD '<reader-password>';"
411
+
412
+ # 2. A second Hyperdrive config, caching ON, as that role.
413
+ npx wrangler hyperdrive create my-app-db-cached \
414
+ --max-age 60 \
415
+ --connection-string="postgresql://quickback_reader:<reader-password>@<endpoint>.<region>.aws.neon.tech/neondb?sslmode=require"
416
+ ```
417
+
418
+ ```ts
419
+ database: defineDatabase("neon", {
420
+ connectionMode: "hyperdrive",
421
+ hyperdrive: {
422
+ id: "<hyperdrive-config-id>",
423
+ cached: { id: "<cached-config-id>" },
424
+ },
425
+ }),
426
+ ```
427
+
428
+ With named environments, declare `bindings.hyperdrive.cached: { id }` on
429
+ every target; the `dev` target also needs
430
+ `cached.localConnectionString` (the reader role's local URL), as does the
431
+ provider-level `hyperdrive.cached` whenever `hyperdrive.localConnectionString`
432
+ is set — `wrangler dev` connects the cached binding as `quickback_reader`,
433
+ and the `quickback` role's URL reads nothing through it. The emitted
434
+ `createCachedDb(env)` is read-only by construction: a write or a
435
+ `db.transaction()` on it throws before reaching the database.
436
+
351
437
  For local `wrangler dev` without named environments, set
352
438
  `providers.database.config.hyperdrive.localConnectionString` to a local or
353
439
  development-only Postgres URL. With named environments, put it on the target
@@ -206,6 +206,13 @@ project sets neither. The rest of the tuning notes — the session cookie cache
206
206
  and connection limits — are on
207
207
  [Neon → Tuning the Worker for Hyperdrive](/platform/database/neon#tuning-the-worker-for-hyperdrive).
208
208
 
209
+ Public, tenant-free resources can opt into Hyperdrive's query cache with
210
+ `read: { cache: "hyperdrive" }` through a second binding and the read-only
211
+ `quickback_reader` role — see
212
+ [Cached public reads](/platform/database/neon#cached-public-reads-a-second-hyperdrive-binding).
213
+ On PlanetScale the reader's connection username is the role name plus the
214
+ branch id, `quickback_reader.<branch_id>`, like the other roles.
215
+
209
216
  ## What is shared with Neon, and what is not
210
217
 
211
218
  Shared — read the Neon page for the detail, it is the same generated output: