Neon

Neon provides serverless PostgreSQL for Cloudflare Workers. Choose it when the application is designed around PostgreSQL: native JSONB and arrays, tsvector with GIN indexes, PostGIS or other extensions, sustained concurrent writes, or database-level Row Level Security alongside the generated Hono API. D1 also supports JSON functions and FTS5; Neon is the choice when the PostgreSQL implementation and ecosystem are the requirement.

Why Neon

• Full PostgreSQL — Advanced queries, joins, PostGIS, full-text search
• Database-level security — RLS policies enforce access even if the API is bypassed
• Serverless — HTTP connection mode (@neondatabase/serverless) for Cloudflare Workers
• Worker-scoped RLS — the Worker verifies each caller, then writes the trusted user/org/team context into transaction-local Postgres settings that RLS policies read (see How Worker-scoped RLS works)
• Better Auth integration — Works seamlessly with the Quickback auth provider

One database for auth and features

Quickback uses a single database provider per app. On Neon, Better Auth tables and feature tables live in the same Postgres database: Better Auth runs on its PostgreSQL/Drizzle adapter, and everything connects through one DATABASE_URL. There is no AUTH_DATABASE_URL, and split-database mode is a D1-only option.

In Hyperdrive mode the same one-database rule holds, but the Worker connection comes exclusively from env.HYPERDRIVE.connectionString: feature queries and Better Auth share the generated database helpers. DATABASE_URL is then a compiler/migration input, not a deployed Worker secret.

Where the tables go

One Neon project hosts one app, and that app uses the project's existing database (neondb by default). Quickback's migrations create schemas inside it — app for feature tables, auth for Better Auth, plus webhooks, audit and drizzle when the project uses them.

Do not CREATE DATABASE per app inside a project. Postgres roles are cluster-wide but grants, ownership and the migration ledger are per-database, so an extra database silently splits the bootstrap: the roles look right in pg_roles while the grants live somewhere the Worker never connects to. Point DATABASE_URL at the project's own database and let the schemas do the separating. Two apps means two Neon projects, not two databases.

Mixing providers — for example D1 for auth with Neon for features — is not supported. The per-service config form is rejected at compile time:

providers.database service-map form is not supported in v2.
Configure one database provider; auth and feature data use the same database.

Configuration

import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";

export default defineConfig({
  name: "my-app",
  providers: {
    runtime: defineRuntime("cloudflare"),
    database: defineDatabase("neon", {
      connectionMode: "auto",  // detects runtime
      pooled: true,
    }),
    auth: defineAuth("better-auth"),
  },
});

Connection modes

On the Cloudflare runtime, auto resolves to HTTP — batch-only, no binding, and the mode the rest of this page assumes. Opt a project up to connectionMode: 'hyperdrive' when its actions need real interactive transactions (see Interactive transactions).

Named Cloudflare deployment environments

Neon Hyperdrive projects can declare isolated Worker targets under environments. A logical dev / prod pair on a project named attend-v2 deploys through Wrangler as attend-v2-dev and attend-v2-prod:

export default defineConfig({
  name: "attend-v2",
  email: { provider: "cloudflare", from: "hello@attend.vip" },
  bindings: {
    secrets: [
      { name: "EVENT_PASS_HMAC_PEPPER_V1", required: true },
    ],
  },
  providers: {
    runtime: defineRuntime("cloudflare"),
    database: {
      name: "neon",
      config: {
        connectionMode: "hyperdrive",
        hyperdrive: { id: "ffffffffffffffffffffffffffffffff" },
      },
      environments: {
        dev: {
          // Wrangler worker name — required on every target, never derived.
          name: "attend-v2-dev",
          branch: "dev",
          worker: {
            env: "dev",
            workersDev: true,
            previewUrls: false,
            vars: {
              ENVIRONMENT: "dev",
              BETTER_AUTH_URL: "https://attend-v2-dev.example.workers.dev",
            },
            requiredSecrets: [
              "BETTER_AUTH_SECRET",
              "EVENT_PASS_HMAC_PEPPER_V1",
            ],
            bindings: {
              hyperdrive: {
                id: "11111111111111111111111111111111",
                localConnectionString: "postgresql://quickback:dev-only@127.0.0.1:5432/attend_v2",
              },
              kv: { id: "22222222222222222222222222222222" },
              rateLimits: {
                RL_200_60: "61001200",
                RL_1000_60: "61002000",
              },
              sendEmail: { name: "EMAIL" },
            },
          },
        },
        prod: {
          name: "attend-v2",
          branch: "production",
          worker: {
            env: "prod",
            workersDev: true,
            previewUrls: false,
            vars: {
              ENVIRONMENT: "prod",
              BETTER_AUTH_URL: "https://attend-v2-prod.example.workers.dev",
            },
            requiredSecrets: [
              "BETTER_AUTH_SECRET",
              "EVENT_PASS_HMAC_PEPPER_V1",
            ],
            bindings: {
              hyperdrive: { id: "33333333333333333333333333333333" },
              kv: { id: "44444444444444444444444444444444" },
              rateLimits: {
                RL_200_60: "62001200",
                RL_1000_60: "62002000",
              },
              sendEmail: { name: "EMAIL" },
            },
          },
        },
      },
    },
    auth: defineAuth("better-auth"),
  },
});

Wrangler bindings and variables are non-inheritable. Quickback therefore emits the generated vars, required-secret declaration, Hyperdrive, KV, rate-limit, and Cloudflare Email blocks inside every [env.<name>] target. The base Worker carries no deployable stateful binding and has workers_dev = false / preview_urls = false, so a bare deploy cannot accidentally point at shared or placeholder state.

The environment contract is intentionally exact and fails closed:

• workersDev: true and previewUrls: false must be explicit for each target.
• Each target declares its own name (the Wrangler worker name) and no two share one. It is the deployed script's identity — Durable Object state and the migration ledger belong to it — so it is never derived. An existing project must restate the name it already deploys under.
• The auth provider must currently be Better Auth. External auth needs a non-inheritable service binding, so it remains rejected until named targets can require an explicit per-environment service-binding override.
• Hyperdrive and KV IDs must be real 32-character Cloudflare resource IDs and cannot be reused between environments.
• Named environments must include a logical dev target. It is selected by npm run dev and must own a bindings.hyperdrive.localConnectionString. Quickback emits that development-only URL only inside its named Hyperdrive block and rejects it on every other target, so prod always resolves its deployed connection from the remote Hyperdrive ID.
• rateLimits must contain exactly the binding names generated by the current feature set, with account-unique integer namespace IDs. Add or remove a rate limit and the next compile tells you which override changed.
• requiredSecrets must exactly match the generated runtime inventory: BETTER_AUTH_SECRET, a custom auth.jwt.secretEnv when configured, ENCRYPTION_KEK when envelope-encrypted columns are present, and every custom secret declared with required: true. It also includes the shared AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY credentials when generated Better Auth code uses SES, SNS, or AWS-backed anonymous-account upgrades; every enabled social provider's AUTH_<PROVIDER>_CLIENT_ID and AUTH_<PROVIDER>_CLIENT_SECRET; plus the configured R2 account/access/secret env names when presigned uploads are enabled. Values remain out of source control; set them with wrangler secret put <NAME> --env dev (and again for prod).
• Include sendEmail: { name: "EMAIL" } when the generated runtime uses Cloudflare Email Service; omit it when email is not generated.
• Every queue and R2 bucket the config generates needs a per-target entry under bindings.queues / bindings.r2Buckets, with names unique across targets — see Queues and R2 buckets per target.
• Custom domains and routes are owned per target. Quickback emits no top-level routes block for a named-environment project — Wrangler inherits that key, so a shared block would let deploy -e dev rebind the production hostname — and every generated source (providers.runtime.config.routes, domain, CMS/Account/Admin domains, auth.domain, api.domain, app domains and their aliases, and the derived webhook.{baseDomain} route) must be claimed by each environment through domains. The unified quickback.{baseDomain} host is inferred per target as quickback-<env>.{baseDomain}, overridable with domains.primary. See Named Environments for the key-by-key mapping, the single-hostname domain shorthand, and the domains: 'none' workers.dev-only opt-out.

Generated npm run dev selects the dev target (wrangler dev --env dev). Quickback omits the bare deploy script for named-environment projects and generates explicit npm run deploy:dev / npm run deploy:prod scripts. Each maps to its configured Wrangler environment. Apply that branch's migrations first; migrations intentionally remain a separate target-owned step.

Projects that omit environments retain the existing wrangler.toml and package scripts byte-for-byte. Named environments require Better Auth, plus either Neon with connectionMode: "hyperdrive" (this page) or Cloudflare D1 (see Named deployment environments). Quickback rejects other providers or partial binding sets instead of emitting a Worker that can deploy but fail at runtime.

Environment variables

HTTP mode has three connection points, each read by a different tool:

The compiler emits .env.neon.example and .dev.vars.example as templates, and gitignores .dev.vars so local secrets are never committed.

# Migrations read .env — copy the template and fill it in:
cp .env.neon.example .env
# .env holds:
#   DATABASE_URL           — pooled quickback (runtime) role URL
#   DATABASE_MIGRATION_URL — unpooled quickback_admin role URL (optional)

# wrangler dev reads .dev.vars (NOT .env) — copy the template:
cp .dev.vars.example .dev.vars   # gitignored; holds DATABASE_URL + BETTER_AUTH_SECRET

# Production: secrets live in Worker secrets, never in files:
npx wrangler secret put DATABASE_URL       # pooled quickback role URL
npx wrangler secret put BETTER_AUTH_SECRET

DATABASE_URL is the only connection string the Worker needs at runtime — auth and feature queries share it. DATABASE_MIGRATION_URL is used only by drizzle-kit: the generated drizzle.config.ts reads process.env.DATABASE_MIGRATION_URL ?? process.env.DATABASE_URL, so migrations run as the privileged quickback_admin role when it is set and fall back to DATABASE_URL when it is not. Never deploy DATABASE_MIGRATION_URL to the Worker.

Hyperdrive runtime credentials

With connectionMode: "hyperdrive", do not deploy DATABASE_URL to the Worker. Configure the HYPERDRIVE binding with query caching disabled and keep DATABASE_URL / DATABASE_MIGRATION_URL only in the compiler or CI environment for Drizzle schema generation and migrations. Better Auth and feature queries both use Hyperdrive at runtime, eliminating a second direct Neon connection lane.

For local wrangler dev without named environments, set providers.database.config.hyperdrive.localConnectionString to a local or development-only Postgres URL. With named environments, put it on the target selected by the generated local dev script instead:

environments: {
  dev: {
    worker: {
      bindings: {
        hyperdrive: {
          id: "11111111111111111111111111111111",
          localConnectionString: "postgresql://quickback:dev-only@127.0.0.1:5432/attend_v2",
        },
      },
    },
  },
}

Quickback requires the logical dev target, rejects the top-level local override when named environments exist, and rejects localConnectionString on staging or production targets. Wrangler uses this field only for local development; deployed Workers obtain their connection string from the Hyperdrive configuration identified by id.

Better Auth schema generation

src/auth/schema.ts is a compiler-owned artifact derived with the Better Auth CLI during quickback build. The generated build script is deliberately read-only with respect to generated source:

quickback build     # regenerates src/auth/schema.ts and the project output
npm run build        # runs tsc only; does not rewrite generated files

For schema-generator diagnostics, the explicit auth:schema command expands to:

npx better-auth generate --config ./src/lib/auth.ts --output ./src/auth/schema.ts --yes \
  && node scripts/quickback-qualify-auth-schema.mjs

The better-auth executable comes from the auth devDependency in the generated package.json — that's the Better Auth CLI package (the better-auth runtime package ships no bin).

The qualifier script adjusts the CLI output for Postgres schema placement. auth:schema produces the intermediate Better Auth output and may remove Quickback's generated-file envelope. Do not commit that intermediate file; rerun quickback build to restore the canonical project bytes. Don't hand-edit src/auth/schema.ts.

Recompiling also replaces previously generated package.json lifecycle commands with their current definitions. An existing project whose build script still runs auth:schema therefore converges to the TypeScript-only build, while unrelated custom scripts remain intact.

Better Auth's tables stay vanilla Better Auth

Better Auth's own API is the authorization gate for its tables. Quickback does not reimplement that gate in SQL — no policy re-derives membership, checks a role, or splits by verb. What the compiler adds is the same backstop every feature table gets, so a leaked DATABASE_URL or a mis-scoped handle cannot read another user's or another organization's auth rows:

Reads are tenant/self scoped; writes go through Better Auth only. The scope policy is FOR SELECT with a USING clause and no WITH CHECK, so the caller lane can read these rows and change none of them — a handle cannot set its own member.role. Better Auth's adapter always stamps the service marker, so every write it makes runs on the service lane. The predicate:

Everything else is service-only — deny-anon plus the bootstrap lane is the entire policy set, and no caller-scoped handle can read a row either: verification, jwks, the Better Auth rate-limit counters, device_code, the oauth_* provider tables and the agent_* / approval_request agent-auth tables. Better Auth's own adapter always stamps the service marker, so its reads and writes never consult any of this; the policies exist for the handles that are not Better Auth.

A table with no obvious scope column is service-only by construction. The compiler will not invent a predicate for one — it fails closed.

Migrations

Neon uses PostgreSQL migrations, distinct from D1's SQLite migrations. One Drizzle journal covers auth tables, feature tables, indexes, FK/cascade semantics, and the RLS layer:

quickback build      # generates migrations under quickback/drizzle/
npm run db:migrate     # applies schema AND the RLS layer, in order

The RLS layer (helper functions, policies, triggers) rides the same journaled migration set as your schema: the compiler appends a content-addressed <idx>_quickback_rls_<hash> migration, so one db:migrate applies everything in order. The RLS migration is idempotent (DROP POLICY IF EXISTS + re-create) and only a changed security config appends a new entry — recompiles with unchanged security append nothing. No manual SQL application step exists.

The default index set

Indexes are Drizzle's, not the security migration's: the compiler writes the default set (tenant composite, FK columns, filtered columns, view-sortable columns) into the schema source, so drizzle-kit generates and diffs them under <table>_<column>_idx names. See The default index set for the rules and the ...q.indexes(t) placeholder.

Older projects also carry idx_<table>_<column> copies the security migration used to create. Those are dropped in the security migration's trailing "retired indexes" section, which the journal runs after the schema migration that created the replacements. Only idx_* names are dropped.

Quickback also dependency-orders Drizzle's standalone constraint replacements. When a composite unique or primary key and its consuming foreign key are both replaced, the generated migration drops the dependent foreign key first, drops and recreates the referenced key, then recreates the foreign key. This avoids Postgres 2BP01 dependency failures without CASCADE and without requiring a hand-edited migration. Already-correct migrations remain byte-identical.

Cross-schema and composite relationships that cannot live in one generated Drizzle schema may be declared with compiler.migrations.foreignKeys. Quickback appends them to that same content-addressed migration after the schema tables and target unique keys exist. Declarations are deterministic and replay-safe: an existing constraint must match exactly, while existing orphan rows fail the VALIDATE CONSTRAINT step. Foreign keys enforce integrity only; keep authorization and business state transitions in the API action layer.

How Worker-scoped RLS works

Quickback does not send browser or mobile clients directly to Neon, and it does not use Neon Authorize / a JWKS endpoint. Clients authenticate with the Cloudflare Worker; the Worker verifies the Better Auth session or API key, runs the access checks, and then performs the database call as a trusted proxy.

For every feature-table query, the generated database client opens a claims-scoped transaction (an implicit Neon HTTP batch or a Hyperdrive transaction) whose first statement writes the verified caller context into transaction-local Postgres settings:

-- Injected by the Worker as the batch's first statement (is_local = true):
SELECT
  set_config('quickback.service_role',      '',        true),
  set_config('request.jwt.claim.sub',       'usr_123', true),
  set_config('request.jwt.claim.org_id',    'org_abc', true),
  set_config('request.jwt.claim.team_id',   '',        true),
  set_config('quickback.principal.type',       '',     true),
  set_config('quickback.principal.actor_type', '',     true),
  set_config('quickback.principal.actor_id',   '',     true),
  set_config('quickback.principal.session_id', '',     true),
  set_config('quickback.principal.family_id',  '',     true),
  set_config('quickback.principal.claims',     '{}',   true);

RLS policies read those settings through Quickback-defined helper functions — there is no external JWT verification and no persisted session state in the database. auth.user_id() is a compiler-generated shim, not a Neon Authorize function:

-- Generated by Quickback (granted to the quickback runtime role):
CREATE OR REPLACE FUNCTION auth.user_id()
RETURNS TEXT AS $$
  SELECT NULLIF(current_setting('request.jwt.claim.sub', true), '')
$$ LANGUAGE SQL STABLE SET search_path = public;

Because the settings are transaction-local (set_config(..., true)), they apply only to the current batch and never leak between requests. If the Worker never stamps a user id, auth.user_id() returns NULL and the restrictive deny_anon policy blocks the query unless a verified delegated principal is present — fail closed. Account requests explicitly clear all principal fields; delegated requests explicitly clear the account/org/team fields.

An API key's organization metadata is only a candidate scope. Before the middleware stamps it into AppContext, the generated Neon membership lookup opens a request-scoped database handle with the verified API-key owner as userId and the candidate organization as orgId, then requires the member row to match both values. A missing or RLS-denied row clears organization and role authority.

Row Level Security

Generated RLS is a backstop, not a second copy of access. Every database call goes through the API, and the API owns roles, status, transitions and masking. RLS exists so that a bug in a custom route, or a handle that escaped its scope, cannot cross a tenant, resurrect a soft-deleted row, or read another owner's row. It is the floor under the application, not a second application.

Quickback lowers your firewall config — and only your firewall config — into policies that read the transaction-local claims described above through auth.user_id(), get_active_org_id(), get_active_team_id(), get_scope() and the get_principal_*() helpers. Each feature table gets exactly three policies, plus a fourth only where a delegated-principal lane is declared:

The fence is per-lane, not per-table, because on a table no principal can reach it would read get_principal_type() IS NULL — blocking every principal, which is exactly what leaving them out of deny_anon already does. Two policies for one outcome; the compiler emits neither.

Every helper call inside a policy predicate is emitted as (SELECT …). The claims are transaction-local and stamped before the statement, so PostgreSQL hoists the call into an InitPlan and evaluates it once per statement instead of once per scanned row.

firewall: [
  { field: 'organizationId', equals: 'ctx.activeOrgId' },
]

CREATE POLICY "documents_scope"
ON "app"."documents" FOR ALL
TO quickback
USING (
  organization_id = public.get_active_org_id()
  AND (deleted_at IS NULL OR public.in_soft_delete())
)
WITH CHECK (
  organization_id = public.get_active_org_id()
);

The soft-delete lane

deleted_at IS NULL keeps soft-deleted rows out of every caller's reach. On its own it also blocks the delete that put them there.

PostgreSQL applies a SELECT-applicable policy's USING expression to the new row of an UPDATE, not only the existing one, whenever the statement reads the relation — which any UPDATE … WHERE does. The new row of a soft delete has deleted_at set, so a bare deleted_at IS NULL refuses the statement with 42501, including the generated DELETE route's own write. Moving the filter to a FOR SELECT policy does not help, and neither does dropping RETURNING: the check follows the filter wherever it goes.

So the filter carries a lane. public.in_soft_delete() reads the transaction-local quickback.soft_delete marker, and the generated write chokepoint sets it for exactly the statement whose payload stamps deletedAt — the same condition that stamps the audit columns. It is a one-shot token: the claims preamble carries it into that statement's transaction and clears it, so the next statement of the same request runs without it.

It is the same trust model as the service marker: Worker-set, never derived from request input. And it is narrower — it exempts the soft-delete filter and nothing else. Tenancy, ownership and scope stay ANDed beside it, so a statement inside the window still cannot cross a tenant; WITH CHECK never carries the lane, so it cannot land a row the firewall rejects; and the emitted statement keeps deleted_at IS NULL in its own WHERE, so it cannot resurrect one.

Exception tables (firewall: [{ exception: true }]) keep their permissive <table>_all policy, and SYSTEM tables — idempotency keys, the webhook store, Better Auth rate-limit counters, subscriptions, file metadata — stay service-role only.

Better Auth's own tables carry the same backstop, in its two- or three-policy form: see Better Auth's tables stay vanilla Better Auth.

What is deliberately not in SQL

Roles, status, transitions, masking and per-operation access are not lowered into policies. That is a decision, not a gap:

• Roles. access.roles names your application's vocabulary. Mirroring it into SQL made every role rename append a security migration, and left two enforcement points that could disagree — with the SQL copy being the one nobody reads. The API is the single gate.
• Status and transitions. A policy sees one row and no request context, so it cannot express "an archived invoice may only move to restored, by the route that logs the transition". A half-expressed rule in SQL is worse than no rule in SQL.
• Masking. Masking shapes a response. RLS decides which rows a caller may touch, never which columns come back redacted.
• Per-operation access. One FOR ALL scope policy is the same fence for every verb. Four near-identical policies only made the tenant predicate harder to read and easier to get subtly wrong in exactly one of them.

The consequence is intentional: at the SQL layer, a caller whose organization role is member can update a same-org row. The route they would have to call still refuses them, and anything reaching the database outside a generated route holds a caller-scoped handle whose tenant is already fenced.

The compiler enforces the shape at compile time. QB-RLS-SCOPE-POLICY requires the three policies (and the fence wherever a delegated lane exists — and only there), requires a tenant/owner/scope predicate in the scope policy's USING clause, and fails the build if any policy body calls has_any_role. Opt out with compiler.securityContracts.rls.requireScopePolicy: false — requireCrudPolicies is the pre-016 name for the same key and is still honoured.

Upgrading an existing database

An existing project gets one appended quickback_rls security migration on its next compile. It runs DROP POLICY IF EXISTS on the retired names before creating the new ones, so the upgrade is append-only: prior migration files keep their bytes and their journal hashes, and a second unchanged compile appends nothing.

Apply it with the setup-owner credential, not quickback_admin. The security migration reissues the helper functions, and PostgreSQL refuses that to a role that does not own them (42501 must be owner of function ...) — the same requirement that already applies to any changed security or bootstrap SQL.

The same migration also drops the five helper functions the generated policies no longer reference — has_any_role, has_org_role, get_user_role, is_owner and is_org_member — after the policy statements that stop referencing them. Membership is proven by the Worker and stamped as the request org, so nothing re-derives it in SQL.

The retired names include the per-verb auth-table policies (users_select, members_insert, …) that older projects carry. They are dropped, so an upgraded database converges on the narrower set rather than keeping a wider policy nobody emits any more.

Indexes are rebuilt once. The compiler used to infer idx_<table>_<column> indexes in the security migration, alongside the <table>_<column>_idx indexes Drizzle generates from the schema. Drizzle now owns the whole default set, so the schema migration creates the drizzle-managed index and the security migration that follows it in the journal drops the compiler-owned copy — the two overlap for the length of one db:migrate run and nothing is ever left unindexed. Only idx_* names are dropped; a drizzle-managed index is never touched. See the default index set.

Delegated principal RLS

Delegated principals require Cloudflare + Neon Hyperdrive. Their proof hook returns only a digest and receives no database handle. Quickback then runs one lookup under an internal lookup-only principal whose RLS policy admits only the configured table row matching credentialDigest, plus any configured active status condition. The generated unique lookup index is content-addressed: a changed table, digest column, or definition drops the prior logical index and creates the exact replacement. Names are hash-suffixed to avoid collisions and remain inside PostgreSQL's 63-byte identifier limit.

After the lookup, the normal request database handle carries the resolved principal type, actor, optional session/family, and JSON claims in the same transaction-local preamble shown above. RLS reads them with:

Generated request types are a closed union of the configured principal names, literal actor types, exact session shape, and configured claim keys. The Neon database context uses the same resolved union plus separate compiler-internal __credential_lookup__:<type> variants. Lookup-only authority therefore cannot appear in an action AppContext, and a delegated action context cannot carry account/org/team/membership fields.

resource.databaseAccess opens a delegated-principal lane at the database: RLS only, no generic routes and no OpenAPI operations. It exists because a delegated principal has no account identity — no userId, no active organization, no membership roles — so the table's ordinary firewall predicate can never match for it. The lane is the row rule that can: the principal's own verified claims, read through get_principal_claim().

// The account lane is the FIREWALL. The delegate lane is databaseAccess.
firewall: [
  { field: "organizationId", equals: "ctx.activeOrgId" },
],
databaseAccess: {
  select: {
    principals: ["event_delegate"],
    record: {
      eventId: { equals: "$ctx.principal.claims.eventId" },
      personId: { equals: "$ctx.principal.claims.personId" },
    },
  },
}

That emits exactly one permissive policy on the table:

CREATE POLICY "attendance_evidence_principal_scope"
ON "app"."attendance_evidence" FOR SELECT TO quickback
USING (public.get_principal_type() = 'event_delegate'
   AND "event_id" = public.get_principal_claim('eventId')
   AND "person_id" = public.get_principal_claim('personId'));

Several principal types on one table are several OR arms of that same policy, never several policies. Postgres ANDs the record comparisons inside each arm.

The policy's command is the lane's declared reach: FOR SELECT with no WITH CHECK when only databaseAccess.select is declared, FOR ALL with the same predicate as WITH CHECK as soon as any of insert / update / delete is. Whether a delegate lane may write is a property of the lane, declared once by the author, so the database enforces it as the policy's command; WHICH verb a caller may reach is still the API's decision.

The lane lowers principals + record and nothing else. Two shapes are compile errors, with the same message: roles anywhere (authored roles are enforced by the API and never reach SQL, so a role arm here promised an authorization the database did not enforce), and a record equality with no principals gate (that is an owner/tenant rule, and those belong in firewall, the one pillar that lowers to SQL). Every authorization path must still carry at least one SQL-lowerable record equality; an unbounded or arm or a principal-only leaf fails the compile.

The policy is permissive, and PostgreSQL ORs permissive policies together, so databaseAccess opens a lane beside <table>_scope rather than narrowing it — that is the point (the delegated caller has no active organization, so the tenant predicate can never match), but it means a databaseAccess arm is never a place to write a restriction. A row that satisfies the arm is reachable even when the table firewall would not have matched it, and even when it is soft-deleted. Write the restriction in firewall; the restrictive <table>_deny_anon and, where a lane is declared, <table>_principal_fence are the only arms that cap every lane. The fence also means a table admits a principal type only where its access (or its lane) names that type — a ctx.principal.claims.* firewall arm on a table whose access names no principal is unreachable.

Firewall patterns

Every pattern is the same one FOR ALL scope policy with a different predicate — no per-operation variants, no role arms.

Organization-scoped:

CREATE POLICY "projects_scope" ON "app"."projects" FOR ALL TO quickback
USING (organization_id = public.get_active_org_id())
WITH CHECK (organization_id = public.get_active_org_id());

User-scoped (owner_id, the auto-firewalled ownership column):

CREATE POLICY "preferences_scope" ON "app"."preferences" FOR ALL TO quickback
USING (owner_id = auth.user_id())
WITH CHECK (owner_id = auth.user_id());

Exception tables (firewall: [{ exception: true }]) — no scope predicate, so the restrictive deny-anon policy is the only fence left:

CREATE POLICY "categories_all" ON "app"."categories" FOR ALL TO quickback
USING (true) WITH CHECK (true);

Helper functions

There is no role-lookup helper and no membership helper. Roles are the API's gate, not SQL's: QB-RLS-SCOPE-POLICY fails the build if any policy body calls has_any_role. Membership is Better Auth's gate: the Worker proves it once and stamps the active organization, and policies compare against that stamp.

is_admin() is no part of that gate either. Enabling the admin plugin does not widen any scope policy: "admin" is a role, and a scope policy is the firewall predicate, full stop. An admin's cross-tenant read goes through the API on the service lane — an unsafe: { crossTenant: true } action stamps quickback.service_role, which <table>_service_role admits — not by SQL re-deriving admin from auth.admins. Older databases carry the previous (public.is_admin() OR (…)) form until the new security migration replaces those policies; it does, in the same append-only pass.

All helpers are TEXT-typed to match Better Auth's prefixed ids (org_abc123). The request org/team scope is passed by the Worker per transaction, not read from a persisted mirror. There is no compiler-owned user_sessions table and no session hook that syncs the active organization into the database — switching to "no org" simply means the Worker stamps an empty request.jwt.claim.org_id, and SQL-side access is revoked immediately. Fail closed.

The only compiler-owned support tables the RLS layer reads live in src/db/rls-support.schema.ts: a profiles table (populated by the sync_profile_display_name() trigger and protected by profiles_deny_anon plus a self-scoped, read-only profiles_scope) and, when admin/sysadmin helpers are emitted, an admins table (read by is_admin() / is_sysadmin()). Better Auth's own sessions table may still carry an active_organization_id, but Quickback RLS never reads it.

RLS coverage includes Better Auth's own tables — including those the compiler force-enables (organization, admin, apikeys; plus the OAuth/agent table families when those surfaces are on, which are service-only). Database-backed Better Auth rate-limit counters also receive both ENABLE and FORCE ROW LEVEL SECURITY. Only the internal auth service context can read or change those counters; ordinary caller claims grant no access. See Better Auth's tables stay vanilla Better Auth for the exact policy set per table. Cloudflare uses database counters by default. Explicit memory storage or inactive rate limiting does not generate policies for a missing counter table.

For existing databases, recompile and apply the newly appended security migration using the setup-owner credential, as required for changed security/bootstrap SQL, to protect existing counters. Applied migration files stay unchanged and existing counter rows are preserved.

Background jobs and cross-tenant actions

Some code runs with no HTTP request and therefore no caller claims: queue consumers, cron schedules, and cross-tenant unsafe actions. These acquire the service-role handle createServiceDb(env) from the generated src/db index. Instead of caller claims, it sets quickback.service_role = 'true' (with all request claims cleared) — the same marker the Better Auth adapter's transactions use. Every feature table carries a <table>_service_role RLS policy that admits exactly that context, so background work can reach rows across tenants while the request-scoped createDb() client stays caller-scoped.

The service-role marker is only ever set by Worker-internal chokepoints (createServiceDb, the Better Auth adapter) — it is never derived from request input. Unsafe actions keep their mandatory audit contract: cross-tenant writes still land audit events (the audit Postgres schema), unchanged from D1.

Reads through a user-anchored relationship

Some resources are readable not because you own them or belong to their org, but because you are reachable from them through a chain of tables anchored on the caller's user id. A conference attendee, for example, can read their own registrations even though they are not an org member — the grant travels person_account_links.user_id = ctx.userId → people → event_people → registrations.

Declare the chain once as an authz.relationships entry using the hops form (each hop names the joined table, the column it is joined on, and the prev column on the previous table that points at it). The terminal hop's table is the anchor — the table carrying the caller's user id:

// quickback.config.ts
authz: {
  relationships: {
    attendeeReachable: {
      from: 'person_account_links',            // the anchor table
      subject: { column: 'userId', equals: 'ctx.userId' },
      resource: { column: 'eventPersonId' },   // the column on the resource this constrains
      hops: [
        { table: 'event_people', on: 'id', prev: 'eventPersonId' },
        { table: 'people',       on: 'id', prev: 'personId' },
        { table: 'person_account_links', on: 'personId', prev: 'id' },
      ],
    },
  },
},

A resource opts into the grant by referencing the relationship from its firewall — typically as one arm of an any: group so org members keep their own path in:

// features/registrations/registrations.ts
firewall: [
  {
    any: [
      { field: 'organizationId', equals: 'ctx.activeOrgId' }, // org-member grant
      { field: 'eventPersonId',  via: 'attendeeReachable' },  // reachable-attendee grant
    ],
  },
],

The anchor must be non-forgeable (fail closed on both targets)

The reachability chain terminates in anchor.user_id = ctx.userId, so whoever can write an anchor row can mint themselves reachability to a victim's data. Quickback therefore refuses to compile a user-anchored multi-hop relationship unless the anchor table is:

• caller-read-own on the subject column — its firewall scopes reads to ctx.userId (e.g. firewall: [{ field: 'userId', equals: 'ctx.userId' }]), and
• service-role-write-only — it exposes no caller-reachable create / update / delete endpoint, so the link can only be created by Worker-internal code.

This check is target-independent: it fires identically on Neon and D1, because the reachability join runs in the app layer on both. A forgeable anchor is a compile error everywhere, not a Neon-only concern.

How the read is served

On Neon, a via-relationship reachability predicate cannot be expressed as an RLS policy — the correlated multi-hop join reaches across intermediate tables that each FORCE ROW LEVEL SECURITY, so caller-claims RLS would deny the attendee to zero rows before the app-layer WHERE ever runs. Quickback resolves this by routing that resource's read handlers through the service-role handle (createServiceDb(c.env)) instead of the caller-claims client. RLS stops denying, and the compiled buildFirewallConditions(...) reachability WHERE — the exact same clause D1 uses — becomes the sole row filter.

This is the D1 trust model, applied to Neon for exactly these reads: the application layer is the firewall, and RLS is a coarse tenant backstop that steps aside where it cannot express the grant. It is surgical and fail-closed:

• Only the affected resource's reads swap handles. Org / owner / team reads keep caller claims + the RLS backstop — they resolve to policies RLS can express.
• The swap is gated on a non-empty firewall carrying the reachability predicate; a service-handle read with no WHERE is a compile error (it would return every tenant's rows). Fail closed.
• It applies to the collection GET /, GET /:id, and views alike. Writes are unchanged — creates/updates/deletes keep caller claims and the RLS backstop.

The same config compiles identically on D1, where there is no RLS to bypass: the read handlers keep c.get('db') and the app-layer reachability WHERE was already the whole story.

Webhooks on Neon

Webhooks are supported on Neon over HTTP. The store (webhook_events, webhook_endpoints, webhook_deliveries) lives in a dedicated webhooks Postgres schema of the same database — following the audit schema precedent — so there is no separate WEBHOOKS_DB binding.

• Set webhooksBinding to enable webhooks. On Neon its value is a pure enable flag (no D1 binding is emitted); the queue names stay provider-neutral.
• The D1-only keys webhooksDatabaseId and webhooksDatabaseName are rejected at compile time — they name a D1 database that cannot exist on Neon.
• The webhook store is Worker-internal (endpoint signing secrets live there): every table in the webhooks schema has RLS enabled with a single service-role-only policy, so only createWebhooksDb() (which wraps createServiceDb) can touch it. Route handlers gate access at the app layer (requireOrgMember / endpoint-ownership checks) before querying.
• Webhooks require connectionMode: 'http'.

Managed file storage on Neon

fileStorage: { managed: true } is supported on http and hyperdrive. The file metadata (buckets, objects) lives in a dedicated files Postgres schema of the same database — the webhooks precedent again — so there is no FILES_DB binding, no second drizzle config and no second migration target.

• The tables ride the project's single journal, reached through the src/db/schema.ts barrel.
• Column shapes are 1:1 with the D1 version so no /storage/v1/* body changes: ISO-8601 date strings, JSON-encoded role and MIME lists, the same object keys and the same soft-delete column. The one divergence is numeric width — size and file_size_limit are bigint, because a Postgres integer would cap objects at 2 GiB.
• The store is a SYSTEM table: RLS is enabled and forced with a single service-role policy, so only createFilesDb() (which wraps createServiceDb) can read or write it. There is no caller-scope policy and no role arm — public-versus-private file access is decided by the /storage/v1/* routes and the file-serving Worker before the handle is used, exactly as it was against the D1 binding.
• The file-serving Worker reads the same database over the same transport: a HYPERDRIVE binding on Hyperdrive projects, or the same DATABASE_URL secret on HTTP projects — set on that Worker too. Never a mix of the two.
• connectionMode: 'websocket' is rejected: it emits no createServiceDb.

See File Storage for the endpoints, bucket scopes and deployment steps.

Encryption on Neon

The encryption pillar — .encrypted() (envelope) and .sealed() / q.vaultRef() (sealed) columns — is supported on Neon over HTTP and Hyperdrive. The org_data_keys and seal-vault tables fold into the single journaled migration set, and the encryption RLS section rides the journaled RLS migration: org_data_keys gets org-scoped RLS (the envelope DEK path needs caller claims), and the vault spine is locked to service-role-only. The seal chokepoints acquire createServiceDb.

The deprecated Node/Bun WebSocket mode is a fail-closed compile error for both tiers because it cannot provide the request-scoped and service-role handles the key tables require.

Batch transactions

Whether a batch handler (PATCH /batch, DELETE /batch, …) is truly atomic depends on the connection mode, and the response advertises the guarantee via meta.transactional:

drizzle-orm/neon-http throws "No transactions support in neon-http driver" at runtime, so the HTTP path deliberately treats batches like D1 (fail-fast, non-transactional) rather than emitting code that would 500 on every failed batch. Honest advertisement over runtime surprises. For true atomic batches and interactive transactions on Cloudflare, use connectionMode: 'hyperdrive'.

Interactive transactions

connectionMode: 'hyperdrive' runs the feature database over a Cloudflare Hyperdrive binding using postgres.js (drizzle-orm/postgres-js), which supports real interactive transactions — read current state, lock it, decide in TypeScript, then write dependent rows, all committed atomically:

import { z } from "zod";
import { eq } from "drizzle-orm";
import {
  defineAction,
  ActionError,
  registrations,
  registrationEvents,
} from "../.quickback/define-action";

export default defineAction({
  description: "Advance a registration inside one interactive transaction.",
  access: { roles: ["admin"] },
  input: z.object({ registrationId: z.string() }),
  async execute({ db, input }) {
    return db.transaction(async (tx) => {                 // tx is fully typed
      const [reg] = await tx.select()
        .from(registrations)
        .where(eq(registrations.id, input.registrationId))
        .for("update");                                   // row lock held to commit
      if (!reg) throw new ActionError("Not found", "NOT_FOUND", 404); // → rollback
      const [updated] = await tx.update(registrations)
        .set({ status: nextStatus(reg) })
        .where(eq(registrations.id, reg.id))
        .returning();
      await tx.insert(registrationEvents).values({ registrationId: updated.id });
      return updated;                                     // atomic commit
    });
  },
});

Note the tx.select()…for("update") form: Drizzle's relational query API (tx.query.<table>.findFirst) is blocked on the scoped db/tx because the tenant firewall can't be injected into relational queries. The select builder gives you the same row lock with scope conditions applied automatically.

Configure it on the database provider:

providers: {
  database: {
    provider: "neon",
    config: { connectionMode: "hyperdrive", hyperdrive: { id: "<binding-id>" } },
  },
}

The compiler emits the [[hyperdrive]] wrangler binding pointing at your Neon direct connection string. Its request-scoped postgres.js client uses max: 5, disables prepared statements, and skips type-fetch round trips — the small client pool bounds origin connections per Worker isolate while Hyperdrive owns the shared connection pool.

Security is preserved, unchanged. The verified caller claims run as the first transaction-local statement inside the transaction (the same set_config(..., true) preamble batches use), so RLS enforces inside the callback and the claims reset at commit/rollback — they never leak across Hyperdrive's connection pool.

Capability limits (fail closed)

Anything not yet ported to Postgres is a compile-time error on Neon, never silently-broken output:

• Managed file storage with connectionMode: 'websocket' is rejected: the websocket db index emits no createServiceDb, and both createFilesDb and the file-serving Worker wrap that handle. Managed storage is supported on http and hyperdrive — the buckets/objects metadata lives in a files schema of this same database (one journal, no FILES_DB binding). See File Storage.
• The Better Auth subscriptions plugin is supported. Its table is created as auth.subscriptions in the same journal as everything else and is a SYSTEM table — service-role only, like the webhook store — because entitlement state is written by the Stripe queue consumer and the admin endpoints and read by tier-role resolution, all of which run on the internal service lane. Rejected on WebSocket mode, which emits no createServiceDb.
• Raw sqliteTable interop sources on a Postgres target are rejected — write child tables with pgTable (see below).
• WebSocket mode (deprecated) rejects webhooks, cross-tenant unsafe actions, and encrypted/sealed columns. Use connectionMode: 'hyperdrive' instead — it is the full-capability interactive-transaction path and supersedes WebSocket.

Mixed database providers (e.g. D1 auth + Neon features) remain unsupported.

Table triggers are supported in both lanes here. A sql: body is PL/pgSQL and lowers to a SECURITY INVOKER function plus its trigger in the app schema, so a cross-table write from a trigger stays subject to RLS and grants. Bodies are never translated between dialects — a SQLite RAISE(ABORT, ...) on this provider is a compile error.

Deploying

Projects with no custom domain

A Worker that lives only on workers.dev (no providers.runtime.config.routes, no domains) must tell the generated auth layer its own host. Without it the JWT issuer defaults to the local dev URL and cookie-backed browser mutations are refused as cross-site:

npx wrangler deploy \
  --var EXTRA_APP_HOSTS:<name>.<account>.workers.dev \
  --var BETTER_AUTH_URL:https://<name>.<account>.workers.dev

Named environments set BETTER_AUTH_URL in worker.vars (see above); EXTRA_APP_HOSTS is documented under Multi-domain architecture.

For an unnamed target, the generated deploy script runs migrations, then ships the Worker:

npm run deploy   # runs db:migrate (drizzle-kit) then wrangler deploy

HTTP mode reads DATABASE_URL in the Worker, so set both runtime secrets before its first deploy:

npx wrangler secret put DATABASE_URL       # pooled quickback role URL
npx wrangler secret put BETTER_AUTH_SECRET

The generated HTTP client fails fast at boot if DATABASE_URL is missing.

Hyperdrive mode gets its runtime connection string from the HYPERDRIVE binding and must not receive a Worker DATABASE_URL secret. Its DATABASE_URL / DATABASE_MIGRATION_URL values remain local or CI migration inputs only. Set BETTER_AUTH_SECRET and any other exact generated secret inventory, then deploy:

npx wrangler secret put BETTER_AUTH_SECRET
npm run deploy

Named Hyperdrive targets intentionally omit the bare deploy script and keep the base Worker non-deployable. Apply the target branch's migrations, set each secret with --env dev or --env prod, then use an explicit target:

npx wrangler secret put BETTER_AUTH_SECRET --env dev
npm run deploy:dev

npx wrangler secret put BETTER_AUTH_SECRET --env prod
npm run deploy:prod

Required migration canaries

quickback canary dev --required
quickback canary prod --required --apply

Canary takes the logical target key and reads its branch from top-level environments or legacy providers.database.environments. Declaring both placements or naming an unknown target is an error. It only accepts the neon provider: another Postgres provider cannot use Neon APIs even when NEON_API_KEY and NEON_PROJECT_ID are set.

Set NEON_API_KEY and NEON_PROJECT_ID (or neon.projectId). --required fails when credentials or branch mapping are missing; without it, an unconfigured Neon canary deliberately skips. Use --required for CI gates.

Both rehearsal and parent apply request connection strings for the same neon.database and neon.role. These select the migration database and actor; the runtime quickback role is not a suitable routine migration actor. The existing defaults remain neondb and neondb_owner. Set neon.role: "quickback_admin" for routine migrations after bootstrap; first bootstrap and security/RLS migrations still require the setup-owner capability described above. Connection strings go to the Drizzle subprocess environment.

The command fingerprints the entire local quickback/drizzle/ inventory before rehearsal, rechecks it after rehearsal, and checks again immediately before parent apply. A changed journal, SQL file or other migration-state file aborts parent apply and attempts canary cleanup. Keep migration files unchanged throughout the command; this check does not freeze the working directory while Drizzle runs. Cleanup failure returns a nonzero exit status even after successful verification. --apply migrates the parent; it does not deploy the Worker.

Generated files

quickback/drizzle/
├── 0000_<name>.sql               # schema migrations (drizzle-kit)
├── 0001_quickback_rls_<hash>.sql # journaled RLS layer (content-addressed)
└── meta/_journal.json            # one journal covers both
src/
├── db/index.ts                   # createDb / createServiceDb (claim-scoped clients)
├── db/schema.ts                  # Drizzle schema barrel
├── db/rls-support.schema.ts      # profiles (+ admins) — RLS support tables
└── auth/schema.ts                # Better Auth schema (owned by the BA CLI)
.env.neon.example                 # migration connection strings (copy to .env)
.dev.vars.example                 # wrangler dev secrets (copy to .dev.vars)
docs/neon-setup.md                # role bootstrap + deploy walkthrough

Raw Drizzle interop tables must use pg-core

Internal child tables authored as raw Drizzle (a table file with no export default defineTable(...)) are not dialect-translated by the compiler — on Neon they must be written with pgTable from drizzle-orm/pg-core. A sqliteTable interop source on a Postgres target is a compile-time error: the mechanical sqlite→pg rewrite would leave SQLite-shaped audit columns (text ISO strings instead of timestamptz, which the RLS audit triggers stamp) and SQLite-only column options in the Postgres schema.

// quickback/features/interviews/interview_scores.ts
// @quickback-internal — child table, no CRUD routes
import { integer, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const interviewScores = pgTable('interview_scores', {
  id: text('id').primaryKey(),
  interviewId: text('interview_id').notNull(),
  rating: integer('rating').notNull(),
  // ── quickback:audit (compiler-managed — edits are validated, not merged) ──
  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  modifiedAt: timestamp('modified_at', { withTimezone: true }).notNull().defaultNow().$onUpdate(() => new Date()),
  createdBy: text('created_by'),
  modifiedBy: text('modified_by'),
  deletedAt: timestamp('deleted_at', { withTimezone: true }),
  deletedBy: text('deleted_by'),
});

Interop tables are not exempt from the visible managed-column rule. The validator runs over every table file in a feature directory (compiler.ts:1210-1230 iterates feature.tables, which raw-input/organize.ts:394 populates regardless of whether the file has a resource config), so the six columns must be declared literally in Drizzle form — ...q.audit() is a q-DSL spread and is not expanded in raw Drizzle source. A child table with no crud config soft-deletes by default, so deletedAt / deletedBy are required too.

Tables with defineTable(...) are unaffected — existing sqliteTable sources with a resource config still compile to the Postgres dialect automatically.

When to choose Neon vs D1

See also

• D1 — SQLite at the edge
• Providers — All database provider options