@quickback-dev/cli 0.50.1 → 0.50.3

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.
Files changed (37) hide show
  1. package/dist/commands/canary.d.ts +23 -0
  2. package/dist/commands/canary.d.ts.map +1 -0
  3. package/dist/commands/canary.js +138 -0
  4. package/dist/commands/canary.js.map +1 -0
  5. package/dist/docs/content.js +2 -2
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +7 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/lib/neon-canary.d.ts +65 -0
  10. package/dist/lib/neon-canary.d.ts.map +1 -0
  11. package/dist/lib/neon-canary.js +113 -0
  12. package/dist/lib/neon-canary.js.map +1 -0
  13. package/dist/lib/neon-canary.test.d.ts +2 -0
  14. package/dist/lib/neon-canary.test.d.ts.map +1 -0
  15. package/dist/lib/neon-canary.test.js +150 -0
  16. package/dist/lib/neon-canary.test.js.map +1 -0
  17. package/dist/lib/neon-target.d.ts +89 -0
  18. package/dist/lib/neon-target.d.ts.map +1 -0
  19. package/dist/lib/neon-target.js +68 -0
  20. package/dist/lib/neon-target.js.map +1 -0
  21. package/dist/lib/neon-target.test.d.ts +2 -0
  22. package/dist/lib/neon-target.test.d.ts.map +1 -0
  23. package/dist/lib/neon-target.test.js +100 -0
  24. package/dist/lib/neon-target.test.js.map +1 -0
  25. package/dist/lib/neon.d.ts +152 -0
  26. package/dist/lib/neon.d.ts.map +1 -0
  27. package/dist/lib/neon.js +171 -0
  28. package/dist/lib/neon.js.map +1 -0
  29. package/dist/lib/neon.test.d.ts +2 -0
  30. package/dist/lib/neon.test.d.ts.map +1 -0
  31. package/dist/lib/neon.test.js +154 -0
  32. package/dist/lib/neon.test.js.map +1 -0
  33. package/dist/skill/docs/changelog.md +47 -0
  34. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +177 -19
  35. package/package.json +1 -1
  36. package/src/skill/docs/changelog.md +47 -0
  37. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +177 -19
