@quickback-dev/cli 0.50.0 → 0.50.2

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 +35 -0
  34. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +97 -19
  35. package/package.json +1 -1
  36. package/src/skill/docs/changelog.md +35 -0
  37. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +97 -19
@@ -2,6 +2,32 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Neon interactive transactions via Hyperdrive
6
+
7
+ A Neon project can now opt into `connectionMode: 'hyperdrive'` to run its feature
8
+ database over a Cloudflare Hyperdrive binding (`postgres.js` /
9
+ `drizzle-orm/postgres-js`), unlocking **real interactive transactions** in
10
+ generated actions: read current state, lock it (`for update`), decide in
11
+ TypeScript, then write dependent rows — committed atomically, rolled back on
12
+ throw. `tx` is fully schema-typed (invalid columns fail `tsc`), the verified RLS
13
+ claims run as the first transaction-local statement inside the transaction (no
14
+ leak across the connection pool), and Hyperdrive query caching is force-disabled
15
+ (ETags cache at the correct post-auth layer). `http` mode stays the lightweight
16
+ batch-only default and is byte-identical; requesting `db.transaction()` outside
17
+ hyperdrive mode is a fail-closed compile error. WebSocket mode is deprecated —
18
+ Hyperdrive supersedes it as the full-capability path. See
19
+ [Interactive transactions](/compiler/targets/hono-api/database/neon#interactive-transactions).
20
+
21
+ ### Neon migration & environment tooling
22
+
23
+ `environments` config maps dev/staging/prod to Neon branches + Cloudflare envs;
24
+ `quickback canary <env>` branches the target DB, applies pending migrations to
25
+ the branch, diffs, and (with `--apply`) promotes — verifying schema changes
26
+ against real state before they touch a live environment. Record-condition
27
+ firewall predicates now lower to Postgres RLS policy arms (enforced twice — app
28
+ layer and database). Opt-in API `contract.version` scaffolding landed (`v1`
29
+ default; `v2` fail-closed pending completion).
30
+
5
31
  ### Neon PostgreSQL reaches deploy parity with D1 (v0.50)
6
32
 
7
33
  A Neon-backed service now compiles, typechecks, migrates, and deploys with the
@@ -43,6 +69,15 @@ first statement of every query batch. RLS reads them through a compiler-defined
43
69
  - **Docs corrected:** the [Neon page](/compiler/targets/hono-api/database/neon)
44
70
  no longer describes Neon Authorize, a `user_sessions` table, or Hyperdrive —
45
71
  none of which the compiler emits.
72
+ - **Migration-journal hardening.** The role bootstrap now grants
73
+ `quickback_admin` everything the pinned Drizzle runner's journal needs —
74
+ database-level `CREATE` (so `CREATE SCHEMA IF NOT EXISTS drizzle` passes even
75
+ as a no-op) plus ownership of the `drizzle` schema and
76
+ `drizzle.__drizzle_migrations` — so routine migrates after the owner-run
77
+ bootstrap need no owner credential. Generated Postgres migrations are also
78
+ post-processed so a referenced composite `UNIQUE` / `PRIMARY KEY` constraint
79
+ always precedes the foreign keys that consume it (an upgrade delta applies
80
+ unedited instead of failing with "no unique constraint matching given keys").
46
81
 
47
82
  ### Realtime identity tags — one send reaches a person on either auth door (v0.49)
48
83
 
@@ -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
@@ -108,6 +114,18 @@ runtime role, the **only** deployed DB role — use its pooled URL for
108
114
  `DATABASE_URL`). The first generated migration bootstraps these roles as
109
115
  NOLOGIN; enable login and set passwords before use. Full walkthrough in the
110
116
  generated `docs/neon-setup.md`.
117
+
118
+ Run the **first** `db:migrate` with your database owner credential (Neon's
119
+ `neondb_owner`) — that bootstrap run also grants `quickback_admin` everything
120
+ the Drizzle journal needs (`CREATE` on the database, plus ownership of the
121
+ `drizzle` schema and `drizzle.__drizzle_migrations`). Routine migrates **after**
122
+ bootstrap — applying new schema deltas — then run entirely as `quickback_admin`
123
+ via `DATABASE_MIGRATION_URL`, no owner credential required. This includes the
124
+ pinned runner's `CREATE SCHEMA IF NOT EXISTS drizzle` preamble, which needs
125
+ database-level `CREATE` even as a no-op and previously forced every migrate
126
+ back onto the owner credential. (A change to the **security/RLS config** appends
127
+ a new `quickback_rls` migration that re-runs the role bootstrap, so re-point
128
+ `DATABASE_MIGRATION_URL` at the owner credential for that one apply.)
111
129
  </Callout>
