Providers

Providers configure which services your compiled backend targets.

Runtime Providers

The Quickback Stack is Cloudflare-only. cloudflare is the single supported runtime.

import { defineRuntime } from "@quickback/compiler";

providers: {
  runtime: defineRuntime("cloudflare"),
}

Runtime Options

providers: {
  runtime: defineRuntime("cloudflare", {
    compatibilityDate: "2026-05-13",
    placement: { mode: "smart" },
    observability: {
      enabled: true,
      logs: {
        enabled: true,
        invocationLogs: false,
        destinations: ["logs-prod"],
        headSamplingRate: 0.6,
      },
      traces: {
        enabled: true,
        destinations: ["otel-prod"],
        headSamplingRate: 0.05,
        persist: false,
      },
    },
  }),
}

Database Providers

Three provider names are supported — one SQLite target and one Postgres implementation on two hosts:

planetscale — without the suffix — is the MySQL name and is not a registered provider; MySQL is not supported.

One database provider per app: auth tables and feature tables always share the selected database. On either Postgres provider, Better Auth uses its PostgreSQL/Drizzle adapter in the same Postgres database as your features; on cloudflare-d1, both use D1. A per-service map (database: { auth: ..., features: ... }) is not part of the config type (quickback check flags it) and is rejected at compile time — mixed database providers are not supported. On D1, auth still gets its own database by default (splitDatabases: true); authBinding and featuresBinding name the two bindings.

import { defineDatabase } from "@quickback/compiler";

providers: {
  database: defineDatabase("cloudflare-d1", {
    generateId: "uuid",              // default; "cuid" | "nanoid" | "short" | "prefixed" | "serial" | false
    allowClientIds: false,           // true: POST bodies MAY carry a strategy-shaped id
    validateIdParams: true,          // false: /:id is a plain string again (see the hazard below)
    namingConvention: "snake_case",   // "camelCase" | "snake_case"
    usePlurals: false,                // Auth table names: "users" vs "user"
  }),
}

Database Options

Options from splitDatabases down apply to cloudflare-d1 only — Neon uses a single Postgres database with no bindings or split mode (see Neon options below).

Neon Options

The Worker connects through a single DATABASE_URL secret — auth and feature queries share it. See Neon for connection modes, RLS, and the migration workflow.

PlanetScale Postgres Options

Same options, one transport: connectionMode accepts "auto" and "hyperdrive" only (omitted is "hyperdrive"), hyperdrive.id is required, and there is no DATABASE_URL Worker secret — the runtime reads env.HYPERDRIVE.connectionString. pooled does not apply; Hyperdrive is the pool. See PlanetScale Postgres for role bootstrap, the role.branch_id connection username, and the mandatory cache-disabled Hyperdrive config.

Audit Database

Cross-tenant unsafe actions (see Actions → Unsafe mode) write mandatory audit events. Those events land in a dedicated D1 database — separate from your features DB — so audit history stays isolated from application data and can't be tampered with through a normal CRUD route.

You don't need to do anything to enable it — the compiler wires up the binding automatically if your project declares any unsafe, PUBLIC, or hard-delete action. Leave auditDatabaseId unset until deploy: compile emits a placeholder, and quickback deploy (or the Start Cloudflare card) creates the D1 and writes the id back. Do not put an empty string in the config.

To override defaults:

providers: {
  database: defineDatabase("cloudflare-d1", {
    auditBinding: "MY_AUDIT_DB",            // default: AUDIT_DB
    auditDatabaseName: "my-app-audit-prod", // default: {app}-audit
    auditDatabaseId: "c3b8866b-cc4f-4e51-8382-0af244584d93",
  }),
}

The binding name must match what your Worker reads at runtime. If you don't declare any unsafe, PUBLIC, or hard-delete actions, no audit DB is provisioned and these options have no effect.

Setting Database IDs for Deployment

When deploying to production, set your D1 database IDs so the compiler generates a ready-to-deploy wrangler.toml:

providers: {
  database: defineDatabase("cloudflare-d1", {
    authDatabaseId: "fe6c77c4-2131-40be-a8fc-3649eef2a38c",
    databaseId: "bba22981-cb6e-43d6-bf32-4193513c60b1",
    filesDatabaseId: "c3b8866b-cc4f-4e51-8382-0af244584d93",
  }),
}

If these are omitted, the compiler uses local-dev placeholders and you'll need to manually edit wrangler.toml before deploying.

Sharing deployed D1 in dev (experimental_remote)

Wrangler can read or write the deployed D1 for a specific binding while wrangler dev runs locally. A common workflow: share the production auth DB in dev so real sessions and users work against the running local Worker, while feature writes stay sandboxed in the local SQLite shadow.

Quickback regenerates wrangler.toml on every compile, so flags like experimental_remote = true need to live in quickback.config.ts:

providers: {
  database: defineDatabase("cloudflare-d1", {
    authDatabaseId: "fe6c77c4-2131-40be-a8fc-3649eef2a38c",
    experimentalRemote: { auth: true },
  }),
}

Keys map to logical bindings, not the runtime binding string:

Only true flips the flag on; false or omitted leaves the binding local. Off by default — only enable against databases you intend to share.

Realtime Broadcast Config

Set realtime: true to enable the generated Broadcaster Durable Object with the default organization-scoped routing model:

providers: {
  database: defineDatabase("cloudflare-d1", {
    realtime: true,
  }),
}

For resource-scoped tickets, use the object form. The mint gate is a discriminated access union — exactly one arm:

providers: {
  database: defineDatabase("cloudflare-d1", {
    realtime: {
      wsTicket: {
        access: { authzRole: "attendee" },   // or { roles: ["member+"] } or { fga: { relation, object } }
        requestField: "eventId",
        scopeTable: "events",
      },
    },
  }),
}

The broadcast surface mounts at /broadcast/v1 by default and /broadcast/v2 under contract.routes: "v2". The path is the only thing routes moves — frame format is unaffected.

wsTicket tells the compiler how to authorize /broadcast/v1/ws-ticket and what scope to stamp into the short-lived websocket ticket:

• access: the mint gate — one of { roles: ["member+"] } (org-membership roles with hierarchy expansion; also verifies the scope row is in the caller's active org), { authzRole: "attendee" } (an authz role declared under authz.roles with a direct relationship { via: "..." }), or { fga: { relation: "viewer", object: "event:{id}" } } (an FGA relation on the object derived from the scope row). The legacy role: "attendee" string is the shorthand for { authzRole }.
• requestField: the JSON body field the client posts to /broadcast/v1/ws-ticket
• scopeTable: the parent resource table that defines the broadcast scope key

Instead of access, wsTicket may name a namespace (namespace: "eventScope") to authorize through that namespace's full multi-lane via — including a namespace declared by a feature area's _area.ts (the one root-config surface allowed to reference an area-declared name; it attaches the area's complete gate and is listed in the authz manifest under the owning area). See Namespace-backed tickets.

In other words: the declared gate proves access, and the scopeTable row defines the channel. For an attendee flow, guests (or RSVP) would be the relationship evidence and events would be the scopeTable; see Realtime for the full per-arm semantics.

Quickback keeps Better Auth as the front door, then mints its own 60-second websocket ticket after the authz check succeeds. The generated createRealtime() helper and Broadcaster share the same targeting model:

• string target: historical organizationId shorthand
• object target: { scopeKey?, organizationId?, userId? }

See Realtime for the client-side connection flow and helper examples.

ID Generation Options

Leave generateId unset and every provider mints UUIDs, in the CRUD route and in the schema default an action's db.insert() falls back on alike.

Auth Providers

import { defineAuth } from "@quickback/compiler";

providers: {
  auth: defineAuth("better-auth", {
    session: {
      expiresInDays: 7,
      updateAgeInDays: 1,
    },
    rateLimit: {
      enabled: true,
      window: 60,
      max: 100,
    },
  }),
}

Better Auth Options

Better Auth Plugins

When features: ["organizations"] is set in your config, the compiler automatically enables organization-related plugins. Additional plugins can be configured:

emailOtp also accepts an options object. Set expiresIn to a positive integer number of seconds to override Better Auth's OTP lifetime. The setting is transport-neutral and is emitted identically for Cloudflare Email and AWS SES:

plugins: { emailOtp: { expiresIn: 1200 } }

organization accepts Better Auth's own options too. invitationLimit caps pending invitations per organization (Better Auth defaults to 100):

plugins: { organization: { invitationLimit: 10 } }

organizationHooks is compiler-owned and rejected from config; gate or reroute invitations with hooks/before-invitation-create.ts instead.

Storage Providers

import { defineStorage, defineFileStorage } from "@quickback/compiler";

providers: {
  storage: defineStorage("cloudflare-kv", {
    binding: "KV_STORE",
    namespaceId: "7ed0f824a8c54c388713d9fdf63cd004",
  }),
  fileStorage: defineFileStorage("cloudflare-r2", {
    binding: "FILES",
    maxFileSize: "10mb",
    allowedTypes: ["image/png", "image/jpeg", "application/pdf"],
    publicDomain: "files.example.com",
  }),
}

Storage Types

These three names are the complete registry. Any other name — kv, r2, redis — fails the compile with Unknown storage provider.

File Storage Options