@quickback-dev/cli 0.66.8 → 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 (74) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +11 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/build.test.js +53 -2
  5. package/dist/commands/build.test.js.map +1 -1
  6. package/dist/commands/canary.d.ts +17 -5
  7. package/dist/commands/canary.d.ts.map +1 -1
  8. package/dist/commands/canary.js +34 -24
  9. package/dist/commands/canary.js.map +1 -1
  10. package/dist/commands/canary.test.d.ts +2 -0
  11. package/dist/commands/canary.test.d.ts.map +1 -0
  12. package/dist/commands/canary.test.js +100 -0
  13. package/dist/commands/canary.test.js.map +1 -0
  14. package/dist/commands/deploy.d.ts +14 -1
  15. package/dist/commands/deploy.d.ts.map +1 -1
  16. package/dist/commands/deploy.js +49 -19
  17. package/dist/commands/deploy.js.map +1 -1
  18. package/dist/commands/deploy.test.d.ts +2 -0
  19. package/dist/commands/deploy.test.d.ts.map +1 -0
  20. package/dist/commands/deploy.test.js +139 -0
  21. package/dist/commands/deploy.test.js.map +1 -0
  22. package/dist/index.js +3 -3
  23. package/dist/lib/compile-next-steps.d.ts.map +1 -1
  24. package/dist/lib/compile-next-steps.js +12 -5
  25. package/dist/lib/compile-next-steps.js.map +1 -1
  26. package/dist/lib/deployment-target.d.ts +29 -0
  27. package/dist/lib/deployment-target.d.ts.map +1 -0
  28. package/dist/lib/deployment-target.js +46 -0
  29. package/dist/lib/deployment-target.js.map +1 -0
  30. package/dist/lib/deployment-target.test.d.ts +2 -0
  31. package/dist/lib/deployment-target.test.d.ts.map +1 -0
  32. package/dist/lib/deployment-target.test.js +27 -0
  33. package/dist/lib/deployment-target.test.js.map +1 -0
  34. package/dist/lib/neon-canary.d.ts +4 -0
  35. package/dist/lib/neon-canary.d.ts.map +1 -1
  36. package/dist/lib/neon-canary.js +24 -4
  37. package/dist/lib/neon-canary.js.map +1 -1
  38. package/dist/lib/neon-canary.test.js +39 -3
  39. package/dist/lib/neon-canary.test.js.map +1 -1
  40. package/dist/lib/neon-target.d.ts +5 -48
  41. package/dist/lib/neon-target.d.ts.map +1 -1
  42. package/dist/lib/neon-target.js +18 -42
  43. package/dist/lib/neon-target.js.map +1 -1
  44. package/dist/lib/neon-target.test.js +26 -4
  45. package/dist/lib/neon-target.test.js.map +1 -1
  46. package/dist/lib/shell.d.ts +10 -0
  47. package/dist/lib/shell.d.ts.map +1 -1
  48. package/dist/lib/shell.js +20 -0
  49. package/dist/lib/shell.js.map +1 -1
  50. package/dist/lib/shell.test.js +35 -1
  51. package/dist/lib/shell.test.js.map +1 -1
  52. package/dist/lib/wrangler-resources.d.ts +1 -1
  53. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  54. package/dist/lib/wrangler-resources.js +20 -9
  55. package/dist/lib/wrangler-resources.js.map +1 -1
  56. package/dist/lib/wrangler-resources.test.js +20 -0
  57. package/dist/lib/wrangler-resources.test.js.map +1 -1
  58. package/dist/schema-engine/index.js +3 -0
  59. package/dist/schema-engine/index.js.map +2 -2
  60. package/dist/schema-engine/provider-dialects.d.ts +1 -1
  61. package/dist/schema-engine/provider-dialects.d.ts.map +1 -1
  62. package/dist/skill/docs/configure/providers.md +18 -3
  63. package/dist/skill/docs/platform/database/index.md +7 -2
  64. package/dist/skill/docs/platform/database/neon.md +37 -2
  65. package/dist/skill/docs/platform/database/planetscale-postgres.md +205 -0
  66. package/dist/skill/docs/start/deploy.md +30 -0
  67. package/dist/skill/docs/tooling/cli.md +41 -0
  68. package/package.json +1 -1
  69. package/src/skill/docs/configure/providers.md +18 -3
  70. package/src/skill/docs/platform/database/index.md +7 -2
  71. package/src/skill/docs/platform/database/neon.md +37 -2
  72. package/src/skill/docs/platform/database/planetscale-postgres.md +205 -0
  73. package/src/skill/docs/start/deploy.md +30 -0
  74. package/src/skill/docs/tooling/cli.md +41 -0