112
130
 
113
131
  ## Better Auth schema generation
@@ -321,12 +339,71 @@ depends on the connection mode, and the response advertises the guarantee via
321
339
  | Mode | `meta.transactional` | Behavior |
322
340
  |------|----------------------|----------|
323
341
  | 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 |
342
+ | Neon Hyperdrive (Cloudflare) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
324
343
  | Neon WebSocket (Node/Bun) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
325
344
 
326
345
  `drizzle-orm/neon-http` throws "No transactions support in neon-http driver" at
327
346
  runtime, so the HTTP path deliberately treats batches like D1 (fail-fast,
328
347
  non-transactional) rather than emitting code that would 500 on every failed
329
- batch. Honest advertisement over runtime surprises.
348
+ batch. Honest advertisement over runtime surprises. For true atomic batches and
349
+ interactive transactions on Cloudflare, use
350
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions).
351
+
352
+ ## Interactive transactions
353
+
354
+ `connectionMode: 'hyperdrive'` runs the feature database over a Cloudflare
355
+ [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) binding using
356
+ `postgres.js` (`drizzle-orm/postgres-js`), which supports **real interactive
357
+ transactions** — read current state, lock it, decide in TypeScript, then write
358
+ dependent rows, all committed atomically:
359
+
360
+ ```ts
361
+ export default defineAction({
362
+ input: z.object({ registrationId: z.string() }),
363
+ async execute({ db, input }) {
364
+ return db.transaction(async (tx) => { // tx is fully typed
365
+ const reg = await tx.query.registrations.findFirst({
366
+ where: eq(registrations.id, input.registrationId),
367
+ lock: "for update", // row lock held to commit
368
+ });
369
+ if (!reg) throw new ActionError("Not found", "NOT_FOUND", 404); // → rollback
370
+ const [updated] = await tx.update(registrations)
371
+ .set({ status: nextStatus(reg) })
372
+ .where(eq(registrations.id, reg.id))
373
+ .returning();
374
+ await tx.insert(registrationEvents).values({ registrationId: updated.id });
375
+ return updated; // atomic commit
376
+ });
377
+ },
378
+ });
379
+ ```
380
+
381
+ Configure it on the database provider:
382
+
383
+ ```ts
384
+ providers: {
385
+ database: {
386
+ provider: "neon",
387
+ config: { connectionMode: "hyperdrive", hyperdrive: { id: "<binding-id>" } },
388
+ },
389
+ }
390
+ ```
391
+
392
+ The compiler emits the `[[hyperdrive]]` wrangler binding pointing at your Neon
393
+ **direct** connection string.
394
+
395
+ **Security is preserved, unchanged.** The verified caller claims run as the
396
+ first transaction-local statement inside the transaction (the same
397
+ `set_config(..., true)` preamble batches use), so RLS enforces inside the
398
+ callback and the claims reset at commit/rollback — they never leak across
399
+ Hyperdrive's connection pool.
400
+
401
+ > Hyperdrive query **caching is force-disabled**: its cache keys on query text,
402
+ > not the caller's RLS claims, so a cached read would leak across tenants. HTTP
403
+ > response ETags provide caching at the correct post-auth layer. Requesting an
404
+ > interactive `db.transaction()` under any other `connectionMode` is a fail-closed
405
+ > compile error.
406
+
330
407
 
331
408
  ## Capability limits (fail closed)
332
409
 
@@ -340,9 +417,10 @@ silently-broken output:
340
417
  provider-aware db acquisition and a Postgres dialect schema.
341
418
  - **Raw `sqliteTable` interop sources** on a Postgres target are rejected — write
342
419
  child tables with `pgTable` (see [below](#raw-drizzle-interop-tables-must-use-pg-core)).
343
- - **WebSocket mode** rejects webhooks, cross-tenant `unsafe` actions, and
344
- encrypted/sealed columns (see the [connection modes](#connection-modes)
345
- callout).
420
+ - **WebSocket mode** (deprecated) rejects webhooks, cross-tenant `unsafe`
421
+ actions, and encrypted/sealed columns. Use
422
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions) instead — it is the
423
+ full-capability interactive-transaction path and supersedes WebSocket.
346
424
 
347
425
  Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.
348
426
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.50.0",
3
+ "version": "0.50.2",
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,32 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Neon interactive transactions via Hyperdrive
6
+
7
+ A Neon project can now opt into `connectionMode: 'hyperdrive'` to run its feature
8
+ database over a Cloudflare Hyperdrive binding (`postgres.js` /
9
+ `drizzle-orm/postgres-js`), unlocking **real interactive transactions** in
10
+ generated actions: read current state, lock it (`for update`), decide in
11
+ TypeScript, then write dependent rows — committed atomically, rolled back on
12
+ throw. `tx` is fully schema-typed (invalid columns fail `tsc`), the verified RLS
13
+ claims run as the first transaction-local statement inside the transaction (no
14
+ leak across the connection pool), and Hyperdrive query caching is force-disabled
15
+ (ETags cache at the correct post-auth layer). `http` mode stays the lightweight
16
+ batch-only default and is byte-identical; requesting `db.transaction()` outside
17
+ hyperdrive mode is a fail-closed compile error. WebSocket mode is deprecated —
18
+ Hyperdrive supersedes it as the full-capability path. See
19
+ [Interactive transactions](/compiler/targets/hono-api/database/neon#interactive-transactions).
20
+
21
+ ### Neon migration & environment tooling
22
+
23
+ `environments` config maps dev/staging/prod to Neon branches + Cloudflare envs;
24
+ `quickback canary <env>` branches the target DB, applies pending migrations to
25
+ the branch, diffs, and (with `--apply`) promotes — verifying schema changes
26
+ against real state before they touch a live environment. Record-condition
27
+ firewall predicates now lower to Postgres RLS policy arms (enforced twice — app
28
+ layer and database). Opt-in API `contract.version` scaffolding landed (`v1`
29
+ default; `v2` fail-closed pending completion).
30
+
5
31
  ### Neon PostgreSQL reaches deploy parity with D1 (v0.50)
6
32
 
7
33
  A Neon-backed service now compiles, typechecks, migrates, and deploys with the
@@ -43,6 +69,15 @@ first statement of every query batch. RLS reads them through a compiler-defined
43
69
  - **Docs corrected:** the [Neon page](/compiler/targets/hono-api/database/neon)
44
70
  no longer describes Neon Authorize, a `user_sessions` table, or Hyperdrive —
45
71
  none of which the compiler emits.
72
+ - **Migration-journal hardening.** The role bootstrap now grants
73
+ `quickback_admin` everything the pinned Drizzle runner's journal needs —
74
+ database-level `CREATE` (so `CREATE SCHEMA IF NOT EXISTS drizzle` passes even
75
+ as a no-op) plus ownership of the `drizzle` schema and
76
+ `drizzle.__drizzle_migrations` — so routine migrates after the owner-run
77
+ bootstrap need no owner credential. Generated Postgres migrations are also
78
+ post-processed so a referenced composite `UNIQUE` / `PRIMARY KEY` constraint
79
+ always precedes the foreign keys that consume it (an upgrade delta applies
80
+ unedited instead of failing with "no unique constraint matching given keys").
46
81
 
47
82
  ### Realtime identity tags — one send reaches a person on either auth door (v0.49)
48
83
 
@@ -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
@@ -108,6 +114,18 @@ runtime role, the **only** deployed DB role — use its pooled URL for
108
114
  `DATABASE_URL`). The first generated migration bootstraps these roles as
109
115
  NOLOGIN; enable login and set passwords before use. Full walkthrough in the
110
116
  generated `docs/neon-setup.md`.
117
+
118
+ Run the **first** `db:migrate` with your database owner credential (Neon's
119
+ `neondb_owner`) — that bootstrap run also grants `quickback_admin` everything
120
+ the Drizzle journal needs (`CREATE` on the database, plus ownership of the
121
+ `drizzle` schema and `drizzle.__drizzle_migrations`). Routine migrates **after**
122
+ bootstrap — applying new schema deltas — then run entirely as `quickback_admin`
123
+ via `DATABASE_MIGRATION_URL`, no owner credential required. This includes the
124
+ pinned runner's `CREATE SCHEMA IF NOT EXISTS drizzle` preamble, which needs
125
+ database-level `CREATE` even as a no-op and previously forced every migrate
126
+ back onto the owner credential. (A change to the **security/RLS config** appends
127
+ a new `quickback_rls` migration that re-runs the role bootstrap, so re-point
128
+ `DATABASE_MIGRATION_URL` at the owner credential for that one apply.)
111
129
  </Callout>
112
130
 
113
131
  ## Better Auth schema generation
@@ -321,12 +339,71 @@ depends on the connection mode, and the response advertises the guarantee via
321
339
  | Mode | `meta.transactional` | Behavior |
322
340
  |------|----------------------|----------|
323
341
  | 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 |
342
+ | Neon Hyperdrive (Cloudflare) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
324
343
  | Neon WebSocket (Node/Bun) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
325
344
 
326
345
  `drizzle-orm/neon-http` throws "No transactions support in neon-http driver" at
327
346
  runtime, so the HTTP path deliberately treats batches like D1 (fail-fast,
328
347
  non-transactional) rather than emitting code that would 500 on every failed
329
- batch. Honest advertisement over runtime surprises.
348
+ batch. Honest advertisement over runtime surprises. For true atomic batches and
349
+ interactive transactions on Cloudflare, use
350
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions).
351
+
352
+ ## Interactive transactions
353
+
354
+ `connectionMode: 'hyperdrive'` runs the feature database over a Cloudflare
355
+ [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) binding using
356
+ `postgres.js` (`drizzle-orm/postgres-js`), which supports **real interactive
357
+ transactions** — read current state, lock it, decide in TypeScript, then write
358
+ dependent rows, all committed atomically:
359
+
360
+ ```ts
361
+ export default defineAction({
362
+ input: z.object({ registrationId: z.string() }),
363
+ async execute({ db, input }) {
364
+ return db.transaction(async (tx) => { // tx is fully typed
365
+ const reg = await tx.query.registrations.findFirst({
366
+ where: eq(registrations.id, input.registrationId),
367
+ lock: "for update", // row lock held to commit
368
+ });
369
+ if (!reg) throw new ActionError("Not found", "NOT_FOUND", 404); // → rollback
370
+ const [updated] = await tx.update(registrations)
371
+ .set({ status: nextStatus(reg) })
372
+ .where(eq(registrations.id, reg.id))
373
+ .returning();
374
+ await tx.insert(registrationEvents).values({ registrationId: updated.id });
375
+ return updated; // atomic commit
376
+ });
377
+ },
378
+ });
379
+ ```
380
+
381
+ Configure it on the database provider:
382
+
383
+ ```ts
384
+ providers: {
385
+ database: {
386
+ provider: "neon",
387
+ config: { connectionMode: "hyperdrive", hyperdrive: { id: "<binding-id>" } },
388
+ },
389
+ }
390
+ ```
391
+
392
+ The compiler emits the `[[hyperdrive]]` wrangler binding pointing at your Neon
393
+ **direct** connection string.
394
+
395
+ **Security is preserved, unchanged.** The verified caller claims run as the
396
+ first transaction-local statement inside the transaction (the same
397
+ `set_config(..., true)` preamble batches use), so RLS enforces inside the
398
+ callback and the claims reset at commit/rollback — they never leak across
399
+ Hyperdrive's connection pool.
400
+
401
+ > Hyperdrive query **caching is force-disabled**: its cache keys on query text,
402
+ > not the caller's RLS claims, so a cached read would leak across tenants. HTTP
403
+ > response ETags provide caching at the correct post-auth layer. Requesting an
404
+ > interactive `db.transaction()` under any other `connectionMode` is a fail-closed
405
+ > compile error.
406
+
330
407
 
331
408
  ## Capability limits (fail closed)
332
409
 
@@ -340,9 +417,10 @@ silently-broken output:
340
417
  provider-aware db acquisition and a Postgres dialect schema.
341
418
  - **Raw `sqliteTable` interop sources** on a Postgres target are rejected — write
342
419
  child tables with `pgTable` (see [below](#raw-drizzle-interop-tables-must-use-pg-core)).
343
- - **WebSocket mode** rejects webhooks, cross-tenant `unsafe` actions, and
344
- encrypted/sealed columns (see the [connection modes](#connection-modes)
345
- callout).
420
+ - **WebSocket mode** (deprecated) rejects webhooks, cross-tenant `unsafe`
421
+ actions, and encrypted/sealed columns. Use
422
+ [`connectionMode: 'hyperdrive'`](#interactive-transactions) instead — it is the
423
+ full-capability interactive-transaction path and supersedes WebSocket.
346
424
 
347
425
  Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.
348
426