@quickback-dev/cli 0.66.8 → 0.66.10

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 (93) 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/index.js.map +1 -1
  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/neon-canary.d.ts +4 -0
  36. package/dist/lib/neon-canary.d.ts.map +1 -1
  37. package/dist/lib/neon-canary.js +24 -4
  38. package/dist/lib/neon-canary.js.map +1 -1
  39. package/dist/lib/neon-canary.test.js +39 -3
  40. package/dist/lib/neon-canary.test.js.map +1 -1
  41. package/dist/lib/neon-target.d.ts +5 -48
  42. package/dist/lib/neon-target.d.ts.map +1 -1
  43. package/dist/lib/neon-target.js +18 -42
  44. package/dist/lib/neon-target.js.map +1 -1
  45. package/dist/lib/neon-target.test.js +26 -4
  46. package/dist/lib/neon-target.test.js.map +1 -1
  47. package/dist/lib/shell.d.ts +10 -0
  48. package/dist/lib/shell.d.ts.map +1 -1
  49. package/dist/lib/shell.js +20 -0
  50. package/dist/lib/shell.js.map +1 -1
  51. package/dist/lib/shell.test.js +35 -1
  52. package/dist/lib/shell.test.js.map +1 -1
  53. package/dist/lib/wrangler-resources.d.ts +1 -1
  54. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  55. package/dist/lib/wrangler-resources.js +20 -9
  56. package/dist/lib/wrangler-resources.js.map +1 -1
  57. package/dist/lib/wrangler-resources.test.js +20 -0
  58. package/dist/lib/wrangler-resources.test.js.map +1 -1
  59. package/dist/schema-engine/index.js +3 -0
  60. package/dist/schema-engine/index.js.map +2 -2
  61. package/dist/schema-engine/provider-dialects.d.ts +1 -1
  62. package/dist/schema-engine/provider-dialects.d.ts.map +1 -1
  63. package/dist/skill/SKILL.md +12 -6
  64. package/dist/skill/agents/quickback-specialist/AGENT.md +1 -1
  65. package/dist/skill/docs/api/batch-operations.md +14 -8
  66. package/dist/skill/docs/configure/providers.md +18 -3
  67. package/dist/skill/docs/define/changesets.md +1 -1
  68. package/dist/skill/docs/define/firewall.md +7 -0
  69. package/dist/skill/docs/define/schema.md +3 -3
  70. package/dist/skill/docs/define/security.md +22 -0
  71. package/dist/skill/docs/platform/auth/index.md +5 -1
  72. package/dist/skill/docs/platform/database/index.md +7 -2
  73. package/dist/skill/docs/platform/database/neon.md +37 -2
  74. package/dist/skill/docs/platform/database/planetscale-postgres.md +205 -0
  75. package/dist/skill/docs/start/deploy.md +30 -0
  76. package/dist/skill/docs/tooling/cli.md +43 -2
  77. package/dist/skill/docs/tooling/output.md +19 -0
  78. package/package.json +1 -1
  79. package/src/skill/SKILL.md +12 -6
  80. package/src/skill/agents/quickback-specialist/AGENT.md +1 -1
  81. package/src/skill/docs/api/batch-operations.md +14 -8
  82. package/src/skill/docs/configure/providers.md +18 -3
  83. package/src/skill/docs/define/changesets.md +1 -1
  84. package/src/skill/docs/define/firewall.md +7 -0
  85. package/src/skill/docs/define/schema.md +3 -3
  86. package/src/skill/docs/define/security.md +22 -0
  87. package/src/skill/docs/platform/auth/index.md +5 -1
  88. package/src/skill/docs/platform/database/index.md +7 -2
  89. package/src/skill/docs/platform/database/neon.md +37 -2
  90. package/src/skill/docs/platform/database/planetscale-postgres.md +205 -0
  91. package/src/skill/docs/start/deploy.md +30 -0
  92. package/src/skill/docs/tooling/cli.md +43 -2
  93. package/src/skill/docs/tooling/output.md +19 -0
@@ -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`
@@ -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:
@@ -167,12 +167,18 @@ blocks the write.
167
167
 
168
168
  The SQL dialect for written declarations comes from your configured database
169
169
  provider — the same provider→dialect table the compiler uses. Postgres
170
- providers (`supabase`, `neon`, `vercel-postgres`, `postgres`, `postgresql`)
171
- get Postgres declarations; SQLite providers (`cloudflare-d1`,
170
+ providers (`neon`, `planetscale-postgres`, `supabase`, `vercel-postgres`,
171
+ `postgres`, `postgresql`) get Postgres declarations; SQLite providers (`cloudflare-d1`,
172
172
  `better-sqlite3`, `bun-sqlite`, `libsql`, `turso`) get SQLite. MySQL
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.
@@ -254,6 +254,25 @@ projects acquire build and deployment fixes without losing unrelated tooling.
254
254
 
255
255
  These files are generated only when the corresponding features are configured:
256
256
 
257
+ ### Database provider setup files
258
+
259
+ Every compile emits an environment example named for the configured provider.
260
+ Postgres providers additionally emit a setup guide under `docs/` and the auth
261
+ schema qualifier script:
262
+
263
+ | Provider | Emitted |
264
+ |----------|---------|
265
+ | `cloudflare-d1` | `.env.cloudflare-d1.example`, `wrangler.d1.example`, `drizzle.auth.config.ts` (dual-database mode) |
266
+ | `neon` | `.env.neon.example`, `.dev.vars.example`, `docs/neon-setup.md`, `scripts/quickback-qualify-auth-schema.mjs` |
267
+ | `planetscale-postgres` | `.env.planetscale.example`, `.dev.vars.example`, `docs/planetscale-postgres-setup.md`, `scripts/quickback-qualify-auth-schema.mjs` |
268
+
269
+ The setup guide is host-specific — role bootstrap, the connection username, the
270
+ Hyperdrive binding and named environments — and is regenerated on every compile.
271
+ Both Postgres providers keep auth and feature tables in **one** database, so
272
+ they emit a single `drizzle.config.ts` rather than the D1 dual-database pair.
273
+ See [Neon](/platform/database/neon) and
274
+ [PlanetScale Postgres](/platform/database/planetscale-postgres).
275
+
257
276
  ### Embeddings
258
277
 
259
278
  When any feature has `embeddings` configured:
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.10",
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",
@@ -6,18 +6,24 @@ allowed-tools: Read, Grep, Glob, Edit, Write
6
6
 
7
7
  # Quickback
8
8
 
9
- Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript; compile them into either a Hono API or PostgreSQL Row Level Security policies. Pair the output with the Quickback Stack for a complete Supabase alternative on Cloudflare.
9
+ Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript; compile them into a Hono API running on Cloudflare Workers. Pair the output with the Quickback Stack for a complete Supabase alternative on Cloudflare.
10
10
 
11
11
  It's two products:
12
12
 
13
13
  ## 1. Quickback Compiler — the build tool
14
14
 
15
- Define schema + security in TypeScript. Compile to one of two targets:
15
+ Define schema + security in TypeScript. Compile to a full Hono application with
16
+ CRUD, batch endpoints, OpenAPI, and an MCP server, on one of three registered
17
+ database providers:
16
18
 
17
- - **Quickback for Hono API** — Cloudflare D1 or Neon. Full Hono application with CRUD, batch endpoints, OpenAPI, and an MCP server.
18
- - **Quickback for Supabase** — PostgreSQL Row Level Security policies. Keep Supabase Auth, Storage, and Realtime; Quickback adds the security layer.
19
+ - **`cloudflare-d1`** — edge SQLite, the default.
20
+ - **`neon`** — Postgres over HTTP, WebSocket or Cloudflare Hyperdrive.
21
+ - **`planetscale-postgres`** — the same Postgres emitters, Hyperdrive only. Compiler support; live acceptance pending. `planetscale` without the suffix means MySQL and is not registered.
19
22
 
20
- The same `defineTable()` definitions work for both targets. The compiler runs as a remote service at `compiler.quickback.dev` (override with `QUICKBACK_API_URL`) — the CLI is a thin client that sends config + features and writes the generated files.
23
+ The same `defineTable()` definitions work across every provider. On Postgres,
24
+ the compiler additionally emits **backstop** Row Level Security: it fences
25
+ tenant scope, soft delete and lane admission only — roles, status, transitions
26
+ and masking stay with the API. The compiler runs as a remote service at `compiler.quickback.dev` (override with `QUICKBACK_API_URL`) — the CLI is a thin client that sends config + features and writes the generated files.
21
27
 
22
28
  ## 2. Quickback Stack — the runtime services
23
29
 
@@ -409,7 +415,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
409
415
 
410
416
  **Platform services** (`docs/platform/<topic>.md`)
411
417
  - `cloudflare` — the Workers runtime target
412
- - `database/{index,d1,neon}` — D1 and Neon/Postgres
418
+ - `database/{index,d1,neon,planetscale-postgres}` — D1, and Neon / PlanetScale Postgres
413
419
  - `auth` — Better Auth integration, JWT optimization, plugins, device-auth, security
414
420
  - `storage/{kv,r2}` — using KV and R2 in actions
415
421
  - `realtime` — Durable Objects, WebSocket
@@ -70,7 +70,7 @@ When explaining compile outputs:
70
70
 
71
71
  Detect the database dialect from `quickback.config.ts`:
72
72
  - Cloudflare D1 / SQLite: Use `sqliteTable`, `text`, `integer` from `drizzle-orm/sqlite-core`
73
- - Supabase / PostgreSQL: Use `pgTable`, `text`, `boolean`, `timestamp` from `drizzle-orm/pg-core`
73
+ - Neon / PlanetScale Postgres / PostgreSQL: Use `pgTable`, `text`, `boolean`, `timestamp` from `drizzle-orm/pg-core`
74
74
 
75
75
  ### Table Definition Pattern (recommended: `feature()` + `q.scope()`)
76
76
 
@@ -273,24 +273,30 @@ and, for Neon, its **connection mode** — supports interactive transactions.
273
273
  The response's `meta.transactional` flag tells you which guarantee you
274
274
  actually got — inspect it in clients that care about rollback.
275
275
 
276
- Neon is transactional **only over websocket** (`connectionMode: 'websocket'`,
277
- the default on Node/Bun runtimes). Over HTTP — the default on Cloudflare
278
- Workers — the `drizzle-orm/neon-http` driver has no `db.transaction()` (it
279
- throws at runtime), so Neon-over-HTTP batches behave exactly like D1:
280
- fail-fast per-record loop, `meta.transactional: false`.
276
+ Neon is transactional over **websocket** (`connectionMode: 'websocket'`, the
277
+ default on Node/Bun runtimes) and over **hyperdrive** (postgres.js on a
278
+ Cloudflare Hyperdrive binding — the only Neon mode with interactive
279
+ transactions on Workers). Over HTTP — the default on Cloudflare Workers — the
280
+ `drizzle-orm/neon-http` driver has no `db.transaction()` (it throws at
281
+ runtime), so Neon-over-HTTP batches behave exactly like D1: fail-fast
282
+ per-record loop, `meta.transactional: false`.
283
+
284
+ [PlanetScale Postgres](/platform/database/planetscale-postgres) is Hyperdrive-only
285
+ and therefore always transactional — it shares the `postgres-js-hyperdrive`
286
+ transport with Neon's hyperdrive mode.
281
287
 
282
288
  ### Per-Provider Matrix
283
289
 
284
290
  | Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
285
291
  |----------|----------|-----------|----------------------|----------|
286
- | `PATCH /batch` (update) | tx-supporting (postgres, neon over websocket) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
292
+ | `PATCH /batch` (update) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
287
293
  | `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
288
294
  | `PATCH /batch` (update) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Fail-fast loop without rollback — the driver has no `db.transaction`. Records before the failure stay committed. |
289
- | `PUT /batch` (upsert) | tx-supporting (postgres, neon over websocket) | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
295
+ | `PUT /batch` (upsert) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
290
296
  | `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
291
297
  | `POST /batch` (create) | (any) | (any) | `true` | Single bulk `INSERT` — atomic at the DB level. |
292
298
  | `DELETE /batch` | (any) | (any) | `true` | Single bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. |
293
- | [Changeset](/define/changesets) (`application/vnd.quickback.changeset+json`) | tx-supporting (postgres, neon over websocket/hyperdrive) | n/a | `true` | Root op + every child op share one transaction; any op failure rolls back the whole changeset. |
299
+ | [Changeset](/define/changesets) (`application/vnd.quickback.changeset+json`) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | n/a | `true` | Root op + every child op share one transaction; any op failure rolls back the whole changeset. |
294
300
  | [Changeset](/define/changesets) | cloudflare-d1, neon over http (Cloudflare default) | n/a | `false` | Deterministic parent-first fail-fast — the first op failure stops the changeset; already-applied ops stay committed (a consistent, independently-authorized prefix). |
295
301
 
296
302
  ### Reading `meta.transactional` in clients
@@ -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.
@@ -417,7 +417,7 @@ it; `meta.transactional` reports the actual guarantee (same contract as
417
417
 
418
418
  | Provider | transactional | Behavior |
419
419
  |---|---|---|
420
- | postgres / supabase / neon (websocket / hyperdrive) / libsql / better-sqlite3 / bun-sqlite | `true` | One transaction; any op failure rolls back the root op and every child op |
420
+ | postgres / neon (websocket / hyperdrive) / planetscale-postgres (hyperdrive) / libsql / better-sqlite3 / bun-sqlite | `true` | One transaction; any op failure rolls back the root op and every child op |
421
421
  | cloudflare-d1, neon over http (the Cloudflare default) | `false` | Deterministic parent-first **fail-fast**: the first failure stops the changeset; ops already applied stay committed (a consistent prefix — each was independently authorized) |
422
422
 
423
423
  ## Calling it from authored code
@@ -2,6 +2,13 @@
2
2
 
3
3
  The firewall generates WHERE clauses automatically to isolate data by user, organization, or team.
4
4
 
5
+ The firewall is also **the only security pillar that lowers to SQL**. On a Postgres
6
+ provider the compiler mirrors it into backstop Row Level Security — tenant scope,
7
+ owner scope, soft delete and lane admission — so a custom route or a mis-scoped
8
+ handle cannot escape it. Roles, status, transitions and masking stay in the API and
9
+ appear in no policy. See [Security Overview](/define/security#where-each-pillar-is-enforced)
10
+ and [Row Level Security](/platform/database/neon#row-level-security).
11
+
5
12
  ## Basic Usage
6
13
 
7
14
  The cleanest pattern is `q.scope()` — declare the tenant column once and the firewall is auto-derived:
@@ -224,8 +224,8 @@ If you have an existing Drizzle schema you're bringing forward — or need a dia
224
224
  | Target Database | Import From | Table Function |
225
225
  |-----------------|-------------|----------------|
226
226
  | Cloudflare D1, Turso, SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
227
- | Supabase, Neon, PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
228
- | PlanetScale, MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
227
+ | Neon, PlanetScale Postgres, PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
228
+ | MySQL (`planetscale`, `mysql`) — dialect only, no registered provider | `drizzle-orm/mysql-core` | `mysqlTable` |
229
229
 
230
230
  ```typescript
