@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.
- package/dist/commands/canary.d.ts +23 -0
- package/dist/commands/canary.d.ts.map +1 -0
- package/dist/commands/canary.js +138 -0
- package/dist/commands/canary.js.map +1 -0
- package/dist/docs/content.js +2 -2
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/neon-canary.d.ts +65 -0
- package/dist/lib/neon-canary.d.ts.map +1 -0
- package/dist/lib/neon-canary.js +113 -0
- package/dist/lib/neon-canary.js.map +1 -0
- package/dist/lib/neon-canary.test.d.ts +2 -0
- package/dist/lib/neon-canary.test.d.ts.map +1 -0
- package/dist/lib/neon-canary.test.js +150 -0
- package/dist/lib/neon-canary.test.js.map +1 -0
- package/dist/lib/neon-target.d.ts +89 -0
- package/dist/lib/neon-target.d.ts.map +1 -0
- package/dist/lib/neon-target.js +68 -0
- package/dist/lib/neon-target.js.map +1 -0
- package/dist/lib/neon-target.test.d.ts +2 -0
- package/dist/lib/neon-target.test.d.ts.map +1 -0
- package/dist/lib/neon-target.test.js +100 -0
- package/dist/lib/neon-target.test.js.map +1 -0
- package/dist/lib/neon.d.ts +152 -0
- package/dist/lib/neon.d.ts.map +1 -0
- package/dist/lib/neon.js +171 -0
- package/dist/lib/neon.js.map +1 -0
- package/dist/lib/neon.test.d.ts +2 -0
- package/dist/lib/neon.test.d.ts.map +1 -0
- package/dist/lib/neon.test.js +154 -0
- package/dist/lib/neon.test.js.map +1 -0
- package/dist/skill/docs/changelog.md +26 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +85 -19
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +26 -0
- 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
|
|
51
|
-
| **
|
|
52
|
-
| **
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
> **
|
|
61
|
-
>
|
|
62
|
-
> `
|
|
63
|
-
>
|
|
64
|
-
> the full
|
|
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`
|
|
356
|
-
encrypted/sealed columns
|
|
357
|
-
|
|
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.
|
|
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
|
|
51
|
-
| **
|
|
52
|
-
| **
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
> **
|
|
61
|
-
>
|
|
62
|
-
> `
|
|
63
|
-
>
|
|
64
|
-
> the full
|
|
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`
|
|
356
|
-
encrypted/sealed columns
|
|
357
|
-
|
|
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
|
|