@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.
- 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 +47 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +177 -19
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +47 -0
- 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
|
|
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
|
|
@@ -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`
|
|
356
|
-
encrypted/sealed columns
|
|
357
|
-
|
|
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.
|
|
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
|
|
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
|
|
@@ -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`
|
|
356
|
-
encrypted/sealed columns
|
|
357
|
-
|
|
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
|
|