@quickback-dev/cli 0.66.7 → 0.66.9
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/build.d.ts +0 -1
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +11 -2
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/build.test.js +53 -2
- package/dist/commands/build.test.js.map +1 -1
- package/dist/commands/canary.d.ts +17 -5
- package/dist/commands/canary.d.ts.map +1 -1
- package/dist/commands/canary.js +34 -24
- package/dist/commands/canary.js.map +1 -1
- package/dist/commands/canary.test.d.ts +2 -0
- package/dist/commands/canary.test.d.ts.map +1 -0
- package/dist/commands/canary.test.js +100 -0
- package/dist/commands/canary.test.js.map +1 -0
- package/dist/commands/deploy.d.ts +14 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +49 -19
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/deploy.test.d.ts +2 -0
- package/dist/commands/deploy.test.d.ts.map +1 -0
- package/dist/commands/deploy.test.js +139 -0
- package/dist/commands/deploy.test.js.map +1 -0
- package/dist/index.js +3 -3
- package/dist/lib/compile-next-steps.d.ts.map +1 -1
- package/dist/lib/compile-next-steps.js +12 -5
- package/dist/lib/compile-next-steps.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +29 -0
- package/dist/lib/deployment-target.d.ts.map +1 -0
- package/dist/lib/deployment-target.js +46 -0
- package/dist/lib/deployment-target.js.map +1 -0
- package/dist/lib/deployment-target.test.d.ts +2 -0
- package/dist/lib/deployment-target.test.d.ts.map +1 -0
- package/dist/lib/deployment-target.test.js +27 -0
- package/dist/lib/deployment-target.test.js.map +1 -0
- package/dist/lib/file-writer.d.ts +1 -1
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +2 -3
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/neon-canary.d.ts +4 -0
- package/dist/lib/neon-canary.d.ts.map +1 -1
- package/dist/lib/neon-canary.js +24 -4
- package/dist/lib/neon-canary.js.map +1 -1
- package/dist/lib/neon-canary.test.js +39 -3
- package/dist/lib/neon-canary.test.js.map +1 -1
- package/dist/lib/neon-target.d.ts +5 -48
- package/dist/lib/neon-target.d.ts.map +1 -1
- package/dist/lib/neon-target.js +18 -42
- package/dist/lib/neon-target.js.map +1 -1
- package/dist/lib/neon-target.test.js +26 -4
- package/dist/lib/neon-target.test.js.map +1 -1
- package/dist/lib/shell.d.ts +10 -0
- package/dist/lib/shell.d.ts.map +1 -1
- package/dist/lib/shell.js +20 -0
- package/dist/lib/shell.js.map +1 -1
- package/dist/lib/shell.test.js +35 -1
- package/dist/lib/shell.test.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +1 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +20 -9
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/lib/wrangler-resources.test.js +20 -0
- package/dist/lib/wrangler-resources.test.js.map +1 -1
- package/dist/schema-engine/index.js +3 -0
- package/dist/schema-engine/index.js.map +2 -2
- package/dist/schema-engine/provider-dialects.d.ts +1 -1
- package/dist/schema-engine/provider-dialects.d.ts.map +1 -1
- package/dist/skill/docs/configure/providers.md +18 -3
- package/dist/skill/docs/define/actions/scoped-db.md +88 -41
- package/dist/skill/docs/platform/database/d1.md +2 -2
- package/dist/skill/docs/platform/database/index.md +7 -2
- package/dist/skill/docs/platform/database/neon.md +283 -57
- package/dist/skill/docs/platform/database/planetscale-postgres.md +205 -0
- package/dist/skill/docs/start/deploy.md +30 -0
- package/dist/skill/docs/tooling/cli.md +41 -0
- package/package.json +1 -1
- package/src/skill/docs/configure/providers.md +18 -3
- package/src/skill/docs/define/actions/scoped-db.md +88 -41
- package/src/skill/docs/platform/database/d1.md +2 -2
- package/src/skill/docs/platform/database/index.md +7 -2
- package/src/skill/docs/platform/database/neon.md +283 -57
- package/src/skill/docs/platform/database/planetscale-postgres.md +205 -0
- package/src/skill/docs/start/deploy.md +30 -0
- package/src/skill/docs/tooling/cli.md +41 -0
|
@@ -390,6 +390,46 @@ commands with their current definitions. An existing project whose `build`
|
|
|
390
390
|
script still runs `auth:schema` therefore converges to the TypeScript-only
|
|
391
391
|
build, while unrelated custom scripts remain intact.
|
|
392
392
|
|
|
393
|
+
### Better Auth's tables stay vanilla Better Auth
|
|
394
|
+
|
|
395
|
+
Better Auth's own API is the authorization gate for its tables. Quickback does
|
|
396
|
+
not reimplement that gate in SQL — no policy re-derives membership, checks a
|
|
397
|
+
role, or splits by verb. What the compiler adds is the same **backstop** every
|
|
398
|
+
feature table gets, so a leaked `DATABASE_URL` or a mis-scoped handle cannot
|
|
399
|
+
read another user's or another organization's auth rows:
|
|
400
|
+
|
|
401
|
+
| Policy | Kind | On which tables |
|
|
402
|
+
|--------|------|-----------------|
|
|
403
|
+
| `<table>_deny_anon` | RESTRICTIVE `FOR ALL` | Every managed table |
|
|
404
|
+
| `quickback_service_role_all` | permissive `FOR ALL` | Every table in the `auth` schema, created by the role bootstrap |
|
|
405
|
+
| `<table>_scope` | permissive **`FOR SELECT`** | Only tables with a caller-readable scope column |
|
|
406
|
+
|
|
407
|
+
**Reads are tenant/self scoped; writes go through Better Auth only.** The scope
|
|
408
|
+
policy is `FOR SELECT` with a `USING` clause and no `WITH CHECK`, so the caller
|
|
409
|
+
lane can read these rows and change none of them — a handle cannot set its own
|
|
410
|
+
`member.role`. Better Auth's adapter always stamps the service marker, so every
|
|
411
|
+
write it makes runs on the service lane. The predicate:
|
|
412
|
+
|
|
413
|
+
| Table | Scope |
|
|
414
|
+
|-------|-------|
|
|
415
|
+
| `user` | `id = auth.user_id()` |
|
|
416
|
+
| `session`, `account`, `passkey` | `user_id = auth.user_id()` |
|
|
417
|
+
| `apikey` | `reference_id = auth.user_id()` — Better Auth's apikey table has no `user_id` |
|
|
418
|
+
| `organization` | `id = public.get_active_org_id()` |
|
|
419
|
+
| `member`, `invitation`, `team` | `organization_id = public.get_active_org_id()` |
|
|
420
|
+
| `team_member` | `team_id = public.get_active_team_id()` |
|
|
421
|
+
|
|
422
|
+
Everything else is **service-only** — deny-anon plus the bootstrap lane is the
|
|
423
|
+
entire policy set, and no caller-scoped handle can read a row either: `verification`,
|
|
424
|
+
`jwks`, the Better Auth rate-limit counters, `device_code`, the
|
|
425
|
+
`oauth_*` provider tables and the `agent_*` / `approval_request` agent-auth
|
|
426
|
+
tables. Better Auth's own adapter always stamps the service marker, so its
|
|
427
|
+
reads and writes never consult any of this; the policies exist for the handles
|
|
428
|
+
that are *not* Better Auth.
|
|
429
|
+
|
|
430
|
+
A table with no obvious scope column is service-only by construction. The
|
|
431
|
+
compiler will not invent a predicate for one — it fails closed.
|
|
432
|
+
|
|
393
433
|
## Migrations
|
|
394
434
|
|
|
395
435
|
Neon uses PostgreSQL migrations, distinct from D1's SQLite migrations. One
|
|
@@ -481,9 +521,24 @@ role authority.
|
|
|
481
521
|
|
|
482
522
|
## Row Level Security
|
|
483
523
|
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
524
|
+
Generated RLS is a **backstop, not a second copy of `access`**. Every database
|
|
525
|
+
call goes through the API, and the API owns roles, status, transitions and
|
|
526
|
+
masking. RLS exists so that a bug in a custom route, or a handle that escaped
|
|
527
|
+
its scope, cannot cross a tenant, resurrect a soft-deleted row, or read another
|
|
528
|
+
owner's row. It is the floor under the application, not a second application.
|
|
529
|
+
|
|
530
|
+
Quickback lowers your `firewall` config — and only your `firewall` config —
|
|
531
|
+
into policies that read the transaction-local claims described above through
|
|
532
|
+
`auth.user_id()`, `get_active_org_id()`, `get_active_team_id()`, `get_scope()`
|
|
533
|
+
and the `get_principal_*()` helpers. Each feature table gets exactly four
|
|
534
|
+
policies:
|
|
535
|
+
|
|
536
|
+
| Policy | Kind | What it does |
|
|
537
|
+
|--------|------|--------------|
|
|
538
|
+
| `<table>_deny_anon` | RESTRICTIVE `FOR ALL` | Blocks any query carrying neither a stamped user id, nor a verified delegated/scope principal, nor the service marker |
|
|
539
|
+
| `<table>_service_role` | permissive `FOR ALL` | Admits Worker-internal contexts — see [Background jobs and cross-tenant actions](#background-jobs-and-cross-tenant-actions) |
|
|
540
|
+
| `<table>_principal_fence` | RESTRICTIVE `FOR ALL` | Caps every permissive policy, so no policy can broaden a request that carries the wrong principal type |
|
|
541
|
+
| `<table>_scope` | permissive `FOR ALL` | The firewall scope predicate. `USING` also requires `deleted_at IS NULL` on soft-deletable tables; `WITH CHECK` is the scope predicate alone, so a row can be soft-deleted but never resurrected |
|
|
487
542
|
|
|
488
543
|
```typescript
|
|
489
544
|
firewall: [
|
|
@@ -492,17 +547,86 @@ firewall: [
|
|
|
492
547
|
```
|
|
493
548
|
|
|
494
549
|
```sql
|
|
495
|
-
CREATE POLICY "
|
|
550
|
+
CREATE POLICY "documents_scope"
|
|
551
|
+
ON "app"."documents" FOR ALL
|
|
552
|
+
TO quickback
|
|
496
553
|
USING (
|
|
497
554
|
organization_id = public.get_active_org_id()
|
|
498
|
-
AND
|
|
555
|
+
AND deleted_at IS NULL
|
|
556
|
+
)
|
|
557
|
+
WITH CHECK (
|
|
558
|
+
organization_id = public.get_active_org_id()
|
|
499
559
|
);
|
|
500
560
|
```
|
|
501
561
|
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
562
|
+
Exception tables (`firewall: [{ exception: true }]`) keep their permissive
|
|
563
|
+
`<table>_all` policy, and SYSTEM tables — idempotency keys, the webhook store,
|
|
564
|
+
Better Auth rate-limit counters, subscriptions, file metadata — stay
|
|
565
|
+
service-role only.
|
|
566
|
+
|
|
567
|
+
Better Auth's own tables carry the same backstop, in its two- or three-policy
|
|
568
|
+
form: see [Better Auth's tables stay vanilla Better
|
|
569
|
+
Auth](#better-auths-tables-stay-vanilla-better-auth).
|
|
570
|
+
|
|
571
|
+
### What is deliberately not in SQL
|
|
572
|
+
|
|
573
|
+
Roles, status, transitions, masking and per-operation access are **not**
|
|
574
|
+
lowered into policies. That is a decision, not a gap:
|
|
575
|
+
|
|
576
|
+
- **Roles.** `access.roles` names your application's vocabulary. Mirroring it
|
|
577
|
+
into SQL made every role rename append a security migration, and left two
|
|
578
|
+
enforcement points that could disagree — with the SQL copy being the one
|
|
579
|
+
nobody reads. The API is the single gate.
|
|
580
|
+
- **Status and transitions.** A policy sees one row and no request context, so
|
|
581
|
+
it cannot express "an archived invoice may only move to `restored`, by the
|
|
582
|
+
route that logs the transition". A half-expressed rule in SQL is worse than
|
|
583
|
+
no rule in SQL.
|
|
584
|
+
- **Masking.** Masking shapes a response. RLS decides which rows a caller may
|
|
585
|
+
touch, never which columns come back redacted.
|
|
586
|
+
- **Per-operation access.** One `FOR ALL` scope policy is the same fence for
|
|
587
|
+
every verb. Four near-identical policies only made the tenant predicate
|
|
588
|
+
harder to read and easier to get subtly wrong in exactly one of them.
|
|
589
|
+
|
|
590
|
+
The consequence is intentional: at the **SQL layer**, a caller whose
|
|
591
|
+
organization role is `member` can update a same-org row. The route they would
|
|
592
|
+
have to call still refuses them, and anything reaching the database outside a
|
|
593
|
+
generated route holds a caller-scoped handle whose tenant is already fenced.
|
|
594
|
+
|
|
595
|
+
The compiler enforces the shape at compile time. `QB-RLS-SCOPE-POLICY` requires
|
|
596
|
+
all four policies, requires a tenant/owner/scope predicate in the scope policy's
|
|
597
|
+
`USING` clause, and **fails the build if any policy body calls `has_any_role`**.
|
|
598
|
+
Opt out with `compiler.securityContracts.rls.requireScopePolicy: false` —
|
|
599
|
+
`requireCrudPolicies` is the pre-016 name for the same key and is still honoured.
|
|
600
|
+
|
|
601
|
+
### Upgrading an existing database
|
|
602
|
+
|
|
603
|
+
An existing project gets **one appended `quickback_rls` security migration** on
|
|
604
|
+
its next compile. It runs `DROP POLICY IF EXISTS` on the retired names before
|
|
605
|
+
creating the new ones, so the upgrade is append-only: prior migration files keep
|
|
606
|
+
their bytes and their journal hashes, and a second unchanged compile appends
|
|
607
|
+
nothing.
|
|
608
|
+
|
|
609
|
+
Apply it with the **setup-owner credential**, not `quickback_admin`. The
|
|
610
|
+
security migration reissues the helper functions, and PostgreSQL refuses that to
|
|
611
|
+
a role that does not own them (`42501 must be owner of function ...`) — the same
|
|
612
|
+
requirement that already applies to any changed security or bootstrap SQL.
|
|
613
|
+
|
|
614
|
+
The same migration also drops the five helper functions the generated policies
|
|
615
|
+
no longer reference — `has_any_role`, `has_org_role`, `get_user_role`,
|
|
616
|
+
`is_owner` and `is_org_member` — after the policy statements that stop
|
|
617
|
+
referencing them. Membership is proven by the Worker and stamped as the request
|
|
618
|
+
org, so nothing re-derives it in SQL.
|
|
619
|
+
|
|
620
|
+
The retired names include the per-verb auth-table policies
|
|
621
|
+
(`users_select`, `members_insert`, …) that older projects carry. They are
|
|
622
|
+
dropped, so an upgraded database converges on the narrower set rather than
|
|
623
|
+
keeping a wider policy nobody emits any more.
|
|
624
|
+
|
|
625
|
+
One leftover worth knowing: the redundant `idx_<table>_<column>` index the
|
|
626
|
+
compiler used to infer alongside an index your schema already declared is no
|
|
627
|
+
longer emitted, but an append-only security migration does not drop an index an
|
|
628
|
+
older journal created. New databases get one index; existing ones keep the
|
|
629
|
+
duplicate until you drop it yourself.
|
|
506
630
|
|
|
507
631
|
### Delegated principal RLS
|
|
508
632
|
|
|
@@ -534,60 +658,103 @@ database context uses the same resolved union plus separate compiler-internal
|
|
|
534
658
|
cannot appear in an action `AppContext`, and a delegated action context cannot
|
|
535
659
|
carry account/org/team/membership fields.
|
|
536
660
|
|
|
537
|
-
`resource.databaseAccess`
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
661
|
+
`resource.databaseAccess` opens a **delegated-principal lane** at the database:
|
|
662
|
+
RLS only, no generic routes and no OpenAPI operations. It exists because a
|
|
663
|
+
delegated principal has no account identity — no `userId`, no active
|
|
664
|
+
organization, no membership roles — so the table's ordinary firewall predicate
|
|
665
|
+
can never match for it. The lane is the row rule that can: the principal's own
|
|
666
|
+
verified claims, read through `get_principal_claim()`.
|
|
543
667
|
|
|
544
668
|
```typescript
|
|
669
|
+
// The account lane is the FIREWALL. The delegate lane is databaseAccess.
|
|
670
|
+
firewall: [
|
|
671
|
+
{ field: "organizationId", equals: "ctx.activeOrgId" },
|
|
672
|
+
],
|
|
545
673
|
databaseAccess: {
|
|
546
674
|
select: {
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
{
|
|
553
|
-
principals: ["event_delegate"],
|
|
554
|
-
record: {
|
|
555
|
-
eventId: { equals: "$ctx.principal.claims.eventId" },
|
|
556
|
-
personId: { equals: "$ctx.principal.claims.personId" },
|
|
557
|
-
},
|
|
558
|
-
},
|
|
559
|
-
],
|
|
675
|
+
principals: ["event_delegate"],
|
|
676
|
+
record: {
|
|
677
|
+
eventId: { equals: "$ctx.principal.claims.eventId" },
|
|
678
|
+
personId: { equals: "$ctx.principal.claims.personId" },
|
|
679
|
+
},
|
|
560
680
|
},
|
|
561
681
|
}
|
|
562
682
|
```
|
|
563
683
|
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
684
|
+
That emits exactly **one** permissive policy on the table:
|
|
685
|
+
|
|
686
|
+
```sql
|
|
687
|
+
CREATE POLICY "attendance_evidence_principal_scope"
|
|
688
|
+
ON "app"."attendance_evidence" FOR SELECT TO quickback
|
|
689
|
+
USING (public.get_principal_type() = 'event_delegate'
|
|
690
|
+
AND "event_id" = public.get_principal_claim('eventId')
|
|
691
|
+
AND "person_id" = public.get_principal_claim('personId'));
|
|
692
|
+
```
|
|
693
|
+
|
|
694
|
+
Several principal types on one table are several OR arms of that same policy,
|
|
695
|
+
never several policies. Postgres ANDs the record comparisons inside each arm.
|
|
696
|
+
|
|
697
|
+
The policy's **command is the lane's declared reach**: `FOR SELECT` with no
|
|
698
|
+
`WITH CHECK` when only `databaseAccess.select` is declared, `FOR ALL` with the
|
|
699
|
+
same predicate as `WITH CHECK` as soon as any of `insert` / `update` / `delete`
|
|
700
|
+
is. Whether a delegate lane may write is a property of the lane, declared once
|
|
701
|
+
by the author, so the database enforces it as the policy's command; WHICH verb
|
|
702
|
+
a caller may reach is still the API's decision.
|
|
703
|
+
|
|
704
|
+
The lane lowers `principals` + `record` and nothing else. Two shapes are
|
|
705
|
+
compile errors, with the same message: **`roles` anywhere** (authored roles are
|
|
706
|
+
enforced by the API and never reach SQL, so a role arm here promised an
|
|
707
|
+
authorization the database did not enforce), and **a `record` equality with no
|
|
708
|
+
`principals` gate** (that is an owner/tenant rule, and those belong in
|
|
709
|
+
`firewall`, the one pillar that lowers to SQL). Every authorization path must
|
|
710
|
+
still carry at least one SQL-lowerable record equality; an unbounded `or` arm
|
|
711
|
+
or a principal-only leaf fails the compile.
|
|
712
|
+
|
|
713
|
+
The policy is **permissive**, and PostgreSQL ORs permissive policies together,
|
|
714
|
+
so `databaseAccess` opens a lane *beside* `<table>_scope` rather than narrowing
|
|
715
|
+
it — that is the point (the delegated caller has no active organization, so the
|
|
716
|
+
tenant predicate can never match), but it means a `databaseAccess` arm is never
|
|
717
|
+
a place to write a restriction. A row that satisfies the arm is reachable even
|
|
718
|
+
when the table firewall would not have matched it, and even when it is
|
|
719
|
+
soft-deleted. Write the restriction in `firewall`; the restrictive
|
|
720
|
+
`<table>_deny_anon` and `<table>_principal_fence` policies are the only arms
|
|
721
|
+
that cap every lane. The fence also means a table admits a principal type only
|
|
722
|
+
where its `access` (or its lane) names that type — a `ctx.principal.claims.*`
|
|
723
|
+
firewall arm on a table whose access names no principal is unreachable.
|
|
724
|
+
|
|
725
|
+
> **Upgrading.** The four per-operation `<table>_database_<op>` policies are
|
|
726
|
+
> retired. One appended `quickback_rls` migration drops them on every table and
|
|
727
|
+
> creates the single `<table>_principal_scope` where a lane is declared —
|
|
728
|
+
> append-only, like every other security migration, so no applied file changes.
|
|
729
|
+
|
|
569
730
|
|
|
570
731
|
### Firewall patterns
|
|
571
732
|
|
|
733
|
+
Every pattern is the same one `FOR ALL` scope policy with a different
|
|
734
|
+
predicate — no per-operation variants, no role arms.
|
|
735
|
+
|
|
572
736
|
**Organization-scoped:**
|
|
573
737
|
|
|
574
738
|
```sql
|
|
575
|
-
CREATE POLICY "
|
|
576
|
-
USING (organization_id = public.get_active_org_id())
|
|
739
|
+
CREATE POLICY "projects_scope" ON "app"."projects" FOR ALL TO quickback
|
|
740
|
+
USING (organization_id = public.get_active_org_id())
|
|
741
|
+
WITH CHECK (organization_id = public.get_active_org_id());
|
|
577
742
|
```
|
|
578
743
|
|
|
579
|
-
**User-scoped
|
|
744
|
+
**User-scoped** (`owner_id`, the auto-firewalled ownership column):
|
|
580
745
|
|
|
581
746
|
```sql
|
|
582
|
-
CREATE POLICY "
|
|
583
|
-
USING (
|
|
747
|
+
CREATE POLICY "preferences_scope" ON "app"."preferences" FOR ALL TO quickback
|
|
748
|
+
USING (owner_id = auth.user_id())
|
|
749
|
+
WITH CHECK (owner_id = auth.user_id());
|
|
584
750
|
```
|
|
585
751
|
|
|
586
|
-
**
|
|
752
|
+
**Exception tables** (`firewall: [{ exception: true }]`) — no scope predicate,
|
|
753
|
+
so the restrictive deny-anon policy is the only fence left:
|
|
587
754
|
|
|
588
755
|
```sql
|
|
589
|
-
CREATE POLICY "
|
|
590
|
-
|
|
756
|
+
CREATE POLICY "categories_all" ON "app"."categories" FOR ALL TO quickback
|
|
757
|
+
USING (true) WITH CHECK (true);
|
|
591
758
|
```
|
|
592
759
|
|
|
593
760
|
### Helper functions
|
|
@@ -597,11 +764,21 @@ CREATE POLICY "categories_all" ON categories FOR ALL TO authenticated USING (tru
|
|
|
597
764
|
| `auth.user_id()` | Reads the verified user id from the transaction-local `request.jwt.claim.sub` setting |
|
|
598
765
|
| `get_active_org_id()` | Reads the request-scoped org from the transaction-local `request.jwt.claim.org_id` setting |
|
|
599
766
|
| `get_active_team_id()` | Reads the request-scoped team from `request.jwt.claim.team_id` (teams mode) |
|
|
600
|
-
| `
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
767
|
+
| `is_admin()` | Checks the `auth.admins` table (admin mode). No scope policy calls it. |
|
|
768
|
+
|
|
769
|
+
There is no role-lookup helper and no membership helper. Roles are the API's
|
|
770
|
+
gate, not SQL's: `QB-RLS-SCOPE-POLICY` fails the build if any policy body calls
|
|
771
|
+
`has_any_role`. Membership is Better Auth's gate: the Worker proves it once and
|
|
772
|
+
stamps the active organization, and policies compare against that stamp.
|
|
773
|
+
|
|
774
|
+
`is_admin()` is no part of that gate either. Enabling the admin plugin does
|
|
775
|
+
**not** widen any scope policy: "admin" is a role, and a scope policy is the
|
|
776
|
+
firewall predicate, full stop. An admin's cross-tenant read goes through the
|
|
777
|
+
API on the service lane — an `unsafe: { crossTenant: true }` action stamps
|
|
778
|
+
`quickback.service_role`, which `<table>_service_role` admits — not by SQL
|
|
779
|
+
re-deriving admin from `auth.admins`. Older databases carry the previous
|
|
780
|
+
`(public.is_admin() OR (…))` form until the new security migration replaces
|
|
781
|
+
those policies; it does, in the same append-only pass.
|
|
605
782
|
|
|
606
783
|
All helpers are TEXT-typed to match Better Auth's prefixed ids (`org_abc123`).
|
|
607
784
|
The request org/team scope is passed by the Worker **per transaction**, not read
|
|
@@ -612,14 +789,27 @@ SQL-side access is revoked immediately. Fail closed.
|
|
|
612
789
|
|
|
613
790
|
The only compiler-owned support tables the RLS layer reads live in
|
|
614
791
|
`src/db/rls-support.schema.ts`: a `profiles` table (populated by the
|
|
615
|
-
`sync_profile_display_name()` trigger and protected by
|
|
616
|
-
|
|
792
|
+
`sync_profile_display_name()` trigger and protected by `profiles_deny_anon`
|
|
793
|
+
plus a self-scoped, read-only `profiles_scope`) and, when admin/sysadmin helpers are
|
|
794
|
+
emitted, an `admins` table (read
|
|
617
795
|
by `is_admin()` / `is_sysadmin()`). Better Auth's own `sessions` table may still
|
|
618
796
|
carry an `active_organization_id`, but Quickback RLS never reads it.
|
|
619
797
|
|
|
620
798
|
RLS coverage includes Better Auth's own tables — including those the compiler
|
|
621
799
|
force-enables (organization, admin, `apikeys`; plus the OAuth/agent table
|
|
622
|
-
families when those surfaces are on,
|
|
800
|
+
families when those surfaces are on, which are service-only). Database-backed
|
|
801
|
+
Better Auth rate-limit counters also receive both `ENABLE` and `FORCE ROW LEVEL
|
|
802
|
+
SECURITY`. Only the internal auth service context can read or change those
|
|
803
|
+
counters; ordinary caller claims grant no access. See [Better Auth's tables
|
|
804
|
+
stay vanilla Better Auth](#better-auths-tables-stay-vanilla-better-auth) for
|
|
805
|
+
the exact policy set per table.
|
|
806
|
+
Cloudflare uses database counters by default. Explicit memory storage or
|
|
807
|
+
inactive rate limiting does not generate policies for a missing counter table.
|
|
808
|
+
|
|
809
|
+
For existing databases, recompile and apply the newly appended security
|
|
810
|
+
migration using the **setup-owner credential**, as required for changed
|
|
811
|
+
security/bootstrap SQL, to protect existing counters. Applied migration files stay unchanged
|
|
812
|
+
and existing counter rows are preserved.
|
|
623
813
|
|
|
624
814
|
## Background jobs and cross-tenant actions
|
|
625
815
|
|
|
@@ -847,16 +1037,17 @@ Hyperdrive owns the shared connection pool.
|
|
|
847
1037
|
|
|
848
1038
|
> Postgres authorizes `SELECT … FOR UPDATE` as both a read and a write: the row
|
|
849
1039
|
> must pass its `SELECT` **and** `UPDATE` policies. This matters for delegated
|
|
850
|
-
> principals because
|
|
851
|
-
>
|
|
852
|
-
>
|
|
1040
|
+
> principals because a lane that declares only `databaseAccess.select` emits a
|
|
1041
|
+
> `FOR SELECT` policy — by design, since read-only is what the author declared.
|
|
1042
|
+
> Such a principal can read an eligible row but cannot lock it with
|
|
853
1043
|
> `.for("update")`.
|
|
854
1044
|
>
|
|
855
1045
|
> Keep read-only eligibility and reference-table lookups as ordinary scoped
|
|
856
1046
|
> selects. Lock the mutable grant, capacity, or redemption row that the action is
|
|
857
|
-
> authorized to update. If an action legitimately must lock another table,
|
|
858
|
-
>
|
|
859
|
-
>
|
|
1047
|
+
> authorized to update. If an action legitimately must lock another table, declare
|
|
1048
|
+
> a narrowly bounded `databaseAccess.update` rule for that principal — which makes
|
|
1049
|
+
> its one lane policy `FOR ALL` with the same predicate as `WITH CHECK`. Do not
|
|
1050
|
+
> broaden the predicate or bypass the generated principal fence.
|
|
860
1051
|
|
|
861
1052
|
|
|
862
1053
|
**Security is preserved, unchanged.** The verified caller claims run as the
|
|
@@ -865,9 +1056,11 @@ first transaction-local statement inside the transaction (the same
|
|
|
865
1056
|
callback and the claims reset at commit/rollback — they never leak across
|
|
866
1057
|
Hyperdrive's connection pool.
|
|
867
1058
|
|
|
868
|
-
> Hyperdrive query **caching
|
|
1059
|
+
> Hyperdrive query **caching must be disabled in the Hyperdrive configuration**: its cache keys on query text,
|
|
869
1060
|
> not the caller's RLS claims, so a cached read would leak across tenants. HTTP
|
|
870
|
-
> response ETags provide caching at the correct post-auth layer.
|
|
1061
|
+
> response ETags provide caching at the correct post-auth layer. The compiler
|
|
1062
|
+
> emits the binding but does not inspect or change the remote caching setting;
|
|
1063
|
+
> `quickback deploy` does not yet verify that setting either. Requesting an
|
|
871
1064
|
> interactive `db.transaction()` under any other `connectionMode` is a fail-closed
|
|
872
1065
|
> compile error.
|
|
873
1066
|
|
|
@@ -940,6 +1133,39 @@ npm run deploy:prod
|
|
|
940
1133
|
> batch write before relying on it.
|
|
941
1134
|
|
|
942
1135
|
|
|
1136
|
+
## Required migration canaries
|
|
1137
|
+
|
|
1138
|
+
```bash
|
|
1139
|
+
quickback canary dev --required
|
|
1140
|
+
quickback canary prod --required --apply
|
|
1141
|
+
```
|
|
1142
|
+
|
|
1143
|
+
Canary takes the logical target key and reads its `branch` from top-level
|
|
1144
|
+
`environments` or legacy `providers.database.environments`. Declaring both
|
|
1145
|
+
placements or naming an unknown target is an error. It only accepts the
|
|
1146
|
+
`neon` provider: another Postgres provider cannot use Neon APIs even when
|
|
1147
|
+
`NEON_API_KEY` and `NEON_PROJECT_ID` are set.
|
|
1148
|
+
|
|
1149
|
+
Set `NEON_API_KEY` and `NEON_PROJECT_ID` (or `neon.projectId`). `--required`
|
|
1150
|
+
fails when credentials or branch mapping are missing; without it, an
|
|
1151
|
+
unconfigured Neon canary deliberately skips. Use `--required` for CI gates.
|
|
1152
|
+
|
|
1153
|
+
Both rehearsal and parent apply request connection strings for the same
|
|
1154
|
+
`neon.database` and `neon.role`. These select the **migration** database and
|
|
1155
|
+
actor; the runtime `quickback` role is not a suitable routine migration actor.
|
|
1156
|
+
The existing defaults remain `neondb` and `neondb_owner`. Set
|
|
1157
|
+
`neon.role: "quickback_admin"` for routine migrations after bootstrap; first
|
|
1158
|
+
bootstrap and security/RLS migrations still require the setup-owner capability
|
|
1159
|
+
described above. Connection strings go to the Drizzle subprocess environment.
|
|
1160
|
+
|
|
1161
|
+
The command fingerprints the entire local `quickback/drizzle/` inventory
|
|
1162
|
+
before rehearsal, rechecks it after rehearsal, and checks again immediately
|
|
1163
|
+
before parent apply. A changed journal, SQL file or other migration-state file
|
|
1164
|
+
aborts parent apply and attempts canary cleanup. Keep migration files unchanged
|
|
1165
|
+
throughout the command; this check does not freeze the working directory while
|
|
1166
|
+
Drizzle runs. Cleanup failure returns a nonzero exit status even after successful
|
|
1167
|
+
verification. `--apply` migrates the parent; it does not deploy the Worker.
|
|
1168
|
+
|
|
943
1169
|
## Generated files
|
|
944
1170
|
|
|
945
1171
|
```
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# PlanetScale Postgres
|
|
2
|
+
|
|
3
|
+
PlanetScale Postgres is the same Postgres target as [Neon](/platform/database/neon),
|
|
4
|
+
on a different host. The compiler emits one Postgres implementation: the same
|
|
5
|
+
schema, the same Better Auth wiring, the same
|
|
6
|
+
[RLS backstop](/platform/database/neon#row-level-security), and the same
|
|
7
|
+
migrations. For identical definitions the generated schema and security
|
|
8
|
+
migrations are byte-identical between the two providers.
|
|
9
|
+
|
|
10
|
+
> **Compiler support; live acceptance pending.** Every gate below is proven
|
|
11
|
+
> locally — compile, generated TypeScript, migration generation and ownership
|
|
12
|
+
> parity. The acceptance run against a real PlanetScale branch (role bootstrap,
|
|
13
|
+
> ownership transfer, restricted runtime queries, transaction rollback) has not
|
|
14
|
+
> been executed yet. Treat this page as the intended runbook rather than a
|
|
15
|
+
> support claim.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
## Configuration
|
|
19
|
+
|
|
20
|
+
```typescript title="quickback/quickback.config.ts"
|
|
21
|
+
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
22
|
+
|
|
23
|
+
export default defineConfig({
|
|
24
|
+
name: "my-app",
|
|
25
|
+
providers: {
|
|
26
|
+
runtime: defineRuntime("cloudflare"),
|
|
27
|
+
database: defineDatabase("planetscale-postgres", {
|
|
28
|
+
connectionMode: "hyperdrive",
|
|
29
|
+
hyperdrive: { id: "ffffffffffffffffffffffffffffffff" },
|
|
30
|
+
}),
|
|
31
|
+
auth: defineAuth("better-auth"),
|
|
32
|
+
},
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Hyperdrive is the only transport. Omitting `connectionMode` resolves to
|
|
37
|
+
`hyperdrive`; `http` and `websocket` are Neon driver modes and are rejected at
|
|
38
|
+
compile time, as is any runtime other than `cloudflare`.
|
|
39
|
+
|
|
40
|
+
`planetscale` — without the suffix — remains the MySQL provider name and is not
|
|
41
|
+
registered. Only `planetscale-postgres` selects this provider.
|
|
42
|
+
|
|
43
|
+
## Roles: three SQL roles, one deployed
|
|
44
|
+
|
|
45
|
+
The first generated migration creates the same three roles it creates on Neon:
|
|
46
|
+
|
|
47
|
+
| SQL role | Purpose | Deployed? |
|
|
48
|
+
|----------|---------|-----------|
|
|
49
|
+
| `quickback_owner` | `NOLOGIN` owner of the `app` and `auth` schemas and their objects | no |
|
|
50
|
+
| `quickback_admin` | routine migration actor — drizzle-kit and Better Auth migrations | no |
|
|
51
|
+
| `quickback` | Cloudflare Worker runtime role, `NOINHERIT NOBYPASSRLS` | **yes, only this one** |
|
|
52
|
+
|
|
53
|
+
They are created `NOLOGIN` because generated SQL cannot choose your passwords.
|
|
54
|
+
Enable login afterwards, and change nothing else:
|
|
55
|
+
|
|
56
|
+
```sql
|
|
57
|
+
ALTER ROLE quickback_admin LOGIN PASSWORD '<strong-admin-password>';
|
|
58
|
+
ALTER ROLE quickback LOGIN PASSWORD '<strong-password>';
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### SQL role vs connection username
|
|
62
|
+
|
|
63
|
+
PlanetScale routes a connection to a branch by a suffix on the username. The
|
|
64
|
+
two names are not interchangeable:
|
|
65
|
+
|
|
66
|
+
| | Value | Where it appears |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| SQL role | `quickback` | `CREATE ROLE`, `GRANT`, `ALTER ROLE`, every policy's `TO` clause |
|
|
69
|
+
| Connection username | `quickback.<branch_id>` | the connection string, and nowhere else |
|
|
70
|
+
|
|
71
|
+
Generated SQL never contains a branch id. If a policy or grant is written
|
|
72
|
+
against `quickback.<branch_id>`, it is wrong.
|
|
73
|
+
|
|
74
|
+
### Setup owner vs migration actor
|
|
75
|
+
|
|
76
|
+
The branch's default `postgres` role is the **setup owner**. It has
|
|
77
|
+
`BYPASSRLS`, so it is exactly the role that must never run application traffic:
|
|
78
|
+
|
|
79
|
+
- **Setup owner (`postgres`)** — runs the role-bootstrap migration once, and
|
|
80
|
+
any later migration that changes ownership or role membership.
|
|
81
|
+
- **Migration actor (`quickback_admin`)** — every routine schema and security
|
|
82
|
+
migration afterwards.
|
|
83
|
+
- **Runtime (`quickback`)** — the Hyperdrive connection string. Nothing else.
|
|
84
|
+
|
|
85
|
+
Cloudflare's generic PlanetScale integration guide suggests granting a driver
|
|
86
|
+
role `pg_read_all_data` and `pg_write_all_data`. Do not grant those to
|
|
87
|
+
`quickback`: they hand the Worker blanket table access in place of the
|
|
88
|
+
generated grants. (Neither bypasses RLS, so this is a least-privilege
|
|
89
|
+
regression rather than an isolation hole — but the generated grants are the
|
|
90
|
+
contract this provider is tested against.)
|
|
91
|
+
|
|
92
|
+
## The Hyperdrive binding
|
|
93
|
+
|
|
94
|
+
Point Hyperdrive at the branch's **direct** host over TLS. Hyperdrive is the
|
|
95
|
+
connection pool; stacking a second vendor pooler in front of it adds a hop and
|
|
96
|
+
another place for session state to be reused.
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npx wrangler hyperdrive create my-app-db \
|
|
100
|
+
--caching-disabled \
|
|
101
|
+
--connection-string="postgres://quickback.<branch_id>:<password>@<host>:5432/<database>?sslmode=verify-full"
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
> `--caching-disabled` is mandatory. Quickback scopes RLS per request by writing
|
|
105
|
+
> the caller's claims into transaction-local settings; a cached result set would
|
|
106
|
+
> be replayed to a different caller, across tenants. Caching happens at the app
|
|
107
|
+
> layer instead.
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
The compiler emits the binding into `wrangler.toml`:
|
|
111
|
+
|
|
112
|
+
```toml
|
|
113
|
+
[[hyperdrive]]
|
|
114
|
+
binding = "HYPERDRIVE"
|
|
115
|
+
id = "ffffffffffffffffffffffffffffffff"
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## No `DATABASE_URL` Worker secret
|
|
119
|
+
|
|
120
|
+
Feature queries and Better Auth both read `env.HYPERDRIVE.connectionString`.
|
|
121
|
+
The Worker holds no database password.
|
|
122
|
+
|
|
123
|
+
Migration credentials are compiler/CI inputs and never Worker secrets:
|
|
124
|
+
drizzle-kit reads `DATABASE_MIGRATION_URL` (falling back to `DATABASE_URL`)
|
|
125
|
+
from `.env`. Copy the generated `.env.planetscale.example` to `.env` and fill
|
|
126
|
+
in the `quickback_admin` connection string.
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
npm run db:migrate # schema + security migrations, as quickback_admin
|
|
130
|
+
npx wrangler deploy
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`quickback deploy` applies D1 migrations only — on any Postgres provider it
|
|
134
|
+
prints a warning and leaves migrations to `npm run db:migrate`.
|
|
135
|
+
|
|
136
|
+
## Named environments
|
|
137
|
+
|
|
138
|
+
Each target owns its own branch, Hyperdrive config and Worker script, exactly
|
|
139
|
+
as on [Neon](/platform/database/neon#named-cloudflare-deployment-environments):
|
|
140
|
+
one `environments.<name>` entry per target, each with its own
|
|
141
|
+
`worker.bindings.hyperdrive.id`, and the local `dev` target additionally
|
|
142
|
+
carrying `localConnectionString`. Since every environment runs the same
|
|
143
|
+
bundle, a target that shares another target's Hyperdrive id shares its
|
|
144
|
+
database — the compiler requires each one to declare its own.
|
|
145
|
+
|
|
146
|
+
## What is shared with Neon, and what is not
|
|
147
|
+
|
|
148
|
+
Shared — read the Neon page for the detail, it is the same generated output:
|
|
149
|
+
|
|
150
|
+
- [Worker-scoped RLS and the claim model](/platform/database/neon#how-worker-scoped-rls-works)
|
|
151
|
+
- [Row Level Security as a backstop](/platform/database/neon#row-level-security)
|
|
152
|
+
- [Better Auth schema generation](/platform/database/neon#better-auth-schema-generation)
|
|
153
|
+
- [Migrations](/platform/database/neon#migrations) and the journaled security migration
|
|
154
|
+
- [Interactive transactions](/platform/database/neon#interactive-transactions),
|
|
155
|
+
webhooks, encryption and background jobs — all available, as on Neon
|
|
156
|
+
Hyperdrive
|
|
157
|
+
|
|
158
|
+
Not shared:
|
|
159
|
+
|
|
160
|
+
- **Control plane.** Branch creation, canaries and the `NEON_*` API path are
|
|
161
|
+
Neon-specific. `quickback canary` refuses a PlanetScale project even when
|
|
162
|
+
`NEON_API_KEY` and `NEON_PROJECT_ID` are set; PlanetScale branch operations
|
|
163
|
+
are manual today.
|
|
164
|
+
- **Setup output.** `.env.planetscale.example` and
|
|
165
|
+
`docs/planetscale-postgres-setup.md` replace their Neon equivalents.
|
|
166
|
+
- **Dependencies.** No `@neondatabase/serverless`; the runtime is
|
|
167
|
+
`postgres` (postgres.js) with `drizzle-orm/postgres-js`.
|
|
168
|
+
|
|
169
|
+
## Capability limits (fail closed)
|
|
170
|
+
|
|
171
|
+
The same gates as Neon, and for the same reason — each is a compile-time error,
|
|
172
|
+
never silently-broken output:
|
|
173
|
+
|
|
174
|
+
| Feature | Status |
|
|
175
|
+
|---------|--------|
|
|
176
|
+
| Managed file storage (`managed: true`) | rejected — the file-metadata store is a D1 database |
|
|
177
|
+
| Better Auth `subscriptions` plugin | rejected — its schema and db acquisition are D1-only |
|
|
178
|
+
| Generated SQL triggers | not emitted on Postgres |
|
|
179
|
+
| `webhooksDatabaseId` / `webhooksDatabaseName` | rejected — D1-only keys; webhook tables live in the `webhooks` schema of the same database |
|
|
180
|
+
| `connectionMode` of `'http'` or `'websocket'` | rejected — no such driver for this provider |
|
|
181
|
+
|
|
182
|
+
## Open questions for live acceptance
|
|
183
|
+
|
|
184
|
+
Recorded from the vendor documentation review (2026-09-06) so the live spike
|
|
185
|
+
settles them rather than a reader discovering them:
|
|
186
|
+
|
|
187
|
+
- **`SET LOCAL ROLE` to a `NOLOGIN` role**, and `GRANT … WITH SET TRUE` — the
|
|
188
|
+
bootstrap grants `quickback_admin` and `quickback` membership in
|
|
189
|
+
`quickback_owner` and relies on assuming it. PlanetScale documents
|
|
190
|
+
`CREATE ROLE` but not membership or role assumption on a managed branch.
|
|
191
|
+
- **Ownership transfer** — `ALTER … OWNER TO quickback_owner` from the branch's
|
|
192
|
+
setup owner to a SQL-created role.
|
|
193
|
+
- **`SECURITY DEFINER` and a pinned `search_path`** on the generated RLS helper
|
|
194
|
+
functions.
|
|
195
|
+
- **`ALTER ROLE … LOGIN PASSWORD`** on a SQL-created role, and whether such a
|
|
196
|
+
role's credentials are manageable outside the console.
|
|
197
|
+
|
|
198
|
+
If any of these does not hold, it is a blocker to report — not something to
|
|
199
|
+
work around by relaxing the runtime role.
|
|
200
|
+
|
|
201
|
+
## See also
|
|
202
|
+
|
|
203
|
+
- [Neon](/platform/database/neon) — the same Postgres implementation, in full detail
|
|
204
|
+
- [Cloudflare D1](/platform/database/d1) — the SQLite alternative
|
|
205
|
+
- [Database providers](/configure/providers) — configuring `providers.database`
|