@quickback-dev/cli 0.66.10 → 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-wrapper.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle-wrapper.js +11 -1
- package/dist/lib/migrations/drizzle-wrapper.js.map +1 -1
- package/dist/lib/migrations/drizzle-wrapper.test.d.ts +2 -0
- package/dist/lib/migrations/drizzle-wrapper.test.d.ts.map +1 -0
- package/dist/lib/migrations/drizzle-wrapper.test.js +64 -0
- package/dist/lib/migrations/drizzle-wrapper.test.js.map +1 -0
- package/dist/lib/migrations/drizzle.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle.js +6 -2
- package/dist/lib/migrations/drizzle.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/prompt-runner.test.js +8 -1
- package/dist/lib/migrations/prompt-runner.test.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 +67 -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 +133 -18
- package/dist/skill/docs/platform/database/planetscale-postgres.md +60 -26
- 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 +67 -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 +133 -18
- package/src/skill/docs/platform/database/planetscale-postgres.md +60 -26
- package/src/skill/docs/platform/storage/r2.md +75 -8
- package/src/skill/docs/tooling/output.md +49 -5
|
@@ -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,8 +1175,32 @@ 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
|
|
|
1186
|
+
### Projects with no custom domain
|
|
1187
|
+
|
|
1188
|
+
A Worker that lives only on `workers.dev` (no `providers.runtime.config.routes`,
|
|
1189
|
+
no `domains`) must tell the generated auth layer its own host. Without it the
|
|
1190
|
+
JWT issuer defaults to the local dev URL and cookie-backed browser mutations are
|
|
1191
|
+
refused as cross-site:
|
|
1192
|
+
|
|
1193
|
+
```sh
|
|
1194
|
+
npx wrangler deploy \
|
|
1195
|
+
--var EXTRA_APP_HOSTS:<name>.<account>.workers.dev \
|
|
1196
|
+
--var BETTER_AUTH_URL:https://<name>.<account>.workers.dev
|
|
1197
|
+
```
|
|
1198
|
+
|
|
1199
|
+
Named environments set `BETTER_AUTH_URL` in `worker.vars` (see above);
|
|
1200
|
+
`EXTRA_APP_HOSTS` is documented under
|
|
1201
|
+
[Multi-domain architecture](/configure/domains#one-bundle-several-hostnames).
|
|
1202
|
+
|
|
1203
|
+
|
|
1089
1204
|
For an unnamed target, the generated `deploy` script runs migrations, then
|
|
1090
1205
|
ships the Worker:
|
|
1091
1206
|
|
|
@@ -7,12 +7,20 @@ schema, the same Better Auth wiring, the same
|
|
|
7
7
|
migrations. For identical definitions the generated schema and security
|
|
8
8
|
migrations are byte-identical between the two providers.
|
|
9
9
|
|
|
10
|
-
> **
|
|
11
|
-
>
|
|
12
|
-
>
|
|
13
|
-
>
|
|
14
|
-
>
|
|
15
|
-
>
|
|
10
|
+
> **Proven live end to end (2026-09-07).** The direct-connection contract, the
|
|
11
|
+
> Hyperdrive transport, and a generated project's Worker were each run against a
|
|
12
|
+
> real PlanetScale Postgres 18 branch. Against a real PlanetScale Postgres 18 branch, the
|
|
13
|
+
> generated journal applied unchanged: role bootstrap with `CREATE ROLE`
|
|
14
|
+
> verbatim, ownership transfer to `quickback_owner`, the RLS backstop through
|
|
15
|
+
> the emitted client as the restricted role, interactive transaction commit and
|
|
16
|
+
> rollback, incremental migration as `quickback_admin`, and a migration ledger
|
|
17
|
+
> the runtime cannot read. The `recruitment` example, compiled with this provider,
|
|
18
|
+
> applied its four-file upgrade journal, then served sign-up, sessions, organization
|
|
19
|
+
> activation, tenant CRUD, a named view and an action through a cache-disabled
|
|
20
|
+
> Hyperdrive config connected as `quickback.<branch_id>`, with every security
|
|
21
|
+
> layer answering correctly. Not yet exercised there: outbound webhook delivery,
|
|
22
|
+
> realtime traffic and the automated acceptance manifest. Sanitized record in the
|
|
23
|
+
> repository's `plans/postgres-acceptance-results.md`.
|
|
16
24
|
|
|
17
25
|
|
|
18
26
|
## Configuration
|
|
@@ -173,30 +181,56 @@ never silently-broken output:
|
|
|
173
181
|
|
|
174
182
|
| Feature | Status |
|
|
175
183
|
|---------|--------|
|
|
176
|
-
| Managed file storage (`managed: true`) |
|
|
177
|
-
| Better Auth `subscriptions` plugin |
|
|
178
|
-
| 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)) |
|
|
179
187
|
| `webhooksDatabaseId` / `webhooksDatabaseName` | rejected — D1-only keys; webhook tables live in the `webhooks` schema of the same database |
|
|
180
188
|
| `connectionMode` of `'http'` or `'websocket'` | rejected — no such driver for this provider |
|
|
181
189
|
|
|
182
|
-
##
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
190
|
+
## Live acceptance findings
|
|
191
|
+
|
|
192
|
+
Answered by the direct-connection spike on 2026-09-07 (PostgreSQL 18.6,
|
|
193
|
+
postgres.js 3.4.9, drizzle-orm 0.45.2; sanitized record in the repository's
|
|
194
|
+
`plans/postgres-acceptance-results.md`):
|
|
195
|
+
|
|
196
|
+
- **`CREATE ROLE … NOLOGIN NOBYPASSRLS`** runs verbatim from the generated
|
|
197
|
+
journal as the vendor default role. No vendor role API is needed.
|
|
198
|
+
- **Ownership transfer** with `ALTER … OWNER TO quickback_owner` works,
|
|
199
|
+
including `ALTER SCHEMA public`.
|
|
200
|
+
- **`SECURITY DEFINER` with a pinned `search_path`**, `GRANT … WITH SET TRUE`
|
|
201
|
+
and `REVOKE CREATE ON SCHEMA public FROM PUBLIC` are all accepted.
|
|
202
|
+
- **`SET LOCAL ROLE quickback` from the vendor default role is refused**
|
|
203
|
+
(SQLSTATE 42501). PostgreSQL 16+ gives a role's creator ADMIN OPTION but not
|
|
204
|
+
SET. This does not affect the shipped design: the Worker connects directly as
|
|
205
|
+
the restricted role through Hyperdrive, and `quickback_admin` holds SET on it
|
|
206
|
+
for routine migrations. Do not work around it by granting the default role
|
|
207
|
+
more; it is the setup actor only and carries `BYPASSRLS`.
|
|
208
|
+
- **Connection username** is `<role>.<branch_id>`; SQL role names stay bare.
|
|
209
|
+
Create the Hyperdrive origin credential as `quickback.<branch_id>`.
|
|
210
|
+
- **Extensions:** the journal needs only `plpgsql`. `pgcrypto`, `uuid-ossp`,
|
|
211
|
+
`vector`, `pg_trgm`, `citext` and `pg_cron` are available if a project
|
|
212
|
+
declares them.
|
|
213
|
+
|
|
214
|
+
Still to prove, and the reason this page keeps a qualifier: the deployed
|
|
215
|
+
Hyperdrive run, and one provider-independent item — the generated RLS helper
|
|
216
|
+
functions end up owned by the migrating actor rather than `quickback_owner`,
|
|
217
|
+
which is why a changed security migration currently needs the setup-owner
|
|
218
|
+
credential (see [Neon](/platform/database/neon#upgrading-an-existing-database)).
|
|
219
|
+
|
|
220
|
+
## Deploying to workers.dev only
|
|
221
|
+
|
|
222
|
+
A project with no custom domain must tell the generated auth layer its own
|
|
223
|
+
host, or the JWT issuer defaults to the local dev URL and browser mutations
|
|
224
|
+
fail the origin check:
|
|
225
|
+
|
|
226
|
+
```sh
|
|
227
|
+
npx wrangler deploy \
|
|
228
|
+
--var EXTRA_APP_HOSTS:<name>.<account>.workers.dev \
|
|
229
|
+
--var BETTER_AUTH_URL:https://<name>.<account>.workers.dev
|
|
230
|
+
```
|
|
197
231
|
|
|
198
|
-
|
|
199
|
-
|
|
232
|
+
Projects with `providers.runtime.config.routes` or `domains` get both from
|
|
233
|
+
the configured hostnames automatically.
|
|
200
234
|
|
|
201
235
|
## See also
|
|
202
236
|
|
|
@@ -11,11 +11,23 @@ Quickback provides built-in file storage using Cloudflare R2.
|
|
|
11
11
|
files worker.** You compute keys and store file references in your own table.
|
|
12
12
|
Use this when you already have a media table and only need to sign large or
|
|
13
13
|
confidential transfers — see [Presigned uploads](#presigned-uploads).
|
|
14
|
-
- **Managed (`managed: true`)** — adds the turnkey subsystem on top: a
|
|
15
|
-
metadata
|
|
14
|
+
- **Managed (`managed: true`)** — adds the turnkey subsystem on top: a
|
|
15
|
+
metadata store (buckets + objects), the `/storage/v1/*` upload/download/
|
|
16
16
|
manage endpoints, and a files worker for serving. Use this for listing photos,
|
|
17
17
|
avatars, and other files that should be **public-if-you-have-the-link**.
|
|
18
18
|
|
|
19
|
+
Managed mode works on every database provider. Where the metadata lives depends
|
|
20
|
+
on which one you chose:
|
|
21
|
+
|
|
22
|
+
| Database | Metadata store | Migrations |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `cloudflare-d1` | A second D1 database, bound as `FILES_DB` | Its own `drizzle.files.config.ts` and migration folder |
|
|
25
|
+
| `neon`, `planetscale-postgres` | A `files` schema in the **same** Postgres database as auth and feature data — no extra database, no binding | The project's single journal |
|
|
26
|
+
|
|
27
|
+
Nothing above the store moves: ids, object keys, JSON-encoded role and MIME
|
|
28
|
+
lists, ISO-8601 timestamps and soft deletion are identical, so every
|
|
29
|
+
`/storage/v1/*` request and response body is the same on both.
|
|
30
|
+
|
|
19
31
|
```ts
|
|
20
32
|
// Presign-only (default) — ctx.storage against a bucket, nothing else
|
|
21
33
|
defineFileStorage("cloudflare-r2", { bucketName: "my-app-media" })
|
|
@@ -117,7 +129,7 @@ export default {
|
|
|
117
129
|
managed: true,
|
|
118
130
|
binding: 'R2_BUCKET',
|
|
119
131
|
bucketName: 'my-app-files',
|
|
120
|
-
filesBinding: 'FILES_DB',
|
|
132
|
+
filesBinding: 'FILES_DB', // cloudflare-d1 only; ignored on Postgres
|
|
121
133
|
maxFileSize: 10 * 1024 * 1024, // 10MB
|
|
122
134
|
allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
|
|
123
135
|
},
|
|
@@ -127,7 +139,7 @@ export default {
|
|
|
127
139
|
```
|
|
128
140
|
|
|
129
141
|
> `managed: true` is what turns on everything on this page — the `/storage/v1/*`
|
|
130
|
-
> routes, the files worker, and the
|
|
142
|
+
> routes, the files worker, and the metadata store. Without it R2
|
|
131
143
|
> file storage is **presign-only**: the compiler signs requests against the
|
|
132
144
|
> bucket by name and emits **no** bucket binding into `wrangler.toml`, so
|
|
133
145
|
> `binding` and `filesBinding` are ignored and `env.R2_BUCKET` is `undefined`
|
|
@@ -379,6 +391,17 @@ https://files.yourdomain.com/public/org_abc/listings/3f2a…-hero.jpg
|
|
|
379
391
|
Store that URL on the listing row. Send it to the public listing page. This is
|
|
380
392
|
the right model for property photos, avatars, and shareable media.
|
|
381
393
|
|
|
394
|
+
No session is required, but the request is not unconditional: the files worker
|
|
395
|
+
looks the key up in the metadata store and serves bytes only when a live
|
|
396
|
+
(not soft-deleted) object exists in a bucket whose `readScope` is `public`.
|
|
397
|
+
Anything else is a **404**, not a 403 — an anonymous caller must not be able to
|
|
398
|
+
probe for private keys. So a soft-deleted public object stops being served, and
|
|
399
|
+
a key that merely *starts with* `public/` proves nothing on its own.
|
|
400
|
+
|
|
401
|
+
Public responses still carry `Cache-Control: public, max-age=31536000,
|
|
402
|
+
immutable`, so a CDN or browser that already has the bytes keeps them. Soft
|
|
403
|
+
deletion is not a revocation mechanism for something already fetched.
|
|
404
|
+
|
|
382
405
|
### Session-gated private files
|
|
383
406
|
|
|
384
407
|
Private files require a valid Better Auth session cookie:
|
|
@@ -409,7 +432,9 @@ When file storage is configured, the compiler generates:
|
|
|
409
432
|
|------|---------|
|
|
410
433
|
| `src/storage/routes.ts` | Storage API routes (upload, presign, confirm, download) |
|
|
411
434
|
| `src/storage/presign.ts` | R2 presigned-URL signer (`createPresigner`, backs `ctx.storage`) |
|
|
412
|
-
| `src/files/schema.ts` | Files
|
|
435
|
+
| `src/files/schema.ts` | Files metadata schema (buckets, objects) — `sqliteTable` on D1, a `files` Postgres schema otherwise |
|
|
436
|
+
| `src/files/index.ts` | `createFilesDb` — the D1 binding handle, or the Postgres service-lane handle |
|
|
437
|
+
| `drizzle.files.config.ts` | Second migration target — **D1 only** |
|
|
413
438
|
| `cloudflare-workers/files/index.ts` | Files worker for serving |
|
|
414
439
|
| `cloudflare-workers/files/wrangler.toml` | Files worker config |
|
|
415
440
|
|
|
@@ -428,15 +453,20 @@ After compiling:
|
|
|
428
453
|
wrangler r2 bucket create my-app-files
|
|
429
454
|
```
|
|
430
455
|
|
|
431
|
-
2. **Create the files database
|
|
456
|
+
2. **Create the files database** — `cloudflare-d1` only. On Postgres the
|
|
457
|
+
metadata lives in the `files` schema of the database you already have:
|
|
432
458
|
```bash
|
|
433
459
|
wrangler d1 create my-app-files
|
|
434
460
|
```
|
|
435
461
|
|
|
436
462
|
3. **Run migrations:**
|
|
437
463
|
```bash
|
|
464
|
+
# cloudflare-d1
|
|
438
465
|
wrangler d1 migrations apply my-app-files --local
|
|
439
466
|
wrangler d1 migrations apply my-app-files --remote
|
|
467
|
+
|
|
468
|
+
# Postgres — the files schema is in the project's single journal
|
|
469
|
+
npm run db:migrate
|
|
440
470
|
```
|
|
441
471
|
|
|
442
472
|
4. **Deploy the API:**
|
|
@@ -450,6 +480,18 @@ After compiling:
|
|
|
450
480
|
wrangler deploy
|
|
451
481
|
```
|
|
452
482
|
|
|
483
|
+
`quickback deploy` ships the API Worker only and then prints this command —
|
|
484
|
+
managed file storage is two deployed Workers, and having shipped one but not
|
|
485
|
+
the other is a real state worth seeing.
|
|
486
|
+
|
|
487
|
+
On Postgres the files worker reads the **same** database over the **same**
|
|
488
|
+
transport as the API Worker: a `HYPERDRIVE` binding (already in its
|
|
489
|
+
`wrangler.toml`), or a `DATABASE_URL` secret you must also set on this
|
|
490
|
+
Worker:
|
|
491
|
+
```bash
|
|
492
|
+
cd cloudflare-workers/files && wrangler secret put DATABASE_URL # HTTP only
|
|
493
|
+
```
|
|
494
|
+
|
|
453
495
|
6. **Set the R2 presign secrets** only if you use signed PUT/GET. Public-bucket
|
|
454
496
|
uploads through `POST /object` do not need them. See
|
|
455
497
|
[Presigned uploads](#presigned-uploads):
|
|
@@ -459,15 +501,40 @@ After compiling:
|
|
|
459
501
|
wrangler secret put R2_SECRET_ACCESS_KEY
|
|
460
502
|
```
|
|
461
503
|
|
|
504
|
+
### Named environments deploy two Workers per target
|
|
505
|
+
|
|
506
|
+
A project with [named environments](/configure/domains) must name the files
|
|
507
|
+
Worker for every target. It is never derived: the script name is the deployed
|
|
508
|
+
identity, and Wrangler's `routes` key is inheritable, so a shared
|
|
509
|
+
`<project>-files` default would let `deploy --env dev` replace production's file
|
|
510
|
+
server and take its hostname.
|
|
511
|
+
|
|
512
|
+
```ts
|
|
513
|
+
environments: {
|
|
514
|
+
dev: { name: 'app-dev', filesWorker: { name: 'app-files-dev', domain: 'files-dev.example.com' }, /* … */ },
|
|
515
|
+
prod: { name: 'app', filesWorker: { name: 'app-files', domain: 'files.example.com' }, /* … */ },
|
|
516
|
+
}
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
The compile fails with the config path to fix when a target omits it, or when
|
|
520
|
+
two targets claim the same Worker name or hostname. Omitting
|
|
521
|
+
`filesWorker.domain` emits `routes = []` — the explicit workers.dev-only
|
|
522
|
+
opt-out. The files Worker reuses that environment's R2 bucket and database
|
|
523
|
+
bindings; it does not declare its own.
|
|
524
|
+
|
|
525
|
+
```bash
|
|
526
|
+
cd cloudflare-workers/files && npx wrangler deploy --env dev
|
|
527
|
+
```
|
|
528
|
+
|
|
462
529
|
## Configuration Reference
|
|
463
530
|
|
|
464
531
|
| Option | Type | Default | Description |
|
|
465
532
|
|--------|------|---------|-------------|
|
|
466
|
-
| `managed` | `boolean` | `false` | Opt into the
|
|
533
|
+
| `managed` | `boolean` | `false` | Opt into the metadata store + `/storage/v1/*` + files worker. Off = presign-only. |
|
|
467
534
|
| `bucketName` | `string` | `<project>-media` | R2 bucket the signer targets (override per-call with `signPutUrl(key, { bucket })`) |
|
|
468
535
|
| `presign` | `object` | - | Env-var name overrides: `{ accountIdEnv, accessKeyIdEnv, secretAccessKeyEnv, endpointEnv }` |
|
|
469
536
|
| `binding` | `string` | `R2_BUCKET` | R2 bucket binding name (managed mode) |
|
|
470
|
-
| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding (managed mode) |
|
|
537
|
+
| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding (managed mode, `cloudflare-d1` only — Postgres uses the `files` schema of the single database and emits no binding) |
|
|
471
538
|
| `maxFileSize` | `number \| string` | 10MB | Max upload size — bytes or `"100mb"` (managed mode) |
|
|
472
539
|
| `allowedTypes` | `string[]` | Images only | Allowed MIME types (managed mode) |
|
|
473
540
|
| `publicDomain` | `string` | - | Custom domain for files worker (managed mode) |
|
|
@@ -288,18 +288,62 @@ src/
|
|
|
288
288
|
|
|
289
289
|
### File Storage (R2)
|
|
290
290
|
|
|
291
|
-
When `fileStorage` is configured:
|
|
291
|
+
When `fileStorage` is configured, presign-only mode emits just the signer:
|
|
292
292
|
|
|
293
293
|
```
|
|
294
294
|
src/
|
|
295
|
-
└──
|
|
296
|
-
└──
|
|
295
|
+
└── storage/
|
|
296
|
+
└── presign.ts # R2 presigned-URL signer (backs ctx.storage)
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
`managed: true` adds the API routes, the metadata schema and a **second
|
|
300
|
+
deployed Worker** with its own `wrangler.toml`:
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
src/
|
|
304
|
+
├── routes/storage.ts # File upload/download endpoints
|
|
305
|
+
└── files/
|
|
306
|
+
├── schema.ts # buckets + objects
|
|
307
|
+
└── index.ts # createFilesDb
|
|
308
|
+
cloudflare-workers/
|
|
309
|
+
└── files/ # SECOND Worker — deployed separately
|
|
310
|
+
├── index.ts # public + session-gated file serving
|
|
311
|
+
└── wrangler.toml # its own name, bindings and routes
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
`cloudflare-workers/**` is included in the generated `tsconfig.json`, so
|
|
315
|
+
`npm run typecheck` covers both entrypoints.
|
|
316
|
+
|
|
317
|
+
Where the metadata lives, and therefore what else is emitted, depends on the
|
|
318
|
+
database provider:
|
|
319
|
+
|
|
320
|
+
| Provider | Metadata store | Extra output |
|
|
321
|
+
|---|---|---|
|
|
322
|
+
| `cloudflare-d1` | A second D1 database bound as `FILES_DB` | `drizzle.files.config.ts` + `quickback/drizzle/files/` |
|
|
323
|
+
| `neon`, `planetscale-postgres` | A `files` schema in the same Postgres database | none — the tables ride the single journal at `quickback/drizzle/` |
|
|
324
|
+
|
|
325
|
+
```
|
|
297
326
|
quickback/drizzle/
|
|
298
|
-
└── files/ # File metadata migrations
|
|
327
|
+
└── files/ # File metadata migrations — cloudflare-d1 only
|
|
299
328
|
├── meta/
|
|
300
329
|
└── 0000_*.sql
|
|
301
330
|
```
|
|
302
331
|
|
|
332
|
+
Under named environments the second Worker needs its own identity, declared per
|
|
333
|
+
target and never derived — a shared default would make `deploy --env dev`
|
|
334
|
+
overwrite production's file server, and Wrangler's inheritable `routes` would
|
|
335
|
+
take its hostname with it:
|
|
336
|
+
|
|
337
|
+
```ts
|
|
338
|
+
environments: {
|
|
339
|
+
dev: { name: 'app-dev', filesWorker: { name: 'app-files-dev', domain: 'files-dev.example.com' }, /* … */ },
|
|
340
|
+
prod: { name: 'app', filesWorker: { name: 'app-files', domain: 'files.example.com' }, /* … */ },
|
|
341
|
+
}
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Omitting `filesWorker.domain` emits `routes = []` for that target — the explicit
|
|
345
|
+
workers.dev-only opt-out, so it cannot inherit a sibling's hostname.
|
|
346
|
+
|
|
303
347
|
### Webhooks
|
|
304
348
|
|
|
305
349
|
When webhooks are enabled:
|
|
@@ -462,7 +506,7 @@ The CLI loads migration meta JSON from one location only — `<project>/quickbac
|
|
|
462
506
|
|
|
463
507
|
- `quickback/drizzle/auth/meta/`
|
|
464
508
|
- `quickback/drizzle/features/meta/`
|
|
465
|
-
- `quickback/drizzle/files/meta/`
|
|
509
|
+
- `quickback/drizzle/files/meta/` (cloudflare-d1 managed file storage)
|
|
466
510
|
- `quickback/drizzle/webhooks/meta/`
|
|
467
511
|
- `quickback/drizzle/audit/meta/`
|
|
468
512
|
- `quickback/drizzle/meta/` (single-database mode)
|