@quickback-dev/cli 0.50.1 → 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 +26 -0
  34. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +85 -19
  35. package/package.json +1 -1
  36. package/src/skill/docs/changelog.md +26 -0
  37. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +85 -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
@@ -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
@@ -333,12 +339,71 @@ depends on the connection mode, and the response advertises the guarantee via
333
339
  | Mode | `meta.transactional` | Behavior |
334
340
  |------|----------------------|----------|
335
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 |
336
343
  | Neon WebSocket (Node/Bun) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
337
344
 
338
345
  `drizzle-orm/neon-http` throws "No transactions support in neon-http driver" at
339
346
  runtime, so the HTTP path deliberately treats batches like D1 (fail-fast,
340
347
  non-transactional) rather than emitting code that would 500 on every failed
341
- 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
+
342
407
 
343
408
  ## Capability limits (fail closed)
344
409
 
@@ -352,9 +417,10 @@ silently-broken output:
352
417
  provider-aware db acquisition and a Postgres dialect schema.
353
418
  - **Raw `sqliteTable` interop sources** on a Postgres target are rejected — write
354
419
  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).
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.
358
424
 
359
425
  Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.
360
426
 
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.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
@@ -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
@@ -333,12 +339,71 @@ depends on the connection mode, and the response advertises the guarantee via
333
339
  | Mode | `meta.transactional` | Behavior |
334
340
  |------|----------------------|----------|
335
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 |
336
343
  | Neon WebSocket (Node/Bun) | `true` | `db.transaction()` wraps the loop; any failure rolls back every write in the batch |
337
344
 
338
345
  `drizzle-orm/neon-http` throws "No transactions support in neon-http driver" at
339
346
  runtime, so the HTTP path deliberately treats batches like D1 (fail-fast,
340
347
  non-transactional) rather than emitting code that would 500 on every failed
341
- 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
+
342
407
 
343
408
  ## Capability limits (fail closed)
344
409
 
@@ -352,9 +417,10 @@ silently-broken output:
352
417
  provider-aware db acquisition and a Postgres dialect schema.
353
418
  - **Raw `sqliteTable` interop sources** on a Postgres target are rejected — write
354
419
  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).
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.
358
424
 
359
425
  Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.
360
426