@@ -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`
@@ -50,6 +50,7 @@ Run it again any time. When every id is real, there's nothing to create — the
50
50
 
51
51
  | Flag | Effect |
52
52
  |------|--------|
53
+ | `--env <logical-target>` | Select a named target from `environments` (or legacy `providers.database.environments`). Required for named projects. |
53
54
  | `--dry-run` | Print the provisioning plan (what would be created vs. what's already set) and exit. Creates nothing. |
54
55
  | `--skip-deploy` | Provision resources + sync ids + recompile, but skip migrations and the deploy itself. |
55
56
  | `--force` | Overwrite a config id that differs from what Cloudflare reports. Without it, a mismatch prints both values and aborts — never silently overwritten. |
@@ -63,6 +64,35 @@ quickback deploy --dry-run
63
64
  quickback deploy --skip-deploy
64
65
  ```
65
66
 
67
+ ## Named deployment targets
68
+
69
+ ```bash
70
+ quickback deploy --env dev
71
+ quickback deploy --env prod --dry-run
72
+ ```
73
+
74
+ The argument is the **logical config key**. If `dev` declares
75
+ `worker.env: "preview-blue"` and `name: "existing-dev-worker"`, Quickback
76
+ selects `[env.preview-blue]`, migrates only that target's D1 bindings with
77
+ `--env preview-blue`, and uploads that Worker. Top-level bindings are not
78
+ inherited. Both environment placements are supported; declaring both is an
79
+ error. Missing or unknown targets stop before resource creation, migrations,
80
+ or upload.
81
+
82
+ Named targets must already have their D1, KV and Hyperdrive IDs configured in
83
+ their own `worker.bindings`. If an ID is a placeholder, deployment stops before
84
+ provisioning; create that target's resources manually, enter its IDs and run
85
+ `quickback build`. The CLI does not splice named IDs into global provider config.
86
+ R2 buckets declared by the selected target are still ensured by name.
87
+ `--force` does not bypass these checks. `--skip-deploy` skips migrations and
88
+ upload, and `--dry-run` reports without creating resources.
89
+
90
+ Postgres migrations remain a separate operator-owned step, including for named
91
+ Neon targets. `quickback deploy --env dev` selects the Worker but does **not**
92
+ verify that the Hyperdrive origin matches the intended Neon branch, inspect
93
+ remote query caching, or apply Postgres migrations. Configure Hyperdrive with
94
+ query caching disabled and migrate the intended branch before deployment.
95
+
66
96
  ## Conflicting ids
67
97
 
68
98
  If `quickback.config.ts` already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, `quickback deploy` prints both and stops:
@@ -173,6 +173,12 @@ get Postgres declarations; SQLite providers (`cloudflare-d1`,
173
173
  providers are refused with an error rather than written in the wrong
174
174
  dialect; no provider (or an unrecognized one) defaults to SQLite.
175
175
 
176
+ `quickback build` uses the same provider-to-dialect mapping when checking
177
+ managed columns, including with `--fix-schema`. An explicitly configured
178
+ unknown or MySQL provider stops the build before authored schema files are
179
+ changed. Omitting the database provider retains the SQLite default. Dialect
180
+ recognition does not add support for an unregistered database provider.
181
+
176
182
  ### Authored-Source Codemods
177
183
 
178
184
  ```bash
@@ -446,3 +452,38 @@ This can happen if your session token expired or if the API is temporarily unava
446
452
  quickback logout
447
453
  quickback login
448
454
  ```
455
+
456
+ ### Deploy a named target
457
+
458
+ ```bash
459
+ quickback deploy --env dev
460
+ quickback deploy --env prod --dry-run
461
+ ```
462
+
463
+ Named projects require a logical target from top-level `environments` or legacy
464
+ `providers.database.environments`. Quickback maps that key to the configured
465
+ `worker.env` and explicit Worker `name`; the Wrangler environment may differ
466
+ from the logical key. Only selected bindings participate in planning and D1
467
+ migrations. Unknown targets and duplicate placements reject before mutation.
468
+
469
+ Named D1/KV/Hyperdrive placeholder IDs must be provisioned and entered manually
470
+ in the target's `worker.bindings`, followed by `quickback build`. The CLI does
471
+ not overwrite global IDs for named targets. Postgres migrations and remote
472
+ Hyperdrive cache/target verification remain operator-owned. See
473
+ [Deploying](/start/deploy#named-deployment-targets).
474
+
475
+ ### Verify Neon migrations
476
+
477
+ ```bash
478
+ quickback canary dev --required
479
+ quickback canary prod --required --apply
480
+ ```
481
+
482
+ Canary uses the same logical environment mapping. `--required` fails instead
483
+ of skipping if credentials or branch configuration are missing; an unknown
484
+ named target or a non-Neon provider always fails. `--apply` rehearses on a
485
+ branch, then migrates the parent using the same selected database and migration
486
+ role. Local migration inventory changes abort parent apply. See
487
+ [Neon canaries](/platform/database/neon#required-migration-canaries) for role
488
+ selection, inventory-check limits and cleanup behavior. `quickback migrate`
489
+ continues to mean authored-source codemods, not database migration execution.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.66.8",
3
+ "version": "0.66.9",
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",
@@ -59,15 +59,20 @@ providers: {
59
59
 
60
60
  ## Database Providers
61
61
 
62
- Two databases are supported, both Cloudflare-native:
62
+ Three provider names are supported — one SQLite target and one Postgres
63
+ implementation on two hosts:
63
64
 
64
65
  | Provider | Description |
65
66
  |----------|-------------|
66
67
  | `cloudflare-d1` | Cloudflare D1 (SQLite at the edge) |
67
- | `neon` | Neon serverless PostgreSQL (`@neondatabase/serverless` over HTTP) |
68
+ | `neon` | Neon serverless PostgreSQL (`@neondatabase/serverless` over HTTP, or postgres.js over Hyperdrive) |
69
+ | `planetscale-postgres` | [PlanetScale Postgres](/platform/database/planetscale-postgres) over a Cloudflare Hyperdrive binding — the same Postgres emitters as `neon` (Hyperdrive only) |
70
+
71
+ `planetscale` — without the suffix — is the MySQL name and is **not** a
72
+ registered provider; MySQL is not supported.
68
73
 
69
74
  One database provider per app: auth tables and feature tables always share the
70
- selected database. On `neon`, Better Auth uses its PostgreSQL/Drizzle adapter
75
+ selected database. On either Postgres provider, Better Auth uses its PostgreSQL/Drizzle adapter
71
76
  in the same Postgres database as your features; on `cloudflare-d1`, both use
72
77
  D1. A per-service map (`database: { auth: ..., features: ... }`) is rejected at
73
78
  compile time — mixed database providers are not supported.
@@ -126,6 +131,16 @@ The Worker connects through a single `DATABASE_URL` secret — auth and feature
126
131
  queries share it. See [Neon](/platform/database/neon) for
127
132
  connection modes, RLS, and the migration workflow.
128
133
 
134
+ #### PlanetScale Postgres Options
135
+
136
+ Same options, one transport: `connectionMode` accepts `"auto"` and
137
+ `"hyperdrive"` only (omitted is `"hyperdrive"`), `hyperdrive.id` is required,
138
+ and there is no `DATABASE_URL` Worker secret — the runtime reads
139
+ `env.HYPERDRIVE.connectionString`. `pooled` does not apply; Hyperdrive is the
140
+ pool. See [PlanetScale Postgres](/platform/database/planetscale-postgres) for
141
+ role bootstrap, the `role.branch_id` connection username, and the mandatory
142
+ cache-disabled Hyperdrive config.
143
+
129
144
  #### Audit Database
130
145
 
131
146
  Cross-tenant `unsafe` actions (see [Actions → Unsafe mode](/define/actions/scoped-db#unsafe-mode)) write mandatory audit events. Those events land in a dedicated D1 database — separate from your features DB — so audit history stays isolated from application data and can't be tampered with through a normal CRUD route.
@@ -10,6 +10,7 @@ security definitions compile to either provider.
10
10
  |----------|----------|---------------|
11
11
  | [Cloudflare D1](/platform/database/d1) | CRUD-heavy SaaS, content catalogs, internal tools, straightforward workflows | Managed SQLite, no connection strings or pooling, Cloudflare-native operations, FTS5 and JSON functions when needed |
12
12
  | [Neon](/platform/database/neon) | Data-intensive products and apps designed around PostgreSQL | Native JSONB/arrays, `tsvector` + GIN, PostGIS/extensions, database RLS, advanced indexing and interactive transactions through Hyperdrive |
13
+ | [PlanetScale Postgres](/platform/database/planetscale-postgres) | The same Postgres implementation, hosted on PlanetScale | Identical generated schema, RLS and migrations to Neon; Cloudflare Hyperdrive only |
13
14
 
14
15
  ## Quick decision
15
16
 
@@ -18,11 +19,15 @@ security definitions compile to either provider.
18
19
  - Pick **Neon/Postgres** up front when advanced search, rich data types,
19
20
  sustained concurrent writes, Postgres extensions, or database-level RLS are
20
21
  product requirements.
21
- - Hyperdrive is optional: Neon HTTP is the lightweight default on Cloudflare;
22
- Hyperdrive is the full-featured lane for interactive transactions.
22
+ - Hyperdrive is optional on Neon: HTTP is the lightweight default on
23
+ Cloudflare, Hyperdrive the full-featured lane for interactive transactions.
24
+ On **PlanetScale Postgres** Hyperdrive is the only transport.
25
+ - The Postgres choice is a hosting choice: `neon` and `planetscale-postgres`
26
+ emit byte-identical schema and security migrations for the same definitions.
23
27
 
24
28
  ## Getting Started
25
29
 
26
30
  - **[D1 Setup](/platform/database/d1)** — Bindings, wrangler config, migrations
27
31
  - **[Using D1](/platform/database/using-d1)** — Drizzle queries, dual-DB mode, schema patterns
28
32
  - **[Neon](/platform/database/neon)** — Serverless Postgres setup and usage
33
+ - **[PlanetScale Postgres](/platform/database/planetscale-postgres)** — Roles, connection usernames, the cache-disabled Hyperdrive binding
@@ -1056,9 +1056,11 @@ first transaction-local statement inside the transaction (the same
1056
1056
  callback and the claims reset at commit/rollback — they never leak across
1057
1057
  Hyperdrive's connection pool.
1058
1058
 
1059
- > 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,
1060
1060
  > not the caller's RLS claims, so a cached read would leak across tenants. HTTP
1061
- > 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
1062
1064
  > interactive `db.transaction()` under any other `connectionMode` is a fail-closed
1063
1065
  > compile error.
1064
1066
 
@@ -1131,6 +1133,39 @@ npm run deploy:prod
1131
1133
  > batch write before relying on it.
1132
1134
 
1133
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
+
1134
1169
  ## Generated files
1135
1170
 
1136
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`