@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.
Files changed (83) hide show
  1. package/dist/commands/build.d.ts +0 -1
  2. package/dist/commands/build.d.ts.map +1 -1
  3. package/dist/commands/build.js +11 -2
  4. package/dist/commands/build.js.map +1 -1
  5. package/dist/commands/build.test.js +53 -2
  6. package/dist/commands/build.test.js.map +1 -1
  7. package/dist/commands/canary.d.ts +17 -5
  8. package/dist/commands/canary.d.ts.map +1 -1
  9. package/dist/commands/canary.js +34 -24
  10. package/dist/commands/canary.js.map +1 -1
  11. package/dist/commands/canary.test.d.ts +2 -0
  12. package/dist/commands/canary.test.d.ts.map +1 -0
  13. package/dist/commands/canary.test.js +100 -0
  14. package/dist/commands/canary.test.js.map +1 -0
  15. package/dist/commands/deploy.d.ts +14 -1
  16. package/dist/commands/deploy.d.ts.map +1 -1
  17. package/dist/commands/deploy.js +49 -19
  18. package/dist/commands/deploy.js.map +1 -1
  19. package/dist/commands/deploy.test.d.ts +2 -0
  20. package/dist/commands/deploy.test.d.ts.map +1 -0
  21. package/dist/commands/deploy.test.js +139 -0
  22. package/dist/commands/deploy.test.js.map +1 -0
  23. package/dist/index.js +3 -3
  24. package/dist/lib/compile-next-steps.d.ts.map +1 -1
  25. package/dist/lib/compile-next-steps.js +12 -5
  26. package/dist/lib/compile-next-steps.js.map +1 -1
  27. package/dist/lib/deployment-target.d.ts +29 -0
  28. package/dist/lib/deployment-target.d.ts.map +1 -0
  29. package/dist/lib/deployment-target.js +46 -0
  30. package/dist/lib/deployment-target.js.map +1 -0
  31. package/dist/lib/deployment-target.test.d.ts +2 -0
  32. package/dist/lib/deployment-target.test.d.ts.map +1 -0
  33. package/dist/lib/deployment-target.test.js +27 -0
  34. package/dist/lib/deployment-target.test.js.map +1 -0
  35. package/dist/lib/file-writer.d.ts +1 -1
  36. package/dist/lib/file-writer.d.ts.map +1 -1
  37. package/dist/lib/file-writer.js +2 -3
  38. package/dist/lib/file-writer.js.map +1 -1
  39. package/dist/lib/neon-canary.d.ts +4 -0
  40. package/dist/lib/neon-canary.d.ts.map +1 -1
  41. package/dist/lib/neon-canary.js +24 -4
  42. package/dist/lib/neon-canary.js.map +1 -1
  43. package/dist/lib/neon-canary.test.js +39 -3
  44. package/dist/lib/neon-canary.test.js.map +1 -1
  45. package/dist/lib/neon-target.d.ts +5 -48
  46. package/dist/lib/neon-target.d.ts.map +1 -1
  47. package/dist/lib/neon-target.js +18 -42
  48. package/dist/lib/neon-target.js.map +1 -1
  49. package/dist/lib/neon-target.test.js +26 -4
  50. package/dist/lib/neon-target.test.js.map +1 -1
  51. package/dist/lib/shell.d.ts +10 -0
  52. package/dist/lib/shell.d.ts.map +1 -1
  53. package/dist/lib/shell.js +20 -0
  54. package/dist/lib/shell.js.map +1 -1
  55. package/dist/lib/shell.test.js +35 -1
  56. package/dist/lib/shell.test.js.map +1 -1
  57. package/dist/lib/wrangler-resources.d.ts +1 -1
  58. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  59. package/dist/lib/wrangler-resources.js +20 -9
  60. package/dist/lib/wrangler-resources.js.map +1 -1
  61. package/dist/lib/wrangler-resources.test.js +20 -0
  62. package/dist/lib/wrangler-resources.test.js.map +1 -1
  63. package/dist/schema-engine/index.js +3 -0
  64. package/dist/schema-engine/index.js.map +2 -2
  65. package/dist/schema-engine/provider-dialects.d.ts +1 -1
  66. package/dist/schema-engine/provider-dialects.d.ts.map +1 -1
  67. package/dist/skill/docs/configure/providers.md +18 -3
  68. package/dist/skill/docs/define/actions/scoped-db.md +88 -41
  69. package/dist/skill/docs/platform/database/d1.md +2 -2
  70. package/dist/skill/docs/platform/database/index.md +7 -2
  71. package/dist/skill/docs/platform/database/neon.md +283 -57
  72. package/dist/skill/docs/platform/database/planetscale-postgres.md +205 -0
  73. package/dist/skill/docs/start/deploy.md +30 -0
  74. package/dist/skill/docs/tooling/cli.md +41 -0
  75. package/package.json +1 -1
  76. package/src/skill/docs/configure/providers.md +18 -3
  77. package/src/skill/docs/define/actions/scoped-db.md +88 -41
  78. package/src/skill/docs/platform/database/d1.md +2 -2
  79. package/src/skill/docs/platform/database/index.md +7 -2
  80. package/src/skill/docs/platform/database/neon.md +283 -57
  81. package/src/skill/docs/platform/database/planetscale-postgres.md +205 -0
  82. package/src/skill/docs/start/deploy.md +30 -0
  83. 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