@@ -2,6 +2,53 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Neon reads through user-anchored relationships
6
+
7
+ Resources readable via a multi-hop chain anchored on the caller's user id (e.g. a
8
+ conference attendee reaching their own registrations through
9
+ `person_account_links → people → event_people → registrations`) now work on Neon.
10
+ Declare the chain once with the `hops` form on an `authz.relationships` entry and
11
+ reference it from a resource `firewall` via `{ field, via }`. Because the
12
+ correlated multi-hop join reaches across intermediate tables that each `FORCE ROW
13
+ LEVEL SECURITY`, caller-claims RLS would deny such a read to zero rows — so the
14
+ compiler routes **only that resource's read handlers** (collection `GET /`,
15
+ `GET /:id`, and views) through the service-role handle (`createServiceDb`), with
16
+ the compiled app-layer reachability WHERE as the sole row filter. Org/owner/team
17
+ reads are untouched (caller claims + RLS backstop); writes are unchanged. The
18
+ swap is fail-closed — a service-handle read with no firewall WHERE is a compile
19
+ error. The anchor table is required to be caller-read-own on the subject column
20
+ and service-role-write-only (a forgeable link would mint reachability to a
21
+ victim's data); this link-integrity check is target-independent and fails the
22
+ compile on **both** Neon and D1. The same config compiles identically on D1,
23
+ where the app-layer WHERE was already the whole firewall. See
24
+ [Reads through a user-anchored relationship](/compiler/targets/hono-api/database/neon#reads-through-a-user-anchored-relationship).
25
+
26
+ ### Neon interactive transactions via Hyperdrive
27
+
28
+ A Neon project can now opt into `connectionMode: 'hyperdrive'` to run its feature
29
+ database over a Cloudflare Hyperdrive binding (`postgres.js` /
30
+ `drizzle-orm/postgres-js`), unlocking **real interactive transactions** in
31
+ generated actions: read current state, lock it (`for update`), decide in
32
+ TypeScript, then write dependent rows — committed atomically, rolled back on
33
+ throw. `tx` is fully schema-typed (invalid columns fail `tsc`), the verified RLS
34
+ claims run as the first transaction-local statement inside the transaction (no
35
+ leak across the connection pool), and Hyperdrive query caching is force-disabled
36
+ (ETags cache at the correct post-auth layer). `http` mode stays the lightweight
37
+ batch-only default and is byte-identical; requesting `db.transaction()` outside
38
+ hyperdrive mode is a fail-closed compile error. WebSocket mode is deprecated —
39
+ Hyperdrive supersedes it as the full-capability path. See
40
+ [Interactive transactions](/compiler/targets/hono-api/database/neon#interactive-transactions).
41
+
42
+ ### Neon migration & environment tooling
43
+
44
+ `environments` config maps dev/staging/prod to Neon branches + Cloudflare envs;
45
+ `quickback canary <env>` branches the target DB, applies pending migrations to
46
+ the branch, diffs, and (with `--apply`) promotes — verifying schema changes
47
+ against real state before they touch a live environment. Record-condition
48
+ firewall predicates now lower to Postgres RLS policy arms (enforced twice — app
49
+ layer and database). Opt-in API `contract.version` scaffolding landed (`v1`
50
+ default; `v2` fail-closed pending completion).
51
+
5
52
  ### Neon PostgreSQL reaches deploy parity with D1 (v0.50)
6
53
 
7
54
  A Neon-backed service now compiles, typechecks, migrates, and deploys with the
@@ -47,21 +47,27 @@ export default defineConfig({
47
47
 
48
48
  | Mode | Best for | How it works |
49
49
  |------|----------|--------------|
50
- | **HTTP** | Cloudflare Workers, edge functions | Stateless HTTP queries via `@neondatabase/serverless` |
51
- | **WebSocket** | Node.js, Bun | Persistent WebSocket connection (`drizzle-orm/neon-serverless`) |
52
- | **Auto** (default) | Mixed environments | Detects runtime: `http` on `cloudflare`, `websocket` on Node/Bun |
53
-
54
- On the Cloudflare runtime, `auto` resolves to **HTTP** — this is the mode the
55
- rest of this page assumes. The generated Worker uses `@neondatabase/serverless`
56
- over HTTP; there is no Hyperdrive binding.
57
-
58
- > HTTP mode is the fully-featured path. WebSocket mode gets real interactive
59
- > transactions (see [Batch transactions](#batch-transactions)), but it does
60
- > **not** support webhooks, cross-tenant `unsafe` actions, or `.encrypted()` /
61
- > `.sealed()` columns — each of those is a fail-closed compile error under
62
- > `connectionMode: 'websocket'` because the WebSocket db client does not emit the
63
- > service-role handle they depend on. Use HTTP mode (the Cloudflare default) for
64
- > the full capability surface.
50
+ | **HTTP** (default) | Cloudflare Workers — batch writes | Stateless HTTP queries via `@neondatabase/serverless` |
51
+ | **Hyperdrive** | Cloudflare Workers — interactive transactions | `postgres.js` over a Cloudflare Hyperdrive binding (`drizzle-orm/postgres-js`) |
52
+ | **WebSocket** *(deprecated)* | Node.js, Bun | Persistent WebSocket (`drizzle-orm/neon-serverless`) — superseded by Hyperdrive |
53
+ | **Auto** | Mixed environments | Detects runtime: `http` on `cloudflare`, `websocket` on Node/Bun |
54
+
55
+ On the Cloudflare runtime, `auto` resolves to **HTTP** — batch-only, no binding,
56
+ and the mode the rest of this page assumes. Opt a project up to
57
+ `connectionMode: 'hyperdrive'` when its actions need real interactive
58
+ transactions (see [Interactive transactions](#interactive-transactions)).
59
+
60
+ > **HTTP** is the lightweight default: atomic predetermined batches
61
+ > (`db.batch([...])`), no binding. It does **not** support interactive
62
+ > `db.transaction()` — requesting one is a fail-closed compile error.
63
+ >
64
+ > **Hyperdrive** is the full-featured path: everything HTTP does **plus** real
65
+ > interactive transactions, and it keeps webhooks, cross-tenant `unsafe` actions,
66
+ > and `.encrypted()` / `.sealed()` columns.
67
+ >
68
+ > **WebSocket** is deprecated — Hyperdrive supersedes it. The old WebSocket client
69
+ > was unscoped and fail-closed on webhooks / `unsafe` / encryption; new projects
70
+ > that need transactions should use `connectionMode: 'hyperdrive'`.
65
71
 
66
72
 
67
73
  ## Environment variables
@@ -293,6 +299,98 @@ The service-role marker is only ever set by Worker-internal chokepoints
293
299
  input. Unsafe actions keep their mandatory audit contract: cross-tenant writes
294
300
  still land audit events (the `audit` Postgres schema), unchanged from D1.
295
301
 
302
+ ## Reads through a user-anchored relationship
303
+
304
+ Some resources are readable not because you own them or belong to their org, but
305
+ because you are reachable from them through a **chain of tables** anchored on the
306
+ caller's user id. A conference attendee, for example, can read their own
307
+ registrations even though they are not an org member — the grant travels
308
+ `person_account_links.user_id = ctx.userId → people → event_people →
309
+ registrations`.
310
+
311
+ Declare the chain once as an `authz.relationships` entry using the `hops` form
312
+ (each hop names the joined `table`, the column it is joined `on`, and the `prev`
313
+ column on the previous table that points at it). The terminal hop's `table` is
314
+ the **anchor** — the table carrying the caller's user id:
315
+
316
+ ```typescript
317
+ // quickback.config.ts
318
+ authz: {
319
+ relationships: {
320
+ attendeeReachable: {
321
+ from: 'person_account_links', // the anchor table
322
+ subject: { column: 'userId', equals: 'ctx.userId' },
323
+ resource: { column: 'eventPersonId' }, // the column on the resource this constrains
324
+ hops: [
325
+ { table: 'event_people', on: 'id', prev: 'eventPersonId' },
326
+ { table: 'people', on: 'id', prev: 'personId' },
327
+ { table: 'person_account_links', on: 'personId', prev: 'id' },
328
+ ],
329
+ },
330
+ },
331
+ },
332
+ ```
333
+
334
+ A resource opts into the grant by referencing the relationship from its
335
+ `firewall` — typically as one arm of an `any:` group so org members keep their
336
+ own path in:
337
+
338
+ ```typescript
339
+ // features/registrations/registrations.ts
340
+ firewall: [
341
+ {
342
+ any: [
343
+ { field: 'organizationId', equals: 'ctx.activeOrgId' }, // org-member grant
344
+ { field: 'eventPersonId', via: 'attendeeReachable' }, // reachable-attendee grant
345
+ ],
346
+ },
347
+ ],
348
+ ```
349
+
350
+ ### The anchor must be non-forgeable (fail closed on both targets)
351
+
352
+ The reachability chain terminates in `anchor.user_id = ctx.userId`, so whoever
353
+ can **write** an anchor row can mint themselves reachability to a victim's data.
354
+ Quickback therefore refuses to compile a user-anchored multi-hop relationship
355
+ unless the anchor table is:
356
+
357
+ - **caller-read-own on the subject column** — its firewall scopes reads to
358
+ `ctx.userId` (e.g. `firewall: [{ field: 'userId', equals: 'ctx.userId' }]`), and
359
+ - **service-role-write-only** — it exposes no caller-reachable `create` / `update`
360
+ / `delete` endpoint, so the link can only be created by Worker-internal code.
361
+
362
+ This check is **target-independent**: it fires identically on Neon and D1,
363
+ because the reachability join runs in the app layer on both. A forgeable anchor
364
+ is a compile error everywhere, not a Neon-only concern.
365
+
366
+ ### How the read is served
367
+
368
+ On **Neon**, a via-relationship reachability predicate cannot be expressed as an
369
+ RLS policy — the correlated multi-hop join reaches across intermediate tables
370
+ that each `FORCE ROW LEVEL SECURITY`, so caller-claims RLS would deny the attendee
371
+ to *zero* rows before the app-layer WHERE ever runs. Quickback resolves this by
372
+ routing that resource's **read** handlers through the service-role handle
373
+ (`createServiceDb(c.env)`) instead of the caller-claims client. RLS stops denying,
374
+ and the compiled `buildFirewallConditions(...)` reachability WHERE — the exact
375
+ same clause D1 uses — becomes the **sole** row filter.
376
+
377
+ This is the D1 trust model, applied to Neon for exactly these reads: the
378
+ application layer is the firewall, and RLS is a coarse tenant backstop that steps
379
+ aside where it cannot express the grant. It is surgical and fail-closed:
380
+
381
+ - Only the affected resource's reads swap handles. **Org / owner / team reads keep
382
+ caller claims + the RLS backstop** — they resolve to policies RLS *can* express.
383
+ - The swap is gated on a non-empty firewall carrying the reachability predicate;
384
+ a service-handle read with no WHERE is a compile error (it would return every
385
+ tenant's rows). Fail closed.
386
+ - It applies to the **collection `GET /`, `GET /:id`, and views** alike. **Writes
387
+ are unchanged** — creates/updates/deletes keep caller claims and the RLS
388
+ backstop.
389
+
390
+ The **same config compiles identically on D1**, where there is no RLS to bypass:
391
+ the read handlers keep `c.get('db')` and the app-layer reachability WHERE was
392
+ already the whole story.
393
+
296
394
  ## Webhooks on Neon
297
395
 
298
396
  Webhooks are supported on Neon over HTTP. The store (`webhook_events`,
@@ -333,12 +431,71 @@ depends on the connection mode, and the response advertises the guarantee via
333
431
  | Mode | `meta.transactional` | Behavior |
334
432
  |------|----------------------|----------|
335
433
  | Neon HTTP (Cloudflare default) | `false` | Fail-fast per-record loop, no rollback — `drizzle-orm/neon-http` has no interactive transactions, so this matches D1's semantics honestly |
434
+ | Neon Hyperdrive (Cloudflare) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
336
435
  | Neon WebSocket (Node/Bun) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
337
436
 
338
437
  `drizzle-orm/neon-http` throws "No transactions support in neon-http driver" at
339
438
  runtime, so the HTTP path deliberately treats batches like D1 (fail-fast,
340
439
  non-transactional) rather than emitting code that would 500 on every failed
341
- batch. Honest advertisement over runtime surprises.
440
+ batch. Honest advertisement over runtime surprises. For true atomic batches and
441
+ interactive transactions on Cloudflare, use
442
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions).
443
+
444
+ ## Interactive transactions
445
+
446
+ `connectionMode: 'hyperdrive'` runs the feature database over a Cloudflare
447
+ [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) binding using
448
+ `postgres.js` (`drizzle-orm/postgres-js`), which supports **real interactive
449
+ transactions** — read current state, lock it, decide in TypeScript, then write
450
+ dependent rows, all committed atomically:
451
+
452
+ ```ts
453
+ export default defineAction({
454
+ input: z.object({ registrationId: z.string() }),
455
+ async execute({ db, input }) {
456
+ return db.transaction(async (tx) => { // tx is fully typed
457
+ const reg = await tx.query.registrations.findFirst({
458
+ where: eq(registrations.id, input.registrationId),
459
+ lock: "for update", // row lock held to commit
460
+ });
461
+ if (!reg) throw new ActionError("Not found", "NOT_FOUND", 404); // → rollback
462
+ const [updated] = await tx.update(registrations)
463
+ .set({ status: nextStatus(reg) })
464
+ .where(eq(registrations.id, reg.id))
465
+ .returning();
466
+ await tx.insert(registrationEvents).values({ registrationId: updated.id });
467
+ return updated; // atomic commit
468
+ });
469
+ },
470
+ });
471
+ ```
472
+
473
+ Configure it on the database provider:
474
+
475
+ ```ts
476
+ providers: {
477
+ database: {
478
+ provider: "neon",
479
+ config: { connectionMode: "hyperdrive", hyperdrive: { id: "<binding-id>" } },
480
+ },
481
+ }
482
+ ```
483
+
484
+ The compiler emits the `[[hyperdrive]]` wrangler binding pointing at your Neon
485
+ **direct** connection string.
486
+
487
+ **Security is preserved, unchanged.** The verified caller claims run as the
488
+ first transaction-local statement inside the transaction (the same
489
+ `set_config(..., true)` preamble batches use), so RLS enforces inside the
490
+ callback and the claims reset at commit/rollback — they never leak across
491
+ Hyperdrive's connection pool.
492
+
493
+ > Hyperdrive query **caching is force-disabled**: its cache keys on query text,
494
+ > not the caller's RLS claims, so a cached read would leak across tenants. HTTP
495
+ > response ETags provide caching at the correct post-auth layer. Requesting an
496
+ > interactive `db.transaction()` under any other `connectionMode` is a fail-closed
497
+ > compile error.
498
+
342
499
 
343
500
  ## Capability limits (fail closed)
344
501
 
@@ -352,9 +509,10 @@ silently-broken output:
352
509
  provider-aware db acquisition and a Postgres dialect schema.
353
510
  - **Raw `sqliteTable` interop sources** on a Postgres target are rejected — write
354
511
  child tables with `pgTable` (see [below](#raw-drizzle-interop-tables-must-use-pg-core)).
355
- - **WebSocket mode** rejects webhooks, cross-tenant `unsafe` actions, and
356
- encrypted/sealed columns (see the [connection modes](#connection-modes)
357
- callout).
512
+ - **WebSocket mode** (deprecated) rejects webhooks, cross-tenant `unsafe`
513
+ actions, and encrypted/sealed columns. Use
514
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions) instead — it is the
515
+ full-capability interactive-transaction path and supersedes WebSocket.
358
516
 
359
517
  Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.
360
518
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.50.1",
3
+ "version": "0.50.3",
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",
@@ -2,6 +2,53 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Neon reads through user-anchored relationships
6
+
7
+ Resources readable via a multi-hop chain anchored on the caller's user id (e.g. a
8
+ conference attendee reaching their own registrations through
9
+ `person_account_links → people → event_people → registrations`) now work on Neon.
10
+ Declare the chain once with the `hops` form on an `authz.relationships` entry and
11
+ reference it from a resource `firewall` via `{ field, via }`. Because the
12
+ correlated multi-hop join reaches across intermediate tables that each `FORCE ROW
13
+ LEVEL SECURITY`, caller-claims RLS would deny such a read to zero rows — so the
14
+ compiler routes **only that resource's read handlers** (collection `GET /`,
15
+ `GET /:id`, and views) through the service-role handle (`createServiceDb`), with
16
+ the compiled app-layer reachability WHERE as the sole row filter. Org/owner/team
17
+ reads are untouched (caller claims + RLS backstop); writes are unchanged. The
18
+ swap is fail-closed — a service-handle read with no firewall WHERE is a compile
19
+ error. The anchor table is required to be caller-read-own on the subject column
20
+ and service-role-write-only (a forgeable link would mint reachability to a
21
+ victim's data); this link-integrity check is target-independent and fails the
22
+ compile on **both** Neon and D1. The same config compiles identically on D1,
23
+ where the app-layer WHERE was already the whole firewall. See
24
+ [Reads through a user-anchored relationship](/compiler/targets/hono-api/database/neon#reads-through-a-user-anchored-relationship).
25
+
26
+ ### Neon interactive transactions via Hyperdrive
27
+
28
+ A Neon project can now opt into `connectionMode: 'hyperdrive'` to run its feature
29
+ database over a Cloudflare Hyperdrive binding (`postgres.js` /
30
+ `drizzle-orm/postgres-js`), unlocking **real interactive transactions** in
31
+ generated actions: read current state, lock it (`for update`), decide in
32
+ TypeScript, then write dependent rows — committed atomically, rolled back on
33
+ throw. `tx` is fully schema-typed (invalid columns fail `tsc`), the verified RLS
34
+ claims run as the first transaction-local statement inside the transaction (no
35
+ leak across the connection pool), and Hyperdrive query caching is force-disabled
36
+ (ETags cache at the correct post-auth layer). `http` mode stays the lightweight
37
+ batch-only default and is byte-identical; requesting `db.transaction()` outside
38
+ hyperdrive mode is a fail-closed compile error. WebSocket mode is deprecated —
39
+ Hyperdrive supersedes it as the full-capability path. See
40
+ [Interactive transactions](/compiler/targets/hono-api/database/neon#interactive-transactions).
41
+
42
+ ### Neon migration & environment tooling
43
+
44
+ `environments` config maps dev/staging/prod to Neon branches + Cloudflare envs;
45
+ `quickback canary <env>` branches the target DB, applies pending migrations to
46
+ the branch, diffs, and (with `--apply`) promotes — verifying schema changes
47
+ against real state before they touch a live environment. Record-condition
48
+ firewall predicates now lower to Postgres RLS policy arms (enforced twice — app
49
+ layer and database). Opt-in API `contract.version` scaffolding landed (`v1`
50
+ default; `v2` fail-closed pending completion).
51
+
5
52
  ### Neon PostgreSQL reaches deploy parity with D1 (v0.50)
6
53
 
7
54
  A Neon-backed service now compiles, typechecks, migrates, and deploys with the
@@ -47,21 +47,27 @@ export default defineConfig({
47
47
 
48
48
  | Mode | Best for | How it works |
49
49
  |------|----------|--------------|
50
- | **HTTP** | Cloudflare Workers, edge functions | Stateless HTTP queries via `@neondatabase/serverless` |
51
- | **WebSocket** | Node.js, Bun | Persistent WebSocket connection (`drizzle-orm/neon-serverless`) |
52
- | **Auto** (default) | Mixed environments | Detects runtime: `http` on `cloudflare`, `websocket` on Node/Bun |
53
-
54
- On the Cloudflare runtime, `auto` resolves to **HTTP** — this is the mode the
55
- rest of this page assumes. The generated Worker uses `@neondatabase/serverless`
56
- over HTTP; there is no Hyperdrive binding.
57
-
58
- > HTTP mode is the fully-featured path. WebSocket mode gets real interactive
59
- > transactions (see [Batch transactions](#batch-transactions)), but it does
60
- > **not** support webhooks, cross-tenant `unsafe` actions, or `.encrypted()` /
61
- > `.sealed()` columns — each of those is a fail-closed compile error under
62
- > `connectionMode: 'websocket'` because the WebSocket db client does not emit the
63
- > service-role handle they depend on. Use HTTP mode (the Cloudflare default) for
64
- > the full capability surface.
50
+ | **HTTP** (default) | Cloudflare Workers — batch writes | Stateless HTTP queries via `@neondatabase/serverless` |
51
+ | **Hyperdrive** | Cloudflare Workers — interactive transactions | `postgres.js` over a Cloudflare Hyperdrive binding (`drizzle-orm/postgres-js`) |
52
+ | **WebSocket** *(deprecated)* | Node.js, Bun | Persistent WebSocket (`drizzle-orm/neon-serverless`) — superseded by Hyperdrive |
53
+ | **Auto** | Mixed environments | Detects runtime: `http` on `cloudflare`, `websocket` on Node/Bun |
54
+
55
+ On the Cloudflare runtime, `auto` resolves to **HTTP** — batch-only, no binding,
56
+ and the mode the rest of this page assumes. Opt a project up to
57
+ `connectionMode: 'hyperdrive'` when its actions need real interactive
58
+ transactions (see [Interactive transactions](#interactive-transactions)).
59
+
60
+ > **HTTP** is the lightweight default: atomic predetermined batches
61
+ > (`db.batch([...])`), no binding. It does **not** support interactive
62
+ > `db.transaction()` — requesting one is a fail-closed compile error.
63
+ >
64
+ > **Hyperdrive** is the full-featured path: everything HTTP does **plus** real
65
+ > interactive transactions, and it keeps webhooks, cross-tenant `unsafe` actions,
66
+ > and `.encrypted()` / `.sealed()` columns.
67
+ >
68
+ > **WebSocket** is deprecated — Hyperdrive supersedes it. The old WebSocket client
69
+ > was unscoped and fail-closed on webhooks / `unsafe` / encryption; new projects
70
+ > that need transactions should use `connectionMode: 'hyperdrive'`.
65
71
 
66
72
 
67
73
  ## Environment variables
@@ -293,6 +299,98 @@ The service-role marker is only ever set by Worker-internal chokepoints
293
299
  input. Unsafe actions keep their mandatory audit contract: cross-tenant writes
294
300
  still land audit events (the `audit` Postgres schema), unchanged from D1.
295
301
 
302
+ ## Reads through a user-anchored relationship
303
+
304
+ Some resources are readable not because you own them or belong to their org, but
305
+ because you are reachable from them through a **chain of tables** anchored on the
306
+ caller's user id. A conference attendee, for example, can read their own
307
+ registrations even though they are not an org member — the grant travels
308
+ `person_account_links.user_id = ctx.userId → people → event_people →
309
+ registrations`.
310
+
311
+ Declare the chain once as an `authz.relationships` entry using the `hops` form
312
+ (each hop names the joined `table`, the column it is joined `on`, and the `prev`
313
+ column on the previous table that points at it). The terminal hop's `table` is
314
+ the **anchor** — the table carrying the caller's user id:
315
+
316
+ ```typescript
317
+ // quickback.config.ts
318
+ authz: {
319
+ relationships: {
320
+ attendeeReachable: {
321
+ from: 'person_account_links', // the anchor table
322
+ subject: { column: 'userId', equals: 'ctx.userId' },
323
+ resource: { column: 'eventPersonId' }, // the column on the resource this constrains
324
+ hops: [
325
+ { table: 'event_people', on: 'id', prev: 'eventPersonId' },
326
+ { table: 'people', on: 'id', prev: 'personId' },
327
+ { table: 'person_account_links', on: 'personId', prev: 'id' },
328
+ ],
329
+ },
330
+ },
331
+ },
332
+ ```
333
+
334
+ A resource opts into the grant by referencing the relationship from its
335
+ `firewall` — typically as one arm of an `any:` group so org members keep their
336
+ own path in:
337
+
338
+ ```typescript
339
+ // features/registrations/registrations.ts
340
+ firewall: [
341
+ {
342
+ any: [
343
+ { field: 'organizationId', equals: 'ctx.activeOrgId' }, // org-member grant
344
+ { field: 'eventPersonId', via: 'attendeeReachable' }, // reachable-attendee grant
345
+ ],
346
+ },
347
+ ],
348
+ ```
349
+
350
+ ### The anchor must be non-forgeable (fail closed on both targets)
351
+
352
+ The reachability chain terminates in `anchor.user_id = ctx.userId`, so whoever
353
+ can **write** an anchor row can mint themselves reachability to a victim's data.
354
+ Quickback therefore refuses to compile a user-anchored multi-hop relationship
355
+ unless the anchor table is:
356
+
357
+ - **caller-read-own on the subject column** — its firewall scopes reads to
358
+ `ctx.userId` (e.g. `firewall: [{ field: 'userId', equals: 'ctx.userId' }]`), and
359
+ - **service-role-write-only** — it exposes no caller-reachable `create` / `update`
360
+ / `delete` endpoint, so the link can only be created by Worker-internal code.
361
+
362
+ This check is **target-independent**: it fires identically on Neon and D1,
363
+ because the reachability join runs in the app layer on both. A forgeable anchor
364
+ is a compile error everywhere, not a Neon-only concern.
365
+
366
+ ### How the read is served
367
+
368
+ On **Neon**, a via-relationship reachability predicate cannot be expressed as an
369
+ RLS policy — the correlated multi-hop join reaches across intermediate tables
370
+ that each `FORCE ROW LEVEL SECURITY`, so caller-claims RLS would deny the attendee
371
+ to *zero* rows before the app-layer WHERE ever runs. Quickback resolves this by
372
+ routing that resource's **read** handlers through the service-role handle
373
+ (`createServiceDb(c.env)`) instead of the caller-claims client. RLS stops denying,
374
+ and the compiled `buildFirewallConditions(...)` reachability WHERE — the exact
375
+ same clause D1 uses — becomes the **sole** row filter.
376
+
377
+ This is the D1 trust model, applied to Neon for exactly these reads: the
378
+ application layer is the firewall, and RLS is a coarse tenant backstop that steps
379
+ aside where it cannot express the grant. It is surgical and fail-closed:
380
+
381
+ - Only the affected resource's reads swap handles. **Org / owner / team reads keep
382
+ caller claims + the RLS backstop** — they resolve to policies RLS *can* express.
383
+ - The swap is gated on a non-empty firewall carrying the reachability predicate;
384
+ a service-handle read with no WHERE is a compile error (it would return every
385
+ tenant's rows). Fail closed.
386
+ - It applies to the **collection `GET /`, `GET /:id`, and views** alike. **Writes
387
+ are unchanged** — creates/updates/deletes keep caller claims and the RLS
388
+ backstop.
389
+
390
+ The **same config compiles identically on D1**, where there is no RLS to bypass:
391
+ the read handlers keep `c.get('db')` and the app-layer reachability WHERE was
392
+ already the whole story.
393
+
296
394
  ## Webhooks on Neon
297
395
 
298
396
  Webhooks are supported on Neon over HTTP. The store (`webhook_events`,
@@ -333,12 +431,71 @@ depends on the connection mode, and the response advertises the guarantee via
333
431
  | Mode | `meta.transactional` | Behavior |
334
432
  |------|----------------------|----------|
335
433
  | Neon HTTP (Cloudflare default) | `false` | Fail-fast per-record loop, no rollback — `drizzle-orm/neon-http` has no interactive transactions, so this matches D1's semantics honestly |
434
+ | Neon Hyperdrive (Cloudflare) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
336
435
  | Neon WebSocket (Node/Bun) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
337
436
 
338
437
  `drizzle-orm/neon-http` throws "No transactions support in neon-http driver" at
339
438
  runtime, so the HTTP path deliberately treats batches like D1 (fail-fast,
340
439
  non-transactional) rather than emitting code that would 500 on every failed
341
- batch. Honest advertisement over runtime surprises.
440
+ batch. Honest advertisement over runtime surprises. For true atomic batches and
441
+ interactive transactions on Cloudflare, use
442
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions).
443
+
444
+ ## Interactive transactions
445
+
446
+ `connectionMode: 'hyperdrive'` runs the feature database over a Cloudflare
447
+ [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) binding using
448
+ `postgres.js` (`drizzle-orm/postgres-js`), which supports **real interactive
449
+ transactions** — read current state, lock it, decide in TypeScript, then write
450
+ dependent rows, all committed atomically:
451
+
452
+ ```ts
453
+ export default defineAction({
454
+ input: z.object({ registrationId: z.string() }),
455
+ async execute({ db, input }) {
456
+ return db.transaction(async (tx) => { // tx is fully typed
457
+ const reg = await tx.query.registrations.findFirst({
458
+ where: eq(registrations.id, input.registrationId),
459
+ lock: "for update", // row lock held to commit
460
+ });
461
+ if (!reg) throw new ActionError("Not found", "NOT_FOUND", 404); // → rollback
462
+ const [updated] = await tx.update(registrations)
463
+ .set({ status: nextStatus(reg) })
464
+ .where(eq(registrations.id, reg.id))
465
+ .returning();
466
+ await tx.insert(registrationEvents).values({ registrationId: updated.id });
467
+ return updated; // atomic commit
468
+ });
469
+ },
470
+ });
471
+ ```
472
+
473
+ Configure it on the database provider:
474
+
475
+ ```ts
476
+ providers: {
477
+ database: {
478
+ provider: "neon",
479
+ config: { connectionMode: "hyperdrive", hyperdrive: { id: "<binding-id>" } },
480
+ },
481
+ }
482
+ ```
483
+
484
+ The compiler emits the `[[hyperdrive]]` wrangler binding pointing at your Neon
485
+ **direct** connection string.
486
+
487
+ **Security is preserved, unchanged.** The verified caller claims run as the
488
+ first transaction-local statement inside the transaction (the same
489
+ `set_config(..., true)` preamble batches use), so RLS enforces inside the
490
+ callback and the claims reset at commit/rollback — they never leak across
491
+ Hyperdrive's connection pool.
492
+
493
+ > Hyperdrive query **caching is force-disabled**: its cache keys on query text,
494
+ > not the caller's RLS claims, so a cached read would leak across tenants. HTTP
495
+ > response ETags provide caching at the correct post-auth layer. Requesting an
496
+ > interactive `db.transaction()` under any other `connectionMode` is a fail-closed
497
+ > compile error.
498
+
342
499
 
343
500
  ## Capability limits (fail closed)
344
501
 
@@ -352,9 +509,10 @@ silently-broken output:
352
509
  provider-aware db acquisition and a Postgres dialect schema.
353
510
  - **Raw `sqliteTable` interop sources** on a Postgres target are rejected — write
354
511
  child tables with `pgTable` (see [below](#raw-drizzle-interop-tables-must-use-pg-core)).
355
- - **WebSocket mode** rejects webhooks, cross-tenant `unsafe` actions, and
356
- encrypted/sealed columns (see the [connection modes](#connection-modes)
357
- callout).
512
+ - **WebSocket mode** (deprecated) rejects webhooks, cross-tenant `unsafe`
513
+ actions, and encrypted/sealed columns. Use
514
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions) instead — it is the
515
+ full-capability interactive-transaction path and supersedes WebSocket.
358
516
 
359
517
  Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.
360
518