@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.
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +11 -1
- 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/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/platform/database/index.md +7 -2
- package/dist/skill/docs/platform/database/neon.md +37 -2
- 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/platform/database/index.md +7 -2
- package/src/skill/docs/platform/database/neon.md +37 -2
- 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
|
@@ -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.
|
|
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
|
-
|
|
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
|
|
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
|
|
22
|
-
Hyperdrive
|
|
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
|
|
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.
|
|
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`
|