231
231
  // quickback/features/jobs/jobs.ts
@@ -274,7 +274,7 @@ Default to `feature()`. Drop to Drizzle only when:
274
274
 
275
275
  Features in the same project may mix freely — Quickback dispatches per feature — so one interop table doesn't force the rest of the project off `feature()`.
276
276
 
277
- One dialect rule: interop files **without** a `defineTable(...)` default export (internal child tables) are not dialect-translated — author them in the target database's dialect. On Postgres providers (Neon, Supabase), a `sqliteTable` interop source without `defineTable` is a compile-time error; write it with `pgTable` from `drizzle-orm/pg-core` instead. Sources **with** `defineTable(...)` keep compiling across dialects automatically.
277
+ One dialect rule: interop files **without** a `defineTable(...)` default export (internal child tables) are not dialect-translated — author them in the target database's dialect. On Postgres providers (`neon`, `planetscale-postgres`), a `sqliteTable` interop source without `defineTable` is a compile-time error; write it with `pgTable` from `drizzle-orm/pg-core` instead. Sources **with** `defineTable(...)` keep compiling across dialects automatically.
278
278
 
279
279
  ### Drizzle Column Types
280
280
 
@@ -19,6 +19,28 @@ Views and Guards are documented under **Reads** and **Writes** rather than under
19
19
  Security, because that is where you are when you need them: a view is a shape you
20
20
  return, a guard is a rule about a write. They are security mechanisms either way.
21
21
 
22
+ ## Where each pillar is enforced
23
+
24
+ All six pillars run in the API. On a Postgres provider ([Neon](/platform/database/neon),
25
+ [PlanetScale Postgres](/platform/database/planetscale-postgres)) the compiler *also*
26
+ emits Row Level Security — but only as a **backstop**, and only for one pillar:
27
+
28
+ > **The firewall is the only pillar that lowers to SQL.** Generated RLS fences tenant
29
+ > scope, owner scope, soft delete and lane admission. Roles, status, transitions,
30
+ > masking and record conditions are the API's job and appear in no policy body — no
31
+ > generated policy names an authored role.
32
+
33
+ The backstop exists so a bug in a custom route or a mis-scoped handle cannot cross a
34
+ tenant, resurrect a soft-deleted row, or read another owner's row. It is not a second
35
+ copy of `access`. A scoped-role gate or an `access.record` owner rule is an **Access**
36
+ decision and stays in the API; if an owner boundary must hold at the database, author
37
+ it as `firewall.owner`, which does lower.
38
+
39
+ Better Auth's tables carry the same backstop, and **Better Auth's own API is the gate
40
+ for its tables** — the caller lane never writes them. On D1 there is no RLS at all:
41
+ enforcement is the API plus the fact that the database is unreachable except through
42
+ your Worker. See [D1 vs Neon RLS](/platform/database/d1#comparison-with-neon-rls).
43
+
22
44
  ## Firewall — which rows
23
45
 
24
46
  The firewall is tenant isolation. It rewrites every query so a caller can only ever