- Quickback emits RLS policies from your `firewall` and `access` config. Neon's
485
- policies read the transaction-local claims described above via `auth.user_id()`
486
- and the `get_active_org_id()` / `has_any_role()` helpers.
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 "documents_select" ON documents FOR SELECT
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 (public.is_admin() OR user_id = auth.user_id())
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
- Every feature table also gets a restrictive `deny_anon` policy (blocks queries
503
- with neither a stamped user id nor a delegated principal) and a `service_role`
504
- policy (admits Worker-internal contexts — see
505
- [Background jobs and cross-tenant actions](#background-jobs-and-cross-tenant-actions)).
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` emits operation-specific, RLS-only policies for
538
- authored actions and support tables. It does not mount generic routes or
539
- OpenAPI operations. Every authorization path must include at least one
540
- SQL-lowerable record equality; any unbounded OR arm or principal/role-only leaf
541
- fails compilation. This lets an organization account lane and a disjoint
542
- event/person delegated lane share a table without weakening either:
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
- or: [
548
- {
549
- roles: ["AUTHENTICATED"],
550
- record: { organizationId: { equals: "$ctx.activeOrgId" } },
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
- Postgres combines the record comparisons inside each arm with AND. Restrictive
565
- per-operation principal fences also cap every permissive policy, so a public,
566
- firewall-exception, or old permissive policy cannot admit the wrong principal
567
- type. The action still owns all application behavior; these policies only
568
- constrain which rows its caller-scoped `db` or transaction may touch.
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 "projects_select" ON projects FOR SELECT
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 "preferences_select" ON preferences FOR SELECT
583
- USING (user_id = auth.user_id());
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
- **Public tables:**
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 "categories_deny_anon" ON categories FOR ALL TO anon USING (false);
590
- CREATE POLICY "categories_all" ON categories FOR ALL TO authenticated USING (true) WITH CHECK (true);
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
- | `has_any_role(roles[])` | Checks if the user has any specified role in the request org |
601
- | `has_org_role(role)` | Checks for a single specific role |
602
- | `is_org_member()` | Checks org membership in the request org |
603
- | `is_owner(owner_id)` | Checks record ownership against `auth.user_id()` |
604
- | `is_admin()` | Checks the `auth.admins` table (admin mode) |
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 the `profiles_*`
616
- policies) and, when admin/sysadmin helpers are emitted, an `admins` table (read
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, locked to service-role only).
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 Quickback emits a restrictive update fence for every table.
851
- > A principal with `databaseAccess.select` but no matching
852
- > `databaseAccess.update` can read an eligible row, but cannot lock it with
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
- > declare a narrowly bounded `databaseAccess.update` rule for that principal;
859
- > do not broaden or bypass the generated principal fence.
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 is force-disabled**: its cache keys on query text,
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. Requesting an
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`