@quickback-dev/cli 0.66.11 → 0.66.12
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/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +14 -0
- package/dist/commands/deploy.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +29 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +26 -2
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/deployment-target.test.js +37 -1
- package/dist/lib/deployment-target.test.js.map +1 -1
- package/dist/lib/migrations/drizzle.test.js +1 -1
- package/dist/lib/migrations/drizzle.test.js.map +1 -1
- package/dist/lib/migrations/plan.js +6 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts +16 -5
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.js +32 -102
- package/dist/lib/migrations/postprocessors/better-auth-upgrade.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +73 -1
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.test.js +95 -0
- package/dist/lib/migrations/postprocessors/index.test.js.map +1 -1
- package/dist/lib/migrations/postprocessors/trigger-sql.d.ts +18 -0
- package/dist/lib/migrations/postprocessors/trigger-sql.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/trigger-sql.js +63 -0
- package/dist/lib/migrations/postprocessors/trigger-sql.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +1 -1
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +1 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/skill/docs/define/actions/scoped-db.md +3 -0
- package/dist/skill/docs/define/schema.md +58 -6
- package/dist/skill/docs/define/triggers.md +143 -20
- package/dist/skill/docs/platform/auth/index.md +37 -16
- package/dist/skill/docs/platform/auth/plugins/subscriptions.md +25 -5
- package/dist/skill/docs/platform/database/neon.md +115 -18
- package/dist/skill/docs/platform/database/planetscale-postgres.md +3 -3
- package/dist/skill/docs/platform/storage/r2.md +75 -8
- package/dist/skill/docs/tooling/output.md +49 -5
- package/package.json +2 -1
- package/src/skill/docs/define/actions/scoped-db.md +3 -0
- package/src/skill/docs/define/schema.md +58 -6
- package/src/skill/docs/define/triggers.md +143 -20
- package/src/skill/docs/platform/auth/index.md +37 -16
- package/src/skill/docs/platform/auth/plugins/subscriptions.md +25 -5
- package/src/skill/docs/platform/database/neon.md +115 -18
- package/src/skill/docs/platform/database/planetscale-postgres.md +3 -3
- package/src/skill/docs/platform/storage/r2.md +75 -8
- package/src/skill/docs/tooling/output.md +49 -5
|
@@ -6,10 +6,20 @@ Each trigger lowers one of two ways, and the compiler reports which:
|
|
|
6
6
|
|
|
7
7
|
| You write | Lowers to | Fires on |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| `sql:` | A real SQLite `CREATE TRIGGER`
|
|
9
|
+
| `sql:` | A real database trigger in your migrations — a SQLite `CREATE TRIGGER` on D1, a `SECURITY INVOKER` PL/pgSQL function + trigger on Postgres | **Every** write path — REST, actions, queue handlers, cron, raw SQL. Atomic with the write. |
|
|
10
10
|
| `handler:` | An application hook at the audit-wrapper write chokepoint | Writes through the wrapped `db` — REST CRUD and actions. **Not** queue handlers, cron, or raw SQL. |
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Both lanes exist on every database provider, with the same contract.
|
|
13
|
+
`handler:` is the default and the business-logic lane. `sql:` is the
|
|
14
|
+
**invariant** lane: data rules that must hold on every write path, atomically
|
|
15
|
+
with the write — soft-delete mapping, counters, denormalized fields. SQL
|
|
16
|
+
triggers carry data rules, never business flows and never role logic; the
|
|
17
|
+
compiler's own audit-stamping triggers are the precedent.
|
|
18
|
+
|
|
19
|
+
There is no auto-translation between the lanes — SQL bodies stay SQL,
|
|
20
|
+
functions stay functions — and none between SQL **dialects** either. A `sql:`
|
|
21
|
+
body is authored in the target database's own dialect and validated against
|
|
22
|
+
it at compile time. See [Dialects](#dialects-a-sql-body-is-never-translated).
|
|
13
23
|
|
|
14
24
|
## Basic Usage
|
|
15
25
|
|
|
@@ -66,30 +76,116 @@ Events: `beforeInsert`, `afterInsert`, `beforeUpdate`, `afterUpdate`, `beforeDel
|
|
|
66
76
|
|
|
67
77
|
## SQL triggers (`sql:`)
|
|
68
78
|
|
|
69
|
-
The compiler
|
|
70
|
-
`qb_trg_<table>_<event>_<name>` and ships it in the journaled features
|
|
79
|
+
The compiler owns the object names and ships the DDL in a journaled
|
|
71
80
|
migration — content-addressed, so an unchanged trigger set produces no new
|
|
72
81
|
migration, and removing a trigger from config drops it from the database on
|
|
73
82
|
the next migrate.
|
|
74
83
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
84
|
+
What is the same on every provider:
|
|
85
|
+
|
|
86
|
+
- You write **bare, `;`-terminated statements**. The compiler owns the
|
|
87
|
+
surrounding frame — you never author `CREATE TRIGGER` (or, on Postgres,
|
|
88
|
+
`CREATE FUNCTION`).
|
|
78
89
|
- `OLD.column` / `NEW.column` references use **SQL column names**
|
|
79
90
|
(`deleted_at`, not `deletedAt`) and are validated against the table at
|
|
80
91
|
compile time.
|
|
92
|
+
- Optional `when:` is a SQL expression guard (`WHEN` clause).
|
|
93
|
+
- SQL triggers run inside the triggering statement, so they are atomic with
|
|
94
|
+
the write, and a rejection rolls the whole statement back.
|
|
95
|
+
- Names are `qb_trg_<table>_<event-code>_<name>` and are the compiler's, not
|
|
96
|
+
yours.
|
|
97
|
+
|
|
98
|
+
### Dialects — a `sql:` body is never translated
|
|
99
|
+
|
|
100
|
+
A `sql:` body is raw SQL for **your** database. The compiler validates it in
|
|
101
|
+
the target's dialect and fails the compile when it sees the other one; it
|
|
102
|
+
never rewrites a body to fit. Declaring `sql:` on a provider with neither
|
|
103
|
+
lane (anything that is not `cloudflare-d1` or a Postgres provider) is also a
|
|
104
|
+
compile error.
|
|
105
|
+
|
|
106
|
+
> A SQLite `RAISE(ABORT, ...)` in a project targeting Postgres is rejected with:
|
|
107
|
+
>
|
|
108
|
+
> > `RAISE(ABORT, ...)` is SQLite syntax and has no PL/pgSQL equivalent — this
|
|
109
|
+
> > project targets PostgreSQL. Reject the write with `RAISE EXCEPTION
|
|
110
|
+
> > 'message';` instead. Trigger bodies are never translated between dialects.
|
|
111
|
+
>
|
|
112
|
+
> Porting a project between D1 and Postgres means porting its `sql:` bodies by
|
|
113
|
+
> hand. That is deliberate: a silent translation of a rule that must hold on
|
|
114
|
+
> every write path is the last thing you want to be wrong about.
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
#### SQLite (`cloudflare-d1`)
|
|
118
|
+
|
|
119
|
+
The body is inlined into `CREATE TRIGGER ... BEGIN <body> END`.
|
|
120
|
+
|
|
121
|
+
- The compiler emits the `BEGIN`/`END` frame **uppercase**; lowercase `begin`
|
|
122
|
+
breaks remote D1's statement splitter even though local D1 accepts it. An
|
|
123
|
+
authored frame is rejected rather than double-wrapped.
|
|
81
124
|
- Bare `CASE ... END` expressions, including nested cases, are supported.
|
|
82
125
|
For example: `SELECT CASE WHEN NEW.total < 0 THEN RAISE(ABORT, 'invalid total') END;`.
|
|
83
|
-
That `END` closes the expression
|
|
84
|
-
|
|
85
|
-
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
transactional option on D1, which has no `db.transaction()`.
|
|
126
|
+
That `END` closes the expression.
|
|
127
|
+
- To reject a write: `SELECT RAISE(ABORT, 'message');`
|
|
128
|
+
- SQL triggers are the only transactional option on D1, which has no
|
|
129
|
+
`db.transaction()`.
|
|
130
|
+
|
|
131
|
+
#### PostgreSQL (`neon`, `planetscale-postgres`)
|
|
90
132
|
|
|
91
|
-
|
|
92
|
-
|
|
133
|
+
Postgres has no inline trigger body, so each declaration becomes **two**
|
|
134
|
+
compiler-owned objects in the `app` schema: a `RETURNS trigger` function
|
|
135
|
+
carrying your statements, and the trigger that calls it.
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
triggers: {
|
|
139
|
+
beforeInsert: [
|
|
140
|
+
{
|
|
141
|
+
// Before-row mutation: assign to NEW. The compiler adds `RETURN NEW`.
|
|
142
|
+
name: 'defaultNotes',
|
|
143
|
+
sql: `NEW."notes" := COALESCE(NEW."notes", NEW."title");`,
|
|
144
|
+
},
|
|
145
|
+
],
|
|
146
|
+
beforeUpdate: [
|
|
147
|
+
{
|
|
148
|
+
name: 'lockPaid',
|
|
149
|
+
when: `OLD."status" = 'paid' AND NEW."status" <> 'paid'`,
|
|
150
|
+
sql: `RAISE EXCEPTION 'paid invoices cannot be reopened';`,
|
|
151
|
+
},
|
|
152
|
+
],
|
|
153
|
+
afterInsert: [
|
|
154
|
+
{
|
|
155
|
+
// Cross-table write. Unqualified names resolve in the `app` schema.
|
|
156
|
+
name: 'logCreate',
|
|
157
|
+
sql: `INSERT INTO invoice_events (id, invoice_id, organization_id, actor)
|
|
158
|
+
VALUES (NEW."id" || ':ins', NEW."id", NEW."organization_id", auth.user_id());`,
|
|
159
|
+
},
|
|
160
|
+
],
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
- Write **PL/pgSQL statements**, not a function. The compiler owns
|
|
165
|
+
`CREATE OR REPLACE FUNCTION`, the dollar quote, and the trailing
|
|
166
|
+
`RETURN NEW` (or `RETURN OLD` on a hard-delete trigger) — so a `before*`
|
|
167
|
+
trigger that mutates `NEW` proceeds, and you never return `NULL` by
|
|
168
|
+
accident and silently skip a write. Authoring `CREATE FUNCTION` or
|
|
169
|
+
`CREATE TRIGGER` is rejected.
|
|
170
|
+
- `IF … END IF`, `LOOP … END LOOP` and nested `BEGIN … END` blocks are
|
|
171
|
+
ordinary statements here and are accepted.
|
|
172
|
+
- To reject a write: `RAISE EXCEPTION 'message';` (SQLSTATE `P0001`). The
|
|
173
|
+
whole statement rolls back.
|
|
174
|
+
- Functions are **`SECURITY INVOKER`** and run with a pinned
|
|
175
|
+
`search_path = "app", public, pg_catalog`. That is the security contract:
|
|
176
|
+
a cross-table write from your trigger is still subject to RLS and grants,
|
|
177
|
+
so it cannot reach another tenant's rows — a cross-tenant write fails with
|
|
178
|
+
`42501` and rolls the statement back. Quickback never elevates a user
|
|
179
|
+
trigger to `SECURITY DEFINER`.
|
|
180
|
+
- The [caller claims](/platform/database/neon) are transaction-local, so
|
|
181
|
+
`auth.user_id()`, `auth.org_id()` and `current_setting('request.jwt.claim.sub', true)`
|
|
182
|
+
all read the acting principal from inside the body.
|
|
183
|
+
- Your triggers sort **before** the compiler's audit-stamping triggers
|
|
184
|
+
(`qb_trg_*` < `set_*_audit_on_*`, and Postgres fires BEFORE row triggers by
|
|
185
|
+
name), so a trigger cannot forge `createdBy` / `modifiedBy`.
|
|
186
|
+
- Object names are bounded to Postgres' 63-byte identifier limit with a hash
|
|
187
|
+
suffix, so two long trigger names that differ only past the cut stay
|
|
188
|
+
distinct instead of silently truncating onto each other.
|
|
93
189
|
|
|
94
190
|
### Soft-delete mapping
|
|
95
191
|
|
|
@@ -101,6 +197,26 @@ raw-SQL hard deletes are still covered. `*Update` events get the inverse
|
|
|
101
197
|
guard, so a soft delete fires delete triggers exactly once and never
|
|
102
198
|
double-fires as an update.
|
|
103
199
|
|
|
200
|
+
Identical on both dialects. On Postgres the two delete variants are two
|
|
201
|
+
functions, not one, because the transition trigger fires on `UPDATE` and
|
|
202
|
+
returns `NEW` while the hard-delete one returns `OLD`.
|
|
203
|
+
|
|
204
|
+
### Upgrades and removal
|
|
205
|
+
|
|
206
|
+
The trigger migration is appended to the journal after the schema migration
|
|
207
|
+
(and, on Postgres, after the RLS document), and is content-addressed:
|
|
208
|
+
|
|
209
|
+
- An unchanged trigger set appends **nothing** on recompile.
|
|
210
|
+
- Editing or renaming a trigger appends one migration that drops the previous
|
|
211
|
+
objects and creates the current ones.
|
|
212
|
+
- Removing a trigger from config appends one drop-only migration; on Postgres
|
|
213
|
+
the generated **function** is dropped too, so no orphan is left behind.
|
|
214
|
+
- Nothing already applied is ever rewritten.
|
|
215
|
+
|
|
216
|
+
Drops never use `CASCADE` — an unexpected dependency fails loudly rather than
|
|
217
|
+
being swept — and Postgres trigger drops are guarded on `to_regclass`, so a
|
|
218
|
+
table the preceding schema migration removed does not break the cleanup.
|
|
219
|
+
|
|
104
220
|
## Handler triggers (`handler:`)
|
|
105
221
|
|
|
106
222
|
Handlers run at the same write chokepoint that powers audit stamping and
|
|
@@ -161,15 +277,21 @@ Trigger cascades are bounded in every lane:
|
|
|
161
277
|
- **Handler hooks**: the `db` a hook receives is re-wrapped at depth + 1.
|
|
162
278
|
A cascade deeper than 5 levels (a hook's write firing hooks that write
|
|
163
279
|
again, …) throws with the table/op that exceeded the cap.
|
|
164
|
-
- **SQL triggers**: SQLite's `recursive_triggers` pragma defaults off —
|
|
165
|
-
trigger cannot re-enter itself, directly or through a cycle.
|
|
280
|
+
- **SQL triggers on D1**: SQLite's `recursive_triggers` pragma defaults off —
|
|
281
|
+
a trigger cannot re-enter itself, directly or through a cycle.
|
|
282
|
+
- **SQL triggers on Postgres**: there is **no** such guard. A trigger whose
|
|
283
|
+
write fires another trigger that writes back will recurse until Postgres
|
|
284
|
+
aborts on stack depth. Cascading `sql:` triggers on Postgres are yours to
|
|
285
|
+
keep acyclic — a `when:` guard on the state the trigger changes is the
|
|
286
|
+
usual way.
|
|
166
287
|
|
|
167
288
|
### Coverage — read the compile report
|
|
168
289
|
|
|
169
290
|
Handler hooks do **not** fire for queue handlers, cron jobs, or raw SQL.
|
|
170
291
|
The compiler emits a per-trigger lowering report and warns at compile time
|
|
171
292
|
when a `before*` handler is used as a guard — if a rule must hold for every
|
|
172
|
-
write path, use the `sql:` lane with `RAISE(ABORT)
|
|
293
|
+
write path, use the `sql:` lane and reject with `RAISE(ABORT, ...)` (D1) or
|
|
294
|
+
`RAISE EXCEPTION` (Postgres).
|
|
173
295
|
|
|
174
296
|
> Cron jobs themselves are first-class — declare them with
|
|
175
297
|
> [`defineSchedule`](/platform/schedules) and the compiler emits the Worker
|
|
@@ -180,10 +302,11 @@ write path, use the `sql:` lane with `RAISE(ABORT)`.
|
|
|
180
302
|
|
|
181
303
|
| Need | Use |
|
|
182
304
|
|---|---|
|
|
183
|
-
| Invariant that must hold universally (raw SQL included) | `sql:` with `RAISE(ABORT)` |
|
|
305
|
+
| Invariant that must hold universally (raw SQL included) | `sql:` with `RAISE(ABORT)` (D1) / `RAISE EXCEPTION` (Postgres) |
|
|
184
306
|
| Denormalized columns, counters, tombstones | `sql:` |
|
|
185
307
|
| Validation/derivation with application logic | `before*` `handler:` |
|
|
186
308
|
| Side-effects after a write (notify, write related rows) | `after*` `handler:` |
|
|
309
|
+
| Business flow, or anything that reads a role | `handler:` — `sql:` carries data rules only |
|
|
187
310
|
| Atomic with the write (D1 has no transactions) | `sql:` only |
|
|
188
311
|
|
|
189
312
|
Planned (not yet available — declaring them is a compile error rather than
|
|
@@ -70,25 +70,23 @@ role. Better Auth's own API is the gate for its tables.
|
|
|
70
70
|
## Compiler-managed auth versions and upgrades
|
|
71
71
|
|
|
72
72
|
The compiler pins Better Auth, its schema CLI, and the generated companion
|
|
73
|
-
packages to **1.7.
|
|
73
|
+
packages to **1.7.3**. Recompile and install the emitted dependencies together;
|
|
74
74
|
remove older Better Auth overrides from `build.dependencies`. An incompatible
|
|
75
75
|
override is rejected because it would run a different auth version from the
|
|
76
76
|
one that generated your schema.
|
|
77
77
|
|
|
78
78
|
For an existing project, retain its `quickback/drizzle` migration history and
|
|
79
79
|
use the updated CLI when recompiling. The CLI generates the upgrade locally;
|
|
80
|
-
migration history stays on your machine. Apply the newly generated auth
|
|
81
|
-
starting the updated Worker. Existing migration SQL is
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
Rehearse the migration against a database copy, and stop old auth writers during
|
|
91
|
-
the cutover so they cannot write the previous account shape.
|
|
80
|
+
migration history stays on your machine. Apply the newly generated auth
|
|
81
|
+
migration before starting the updated Worker. Existing migration SQL is
|
|
82
|
+
preserved.
|
|
83
|
+
|
|
84
|
+
### Upgrading from 1.6
|
|
85
|
+
|
|
86
|
+
The upgrade adds the current JWT/OAuth schema, including JWKS `alg`/`crv` and
|
|
87
|
+
resource-bound grants. The `account` table is unchanged — accounts are still
|
|
88
|
+
keyed by `(providerId, accountId)`, so there is no identity backfill and no
|
|
89
|
+
credential reset.
|
|
92
90
|
|
|
93
91
|
Existing OAuth grants without a recorded resource set are revoked during the
|
|
94
92
|
upgrade; clients must authorize again. Client registrations and ordinary
|
|
@@ -99,7 +97,30 @@ grants still bind resources and reject widening to an unauthorized resource.
|
|
|
99
97
|
Projects opting into per-client resource restrictions must link their clients
|
|
100
98
|
to resources using the OAuth provider's resource administration APIs.
|
|
101
99
|
|
|
100
|
+
### Projects compiled between 2026-09-05 and the 1.7.3 pin
|
|
101
|
+
|
|
102
|
+
Better Auth 1.7.0–1.7.2 briefly keyed accounts by an `issuer` column with a
|
|
103
|
+
unique `(issuer, accountId)` index. 1.7.3 restored the 1.6 `account` schema, so
|
|
104
|
+
only projects compiled during that window carry the extra column.
|
|
105
|
+
|
|
106
|
+
Recompiling emits one appended migration that drops the identity index and then
|
|
107
|
+
the `issuer` column — index first, because SQLite refuses to drop an indexed
|
|
108
|
+
column. It is generated from the schema diff, so a project that never had
|
|
109
|
+
`issuer` gets nothing, and prior migration SQL is untouched. No backfill is
|
|
110
|
+
needed in either direction: `issuer` was always derived from `providerId`, and
|
|
111
|
+
1.7.3 never reads it.
|
|
112
|
+
|
|
113
|
+
Apply it before the updated Worker serves traffic. A leftover `NOT NULL`
|
|
114
|
+
`issuer` column is an outage on 1.7.3 — Better Auth validates its schema at
|
|
115
|
+
init and refuses a required column it never writes.
|
|
116
|
+
|
|
117
|
+
Generated projects keep that validation **on** at runtime
|
|
118
|
+
(`advanced.database.validateSchema: !!env` in `src/lib/auth.ts`). It is off in
|
|
119
|
+
exactly one case: when the schema CLI imports `auth.ts` there are no bindings,
|
|
120
|
+
so the adapter holds a stub with no tables to check and the validator would
|
|
121
|
+
report every table as missing.
|
|
122
|
+
|
|
102
123
|
The bundled Account UI uses `signIn.social` and `linkSocial` for generic OAuth
|
|
103
|
-
providers, including Cloudflare. Their callback is
|
|
104
|
-
`/auth/v1/callback/cloudflare`; update the registered redirect URI when
|
|
105
|
-
an existing Cloudflare login integration.
|
|
124
|
+
providers, including Cloudflare. Their callback is
|
|
125
|
+
`/auth/v1/oauth2/callback/cloudflare`; update the registered redirect URI when
|
|
126
|
+
upgrading an existing Cloudflare login integration.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
The subscriptions plugin adds subscription tiers and Stripe billing to Better Auth. The compiler configures it from `quickback.config.ts`, emits it into your project as source, and wires its state-sync handlers onto the [inbound webhook surface](/platform/webhooks/inbound) — so Stripe events reach your database through one verified, deduplicated path.
|
|
4
4
|
|
|
5
|
-
The subscriptions table lives
|
|
5
|
+
The subscriptions table lives alongside `user` and `session`: entitlements are an access-control concern, not domain data. See [Where the table lives](#where-the-table-lives) for what that means on each database provider.
|
|
6
6
|
|
|
7
7
|
## Enable it
|
|
8
8
|
|
|
@@ -61,7 +61,8 @@ These are compile errors, not warnings:
|
|
|
61
61
|
- any tier after the first has no `priceId`
|
|
62
62
|
- two tiers share a `priceId` (webhooks resolve a tier *by* price, so it would be ambiguous)
|
|
63
63
|
- `webhooksBinding` is not set — see [Webhook wiring](#webhook-wiring)
|
|
64
|
-
- the
|
|
64
|
+
- the database provider has no subscriptions implementation — `cloudflare-d1`, `neon` and `planetscale-postgres` do
|
|
65
|
+
- the provider is Neon in the deprecated `connectionMode: 'websocket'`, whose database module emits no service-role handle
|
|
65
66
|
|
|
66
67
|
## Secrets
|
|
67
68
|
|
|
@@ -214,6 +215,25 @@ API keys and OAuth bearers stamp **nothing**, deliberately. A key is an integrat
|
|
|
214
215
|
|
|
215
216
|
Org-vs-personal precedence applies here exactly as it does everywhere else — the active organization's subscription is what gets stamped. See below.
|
|
216
217
|
|
|
218
|
+
## Where the table lives
|
|
219
|
+
|
|
220
|
+
One table, two dialects, selected at compile time. `src/plugins/subscriptions/schema.ts` re-exports whichever one your database provider uses, so drizzle-kit, the schema barrel and the runtime all resolve to a single definition.
|
|
221
|
+
|
|
222
|
+
| Provider | Table | Handle |
|
|
223
|
+
|----------|-------|--------|
|
|
224
|
+
| `cloudflare-d1` | `subscriptions` in the auth D1 database (`AUTH_DB`) | `drizzle(env.AUTH_DB)` |
|
|
225
|
+
| `neon`, `planetscale-postgres` | `auth.subscriptions`, in the same Postgres database and the same migration journal as everything else | the database module's internal service-role handle |
|
|
226
|
+
|
|
227
|
+
Column names, nullability and the JS values you read back are identical across the two. Timestamps are `integer` epoch-milliseconds on SQLite and `timestamptz` on Postgres; both hand your code a `Date`. `limits` is a JSON string on both.
|
|
228
|
+
|
|
229
|
+
### On Postgres it is a SYSTEM table
|
|
230
|
+
|
|
231
|
+
`auth.subscriptions` carries the same shape as the webhook store and the rate-limit counters: RLS enabled and forced, an anonymous-denial policy, and the role bootstrap's service-role policy. **There is no caller scope policy**, so a request-scoped database handle reads zero rows from it — including the caller's own — and is denied every write with `42501`.
|
|
232
|
+
|
|
233
|
+
That is not a restriction on the API: every reader and writer of entitlement state already runs on the internal service lane. The Stripe queue consumer has no caller context at all, the admin endpoints run after a platform-admin check, and tier-role resolution runs inside the auth middleware. Authorization for the endpoints above is unchanged — session, admin role and organization membership, checked before the database is touched. What the missing scope policy buys is that a bug in an unrelated route cannot read or mint a paid entitlement through a caller handle.
|
|
234
|
+
|
|
235
|
+
Neon's deprecated `connectionMode: 'websocket'` is rejected for the same reason webhooks are: its database module emits no `createServiceDb`.
|
|
236
|
+
|
|
217
237
|
## Webhook wiring
|
|
218
238
|
|
|
219
239
|
The plugin ships **no webhook route of its own**. Stripe events arrive on the standard inbound surface, which verifies the signature and deduplicates on `(provider, externalId)`, then dispatches through `WEBHOOKS_QUEUE`.
|
|
@@ -250,9 +270,9 @@ State sync runs on the queue, which is correct for entitlement propagation. Anyt
|
|
|
250
270
|
## What the compiler generates
|
|
251
271
|
|
|
252
272
|
1. `src/plugins/subscriptions/lib/` — the plugin itself, emitted as source. It is **not** an npm dependency; the only package added to your `package.json` is `stripe`.
|
|
253
|
-
2. `src/plugins/subscriptions/schema.ts` — a re-export of
|
|
254
|
-
3. `src/plugins/subscriptions/index.ts` — the plugin with your tiers,
|
|
255
|
-
4. A migration creating the
|
|
273
|
+
2. `src/plugins/subscriptions/schema.ts` — a re-export of your dialect's table from `lib/`, so drizzle-kit, the schema barrel and the runtime all resolve to one definition. See [Where the table lives](#where-the-table-lives).
|
|
274
|
+
3. `src/plugins/subscriptions/index.ts` — the plugin with your tiers, database handle and org-membership lookup already bound.
|
|
275
|
+
4. A migration creating the subscriptions table — in the auth D1 database, or as `auth.subscriptions` in the single Postgres journal with service-role-only RLS.
|
|
256
276
|
5. Registration of the Stripe handlers into the webhooks queue consumer.
|
|
257
277
|
6. `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` on the generated `Env` type.
|
|
258
278
|
|
|
@@ -449,6 +449,20 @@ content-addressed `<idx>_quickback_rls_<hash>` migration, so one
|
|
|
449
449
|
appends a new entry — recompiles with unchanged security append nothing. No
|
|
450
450
|
manual SQL application step exists.
|
|
451
451
|
|
|
452
|
+
### The default index set
|
|
453
|
+
|
|
454
|
+
Indexes are Drizzle's, not the security migration's: the compiler writes the
|
|
455
|
+
default set (tenant composite, FK columns, filtered columns, view-sortable
|
|
456
|
+
columns) into the schema source, so drizzle-kit generates and diffs them under
|
|
457
|
+
`<table>_<column>_idx` names. See
|
|
458
|
+
[The default index set](/define/schema#the-default-index-set) for the rules and
|
|
459
|
+
the `...q.indexes(t)` placeholder.
|
|
460
|
+
|
|
461
|
+
Older projects also carry `idx_<table>_<column>` copies the security migration
|
|
462
|
+
used to create. Those are dropped in the security migration's trailing
|
|
463
|
+
"retired indexes" section, which the journal runs after the schema migration
|
|
464
|
+
that created the replacements. Only `idx_*` names are dropped.
|
|
465
|
+
|
|
452
466
|
Quickback also dependency-orders Drizzle's standalone constraint replacements.
|
|
453
467
|
When a composite unique or primary key and its consuming foreign key are both
|
|
454
468
|
replaced, the generated migration drops the dependent foreign key first, drops
|
|
@@ -530,15 +544,25 @@ owner's row. It is the floor under the application, not a second application.
|
|
|
530
544
|
Quickback lowers your `firewall` config — and only your `firewall` config —
|
|
531
545
|
into policies that read the transaction-local claims described above through
|
|
532
546
|
`auth.user_id()`, `get_active_org_id()`, `get_active_team_id()`, `get_scope()`
|
|
533
|
-
and the `get_principal_*()` helpers. Each feature table gets exactly
|
|
534
|
-
policies:
|
|
547
|
+
and the `get_principal_*()` helpers. Each feature table gets exactly three
|
|
548
|
+
policies, plus a fourth only where a delegated-principal lane is declared:
|
|
535
549
|
|
|
536
550
|
| Policy | Kind | What it does |
|
|
537
551
|
|--------|------|--------------|
|
|
538
|
-
| `<table>_deny_anon` | RESTRICTIVE `FOR ALL` | Blocks any query carrying neither a stamped user id, nor a
|
|
552
|
+
| `<table>_deny_anon` | RESTRICTIVE `FOR ALL` | Blocks any query carrying neither a stamped user id, nor the service marker — nor, on a table with a delegated lane, a verified delegated/scope principal |
|
|
539
553
|
| `<table>_service_role` | permissive `FOR ALL` | Admits Worker-internal contexts — see [Background jobs and cross-tenant actions](#background-jobs-and-cross-tenant-actions) |
|
|
540
|
-
| `<table>
|
|
541
|
-
| `<table>
|
|
554
|
+
| `<table>_scope` | permissive `FOR ALL` | The firewall scope predicate. On a soft-deletable table `USING` also requires `deleted_at IS NULL OR public.in_soft_delete()` — see [The soft-delete lane](#the-soft-delete-lane); `WITH CHECK` is the scope predicate alone, so a row can be soft-deleted but never resurrected |
|
|
555
|
+
| `<table>_principal_fence` | RESTRICTIVE `FOR ALL` | **Only on tables with a `databaseAccess` lane or `access.principals`.** Caps every permissive policy, so no policy can broaden a request that carries the wrong principal type |
|
|
556
|
+
|
|
557
|
+
The fence is per-lane, not per-table, because on a table no principal can reach
|
|
558
|
+
it would read `get_principal_type() IS NULL` — blocking every principal, which
|
|
559
|
+
is exactly what leaving them out of `deny_anon` already does. Two policies for
|
|
560
|
+
one outcome; the compiler emits neither.
|
|
561
|
+
|
|
562
|
+
Every helper call inside a policy predicate is emitted as `(SELECT …)`. The
|
|
563
|
+
claims are transaction-local and stamped before the statement, so PostgreSQL
|
|
564
|
+
hoists the call into an **InitPlan** and evaluates it once per statement instead
|
|
565
|
+
of once per scanned row.
|
|
542
566
|
|
|
543
567
|
```typescript
|
|
544
568
|
firewall: [
|
|
@@ -552,13 +576,41 @@ ON "app"."documents" FOR ALL
|
|
|
552
576
|
TO quickback
|
|
553
577
|
USING (
|
|
554
578
|
organization_id = public.get_active_org_id()
|
|
555
|
-
AND deleted_at IS NULL
|
|
579
|
+
AND (deleted_at IS NULL OR public.in_soft_delete())
|
|
556
580
|
)
|
|
557
581
|
WITH CHECK (
|
|
558
582
|
organization_id = public.get_active_org_id()
|
|
559
583
|
);
|
|
560
584
|
```
|
|
561
585
|
|
|
586
|
+
### The soft-delete lane
|
|
587
|
+
|
|
588
|
+
`deleted_at IS NULL` keeps soft-deleted rows out of every caller's reach. On its
|
|
589
|
+
own it also blocks the delete that put them there.
|
|
590
|
+
|
|
591
|
+
PostgreSQL applies a SELECT-applicable policy's `USING` expression to the **new**
|
|
592
|
+
row of an `UPDATE`, not only the existing one, whenever the statement reads the
|
|
593
|
+
relation — which any `UPDATE … WHERE` does. The new row of a soft delete has
|
|
594
|
+
`deleted_at` set, so a bare `deleted_at IS NULL` refuses the statement with
|
|
595
|
+
`42501`, including the generated `DELETE` route's own write. Moving the filter to
|
|
596
|
+
a `FOR SELECT` policy does not help, and neither does dropping `RETURNING`: the
|
|
597
|
+
check follows the filter wherever it goes.
|
|
598
|
+
|
|
599
|
+
So the filter carries a lane. `public.in_soft_delete()` reads the
|
|
600
|
+
transaction-local `quickback.soft_delete` marker, and the generated write
|
|
601
|
+
chokepoint sets it for **exactly** the statement whose payload stamps
|
|
602
|
+
`deletedAt` — the same condition that stamps the audit columns. It is a
|
|
603
|
+
one-shot token: the claims preamble carries it into that statement's
|
|
604
|
+
transaction and clears it, so the next statement of the same request runs
|
|
605
|
+
without it.
|
|
606
|
+
|
|
607
|
+
It is the same trust model as the service marker: Worker-set, never derived from
|
|
608
|
+
request input. And it is narrower — it exempts the soft-delete filter and
|
|
609
|
+
nothing else. Tenancy, ownership and scope stay ANDed beside it, so a statement
|
|
610
|
+
inside the window still cannot cross a tenant; `WITH CHECK` never carries the
|
|
611
|
+
lane, so it cannot land a row the firewall rejects; and the emitted statement
|
|
612
|
+
keeps `deleted_at IS NULL` in its own `WHERE`, so it cannot resurrect one.
|
|
613
|
+
|
|
562
614
|
Exception tables (`firewall: [{ exception: true }]`) keep their permissive
|
|
563
615
|
`<table>_all` policy, and SYSTEM tables — idempotency keys, the webhook store,
|
|
564
616
|
Better Auth rate-limit counters, subscriptions, file metadata — stay
|
|
@@ -593,7 +645,8 @@ have to call still refuses them, and anything reaching the database outside a
|
|
|
593
645
|
generated route holds a caller-scoped handle whose tenant is already fenced.
|
|
594
646
|
|
|
595
647
|
The compiler enforces the shape at compile time. `QB-RLS-SCOPE-POLICY` requires
|
|
596
|
-
|
|
648
|
+
the three policies (and the fence wherever a delegated lane exists — and only
|
|
649
|
+
there), requires a tenant/owner/scope predicate in the scope policy's
|
|
597
650
|
`USING` clause, and **fails the build if any policy body calls `has_any_role`**.
|
|
598
651
|
Opt out with `compiler.securityContracts.rls.requireScopePolicy: false` —
|
|
599
652
|
`requireCrudPolicies` is the pre-016 name for the same key and is still honoured.
|
|
@@ -622,11 +675,14 @@ The retired names include the per-verb auth-table policies
|
|
|
622
675
|
dropped, so an upgraded database converges on the narrower set rather than
|
|
623
676
|
keeping a wider policy nobody emits any more.
|
|
624
677
|
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
678
|
+
**Indexes are rebuilt once.** The compiler used to infer `idx_<table>_<column>`
|
|
679
|
+
indexes in the security migration, alongside the `<table>_<column>_idx` indexes
|
|
680
|
+
Drizzle generates from the schema. Drizzle now owns the whole default set, so
|
|
681
|
+
the schema migration creates the drizzle-managed index and the security
|
|
682
|
+
migration that follows it in the journal drops the compiler-owned copy — the two
|
|
683
|
+
overlap for the length of one `db:migrate` run and nothing is ever left
|
|
684
|
+
unindexed. Only `idx_*` names are dropped; a drizzle-managed index is never
|
|
685
|
+
touched. See [the default index set](#the-default-index-set).
|
|
630
686
|
|
|
631
687
|
### Delegated principal RLS
|
|
632
688
|
|
|
@@ -717,7 +773,7 @@ tenant predicate can never match), but it means a `databaseAccess` arm is never
|
|
|
717
773
|
a place to write a restriction. A row that satisfies the arm is reachable even
|
|
718
774
|
when the table firewall would not have matched it, and even when it is
|
|
719
775
|
soft-deleted. Write the restriction in `firewall`; the restrictive
|
|
720
|
-
`<table>_deny_anon` and `<table>_principal_fence`
|
|
776
|
+
`<table>_deny_anon` and, where a lane is declared, `<table>_principal_fence` are the only arms
|
|
721
777
|
that cap every lane. The fence also means a table admits a principal type only
|
|
722
778
|
where its `access` (or its lane) names that type — a `ctx.principal.claims.*`
|
|
723
779
|
firewall arm on a table whose access names no principal is unreachable.
|
|
@@ -937,6 +993,34 @@ precedent — so there is no separate `WEBHOOKS_DB` binding.
|
|
|
937
993
|
(`requireOrgMember` / endpoint-ownership checks) before querying.
|
|
938
994
|
- Webhooks require `connectionMode: 'http'`.
|
|
939
995
|
|
|
996
|
+
## Managed file storage on Neon
|
|
997
|
+
|
|
998
|
+
`fileStorage: { managed: true }` is supported on `http` and `hyperdrive`. The
|
|
999
|
+
file metadata (`buckets`, `objects`) lives in a dedicated `files` Postgres
|
|
1000
|
+
schema of the **same** database — the `webhooks` precedent again — so there is
|
|
1001
|
+
no `FILES_DB` binding, no second drizzle config and no second migration target.
|
|
1002
|
+
|
|
1003
|
+
- The tables ride the project's single journal, reached through the
|
|
1004
|
+
`src/db/schema.ts` barrel.
|
|
1005
|
+
- Column shapes are 1:1 with the D1 version so no `/storage/v1/*` body changes:
|
|
1006
|
+
ISO-8601 date strings, JSON-encoded role and MIME lists, the same object keys
|
|
1007
|
+
and the same soft-delete column. The one divergence is numeric width —
|
|
1008
|
+
`size` and `file_size_limit` are `bigint`, because a Postgres `integer` would
|
|
1009
|
+
cap objects at 2 GiB.
|
|
1010
|
+
- The store is a SYSTEM table: RLS is enabled and forced with a single
|
|
1011
|
+
service-role policy, so only `createFilesDb()` (which wraps `createServiceDb`)
|
|
1012
|
+
can read or write it. There is no caller-scope policy and no role arm —
|
|
1013
|
+
public-versus-private file access is decided by the `/storage/v1/*` routes and
|
|
1014
|
+
the file-serving Worker before the handle is used, exactly as it was against
|
|
1015
|
+
the D1 binding.
|
|
1016
|
+
- The **file-serving Worker reads the same database over the same transport**:
|
|
1017
|
+
a `HYPERDRIVE` binding on Hyperdrive projects, or the same `DATABASE_URL`
|
|
1018
|
+
secret on HTTP projects — set on that Worker too. Never a mix of the two.
|
|
1019
|
+
- `connectionMode: 'websocket'` is rejected: it emits no `createServiceDb`.
|
|
1020
|
+
|
|
1021
|
+
See [File Storage](/platform/storage/r2) for the endpoints, bucket scopes and
|
|
1022
|
+
deployment steps.
|
|
1023
|
+
|
|
940
1024
|
## Encryption on Neon
|
|
941
1025
|
|
|
942
1026
|
The encryption pillar — `.encrypted()` (envelope) and `.sealed()` /
|
|
@@ -1070,11 +1154,18 @@ Hyperdrive's connection pool.
|
|
|
1070
1154
|
Anything not yet ported to Postgres is a compile-time error on Neon, never
|
|
1071
1155
|
silently-broken output:
|
|
1072
1156
|
|
|
1073
|
-
- **Managed file storage
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1157
|
+
- **Managed file storage with `connectionMode: 'websocket'`** is rejected: the
|
|
1158
|
+
websocket db index emits no `createServiceDb`, and both `createFilesDb` and
|
|
1159
|
+
the file-serving Worker wrap that handle. Managed storage is supported on
|
|
1160
|
+
`http` and `hyperdrive` — the buckets/objects metadata lives in a `files`
|
|
1161
|
+
schema of this same database (one journal, no `FILES_DB` binding). See
|
|
1162
|
+
[File Storage](/platform/storage/r2).
|
|
1163
|
+
- **The Better Auth `subscriptions` plugin** is supported. Its table is created
|
|
1164
|
+
as `auth.subscriptions` in the same journal as everything else and is a SYSTEM
|
|
1165
|
+
table — service-role only, like the webhook store — because entitlement state
|
|
1166
|
+
is written by the Stripe queue consumer and the admin endpoints and read by
|
|
1167
|
+
tier-role resolution, all of which run on the internal service lane. Rejected
|
|
1168
|
+
on **WebSocket mode**, which emits no `createServiceDb`.
|
|
1078
1169
|
- **Raw `sqliteTable` interop sources** on a Postgres target are rejected — write
|
|
1079
1170
|
child tables with `pgTable` (see [below](#raw-drizzle-interop-tables-must-use-pg-core)).
|
|
1080
1171
|
- **WebSocket mode** (deprecated) rejects webhooks, cross-tenant `unsafe`
|
|
@@ -1084,6 +1175,12 @@ silently-broken output:
|
|
|
1084
1175
|
|
|
1085
1176
|
Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.
|
|
1086
1177
|
|
|
1178
|
+
Table [`triggers`](/define/triggers) are supported in **both** lanes here. A
|
|
1179
|
+
`sql:` body is PL/pgSQL and lowers to a `SECURITY INVOKER` function plus its
|
|
1180
|
+
trigger in the `app` schema, so a cross-table write from a trigger stays
|
|
1181
|
+
subject to RLS and grants. Bodies are never translated between dialects — a
|
|
1182
|
+
SQLite `RAISE(ABORT, ...)` on this provider is a compile error.
|
|
1183
|
+
|
|
1087
1184
|
## Deploying
|
|
1088
1185
|
|
|
1089
1186
|
### Projects with no custom domain
|
|
@@ -181,9 +181,9 @@ never silently-broken output:
|
|
|
181
181
|
|
|
182
182
|
| Feature | Status |
|
|
183
183
|
|---------|--------|
|
|
184
|
-
| Managed file storage (`managed: true`) |
|
|
185
|
-
| Better Auth `subscriptions` plugin |
|
|
186
|
-
| Generated SQL triggers |
|
|
184
|
+
| Managed file storage (`managed: true`) | **supported** — metadata lives in a `files` schema of the same database; the file-serving Worker binds the same Hyperdrive config |
|
|
185
|
+
| Better Auth `subscriptions` plugin | supported — `auth.subscriptions` in the same journal, service-role only ([Subscriptions](/platform/auth/plugins/subscriptions#where-the-table-lives)) |
|
|
186
|
+
| Generated SQL triggers (`sql:`) | supported — PL/pgSQL bodies, `SECURITY INVOKER` (see [Triggers](/define/triggers)) |
|
|
187
187
|
| `webhooksDatabaseId` / `webhooksDatabaseName` | rejected — D1-only keys; webhook tables live in the `webhooks` schema of the same database |
|
|
188
188
|
| `connectionMode` of `'http'` or `'websocket'` | rejected — no such driver for this provider |
|
|
189
189
|
|