@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
@@ -56,7 +56,11 @@ These are Better Auth's built-in organization roles — no configuration needed.
56
56
 
57
57
  > **Tip:** Account UI's role picker uses these exact three roles. Use `["owner", "admin", "member"]` in your [Access](/define/access) rules so generated projects plug into Better Auth and Account UI seamlessly.
58
58
 
59
- Roles are used throughout the security layers — in [Access](/define/access) rules, [Firewall](/define/firewall) owner checks, and RLS policies.
59
+ Roles are used throughout the security layers — in [Access](/define/access) rules and
60
+ [Firewall](/define/firewall) owner checks. Roles are an **API** gate: they do not reach SQL.
61
+ Generated [Row Level Security](/platform/database/neon#row-level-security) is a backstop that
62
+ fences tenant scope, soft delete and lane admission only, and no generated policy body names a
63
+ role. Better Auth's own API is the gate for its tables.
60
64
 
61
65
  ## Next Steps
62
66
 
@@ -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: