@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.
- 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/index.js.map +1 -1
- 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/SKILL.md +12 -6
- package/dist/skill/agents/quickback-specialist/AGENT.md +1 -1
- package/dist/skill/docs/api/batch-operations.md +14 -8
- package/dist/skill/docs/configure/providers.md +18 -3
- package/dist/skill/docs/define/changesets.md +1 -1
- package/dist/skill/docs/define/firewall.md +7 -0
- package/dist/skill/docs/define/schema.md +3 -3
- package/dist/skill/docs/define/security.md +22 -0
- package/dist/skill/docs/platform/auth/index.md +5 -1
- 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 +43 -2
- package/dist/skill/docs/tooling/output.md +19 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +12 -6
- package/src/skill/agents/quickback-specialist/AGENT.md +1 -1
- package/src/skill/docs/api/batch-operations.md +14 -8
- package/src/skill/docs/configure/providers.md +18 -3
- package/src/skill/docs/define/changesets.md +1 -1
- package/src/skill/docs/define/firewall.md +7 -0
- package/src/skill/docs/define/schema.md +3 -3
- package/src/skill/docs/define/security.md +22 -0
- package/src/skill/docs/platform/auth/index.md +5 -1
- 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 +43 -2
- 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
|
|
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
|
|
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`
|
|
@@ -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 (`
|
|
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:
|