# Rebase Documentation

> Rebase is an open-source TypeScript backend built on Postgres: REST & GraphQL APIs, authentication,
> row-level security, realtime subscriptions, storage, cron jobs, and an MCP server for AI agents —
> all generated from your schema, with a full admin panel and SQL editor included on top.
> Connect an existing PostgreSQL database or start fresh; Rebase uses Drizzle ORM under the hood and
> keeps your TypeScript collection definitions as the single source of truth.
> Scoped API keys with per-collection permissions plus Postgres-enforced RLS make it safe for
> autonomous agents to read and write production data.

## Introduction


### What is Rebase?

Rebase is an **open-source Backend-as-a-Service (BaaS)** and **admin panel** built with React and TypeScript. It gives you everything you need to build production-ready back-office applications on top of **PostgreSQL**:

- **Schema as Code** — Define your data models as TypeScript collections. Rebase generates PostgreSQL tables, a full CRUD UI, REST API endpoints, and type-safe client SDKs from a single source of truth.
- **Instant Admin Panel** — A beautiful, fast React-based admin UI with spreadsheet tables, lists, forms, Kanban boards, inline editing, and real-time sync.
- **Integrated Backend** — Authentication (JWT + Google OAuth), file storage (local or S3), Row Level Security, entity history, and WebSocket real-time — all built in.
- **Radically Extensible** — If you can build it in React, you can add it to Rebase. Custom fields, custom views, plugins, and full access to internal hooks.

:::tip
Rebase is **not** a hosted SaaS. You self-host it, you own your data, and you own your code. Think of it as an open-source alternative to Supabase or Retool that you control end-to-end.
:::

### How It Works

```
┌──────────────────────────────────────────────────────┐
│                 Client Applications                  │
│  ┌──────────────┐  ┌───────────────────────────────┐ │
│  │   Your App   │  │   Rebase Admin UI             │ │
│  │  (Any Tech)  │  │   Tables / Lists / Kanban     │ │
│  └──────┬───────┘  └──────────────┬────────────────┘ │
└─────────┼──────────────────────────┼─────────────────┘
          │  HTTP + WebSocket        │
          ▼                          ▼
┌──────────────────────────────────────────────────────┐
│              Rebase Backend (Node.js + Hono)         │
│  ┌─────────┐ ┌──────┐ ┌─────────┐ ┌───────────────┐  │
│  │ REST API│ │ Auth │ │ Storage │ │ WebSocket RT  │  │
│  └────┬────┘ └──┬───┘ └────┬────┘ └──────┬────────┘  │
└───────┼─────────┼──────────┼─────────────┼───────────┘
        │         │          │             │
        ▼         ▼          ▼             ▼
┌──────────────────────────────────────────────────────┐
│              PostgreSQL (Drizzle ORM)                │
└──────────────────────────────────────────────────────┘
```

### Quick Start

```bash
pnpm dlx @rebasepro/cli init my-app
cd my-app
```

`init` generates a ready-to-run `.env` for you (secrets, database password, a free local port) — no editing needed to get started. Start the bundled PostgreSQL container, create the tables, then run the dev servers:

```bash
docker compose up -d db   # start the database
pnpm run db:push          # create tables from your collections
pnpm dev                  # start backend + frontend
```

Your admin panel is running at `http://localhost:5173` and the API at `http://localhost:3001`. The first account you register becomes the admin.

→ Follow the full [Quickstart guide](/docs/getting-started/quickstart) for a complete walkthrough, including how to connect your own database.

### Core Features

| Feature | Description |
|---------|-------------|
| **Spreadsheet Views** | Fast, virtualized table with inline editing, filtering, sorting, and text search |
| **List View** | Clean, responsive vertical list view for collections |
| **Kanban Board** | Drag-and-drop board view grouped by any enum property |
| **Relations** | One-to-one, one-to-many, many-to-many with junction tables and multi-hop joins |
| **Row Level Security** | Supabase-style RLS policies defined in your collection config |
| **Authentication** | JWT + refresh tokens, Google OAuth, role-based access control |
| **File Storage** | Local filesystem or S3-compatible with upload fields and browser |
| **Real-time Sync** | WebSocket-powered live updates across all connected clients |
| **Entity History** | Full audit trail for every create, update, and delete |
| **REST API** | Auto-generated CRUD endpoints for every collection |
| **Data Import/Export** | CSV, JSON, and Excel import with field mapping; CSV/JSON export |
| **Collection Editor** | Visual schema editor that generates TypeScript via AST manipulation |
| **Client SDK** | Type-safe JavaScript SDK for your frontend apps |
| **Plugin System** | Extend every part of the UI — toolbar, forms, fields, home page |
| **AI Data Enhancement** | LLM-powered autocompletion for text fields |
| **Cron Jobs** | Scheduled background tasks with monitoring, logging, and Studio dashboard |
| **Custom Functions** | File-based Hono routes auto-mounted with auth middleware and DB access |
| **Email Service** | Built-in SMTP for password reset, verification, and transactional emails |
| **Database Branching** | Instant isolated copies of your database for dev, staging, or testing |
| **Webhooks** | HMAC-signed outbound notifications on INSERT, UPDATE, DELETE |
| **Broadcast Channels** | WebSocket channels for real-time messaging between connected clients |
| **Presence Tracking** | Track online users and sync shared state across participants |

### Next Steps

- **[Quickstart](/docs/getting-started/quickstart)** — Get running in 2 minutes
- **[Project Structure](/docs/getting-started/project-structure)** — Understand the generated code
- **[Collections](/docs/collections)** — Define your data schema
- **[Backend](/docs/backend)** — Configure auth, storage, and the API
- **[Architecture](/docs/architecture)** — Understand how it all fits together

## Quickstart

### Create a New Project

```bash
pnpm dlx @rebasepro/cli init my-app
```

This scaffolds a project with three packages:

| Folder | Description |
|--------|-------------|
| `frontend/` | React SPA — Vite + TypeScript with the Rebase admin UI |
| `backend/` | Node.js server — Hono, PostgreSQL via Drizzle ORM, WebSocket |
| `config/` | Config files and collection definitions shared by both sides |

### Prerequisites

- **Node.js** 18+
- **Docker** — to run the included PostgreSQL container. (Or bring your own PostgreSQL: local install, Neon, Supabase, etc.)
- **pnpm** (recommended) or npm

### Your Environment Is Already Configured

`init` generates a ready-to-run `.env` at the project root with a real `JWT_SECRET`, a database password, and a free local database port. You don't need to create or edit anything to get started.

:::caution
Don't run `cp .env.example .env`. `.env.example` is a reference for the available variables — copying it over your `.env` discards the generated secrets and points `DATABASE_URL` at a database that doesn't exist. Edit `.env` directly if you want to change a value.
:::

If you'd rather point at your own PostgreSQL instead of the bundled container, edit `DATABASE_URL` in `.env`:

```bash
DATABASE_URL=postgresql://username:password@localhost:5432/your_database
```

### Start the Database

The scaffold ships a `docker-compose.yml` with a PostgreSQL service. Start it:

```bash
docker compose up -d db
```

(Skip this if you pointed `DATABASE_URL` at your own database.)

### Create the Tables

Push your collections to the database. This creates the tables for the example `posts`, `authors`, and `tags` collections:

```bash
pnpm run db:push
```

Without this step the admin panel still opens, but every collection is empty and its API calls fail until the tables exist.

### Introspect an Existing Database (Optional)

If you are connecting to an existing database with pre-existing tables, you can introspect it to automatically generate your TypeScript collection files:

```bash
pnpm rebase schema introspect
```

This will analyze your database tables and generate corresponding TypeScript files in `config/collections/` so you don't have to write them manually.

### Start the Dev Servers

```bash
pnpm dev
```

This starts both together:
- **Backend** — REST API, auth, storage, WebSocket
- **Frontend** — the Rebase admin panel
- **Hot reload** for both — changes take effect instantly

Both ports are **derived from this project's path** rather than fixed, so several
Rebase projects can run side by side. `rebase dev` prints the two URLs it bound —
use those, not `localhost:3001`/`localhost:5173`. (`PORT` and `VITE_API_URL` in
`.env` configure `rebase start`, the production server, and are ignored here.)
Pin a port with `rebase dev --port 3001`.

### First Login

When you open the frontend URL `rebase dev` printed, you'll see the login screen. The **first user** to register automatically becomes an admin — this is the bootstrap flow.

1. Click **Sign Up**
2. Enter your email and password
3. You're in — with full admin access

### Define Your First Collection

Open `config/collections/` and create a new file. Export the collection as the **default export** — that's how the registry picks it up:

```typescript title="config/collections/products.ts"

const productsCollection = defineCollection({
    slug: "products",
    name: "Products",
    singularName: "Product",
    table: "products",
    properties: {
        name: {
            type: "string",
            name: "Name",
            validation: { required: true }
        },
        price: {
            type: "number",
            name: "Price",
            validation: { required: true, min: 0 }
        },
        description: {
            type: "string",
            name: "Description",
            admin: { multiline: true }
        },
        active: {
            type: "boolean",
            name: "Active",
            defaultValue: true
        },
        created_at: {
            type: "date",
            name: "Created At",
            autoValue: "on_create"
        }
    }
});

export default productsCollection;
```

Then register it in `config/collections/index.ts` so both the backend and the admin panel know about it:

```typescript title="config/collections/index.ts" {2,5}
// ...existing imports

export const collections = [
    postsCollection, authorsCollection, tagsCollection, usersCollection, productsCollection
];
```

### Create the Table

Push the new collection to the database:

```bash
pnpm run db:push
```

This regenerates the schema from your collections and applies it. Restart the dev servers and your new **Products** collection appears in the navigation.

### Database Commands Reference

| Command | Description |
|---------|-------------|
| `rebase schema generate` | Generate Drizzle schema from your TypeScript collections |
| `rebase schema introspect` | Generate TypeScript collections from an existing database |
| `rebase db push` | Push schema changes directly to the database (dev only) |
| `rebase db generate` | Generate SQL migration files |
| `rebase db migrate` | Run pending migrations |

### What's Next

- **[Project Structure](/docs/getting-started/project-structure)** — Understand the generated code
- **[Collections](/docs/collections)** — Deep dive into schema definition
- **[Environment & Configuration](/docs/getting-started/configuration)** — All configuration options
- **[Deployment](/docs/getting-started/deployment)** — Deploy to production

## Project Structure

A Rebase starter project has three interconnected packages:

```
my-app/
├── .env                    # Environment variables (DATABASE_URL, JWT_SECRET, etc.)
├── package.json            # Root workspace config
│
├── frontend/               # React admin panel (Vite)
│   ├── src/
│   │   ├── App.tsx         # Main application component
│   │   ├── main.tsx        # React entry point
│   │   └── index.css       # Global styles
│   ├── package.json
│   └── vite.config.ts
│
├── backend/                # Node.js API server (Hono)
│   ├── src/
│   │   ├── index.ts        # Server entry — initializes Rebase backend
│   │   └── schema.generated.ts  # Auto-generated Drizzle schema
│   ├── drizzle.config.ts   # Drizzle ORM configuration
│   ├── Dockerfile
│   └── package.json
│
└── config/                 # Collection definitions and configurations
    └── collections/
        ├── index.ts        # Exports all collections
        └── products.ts     # Example: products collection
```

### Frontend (`frontend/`)

The frontend is a standard **Vite + React + TypeScript** application. The key file is `App.tsx`, which wires together all Rebase controllers:

```typescript title="frontend/src/App.tsx"

// The client connects to your backend API and WebSocket
const rebaseClient = createRebaseClient({
    baseUrl: "http://localhost:3001",
    websocketUrl: "ws://localhost:3001"
});

// Collections are imported via a Vite virtual module
// that reads from the config/ directory
```

#### Key Concepts

- **`createRebaseClient`** — Creates the SDK client that handles HTTP requests, WebSocket connections, and auth token management
- **`virtual:rebase-collections`** — A Vite plugin that auto-imports your shared collections at build time
- **Controllers** — `useBuildNavigationStateController`, `useBuildCollectionRegistryController`, etc. — these configure routing, collection resolution, and UI configuration

### Backend (`backend/`)

The backend is a **Node.js server** built on [Hono](https://hono.dev/) (a fast, lightweight HTTP framework). The entry point `index.ts` initializes everything:

```typescript title="backend/src/index.ts"

const app = new Hono<HonoEnv>();

await initializeRebaseBackend({
    app,
    server,
    collectionsDir: "./config/collections",
    database: createPostgresAdapter({
        connection: db,
        schema: { tables, enums, relations }
    }),
    auth: {
        jwtSecret: process.env.JWT_SECRET,
        google: process.env.GOOGLE_CLIENT_ID
            ? { clientId: process.env.GOOGLE_CLIENT_ID }
            : undefined,
    },
    storage: {
        type: "local",
        basePath: "./uploads"
    },
    history: true
});
```

`initializeRebaseBackend` sets up:
- **REST API** routes at `/api/data/*` — auto-generated CRUD for each collection
- **Auth** routes at `/api/auth/*` — signup, login, refresh, Google OAuth
- **Storage** routes at `/api/storage/*` — file upload/download
- **WebSocket** server — real-time entity sync via Postgres LISTEN/NOTIFY
- **History** — audit trail recording on every entity change

### Collections (`config/collections/`)

Collections are the **single source of truth** for your data model. They are defined as TypeScript and consumed by both the frontend (for UI generation) and the backend (for schema generation and API routing).

```typescript title="config/collections/products.ts"

export const productsCollection = defineCollection({
    slug: "products",
    name: "Products",
    table: "products",
    properties: {
        name: { type: "string", name: "Name" },
        price: { type: "number", name: "Price" }
    }
});
```

The `slug` becomes the URL path in the admin UI and the REST API endpoint (`/api/data/products`). The `table` maps to the PostgreSQL table name.

### How They Connect

1. **You define** collections in `config/collections/`
2. **The backend** reads them to generate Drizzle schemas and mount REST routes
3. **The frontend** reads them (via Vite plugin) to render tables, forms, and navigation
4. **The CLI** reads them to generate migration files with `rebase schema generate`

Changes to collections propagate everywhere automatically.

### Next Steps

- **[Quickstart](/docs/getting-started/quickstart)** — Get started with a new Rebase project
- **[Configuration](/docs/getting-started/configuration)** — All environment variables and options

## Environment & Configuration

### Environment Variables

All configuration is done via environment variables in your `.env` file at the project root.

> **Important**: Rebase uses **Zod** to validate environment variables at startup in `src/env.ts`. If any required variables are missing or incorrectly formatted (like URLs or ports), the server will fail to start and provide a clear error message.

#### Required

| Variable | Description | Example |
|----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://user:pass@localhost:5432/mydb` |
| `JWT_SECRET` | Secret key for signing JWT tokens. Use a strong random string (min 32 chars). **Required in production** (auto-generated in development). | `a1b2c3d4e5...` |

> **`sslmode=no-verify` is a node-postgres spelling, not a libpq one.**
>
> Rebase and the Node driver accept it — encrypt, but do not check the
> certificate. `psql`, `pg_dump`, `pg_restore` and Atlas do not, and they do not
> degrade: they refuse to start with `invalid sslmode value: "no-verify"`.
>
> Rebase's own commands (`rebase db push`, `rebase db backup`, `rebase db
> restore`) rewrite it to the equivalent `sslmode=require` before shelling out,
> so they work with the URL as configured. Reaching for `psql` by hand does not
> — swap in `sslmode=require` there, which encrypts without verifying in exactly
> the same way.

#### Frontend

| Variable | Description | Default |
|----------|-------------|---------|
| `VITE_API_URL` | Backend API URL for the client SDK. **Set this in development only** — see below. | page origin |
| `VITE_GOOGLE_CLIENT_ID` | Google OAuth client ID. Enables "Sign in with Google". | — |

> **Leave `VITE_API_URL` unset in production builds.**
>
> In development the frontend and backend are separate origins, so the dev
> server injects this. In production the Rebase backend serves the SPA, so the
> API is the page's own origin and the client resolves it that way on its own.
>
> Baking an absolute URL into a production bundle works right up until a second
> hostname points at the same app: a custom domain then loads the page from
> `example.com` and calls the API on `example.rebase.website`, which is
> cross-origin, so every request fails preflight. Allowing the origin in CORS
> does **not** fix it either — the refresh cookie is `SameSite=Lax` and is not
> sent cross-site, so you would clear the console errors and still have broken
> auth. Unset, every domain pointing at the app works with no CORS
> configuration at all.

#### Backend

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Port for the backend HTTP server | `3001` |
| `LOG_LEVEL` | Logging verbosity: `error`, `warn`, `info`, `debug` | `info` |
| `NODE_ENV` | Environment: `development`, `production`, or `test` | `development` |
| `CORS_ORIGINS` | Comma-separated list of allowed origins. **Required in production** if different from backend domain. | — |
| `FRONTEND_URL` | URL of the frontend app. Used as an alternative to CORS_ORIGINS. | — |
| `ADMIN_CONNECTION_STRING` | Admin-level database connection string (used for schema introspection and admin operations). | `DATABASE_URL` |
| `DISABLE_DB_ROLE_SWITCHING` | Disable PostgreSQL role-switching in SQL Editor (useful for custom authentication where DB roles are not mapped). | `false` |

#### Authentication

| Variable | Description | Default |
|----------|-------------|---------|
| `JWT_SECRET` | Secret for JWT signing (required in production, auto-generated in development) | — |
| `JWT_ACCESS_EXPIRES_IN` | Access token lifetime | `1h` |
| `JWT_REFRESH_EXPIRES_IN` | Refresh token lifetime | `30d` |
| `ALLOW_REGISTRATION` | Allow new users to register (`true`/`false`). First user can always register. | `true` |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID (backend validation) | — |
| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret | — |
| `REBASE_SERVICE_KEY` | Static admin API key. Bypasses normal JWT auth for server-to-server calls when passed as `Authorization: Bearer <key>`. (Auto-generated in development). | — |

#### Storage

| Variable | Description | Default |
|----------|-------------|---------|
| `STORAGE_TYPE` | Storage backend: `local`, `s3` or `gcs`. In production `local` disables storage unless `FORCE_LOCAL_STORAGE=true` | `local` |
| `STORAGE_PATH` | Base path for local storage | `./uploads` |
| `FORCE_LOCAL_STORAGE` | Allow local storage in production — only with a durable volume mounted at `STORAGE_PATH` | `false` |
| `S3_BUCKET` | S3 bucket name (when `STORAGE_TYPE=s3`) | — |
| `S3_REGION` | AWS region | — |
| `S3_ACCESS_KEY_ID` | AWS access key | — |
| `S3_SECRET_ACCESS_KEY` | AWS secret key | — |
| `S3_ENDPOINT` | Custom S3 endpoint (for MinIO, Cloudflare R2, etc.) | — |
| `S3_FORCE_PATH_STYLE` | Force path-style URLs for S3 bucket (`true`/`false`) | `false` |

#### Email (Optional)

| Variable | Description |
|----------|-------------|
| `SMTP_HOST` | SMTP server host |
| `SMTP_PORT` | SMTP server port |
| `SMTP_SECURE` | Enable secure connection (`true`/`false`) |
| `SMTP_USER` | SMTP username |
| `SMTP_PASS` | SMTP password |
| `SMTP_FROM` | Sender address for system emails |

### Backend Config Object

The `RebaseBackendConfig` passed to `initializeRebaseBackend()` provides programmatic control:

```typescript

await initializeRebaseBackend({
    app,
    server,
    collectionsDir: "./config/collections",
    basePath: "/api",        // Base path for all API routes (default: "/api")

    database: createPostgresAdapter({
        connection: db,
        schema: { tables, enums, relations }
    }),

    auth: {                  // Authentication config
        jwtSecret: env.JWT_SECRET,
        accessExpiresIn: env.JWT_ACCESS_EXPIRES_IN,
        refreshExpiresIn: env.JWT_REFRESH_EXPIRES_IN,
        requireAuth: true,    // Require auth for data API (default: true)
        allowRegistration: env.ALLOW_REGISTRATION,
        google: env.GOOGLE_CLIENT_ID
            ? {
                clientId: env.GOOGLE_CLIENT_ID,
                clientSecret: env.GOOGLE_CLIENT_SECRET
            }
            : undefined,
        serviceKey: env.REBASE_SERVICE_KEY
    },

    // No bucket configured in production means storage is off, not local:
    // uploads answer 501 rather than landing on a filesystem that is erased
    // on the next redeploy.
    storage: env.STORAGE_TYPE === "s3"
        ? {
            type: "s3",
            bucket: env.S3_BUCKET!,
            region: env.S3_REGION,
            accessKeyId: env.S3_ACCESS_KEY_ID,
            secretAccessKey: env.S3_SECRET_ACCESS_KEY,
            endpoint: env.S3_ENDPOINT
        }
        : env.STORAGE_TYPE === "gcs"
            ? {
                type: "gcs",
                bucket: env.GCS_BUCKET!,
                projectId: env.GCS_PROJECT_ID,
                keyFilename: env.GCS_KEY_FILENAME
            }
            : isProduction && !env.FORCE_LOCAL_STORAGE
                ? undefined
                : {
                    type: "local",
                    basePath: env.STORAGE_PATH || "./uploads"
                },

    history: true,           // Enable entity change history

    enableSwagger: true,     // Enable OpenAPI docs at /api/data/docs

    logging: {
        level: "info"
    }
});
```

#### Changing `basePath`

`basePath` moves every API route, so the client has to be told the same thing —
otherwise it keeps asking for `/api/...` and gets a 404 for everything:

```typescript

export const rebase = createRebaseClient({
    baseUrl: "https://api.example.com",
    apiPath: "/v1"          // must match the backend's basePath
});
```

The admin panel picks this up from the client it is given; nothing else needs
configuring. If you build a request URL by hand, join it from the client rather
than writing `/api` yourself:

```typescript

function Widget() {
    const apiBase = useApiBase();   // e.g. "https://api.example.com/v1"
    // fetch(`${apiBase}/data/products`)
}
```

### Troubleshooting

#### SQL Editor Permission Denied (`permission denied for table <name>`)

* **Symptoms:** Custom queries executed in the Rebase Studio SQL Editor fail with `cause: error: permission denied for table <name>`, even though the spreadsheet CMS view loads data successfully.
* **Cause:** By default, Rebase attempts to execute SQL Editor queries by temporarily switching database roles to match the active user's application role (e.g., `SET LOCAL ROLE "admin"`). If you are using custom authentication where roles exist only in database tables rather than actual PostgreSQL roles, the role switch fails or database privileges are missing. The CMS spreadsheet view executes under the default connection owner user and bypasses this.
* **Solution:** Add `DISABLE_DB_ROLE_SWITCHING=true` to your backend `.env` configuration. This forces Rebase to run SQL Editor queries using the connection owner's privileges (typically a superuser/owner).

#### SQL Editor Schema Fetch Failed (`Cross-database execution requires adminConnectionString`)

* **Symptoms:** Studio fails to load the schema tree, or SQL Editor throws `Failed to fetch schema: Cross-database execution requires adminConnectionString to be configured in the backend.`
* **Cause:** Rebase requires administrative privileges to query database system catalogs and run administrative commands. If `adminConnectionString` is not provided to the bootstrapper, or `getAdmin()` is overridden to return `undefined`, these operations fail.
* **Solution:** Ensure `adminConnectionString` is configured during backend bootstrapper initialization:
  ```typescript
  createPostgresBootstrapper({
      connection: db,
      schema: { tables, enums, relations },
      adminConnectionString: process.env.ADMIN_CONNECTION_STRING || process.env.DATABASE_URL
  })
  ```

### Next Steps

- **[Deployment](/docs/getting-started/deployment)** — Production deployment guide
- **[Backend Overview](/docs/backend)** — Full backend configuration reference

## Upgrading

## Upgrading an existing app

This release removes the `auth` schema, renames packages, changes what `id`
means, drops CJS, moves the admin panel to react-router 8, and — most
importantly — **fixes three ways access could be granted that you did not ask
for**: a security rule that was silently permissive, and two on the realtime
socket. Read the first three sections before anything else. Section 0 is the one
that changes SQL you may have written by hand; sections 1 and 2 alter who can
read your data, and none of them announces itself.

Work through the sections in order. Each one names the symptom you would
otherwise debug from the wrong end.

---

### 0. The `auth` schema is gone — read this first

#### What changed

Rebase's RLS helper functions moved out of the `auth` schema and into `rebase`:

| Before | Now |
|---|---|
| `auth.uid()` | `rebase.uid()` |
| `auth.roles()` | `rebase.roles()` |
| `auth.jwt()` | `rebase.jwt()` |

`auth` is Supabase's schema name. Borrowing it meant Rebase could not be pointed
at a database that already had one: applying
`CREATE OR REPLACE FUNCTION auth.uid() RETURNS text` over Supabase's
`RETURNS uuid` is something Postgres refuses outright, and the refusal used to
be swallowed — leaving a database with auth tables, no helper functions, and
policies calling functions that did not exist.

Rebase now creates exactly one schema in your database: `rebase`. Nothing else.

#### What you have to do

**If your `securityRules` use the structured helpers** — `policy.authUid()`,
`policy.rolesOverlap()`, `ownerField`, `roles` — **nothing.** They never spelled
a schema name. Re-run `rebase db push` (or redeploy) and your policies are
recompiled.

**If you wrote raw policy SQL**, it keeps working: the compiler rewrites
`auth.uid()` to `rebase.uid()` on its way into the database. The boot log names
every collection still carrying the old spelling so you can update it. Do — the
rewrite is a migration aid, not a second supported spelling.

```ts
// Works, and warns.
securityRules: [{ operation: "select", using: "owner_id = auth.uid()" }]

// The fix.
securityRules: [{ operation: "select", using: "owner_id = rebase.uid()" }]

// Better: no schema name to get wrong.
securityRules: [{ operation: "select",
    condition: policy.compare(policy.field("owner_id"), "eq", policy.authUid()) }]
```

**Hand-written policies you created outside Rebase** — a SQL migration, the
Studio editor — are the one thing nothing can rewrite for you. Until you update
them, Postgres will not drop the functions they depend on, and the `auth` schema
stays. Boot tells you exactly which policies, by name:

```
The pre-1.0 `auth` schema cannot be removed yet: 1 policy still calls
`auth.uid()` and friends … anything listed here is hand-written SQL that has to
be updated to `rebase.uid()` by hand, after which the schema goes on its own:
  • public.posts → "posts_legacy"
```

#### What happens to the old schema

It is dropped automatically once nothing references it, and only when Rebase is
what created it. Each function is identified by its result type and body before
being dropped, and the schema goes by `DROP SCHEMA auth RESTRICT` — never
CASCADE — so a Supabase installation, or anything else living in `auth`, keeps
it untouched.

#### Also: the scaffold's database role is now `rebase_app`

Postgres resolves unqualified names through `search_path`, which defaults to
`"$user", public` — and `$user` is the connection role. A role named `rebase`
therefore put the `rebase` **schema** ahead of `public`, so unqualified SQL from
anything that does not pin the path (psql, `pg_dump`, drizzle-kit, a hand-written
migration) silently landed in the wrong schema.

Existing projects need no change: every connection Rebase opens already pins
`search_path=public`. New projects get `rebase_app`, and boot now warns if your
connection role shares a name with a schema.

---

### 1. `policy.authenticated()` — read this first

#### What changed

`policy.authenticated()` used to compile to:

```sql
auth.uid() IS NOT NULL
```

On the user path that is a **tautology**. `applyAuthContext` coerces a blank
user id to the `'anonymous'` sentinel — deliberately, so that it can never read
back as `NULL` and be mistaken for the trusted server context. So `IS NOT NULL`
was true for anonymous visitors too.

A rule that reads as "logged-in users only" therefore granted access to
**everyone, including signed-out visitors**. It now compiles to:

```sql
auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'
```

`policy.not(policy.authenticated())` was separately special-cased to mean "the
server context". It no longer is — use `policy.serverContext()` for that.

#### Why this is the dangerous one

The compiled SQL lives in your **database**, not in your application code.
Upgrading the packages does not change it. The two failure modes are opposite,
and both are quiet:

| What you do | What happens |
|---|---|
| Upgrade packages, **do not** re-run `db push` | Your database keeps `auth.uid() IS NOT NULL`. **Anonymous visitors keep the access they should never have had.** Nothing warns you. |
| Upgrade packages **and** re-run `db push` | The policy tightens. Anything that was relying on the permissive behaviour — an unauthenticated read your frontend does on page load, a public listing, a webhook without a session — starts returning zero rows or 403. |

> **`rebase doctor --policies` catches this, from 0.10.0 on.** It reads the live
> `qual` and `with_check` straight out of `pg_policies` and reports, under
> **Insecure**, any policy still carrying the bare `auth.uid() IS NOT NULL`
> tautology. It reports the other half of the problem under **Orphaned**: a
> policy an earlier push superseded but never dropped. Editing a rule renames its
> policy — the generated name is a hash of the rule — so the old one is left
> behind, and Postgres ORs permissive policies together, which makes an abandoned
> grant outrank the tightening that replaced it. The command exits non-zero, so
> CI can gate on it.
>
> Plain `rebase doctor` runs the same policy checks alongside the schema diff;
> `--policies` is the policies-only form, and the one to point at a deployed
> database. Both need `DATABASE_URL` (or `ADMIN_CONNECTION_STRING`) — without it
> the policy checks are *skipped with a warning*, not failed.

> **What the scan does not catch.** It matches that one expression shape — in
> whatever whitespace Postgres stored it in — and treats an `<> 'anonymous'` (or
> `!= 'anonymous'`) guard anywhere in the same clause as the corrected form. A
> fail-open policy written by hand in some other spelling — `USING (true)`,
> `USING (1 = 1)`, `USING (current_setting('rebase.uid', true) IS NOT NULL)` — is
> **not** flagged, and neither is a compound expression that happens to mention
> `'anonymous'` in an unrelated branch. It also needs collections to compare
> against: a project whose collections generate no policies at all gets no scan.
> The `pg_policies` read in Step 3 is how you see the expressions yourself.

> **Nothing applies the fix for you.** Policies are not re-run at container boot.
> Upgrading the packages, redeploying and restarting all leave `pg_policies`
> exactly as it was. Only `db push` rewrites it — and it is what drops the
> superseded policies too.

#### What to do

**Step 1 — find every affected rule.** From your project root:

```bash
grep -rn "authenticated()" config/collections/
```

Every hit is a rule whose meaning changed. Also check for the raw spelling,
which was the other way to write the same tautology:

```bash
grep -rn "auth.uid() IS NOT NULL" config/collections/
```

**Step 2 — decide what each one meant.** For each rule, ask which you intended:

- *"Any signed-in user"* → `policy.authenticated()`. No code change; the
  behaviour is now what you wrote. Re-run `db push`.
- *"Anyone at all, including anonymous"* → you were relying on the bug, whether
  you knew it or not. Make it explicit: `{ operation: "select", access: "public" }`.
- *"Only the trusted server context"* → replace `policy.not(policy.authenticated())`
  with `policy.serverContext()`.

**Step 3 — check what your database actually has,** before and after:

```sql
SELECT tablename, policyname, cmd, qual
FROM pg_policies
WHERE schemaname = 'public'
ORDER BY tablename, policyname;
```

Any `qual` containing `auth.uid() IS NOT NULL` **without** the
`<> 'anonymous'` clause is a stale permissive policy. `rebase doctor --policies`
reports exactly those, and the superseded policies alongside them; this query is
how you read the expressions yourself, which is what catches a fail-open policy
written in a spelling the detector does not match.

**Step 4 — re-run `db push` and re-run the query.** `db push` applies the current
policies and then drops the ones an earlier push superseded. Confirm every policy
you expected to change did change, then run:

```bash
rebase doctor --policies
```

It should exit 0 with no Insecure or Orphaned entries.

**Step 5 — test signed-out.** Open your app in a private window with no session
and exercise the read paths. This is where you find the public listing that
quietly depended on the old behaviour.

---

### 2. The realtime socket was open — check who could subscribe

Two separate defects, both of which granted socket access rather than
withholding it, and neither of which logged anything.

**`realtime.requireAuth: true` opened the socket.** The connection handler seeds
each session with `authenticated: !requireAuth`, so the flag does not gate a
later check — it decides whether a connecting client is treated as *already*
authenticated. It was computed as:

```ts
authConfig.requireAuth !== false && !!authConfig.jwtSecret
```

On a server that authenticates through an `AuthAdapter`, or through anything
other than a local `auth.jwtSecret`, that is `false` — so every client that
connected was marked authenticated. Setting `requireAuth: true` was what granted
access.

**The socket and `/api/data` disagreed.** Each computed "does this server
require an authenticated caller?" separately. With no auth configured at all,
the HTTP routes answered 401 to every read while the socket admitted everyone
and served the same rows.

#### Are you affected?

You were exposed if **either** holds:

- you set `realtime.requireAuth: true` while authenticating through an
  `AuthAdapter` (or any path other than `auth.jwtSecret`), or
- you run with no auth configuration at all and assumed the socket matched the
  401 you get from `/api/data`.

RLS still applied to what a subscription returned, so a collection whose
policies are correct leaked nothing. The exposure is the collections whose
protection was "the socket requires auth" rather than a policy.

#### What to do

```bash
# Every collection reachable over the socket relies on RLS, not on the gate.
pnpm rebase doctor --policies
```

Then exercise your app **signed out, in a private window**, with the network
panel open on the websocket — the same check section 1 asks for, for the same
reason. Nothing needs to change in your code: both enforcement points call
`resolveRequireAuth` now and the tests pin that they agree.

---

### 3. The authenticated principal is `uid`, not `userId`

Tokens now carry a `uid` claim and `c.get("user")` returns `{ uid, roles }`.

```bash
grep -rn "\.userId\|payload.userId\|user.userId" src/ config/
```

Anything reading `payload.userId` or `user.userId` gets `undefined` — which,
in a permission check, usually fails open or fails silently rather than
throwing. Search for the defensive `a ?? b` spelling too; several places had
independently grown one to cope with the two names:

```bash
grep -rn "uid ?? \|?? .*userId" src/ config/
```

---

### 4. `id` is an address, not a column

Rows now carry their own columns under their own names and types. Previously a
synthesized `id` was written into rows on the way out, which collided with your
data three ways: it renamed the key (a `sku` primary key was served as `id`,
with `sku` absent), it changed the type (an integer key arrived as `"42"`), and
it destroyed real values (`drizzleResultToRow` spread it last, so it won over a
genuine `id` column).

**If your tables are keyed on `id`, nothing changes for you.**

If any table is keyed on something else, code reading `row.id` must read the
real key. Note the type change too: a numeric primary key now arrives as a
`number`, so `row.id === "42"` becomes `row.sku === 42`. Strict equality against
a string will silently stop matching.

---

### 5. ESM only

`main`, `module` and the `import` condition all point at `index.es.js`; the
`require` condition is gone. The CJS/UMD half was never loadable anyway — the
output banner injects `import` / `import.meta.url`, which a UMD bundle cannot
parse as CommonJS — so this removes a build target that could not have been
working for you.

A CommonJS consumer must use dynamic `import()` or move to ESM.

---

### 6. `react-router` 8, and `react-router-dom` is gone

Only relevant if you use the admin panel — `@rebasepro/admin`, `app`, `studio`
or `plugin-ai`. A headless install has no router.

react-router 8 deletes the `react-router-dom` package. It was only ever a
v6-compatibility shim; everything DOM-specific had already collapsed into
`react-router` itself in v7. Drop the dependency and change two imports:

```diff
- import { createBrowserRouter, RouterProvider } from "react-router-dom";
+ import { createBrowserRouter } from "react-router";
+ import { RouterProvider } from "react-router/dom";
```

`RouterProvider` is the only name that moves to a subpath. Everything else —
`useNavigate`, `useLocation`, `useSearchParams`, `useParams`, `Link`, `NavLink`,
`Outlet`, `Navigate`, `Route`, `Routes`, `MemoryRouter`, `useBlocker` — keeps its
name and comes from `react-router`. So for most files this is one specifier:

```bash
grep -rl '"react-router-dom"' src | xargs sed -i '' 's|"react-router-dom"|"react-router"|g'
```

Then fix up the `RouterProvider` import wherever you mount the router, which is
usually one file.

The floors underneath move with it, because react-router 8 requires them:
`react` and `react-dom` at **19.2.7** or later, and Node **22.22.0** or later.

#### If your tests use Jest

This is the part that will cost you an afternoon if it surprises you.
react-router 8 is ESM-only, and it breaks ts-jest's CommonJS output two
different ways:

- react-router guards a Vite HMR hook with `import.meta.hot`. In CommonJS
  `import.meta` is a **syntax** error, and ts-jest cannot help — TypeScript
  emits the expression verbatim under `module: commonjs` rather than rejecting
  or rewriting it.
- react-router depends on `cookie-es` 3, which ships `.mjs` only, with no CJS
  build to resolve to instead. TypeScript keys module format off the file
  extension, so it will not emit CommonJS for a `.mjs` input whatever `module`
  says.

Every affected suite fails at **module load, with zero tests run**, so the
output reads as a broken Jest config rather than as a dependency-format problem.
The fix is a transformer that strips the HMR guard after ts-jest runs and
transpiles `.mjs` under a `.js` filename; Rebase's own is
[`scripts/jest/react-router-esm-transform.cjs`](https://github.com/rebasepro/rebase/blob/main/scripts/jest/react-router-esm-transform.cjs)
and is meant to be copied. You will also need react-router and `cookie-es`
lifted out of the blanket `node_modules` exclusion in
`transformIgnorePatterns`, and `mjs` added to `moduleFileExtensions`.

Vitest needs none of this.

---

### 7. Package renames

Import paths only — no behaviour moved with them.

| Old | New |
|---|---|
| `@rebasepro/core` | `@rebasepro/app` |
| `@rebasepro/server-core` | `@rebasepro/server` |
| `@rebasepro/server-postgresql` | `@rebasepro/server-postgres` |
| `@rebasepro/server-mongodb` | `@rebasepro/server-mongo` |
| `@rebasepro/client-postgresql` | `@rebasepro/client-postgres` |
| `@rebasepro/client-firebase` | `@rebasepro/firebase` |
| `@rebasepro/formex` | `@rebasepro/forms` |
| `@rebasepro/sdk-generator` | `@rebasepro/codegen` |
| `@rebasepro/schema-inference` | `@rebasepro/inference` |
| `@rebasepro/mcp-server` | `@rebasepro/mcp` |
| `@rebasepro/plugin-data-enhancement` | `@rebasepro/plugin-ai` |

Unchanged: `types`, `utils`, `common`, `client`, `admin`, `admin`, `studio`,
`cli`, `plugin-insights`.

The retired names are deprecated on npm, so installing one tells you rather
than resolving to an abandoned version.

Additionally, **`@rebasepro/auth` is removed**. `useRebaseAuthController`,
`fetchAuthConfig`, `createAuthConfigCache` and `clearAuthConfigCache` now come
from `@rebasepro/app`, beside the `RebaseAuth` and `LoginView` components they
are used with.

**`RebaseCMS` is now `RebaseAdmin`.** `mode: "cms"` on `RebaseBackendConfig` is
unchanged — it describes where collections come from, not the UI.

---

### 8. Every deprecated export is removed

Eleven symbols that carried `@deprecated` are gone rather than carried across
the 1.0 line, where removing one would cost a major.

#### `rebase.data` → `rebase.dataAsAdmin`

The one to grep for first, because it is the one with a security shape. The
server singleton had two names for a single **RLS-bypassing** accessor, and the
shorter one gave no hint of that — while on a browser client, `data` is the
*user-scoped* accessor. The same expression meant two very different things
depending on which side of the wire it ran.

```diff
- const { data: rows } = await rebase.data.projects.find();
+ const { data: rows } = await rebase.dataAsAdmin.projects.find();
```

```bash
grep -rn "rebase\.data\b" src config backend
```

`RebaseServerClient` extends `Omit<RebaseClient, "data">` now, so this is a
compile error rather than a silent privilege. The property is still there at
runtime, aliasing `dataAsAdmin`, so a plain-JavaScript backend keeps running
while you migrate — but do not rely on that.

**Leave these alone.** They are user-scoped and were never deprecated:

- `context.client.data` in an entity callback — runs under the caller's RLS
- `client.data` in a cron handler — a `RebaseClient`
- `rebase.data` in a generated SDK or browser app — a different object

And for user-scoped queries inside a request handler, neither name is what you
want: use `c.var.driver`, which carries the caller's identity.

#### The other ten

Each is a rename at the import site:

| Removed | From | Use instead |
|---|---|---|
| `buildCollection` | `@rebasepro/common` | `defineCollection` |
| `buildProperty` | `@rebasepro/common` | a plain property object |
| `RebaseUser` | `@rebasepro/client` | `User` |
| `RebaseTokens` | `@rebasepro/client` | `AuthTokens` |
| `UserInfo` | `@rebasepro/app` | `User` |
| `Session` | `@rebasepro/app` | `DeviceSession` |
| `AuthApiError` | `@rebasepro/app` | `RebaseApiError` |
| `DatabaseConnection` | `@rebasepro/server` | `DriverConnection` |
| `createApiKeyRateLimiter` | `@rebasepro/server` | `createDataRateLimiter` |
| `resolveChannelBusConfig` | `@rebasepro/server-postgres` | `resolveChannelBusSetting` |

`User`, `AuthTokens`, `DeviceSession` and `RebaseApiError` are all exported from
`@rebasepro/client` and `@rebasepro/app` directly — you do not need to add
`@rebasepro/types` to your `package.json` to name them.

Three of these are worth reading past the table:

**`createApiKeyRateLimiter` skipped every request that was not
API-key-authenticated** — on a normal deployment, nearly all of them. If you
wired it expecting protection, you had none for browser traffic.
`createDataRateLimiter` covers signed-in users and anonymous callers too.

**`buildCollection` and `buildProperty` were announced as removed in 0.11 and
were not.** If you migrated then, nothing changes now. If you did not, your
build kept working and breaks here.

**`DatabaseConnection` is still importable from `@rebasepro/server`** — that is
the point. Two shapes answered to the name; the local alias for
`DriverConnection` is gone and the canonical type from `@rebasepro/types`
remains. If your code still type-checks, you were already using the right one.

```bash
grep -rnE "buildCollection|buildProperty|RebaseUser|RebaseTokens|UserInfo|AuthApiError|createApiKeyRateLimiter|resolveChannelBusConfig" src config backend
```

---

### 9. `defaultSecurityRules` moved off the server config

It used to live on `RebaseBackendConfig`, where it enforced nothing: `db push`
generates the Postgres policies — the only thing that actually enforces
access — from the collection *files*, and never sees the running server.

Declare it in `config/collections/index.ts` instead, where the loader reads it
and both the runtime and `db push` see the same thing:

```ts
// config/collections/index.ts
export const defaultSecurityRules: SecurityRule[] = [
    { operation: "select", access: "public" },
    { operations: ["insert", "update", "delete"], roles: ["admin"] }
];
```

The old documentation claimed collections without rules were "unrestricted".
They are not — the generator locks them to admin-only.

In `baas` mode there are no collection files and no `db push`, so the
database's own RLS is the whole model and there is nothing to default.

---

### 10. Smaller behaviour changes

**A write naming a field the collection lacks is now a 400.** Unknown keys used
to travel into the INSERT, so a typo came back as `column "titel" does not
exist` — phrased by Postgres, from a stack the caller cannot see, and only when
the column really was absent. Bulk writes are checked before the transaction
opens and report the offending row index.

> **Auth collections are checked too, with one narrow exemption.** A signup body
> carries credential fields — `password` above all — that the users collection
> does not declare as columns, so the auth adapter names those explicitly and
> everything else is validated as usual. A typo like `emial` on a signup is a
> 400, same as on any other collection. (An auth collection wired to a custom
> `onCreateUser` hook opts out of the check, because the hook, not the
> collection, then defines the body's shape.)

**A collection file that fails to import is now a hard error.** The loader used
to log and continue, turning a broken file into a missing API route and a
missing policy with a successful exit code. Both read as "no data" rather than
as a failure.

**BaaS mode does not serve tables without row-level security.** A table with RLS
disabled is skipped and named at boot. `baas: { unprotectedTables: "serve" }`
restores the old behaviour.

---

### Upgrade checklist

```
[ ] grep for authenticated() and auth.uid() IS NOT NULL in config/collections/
[ ] decide the intent of each rule; rewrite the ones that meant "public"
[ ] replace not(authenticated()) with serverContext()
[ ] if realtime.requireAuth was true with an AuthAdapter, treat the socket as
    having been open — verify RLS on every subscribable collection (section 2)
[ ] SELECT ... FROM pg_policies — record the qual of every policy BEFORE
[ ] update package names and imports
[ ] grep for rebase.data — it is now rebase.dataAsAdmin (section 8)
[ ] grep for the other ten removed deprecated exports (section 8)
[ ] drop react-router-dom; import RouterProvider from "react-router/dom"
[ ] check node >= 22.22.0 and react >= 19.2.7 (react-router 8 requires both)
[ ] move defaultSecurityRules into config/collections/index.ts
[ ] grep for .userId
[ ] grep for row.id on tables not keyed on id
[ ] run db push
[ ] run rebase doctor --policies — expect no Insecure or Orphaned entries
[ ] SELECT ... FROM pg_policies again — confirm every intended change landed
[ ] exercise the app signed OUT, in a private window — watch the websocket too
```

`rebase doctor --policies` is the one to wire into CI: it exits non-zero on a
policy still carrying the permissive tautology, and on one an earlier push
superseded. The `pg_policies` reads before and after are still worth the minute —
they show you the expressions themselves, which is the only way to spot a
fail-open policy written in a spelling the detector does not match. Neither the
packages nor the type system will tell you: the change lives in the database, and
`db push` is the only thing that puts it there.

## Collections

### What is a Collection?

A **collection** is a TypeScript object that describes a database table and how it should appear in the admin UI. It defines:

- **Schema** — Properties (columns), their types, and validation rules
- **Relations** — Foreign keys, junction tables, and join paths
- **Security** — Row Level Security policies
- **Lifecycle hooks** — Callbacks for create, update, delete operations
- **Admin UI behavior** — View modes, inline editing, entity views, actions — all under `admin`

### Declaring one: `defineCollection`

Wrap the literal in `defineCollection`. At runtime it is the identity function — it
returns the object unchanged — so it costs nothing. What it buys is inference: a `const`
type parameter captures your `properties` keys as literal types, and the key-shaped
fields of the `admin` block are then checked against them. A name that is not one of
your properties is a **compile error**, not just a missing suggestion.

```typescript

const products = defineCollection({
    name: "Products",
    slug: "products",
    table: "products",
    properties: {
        name: { name: "Name", type: "string" },
        price: { name: "Price", type: "number" }
    },
    admin: {
        display: { title: "name" },  // completion: "name" | "price"
        sort: ["price", "asc"],      // completion on the first element
        propertiesOrder: ["name", "price"]
    }
});
```

```typescript
    admin: {
        display: { title: "nmae" }
        //                ~~~~~~ Type '"nmae"' is not assignable to type
        //                       'PropertyPath<…>'. Did you mean '"name"'?
    }
```

The checked fields are `display`, `sort`, `propertiesOrder` and `listProperties`.
Three forms are accepted besides a plain property key:

| Form | Example | Notes |
| --- | --- | --- |
| Dotted path into a `map` | `"profile.displayName"` | The **root** must be a real property; the path below it is not checked. |
| Child-collection column | `"subcollection:orders"` | `propertiesOrder` / `listProperties` only. |
| An `additionalFields` key | `"score" as AdditionalFieldKey` | Needs the cast — see below. |

`AdditionalFieldDelegate.key` is a plain `string`, so the type system has no way to know
which extra keys a collection declares. Rather than reopen these fields to every string,
the cast makes the exception explicit:

```typescript

propertiesOrder: ["title", "score" as AdditionalFieldKey]
```

Import it from `@rebasepro/admin-types` in a project that has an admin panel — that is
the copy that also typechecks the `admin` block. A headless BaaS project, which has no
admin block and no React, imports the same function from `@rebasepro/common` instead.

Annotating the type directly still works and is still checked:

```typescript

const products: PostgresCollectionConfig = {
    name: "Products",
    slug: "products",
    table: "products",
    properties: {
        name: { name: "Name", type: "string" }
    }
};
```

but an annotation only *validates the shape* — it cannot see your property names, so the
`admin` key fields fall back to accepting any string. Prefer `defineCollection` unless you
need to name the type.

:::note
`buildCollection` and `buildProperty` no longer exist. `buildCollection` is
`defineCollection` without the inference; `buildProperty` wrapped a property in a type it
already had. See the [changelog](/docs/changelog) for the one-line migration.
:::

### Anatomy: the contract, and the panel

One file, two audiences. Everything the *database and the API* care about sits at the
top level; everything the *admin panel* renders sits inside `admin`.

```typescript
const posts = {
    // ── The backend reads these ──────────────────────────────
    slug: "posts",
    table: "posts",
    properties: { /* … */ },
    relations: [ /* … */ ],
    securityRules: [ /* … */ ],
    callbacks: { /* … */ },
    history: true,

    // ── The admin panel reads these ──────────────────────────
    admin: {
        icon: "FileText",
        listProperties: ["title", "status"],
        defaultViewMode: "table",
        entityViews: ["preview"]
    }
};
```

The split is not cosmetic. It is what lets Rebase be a backend on its own:

- A **BaaS or headless** project never writes an `admin` block. Its collections — or no
  collections at all, since BaaS mode introspects the database — describe data and
  authorization, nothing else. `@rebasepro/types` contains no React, so there is no
  React anywhere in the dependency tree.
- The **backend never reads inside the block**. It is dropped before a collection is
  serialized to the contract endpoint or into a build bundle, and it is excluded from
  the schema version — so changing an icon does not report every generated SDK as
  stale.

#### The `admin` block exists only if you install the admin types

`@rebasepro/types` declares no `admin` field — not on a collection, not on a property. In
a BaaS project, writing one is a **type error**. `@rebasepro/admin-types` adds it back by
declaration merging, so one line per project turns it on:

```typescript no-verify
// config/admin.d.ts
/// <reference types="@rebasepro/admin-types" />
```

After that, plain core types carry a fully typed block — a typo like `icoon` is an error,
and you get completion:

```typescript

const posts = defineCollection({
    slug: "posts",
    name: "Posts",
    table: "posts",
    properties: {
        title: { name: "Title", type: "string", admin: { multiline: true } }
    },
    admin: { icon: "FileText" }
});
```

An augmentation applies to the whole TypeScript *program*, and `config/` and `frontend/`
are separate programs — which is why the reference belongs in the config package. There
is no `AdminCollectionConfig` wrapper type: with the field merged in, `CollectionConfig`
is the authoring type.

:::note[Why a BaaS project pays nothing]
A property type in a BaaS install has no `Field`, no `columnWidth`, no
`hideFromCollection` — those live in `AdminPropertyOptions` in the admin package. The
guarantee is asserted, not claimed: `e2e/baas-typecheck/src/admin_absent.ts` uses
`@ts-expect-error` on `admin`, so the build fails if the field ever becomes writable in
core again.
:::

#### Migrating from a flat collection

Before 0.11 these fields sat at the top level. To move them:

```bash
node scripts/codemod/collections-admin-block.mjs config/collections
```

It reports anything it cannot move safely — notably presentation inside
`relations[].overrides`, which needs `overrides: { admin: { … } }` by hand.

```typescript

export const productsCollection = defineCollection({
    slug: "products",              // URL path and API endpoint
    name: "Products",              // Display name (plural)
    singularName: "Product",       // Display name (singular)
    table: "products",            // PostgreSQL table name

    properties: {
        name: {
            type: "string",
            name: "Product Name",
            validation: { required: true }
        },
        price: {
            type: "number",
            name: "Price",
            validation: { required: true, min: 0 }
        },
        category: {
            type: "string",
            name: "Category",
            enum: [
                { id: "electronics", label: "Electronics", color: "blue" },
                { id: "clothing", label: "Clothing", color: "pink" },
                { id: "books", label: "Books", color: "orange" }
            ]
        },
        description: {
            type: "string",
            name: "Description",
            admin: { multiline: true }
        },
        active: {
            type: "boolean",
            name: "Active",
            defaultValue: true
        },
        created_at: {
            type: "date",
            name: "Created At",
            autoValue: "on_create",
            admin: { readOnly: true }
        }
    },
    admin: {
        icon: "inventory_2"           // Material icon key
    }
});

```

### Key Properties

#### Identification

| Property | Type | Description |
|----------|------|-------------|
| `slug` | `string` | **Required.** URL-safe identifier. Used in the admin UI URL and REST API path (`/api/data/{slug}`). |
| `name` | `string` | **Required.** Display name (plural). Shown in navigation and page headers. |
| `singularName` | `string` | Display name for a single entity. Used in "New Product", "Edit Product", etc. |
| `table` | `string` | **Required.** PostgreSQL table name. If different from `slug`, allows you to decouple URLs from table names. |
| `admin.icon` | `string` | Icon key. See [Google Fonts Icons](https://fonts.google.com/icons). |

#### Schema

| Property | Type | Description |
|----------|------|-------------|
| `properties` | `Properties` | **Required.** Map of property key → property definition. Each key becomes a database column. |
| `relations` | `Relation[]` | SQL relations — foreign keys, junction tables. See [Relations](/docs/collections/relations). |
| `securityRules` | `SecurityRule[]` | Row Level Security policies. See [Security Rules](/docs/collections/security-rules). |
| `auth` | `boolean | AuthCollectionConfig` | Mark collection as authentication collection (user management, reset password, etc.) |

#### UI Configuration

All of the following go inside `admin`.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `defaultViewMode` | `"list" \| "table" \| "cards" \| "kanban"` | `"table"` | Default view mode |
| `enabledViews` | `ViewMode[]` | All four | Which view modes are available |
| `kanban` | `KanbanConfig` | — | Kanban configuration (column property) |
| `openEntityMode` | `"side_panel" \| "full_screen" \| "split" \| "dialog"` | `"full_screen"` | How entities open for editing |
| `sideDialogWidth` | `number \| string` | — | Width of the side dialog |
| `inlineEditing` | `boolean` | `true` | Enable inline editing in the spreadsheet view |
| `defaultSize` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Default row height in the table |
| `pagination` | `boolean \| number` | `true` (50) | Enable pagination and/or set page size |
| `listProperties` | `string[]` | — | Properties to display in the list view |
| `propertiesOrder` | `string[]` | — | Column order in the table view |
| `selectionEnabled` | `boolean` | `true` | Enable row selection |
| `hideFromNavigation` | `boolean` | `false` | Hide from the sidebar navigation |
| `defaultSelectedView` | `string \| function` | — | Default view or subcollection to open |

#### Entity Options

Inside `admin`, except `history`, which is a backend feature and stays at the top level.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `formAutoSave` | `boolean` | `false` | Auto-save on field change |
| `localChangesBackup` | `"manual_apply" \| "auto_apply" \| false` | `"manual_apply"` | Backup unsaved changes |
| `hideIdFromForm` | `boolean` | `false` | Hide the entity ID from the form |
| `hideIdFromCollection` | `boolean` | `false` | Hide the ID column from the table |
| `includeJsonView` | `boolean` | `true` | Offer the raw values in the record inspector |
| `history` | `boolean` | `false` | Track changes in entity history |
| `alwaysApplyDefaultValues` | `boolean` | `false` | Apply default values on every save |
| `previewProperties` | `string[]` | — | Properties to display in reference previews |
| `display` | `EntityDisplay` | — | What fills each display role — see [Entity display](#entity-display) |

#### Advanced

| Property | Type | Description |
|----------|------|-------------|
| `callbacks` | `CollectionCallbacks` | Lifecycle hooks (`beforeSave`, `afterSave`, `beforeDelete`, etc.) |
| `entityActions` | `EntityAction[]` | Custom actions on entities (archive, publish, etc.) |
| `Actions` | `React.ComponentType` | Custom toolbar actions component |
| `entityViews` | `EntityCustomView[]` | Custom tabs in the entity detail view |
| `additionalFields` | `AdditionalFieldDelegate[]` | Computed/virtual columns |
| `childCollections` | `() => CollectionConfig[]` | Nested child collections |
| `subcollections` | `() => CollectionConfig[]` | Nested collections (e.g., order → line items) |
| `exportable` | `boolean \| ExportConfig` | Enable data export |
| `ownerId` | `string` | Owner user ID (used by plugins/custom code) |
| `overrides` | `EntityOverrides` | Overrides for the entity view |
| `components` | `CollectionComponentOverrideMap` | Collection-scoped UI component overrides |
| `driver` | `string` | Database driver to use (default: `"(default)"`) |
| `databaseId` | `string` | Database/schema ID within the driver |

### Entity display

Every surface that draws a record draws some subset of six roles: **title**,
**subtitle**, **image**, **status**, **date** and **tags**. A list row is image +
title + subtitle + status + date, a card is the same with the image on top, a
reference picker is title + subtitle, and a page heading is the title alone.

Each role is derived from your properties, and each can be stated instead — as a
property path, or as a function:

```typescript
const exercises = defineCollection({
    name: "Exercises",
    slug: "exercises",
    table: "exercises",
    properties: {
        name: { name: "Name", type: "string" },
        cover: { name: "Cover", type: "string", storage: { storagePath: "covers/" } },
        city: { name: "City", type: "string" }
    },
    admin: {
        display: {
            title: "name",                                  // a property path
            image: "cover",
            subtitle: ({ entity }) => `in ${entity.values.city}`   // computed
        }
    }
});
```

Anything you leave out keeps its derived value, so stating one role does not
mean stating all six.

#### Computed and async roles

A resolver may be `async`, which is what lets a role read something the record
does not carry — a document in a subcollection, a value behind an API:

```typescript
admin: {
    display: {
        // The exercise's name lives one document down, per locale.
        title: async ({ entity, context }) => {
            const locale = await context.data.exercise_locales.get(`${entity.id}/de-DE`);
            return locale?.exercise_title;
        }
    }
}
```

While the promise is in flight the surface shows the derived value and swaps the
resolved one in when it lands — a title is never a spinner. Results are cached
per record and per role, and concurrent asks for the same pair share one call, so
a list of fifty rows resolves each row once rather than once per render.

Return `undefined` when a record has nothing for the role; the surface's own
fallback is better informed about what belongs there instead (a heading uses the
singular collection name, a link uses the id). A resolver that throws is treated
as `undefined` and logged once — a title that cannot be fetched must not take
down the row that shows it.

Prefer a path whenever the value is on the record: a path keeps the property's
own rendering, so an enum status stays a coloured chip and a date stays
formatted, which a resolver returning a bare string cannot express.

:::note[Renamed from `titleProperty`]
`admin.titleProperty` is now `admin.display.title`. The same string works there,
and the new field also takes a resolver. The old key is still read, and warns
once per collection at startup.
:::

#### Title Property Selection
When `display.title` is not set, the property used as the entity's display title (previews, headers) is resolved automatically:
1. If `propertiesOrder` is explicitly defined, the first non-ID property that is either a `relation` or `string` type is chosen as the title.
2. If no `propertiesOrder` is defined, the framework searches the properties in order and picks the first string type property.

#### Relation Previews in Tables
When `propertiesOrder` is explicitly set, relation properties are **not** automatically filtered out of the default preview columns (whereas they are excluded from unordered defaults to avoid slow join operations).

#### resolveTitleToString Utility
Rebase provides a `resolveTitleToString(title: any): string` helper to turn complex entity title values (including dates, arrays, or relation shapes like `{ __type: "relation", id, data: { values } }`) into clean, human-readable strings. It prioritizes common fields like `name`, `title`, `label`, and `displayName` from nested relation data.

### Collection Builder

For dynamic collections that change based on the user or external data, use a builder function:

```typescript
const collectionsBuilder: CollectionConfigsBuilder = ({ user, authController }) => {
    const collections = [productsCollection];

    if (authController.extra?.role === "admin") {
        collections.push(adminSettingsCollection);
    }

    return collections;
};
```

### Filtering and Sorting

You can set default or forced filters:

```typescript
{
    // Default filter — users can change it
    defaultFilter: { active: ["==", true] },

    // Fixed filter — cannot be changed
    fixedFilter: { tenant_id: ["==", currentTenantId] },

    // Default sort
    sort: ["created_at", "desc"]
}
```

### Next Steps

- **[Entity Callbacks](/docs/collections/callbacks)** — Lifecycle hooks for syncing data between collections, validation, side effects
- **[Properties](/docs/collections/properties)** — All property types and options
- **[Relations](/docs/collections/relations)** — Foreign keys, junction tables, joins
- **[Security Rules](/docs/collections/security-rules)** — Row Level Security
- **[View Modes](/docs/frontend/view-modes)** — List, Table, Cards, Kanban

## Properties


### Overview

Properties define the columns in your database table and how they are rendered in the admin UI. Each property has a `type` that determines:

- The **database column type** (via Drizzle schema generation)
- The **form field** component
- The **table cell** renderer
- The **validation** rules

### Property Types

| Type | Description | PostgreSQL Column |
|------|-------------|-------------------|
| `string` | Text, select, markdown, file upload, URL, email | `varchar`, `text`, `jsonb` |
| `number` | Integer, decimal, currency | `integer`, `numeric`, `bigint`, `serial` |
| `boolean` | True/false toggle | `boolean` |
| `date` | Date, datetime, timestamp | `timestamp`, `date` |
| `array` | Ordered list of values | `jsonb` |
| `map` | Key-value object | `jsonb` |
| `geopoint` | Latitude/longitude pair | `jsonb` |
| `reference` | Embedded reference to another entity | `varchar` (stores ID) |
| `relation` | SQL foreign key relation | Uses the `relations` array |

### Common Properties

All property types share these options:

| Property | Type | Description |
|----------|------|-------------|
| `type` | `string` | **Required.** Data type (see above) |
| `name` | `string` | **Required.** Display label |
| `description` | `string` | Help text shown below the field |
| `defaultValue` | `any` | Default value for new entities |
| `validation` | `object` | Validation rules |
| `propertyConfig` | `string` | Registered property config key |
| `columnName` | `string` | Explicit database column name (bypasses snake_case conversion) |
| `callbacks` | `PropertyCallbacks` | Hooks for `afterRead` and `beforeSave` transforms |
| `dynamicProps` | `function` | Dynamic property builder (see Conditional Fields) |
| `conditions` | `PropertyConditions` | Declarative JSON Logic conditions |

#### UI Configuration (`admin`)

UI-related options are nested under the `admin` sub-object:

```typescript
price: {
    type: "number",
    name: "Price",
    admin: {
        readOnly: true,
        columnWidth: 120,
        hideFromCollection: false
    }
}
```

| Property | Type | Description |
|----------|------|-------------|
| `admin.readOnly` | `boolean` | Prevent editing |
| `admin.disabled` | `boolean \| PropertyDisabledConfig` | Disable with optional tooltip |
| `admin.hideFromCollection` | `boolean` | Hide from table view |
| `admin.columnWidth` | `number` | Column width in pixels (table view) |
| `admin.span` | `1 \| 2 \| 3 \| 4` | Field width over the four-column form grid |
| `admin.Field` | `React.ComponentType` | Custom field component |
| `admin.Preview` | `React.ComponentType` | Custom table cell component |

### String Properties

The `string` type is the most versatile — depending on the options you set, it renders as different widgets.

#### Text field

A basic single-line text input.

```typescript
name: {
    type: "string",
    name: "Name",
    validation: { required: true, min: 2, max: 200 }
}
```

#### Multiline text

Set `multiline: true` to render as a textarea.

```typescript
description: {
    type: "string",
    name: "Description",
    multiline: true
}
```

#### Markdown editor

Set `markdown: true` to render a full markdown editor with toolbar.

```typescript
body: {
    type: "string",
    name: "Blog text",
    markdown: true
}
```

#### Email field

Set `email: true` to add email format validation and render with an email icon.

```typescript
email: {
    type: "string",
    name: "User email",
    email: true,
    validation: { required: true }
}
```

#### URL field

Set `url: true` to add URL format validation and render with a link icon.

```typescript
website: {
    type: "string",
    name: "Amazon link",
    url: true
}
```

#### File upload

Set `storage` to render a file upload dropzone.

```typescript
avatar: {
    type: "string",
    name: "Main image",
    storage: {
        storagePath: "avatars",
        acceptedFiles: ["image/*"],
        maxSize: 2 * 1024 * 1024
    }
}
```

#### Select (enum)

Set `enum` to render a select dropdown. See the [Enum Values](#enum-values) section for details.

```typescript no-verify
category: {
    type: "string",
    name: "Category",
    enum: [
        { id: "electronics", label: "Electronics", color: "blueDark" },
        { id: "clothing", label: "Clothing", color: "pink" },
    ]
}
```

#### Multi-select

Set `enum` + `multiSelect: true` to allow picking multiple values.

```typescript no-verify
locales: {
    type: "string",
    name: "Available locales",
    multiSelect: true,
    enum: [
        { id: "es", label: "Spanish", color: "pink" },
        { id: "en", label: "English", color: "blueLight" },
        { id: "fr", label: "French", color: "purpleLight" },
    ]
}
```

#### String Options

| Property | Type | Description |
|----------|------|-------------|
| `admin.multiline` | `boolean` | Render as textarea |
| `admin.markdown` | `boolean` | Render as markdown editor |
| `email` | `boolean` | Email format validation |
| `url` | `boolean` | URL format validation |
| `storage` | `StorageConfig` | Enable file upload |
| `enum` | `EnumValues` | Render as select dropdown |
| `multiSelect` | `boolean` | Allow multiple enum selections |
| `columnType` | `string` | Database column: `"varchar"`, `"text"` |
| `isId` | `string` | ID generation: `"uuid"`, `"cuid"`, `"increment"`, `"manual"` |
| `userSelect` | `boolean` | Render as a user picker |
| `admin.previewAsTag` | `boolean` | Render this string as a tag in previews |
| `admin.clearable` | `boolean` | Add an icon to clear the value (set to null) |

### Number Properties

```typescript
price: {
    type: "number",
    name: "Price",
    validation: { required: true, min: 0 }
}

quantity: {
    type: "number",
    name: "Quantity",
    columnType: "integer"  // Store as integer
}
```

Number fields render as a standard text input with numeric validation.

#### Number Options

| Property | Type | Description |
|----------|------|-------------|
| `enum` | `EnumValues` | Render as select with numeric values |
| `columnType` | `string` | `"integer"`, `"bigint"`, `"numeric"`, `"serial"`, `"smallint"` |
| `isId` | `string` | ID generation strategy |
| `admin.clearable` | `boolean` | Add an icon to clear the value (set to null) |

### Boolean Properties

```typescript
active: {
    type: "boolean",
    name: "Selectable",
    defaultValue: true
}
```

Booleans render as a toggle switch.

### Date Properties

#### Date only

Set `mode: "date"` to show a date picker without time.

```typescript
event_date: {
    type: "date",
    name: "Expiry date",
    mode: "date"
}
```

#### Date and time

The default mode `"date_time"` includes both date and time.

```typescript
arrival_time: {
    type: "date",
    name: "Arrival time",
    mode: "date_time"
}
```

#### Auto timestamps

Use `autoValue` to automatically set timestamps on create or update.

```typescript
created_at: {
    type: "date",
    name: "Created At",
    autoValue: "on_create",
    admin: { readOnly: true }
}

updated_at: {
    type: "date",
    name: "Updated At",
    autoValue: "on_update"
}
```

#### Date Options

| Property | Type | Description |
|----------|------|-------------|
| `mode` | `"date" \| "date_time"` | Date only or date + time (default: `"date_time"`) |
| `autoValue` | `"on_create" \| "on_update"` | Auto-set timestamps |
| `columnType` | `string` | `"timestamp"`, `"date"` |
| `timezone` | `string` | Timezone string to evaluate the date in |
| `admin.clearable` | `boolean` | Add an icon to clear the value (set to null) |

### Array Properties

#### Simple repeat

Use `of` to define a repeatable list of items.

```typescript
tags: {
    type: "array",
    name: "Tags",
    of: { type: "string" }
}
```

#### Multi file upload

Combine `of` with `storage` for a multi-file upload.

```typescript
images: {
    type: "array",
    name: "Images",
    of: {
        type: "string",
        storage: { storagePath: "images", acceptedFiles: ["image/*"] }
    }
}
```

#### Block editor

Use `oneOf` to create a block editor with multiple content types. Each key creates a card type that users can pick from.

```typescript
content: {
    type: "array",
    name: "Content",
    oneOf: {
        properties: {
            text: {
                type: "map",
                properties: {
                    body: { type: "string", name: "Text", markdown: true }
                }
            },
            image: {
                type: "map",
                properties: {
                    src: { type: "string", name: "Image", storage: { storagePath: "content" } },
                    caption: { type: "string", name: "Caption" }
                }
            }
        }
    }
}
```

#### Array Options

| Property | Type | Description |
|----------|------|-------------|
| `of` | `Property \| Property[]` | Property schema for array items |
| `oneOf` | `object` | Array of typed objects with multiple discriminator types |
| `admin.expanded` | `boolean` | Should the field be initially expanded (default: true) |
| `admin.minimalistView` | `boolean` | Display child properties directly without extendable panel |
| `admin.sortable` | `boolean` | Can elements be reordered (default: true) |
| `admin.canAddElements` | `boolean` | Can new elements be added (default: true) |

### Map Properties

#### Group (structured)

Use `properties` to define a structured object with named fields.

```typescript
address: {
    type: "map",
    name: "Address",
    properties: {
        street: { type: "string", name: "Street" },
        zip: { type: "string", name: "Postal code" }
    }
}
```

#### Key-value (free-form)

Set `keyValue: true` to render an arbitrary key-value pairs editor.

```typescript
metadata: {
    type: "map",
    name: "Key value",
    keyValue: true
}
```

#### Map Options

| Property | Type | Description |
|----------|------|-------------|
| `properties` | `Properties` | Record of properties included in the map |
| `propertiesOrder` | `string[]` | Ordered keys for rendering |
| `admin.previewProperties` | `string[]` | Which properties to show in the table preview |
| `admin.spreadChildren` | `boolean` | Render child properties as separate columns in table view |
| `admin.minimalistView` | `boolean` | Display properties without a wrapping panel |
| `admin.expanded` | `boolean` | Should the field be initially expanded (default: true) |
| `keyValue` | `boolean` | Render as arbitrary key-value pairs editor |

### Reference Properties

References link to entities in another collection. They render as a preview card showing the referenced entity's details.

```typescript
client: {
    type: "reference",
    name: "Related client",
    path: "clients",
    admin: {
        previewProperties: ["first_name", "last_name", "email"]
    }
}
```

#### Reference & Relation Options

These apply to both `reference` and `relation` properties.

| Property | Type | Description |
|----------|------|-------------|
| `admin.fixedFilter` | `FilterValues` | Filter the entities offered in the selection widget |
| `admin.widget` | `"select" \| "dialog"` | Which widget selects the related entity (relations only) |
| `admin.includeId` | `boolean` | Show the related entity's id in previews (default: true) |
| `admin.includeEntityLink` | `boolean` | Show a link that opens the related entity (default: true) |
| `admin.previewProperties` | `string[]` | Which of the target's properties appear in the preview (max 3) |

### Enum Values

Used with string or number properties to render selects:

```typescript no-verify
// Simple array
enum: ["draft", "published", "archived"]

// With labels
enum: [
    { id: "draft", label: "Draft" },
    { id: "published", label: "Published" },
    { id: "archived", label: "Archived" }
]

// With colors (for Kanban columns and chips)
enum: [
    { id: "draft", label: "Draft", color: "grayDark" },
    { id: "published", label: "Published", color: "greenDark" },
    { id: "archived", label: "Archived", color: "orangeDark" }
]
```

### Validation

```typescript
validation: {
    required: true,             // Field is required
    unique: true,               // Must be unique in the table
    requiredMessage: "Custom error message",

    // String-specific
    min: 2,                     // Minimum length
    max: 200,                   // Maximum length
    matches: /^[a-z]+$/,       // Regex pattern
    email: true,                // Email format
    url: true,                  // URL format

    // Number-specific
    min: 0,                     // Minimum value
    max: 1000,                  // Maximum value
    integer: true,              // Must be integer

    // Array-specific
    min: 1,                     // Minimum items
    max: 10,                    // Maximum items
}
```

### Conditional Fields

You can make fields dynamic so they react to the entity's values. There are two ways to do this:

#### 1. JSON Logic Conditions (Declarative)

You can use the `conditions` property to define declarative JSON Logic rules that can be serialized and modified visually in the collection editor.

```typescript
price: {
    type: "number",
    name: "Price",
    conditions: {
        disabled: { "==": [{ "var": "values.is_free" }, true] },
        required: { "!=": [{ "var": "values.is_free" }, true] },
        min: 0,
        clearOnDisabled: true // Set to null if field gets disabled
    }
}
```

The conditions object gives you access to:
- `disabled`, `hidden`, `readOnly`
- `required`, `min`, `max`
- `defaultValue`
- `enumConditions`, `allowedEnumValues`, `excludedEnumValues`
- `referencePath`, `referenceFilter`
- `canAddElements`, `sortable` (for arrays)

#### 2. Property Builders (Programmatic)

For complex behavior that can't be expressed via JSON Logic, you can use `dynamicProps` which evaluates a Javascript function.

```typescript
price: {
    type: "number",
    name: "Price",
    dynamicProps: ({ values, user }) => ({
        disabled: values.is_free === true || !user.roles.includes("admin"),
        validation: values.is_free ? {} : { required: true, min: 0 }
    })
}
```

### Next Steps

- **[Relations](/docs/collections/relations)** — Foreign keys and joins
- **[Security Rules](/docs/collections/security-rules)** — Row Level Security
- **[Custom Fields](/docs/frontend/custom-fields)** — Build custom field components

## Relations

### Overview

Relations define how collections are connected at the database level. They enable Rebase to:

- Render **relation picker fields** in entity forms
- Resolve **related entities** when displaying previews
- Generate **foreign key constraints** in the Drizzle schema
- Support **cascade delete/update** behaviors

Relations can be defined either inline within the property, or explicitly in the `relations` array of a collection:

#### 1. Inline Relations (Recommended)

Declare the link on the property, nested under `relation`. Pick the `kind` and
the type offers exactly the fields that kind needs.

```typescript

const postsCollection = defineCollection({
    slug: "posts",
    name: "Posts",
    table: "posts",
    properties: {
        title: { type: "string", name: "Title" },
        content: { type: "string", name: "Content", admin: { multiline: true } },
        author: {
            type: "relation",
            name: "Author",
            relation: {
                kind: "belongsTo",
                target: () => usersCollection
            }
        }
    }
});
```

#### 2. Explicit Relations Array

For a link with no property of its own — nothing to name it by in the form or in
a table column — declare it in `relations`:

```typescript

const usersCollection = defineCollection({
    slug: "users",
    name: "Users",
    table: "users",
    properties: {
        name: { type: "string", name: "Name" }
    },
    relations: [
        {
            kind: "hasMany",
            relationName: "posts",
            target: () => postsCollection
        }
    ]
});
```

### The five kinds

A relation is one of five kinds. The kind decides where the key lives, whether
one row or many come back, and what a write through it may touch.

| Kind | The key lives | Returns | Notes |
|---|---|---|---|
| `belongsTo` | on **this** table | one | `localKey`, defaults to `<relationName>_id` |
| `hasOne` | on the **target's** table | one | `foreignKeyOnTarget`, defaults to `<thisCollection>_id` |
| `hasMany` | on the **target's** table | many | children belong to this parent alone |
| `manyToMany` | in a **junction table** | many | rows are shared; you own the link |
| `via` | an explicit `joinPath` | either | read-only; state `cardinality` yourself |

Every field is optional except `kind` and `target` — the rest is derived.

#### belongsTo — the key is on this table

```typescript
author: {
    type: "relation",
    name: "Author",
    relation: { kind: "belongsTo", target: () => usersCollection }
}
// → posts.author_id
```

#### hasMany / hasOne — the key is on theirs

```typescript
relations: [
    { kind: "hasMany", relationName: "posts", target: () => postsCollection }
]
// → reads posts.user_id
```

`hasOne` is the same link with at most one row on the far side.

##### Joining on a natural key

By default the target's foreign key holds the source row's **id**. When the two
sides are joined on something else — an external identity id, a SKU, a tenant
slug — name that column with `sourceKey`:

```typescript
relations: [
    {
        kind: "hasMany",
        relationName: "applications",
        target: () => applicationsCollection,
        sourceKey: "auth_user_id",          // column on THIS table
        foreignKeyOnTarget: "auth_user_id"  // column on the TARGET's table
    }
]
// → reads applications.auth_user_id = talents.auth_user_id
```

`sourceKey` is the mirror of `localKey` on `belongsTo`: that one names the
column this side reads *from*, this one names the column the other side points
*at*. Without it a link like the above is not expressible as `hasMany` at all
and has to drop to [`via`](#via--an-explicit-join-chain), which is read-only.

The column must be unique. A link that addresses more than one source row
cannot say which one a related row belongs to, and Postgres will not accept a
foreign key against a non-unique column either. Rebase checks this at read
time and refuses rather than picking one.

A parent whose `sourceKey` is `NULL` reaches no rows, and writing through the
relation is an error — there is nothing for the related rows to point at.

#### manyToMany — through a junction

```typescript
tags: {
    type: "relation",
    name: "Tags",
    relation: { kind: "manyToMany", target: () => tagsCollection }
}
// → junction `posts_tags` (both table names, sorted), columns post_id / tag_id
```

Both sides declare their own, and each writes `through` **from its own point of
view** — `sourceColumn` always names *this* collection:

```typescript
// on posts
{ kind: "manyToMany", relationName: "tags", target: () => tagsCollection,
  through: { table: "posts_tags", sourceColumn: "post_id", targetColumn: "tag_id" } }

// on tags
{ kind: "manyToMany", relationName: "posts", target: () => postsCollection,
  through: { table: "posts_tags", sourceColumn: "tag_id", targetColumn: "post_id" } }
```

#### via — an explicit join chain

For links the four shapes above cannot express: multi-hop paths, composite keys,
or a join whose condition is not a plain foreign key. Read-only — Rebase will
not infer how to write through an arbitrary chain.

```typescript
{
    kind: "via",
    relationName: "permissions",
    target: () => permissionsCollection,
    cardinality: "many",
    joinPath: [
        { table: "user_roles",       on: { from: "id",            to: "user_id" } },
        { table: "role_permissions", on: { from: "role_id",       to: "role_id" } },
        { table: "permissions",      on: { from: "permission_id", to: "id" } }
    ]
}
```

### Relation Properties

To render a relation field in a form, add a property with `type: "relation"`:

```typescript
properties: {
    author: {
        type: "relation",
        name: "Author",
        relation: { kind: "belongsTo", target: () => usersCollection },
        widget: "select"           // "select" (dropdown) or "dialog" (full picker)
    }
}
```

![Relation field in form](/img/features/relation-form-field.png)

When rendering a preview (like in a table cell or a reference chip), Rebase handles hydration automatically:

![Relation preview in table](/img/features/relation-table-preview.png)

#### To-one gets a picker, many gets a tab

The cardinality decides the surface, and only one surface is used:

- **`belongsTo` / `hasOne`** — one row, so the property is a foreign key the
  author edits. It renders as the picker above.
- **`hasMany` / `manyToMany`** — many rows, so the entity view lists them as a
  **tab** of their own. The property is not rendered in the form: a collection's
  children are a list, not a value the record holds, and selecting them from a
  dropdown is not something the form can meaningfully offer.

Declaring a many-relation as a property is still worth doing — it is what names
the tab, and what gives the relation a column in the collection table, which the
list fetch hydrates so the child rows show up as chips on the row. Only the form
field is dropped.

In the table, a relation with a property of its own gets **one** column: its own.
Every tab also has a jump-to-tab button column, but for a property-declared
relation that button repeated the same heading beside a column already showing
the children, so it is dropped. Hide the relation's column
(`admin: { hideFromCollection: true }`) and the button comes back, so the
relation never falls out of the table entirely.

If you want the inline picker anyway, ask for it:

```typescript
properties: {
    tags: {
        type: "relation",
        name: "Tags",
        relation: { kind: "manyToMany", target: () => tagsCollection },
        admin: { renderInForm: true }   // off by default; the tab is the default treatment
    }
}
```

### Multi-Hop Joins

For relationships that traverse multiple tables, use `kind: "via"` with a `joinPath`.
These are read-only: Rebase will not infer how to write through an arbitrary chain.

```typescript
// Users → Permissions through Roles
relations: [
    {
        kind: "via",
        relationName: "permissions",
        target: () => permissionsCollection,
        cardinality: "many",
        joinPath: [
            {
                table: "user_roles",
                on: { from: "id", to: "user_id" }
            },
            {
                table: "roles",
                on: { from: "role_id", to: "id" }
            },
            {
                table: "role_permissions",
                on: { from: "id", to: "role_id" }
            },
            {
                table: "permissions",
                on: { from: "permission_id", to: "id" }
            }
        ]
    }
]
```

#### Composite Key Joins

```typescript
joinPath: [
    {
        table: "customers",
        on: {
            from: ["company_code", "region_id"],  // Multiple columns
            to: ["code", "region_id"]
        }
    }
]
```

### Cascade Rules

Control what happens when related entities are updated or deleted:

```typescript
relations: [
    {
        kind: "belongsTo",
        relationName: "author",
        target: () => usersCollection,
        localKey: "author_id",
        onDelete: "cascade",    // Delete posts when user is deleted
        onUpdate: "cascade"     // Update FK when user ID changes
    }
]
```

| Action | Behavior |
|--------|----------|
| `"cascade"` | Propagate the change to related rows |
| `"restrict"` | Prevent the operation if related rows exist |
| `"no action"` | Same as restrict (defer to constraint check) |
| `"set null"` | Set the FK column to NULL |
| `"set default"` | Set the FK column to its default value |

### Fetching Relations in the SDK

When querying data through the Rebase Client SDK, relations are **not** included by default. Use the `include()` method to request related entities alongside the primary data.

#### Include specific relations

```typescript
const { data } = await client.data.articles
    .include("author", "categories")
    .find();
```

#### Include all relations

```typescript
const { data } = await client.data.articles
    .include("*")
    .find();
```

#### Using params syntax

```typescript
const { data } = await client.data.articles.find({
    include: ["author", "categories"]
});
```

#### Response structure

When included, the response contains both the **scalar foreign key** and the **hydrated relation object**:

```typescript
const { data } = await client.data
    .collection<{ id: string; author_id: string; author?: { name: string } }>("articles")
    .include("author")
    .find();

// The SDK returns flat rows — there is no `.values` wrapper. (`Entity`, with
// `id`/`path`/`values`, is an admin-UI view model, not what the client hands back.)
for (const article of data) {
    // Scalar FK — always present
    article.author_id;     // "uuid-1234"

    // Hydrated relation — only present when included
    article.author?.name;  // "Jane Doe"
}
```

> The relation names passed to `include()` must match the `relationName` defined in the collection's `relations` array.

For the full query builder reference (filtering, sorting, pagination, real-time), see the [Client SDK documentation](/docs/sdk).

### Relations in the admin panel

Every to-many relation — `hasMany`, `manyToMany`, or a to-many `via` — becomes a
**tab** under a record in the admin panel, listing the rows that record reaches.

#### The path segment is the relation name

A child list is addressed as `parent/parentId/relationName`:

```
/c/authors/a-1/posts          the posts of author a-1
/c/posts/p-1/tags             the tags of post p-1
```

The last segment is the **relation name**, not the target collection's slug. They
are often the same, because an unnamed relation takes its target's slug — but an
inline relation property takes the *property key*:

```typescript
properties: {
    featuredTags: {
        type: "relation",
        relation: { kind: "manyToMany", target: () => tagsCollection }
    }
}
// tab and path segment: featuredTags   (not "tags")
```

This is also what makes two relations to the same collection work: each has its own
name, so each gets its own tab and its own path.

#### Owned rows versus shared rows

What a tab lets you do depends on how the relation is stored, because the two cases
mean different things:

| | One-to-many (`foreignKeyOnTarget`) | Many-to-many (`through`) |
|---|---|---|
| The child belongs to | this parent alone | every parent that links it |
| Create | creates the row under this parent | creates the row and links it |
| Add existing | — | links an existing row |
| Remove | **deletes** the row | **unlinks** it; the row is untouched |

The admin panel renders each accordingly: a many-to-many tab offers **Add existing**
and **Remove from this record**, and never a delete that would take the row away
from other parents.

#### The same rules over REST

Child lists are ordinary collection queries narrowed to one parent, so they accept
everything a root list does — filters, `orderBy`, `limit`, `offset`, `include` — and
`meta.total` counts the filtered rows. Filter either per field (`?field=op.value`) or
with a whole-object `?where={"field":["op","value"]}`; both reach the same query:

```
GET    /api/data/authors/a-1/posts?status=eq.published&orderBy=title&limit=20
GET    /api/data/authors/a-1/posts?where={"status":["==","published"]}&orderBy=title
GET    /api/data/authors/a-1/posts/p-1
POST   /api/data/authors/a-1/posts          create under this parent
PUT    /api/data/authors/a-1/posts/p-1      update; will not reparent
DELETE /api/data/authors/a-1/posts/p-1      delete (one-to-many) / unlink (many-to-many)
```

The parent segment is enforced, not decorative. Addressing a row that is not under
that parent returns `404`, and `PUT` never moves a row from one parent to another —
set the foreign key explicitly if that is what you want.

For a many-to-many, `PUT parent/id/child/childId` is *set membership*: it links the
row if it is not linked yet, and is idempotent. That is how you attach a row that
already exists.

#### What does not become a tab

- **To-one relations** — they are a field on the record, not a list. Writing through
  a to-one path is rejected: the foreign key lives on the parent's table.
- **Relations declared inside a `map`** — they are a field of that map.

### Full Relation Interface

`Relation` is a closed union — one member per kind, each carrying only the
fields that kind has. There is no combination of fields that describes two
different links, and no field you can set that the kind does not use.

```typescript
type Relation =
    | BelongsToRelation
    | HasOneRelation
    | HasManyRelation
    | ManyToManyRelation
    | ViaRelation;

interface RelationBase {
    relationName?: string;          // defaults to the property key, then the target's slug
    target: () => CollectionConfig;
    onUpdate?: OnAction;
    onDelete?: OnAction;
    overrides?: Partial<CollectionConfig>;   // applied when rendered as a tab
    validation?: { required?: boolean };
}

interface BelongsToRelation extends RelationBase {
    kind: "belongsTo";
    localKey?: string;              // column on THIS table
}

interface HasOneRelation extends RelationBase {
    kind: "hasOne";
    foreignKeyOnTarget?: string;    // column on the TARGET's table
    sourceKey?: string;             // column on THIS table; defaults to the primary key
}

interface HasManyRelation extends RelationBase {
    kind: "hasMany";
    foreignKeyOnTarget?: string;    // column on the TARGET's table
    sourceKey?: string;             // column on THIS table; defaults to the primary key
}

interface ManyToManyRelation extends RelationBase {
    kind: "manyToMany";
    through?: { table?: string; sourceColumn?: string; targetColumn?: string };
}

interface ViaRelation extends RelationBase {
    kind: "via";
    cardinality: "one" | "many";    // a join chain cannot imply it
    joinPath: JoinStep[];
}
```

#### The resolved form

What you write above is the *authoring* shape. Internally Rebase works with
`ResolvedRelation`: the same link with every default filled in and nothing
optional, plus `cardinality`, `targetSlug`, and two flags — `writable` (false
only for `via`) and `shared` (true when the target rows belong to other parents
too, so a removal unlinks rather than deletes).

`sourceKey` is the one exception to "nothing optional": its default is the
source's primary key, and resolving that needs the driver's schema, which
resolution does not have. `undefined` there means "the primary key" and nothing
else.

You never write a `ResolvedRelation`. On a relation property, `relation` is
yours and `resolvedRelation` is the filled-in one, stamped during
normalization.

### Next Steps

- **[Security Rules](/docs/collections/security-rules)** — Row Level Security
- **[Properties](/docs/collections/properties)** — Property types reference

## Entity Callbacks

### Overview

Callbacks let you hook into the entity lifecycle to:

- **Sync data between collections** — copy or move entities across tables on status changes
- **Transform data** before saving (computed fields, slugification)
- **Validate** business rules beyond schema validation
- **Trigger side effects** after writes (send emails, sync APIs, update caches)
- **Filter/transform** data after reading
- **Cascade operations** — clean up related records on delete

### Defining Callbacks

```typescript

// The row shape. Without it every `values.x` below is `unknown`.
type Article = {
    title: string;
    slug: string;
    created_at: string;
    updated_at: string;
};

const articlesCollection: PostgresCollectionConfig<Article> = {
    slug: "articles",
    name: "Articles",
    table: "articles",
    properties: {
        title: { name: "Title", type: "string" },
        slug: { name: "Slug", type: "string" },
        created_at: { name: "Created at", type: "string" },
        updated_at: { name: "Updated at", type: "string" }
    },
    callbacks: {
        beforeSave: async ({ values, id, status }) => {
            // Auto-generate slug from title
            if (values.title) {
                values.slug = values.title
                    .toLowerCase()
                    .replace(/[^a-z0-9]+/g, "-")
                    .replace(/(^-|-$)/g, "");
            }

            // Set timestamps
            if (status === "new") {
                values.created_at = new Date().toISOString();
            }
            values.updated_at = new Date().toISOString();

            return values;
        },

        afterSave: async ({ values, id }) => {
            // Send notification
            console.log(`Article ${id} saved: ${values.title}`);
        },

        beforeDelete: async ({ id }) => {
            // Prevent deletion of published articles
            // Throw to block the deletion
        },

        afterRead: async ({ row }) => {
            // Transform data after loading
            return row;
        }
    },
    properties: { /* ... */ }
});
```

### Callback Reference

#### `beforeSave`

Called before a entity is written to the database. Return the modified values.

```typescript
beforeSave: async ({
    values,       // Entity values
    id,           // Entity ID (null for new entities)
    status,       // "new" | "existing" | "copy"
    previousValues, // Previous values (for updates)
    context       // Full Rebase context
}) => {
    // Return modified values
    return { ...values, updated_at: new Date() };
}
```

Throw an error to **block the save**:

```typescript
beforeSave: async ({ values }) => {
    if (values.price < 0) {
        throw new Error("Price cannot be negative");
    }
    return values;
}
```

#### `afterSave`

Called after a successful save. Use for side effects.

```typescript
afterSave: async ({
    values,         // Saved values
    id,             // Entity ID
    previousValues, // Previous values (null for new entities)
    status,         // "new" | "existing" | "copy"
    context
}) => {
    // Send webhook
    await fetch("https://api.slack.com/webhook", {
        method: "POST",
        body: JSON.stringify({ text: `New article: ${values.title}` })
    });
}
```

#### `afterSaveError`

Called when a save operation fails.

```typescript
afterSaveError: async ({
    values,
    id,
    error,
    context
}) => {
    console.error("Save failed:", error);
}
```

#### `afterRead`

Called after reading entities from the database. Transform the data for display.

```typescript
afterRead: async ({
    row,    // The row to transform
    context
}) => {
    // Add computed fields
    return {
        ...row,
        displayName: `${row.first_name} ${row.last_name}`
    };
}
```

#### `beforeDelete`

Called before a entity is deleted. Throw to block deletion.

```typescript
beforeDelete: async ({
    id,
    row,
    context
}) => {
    if (row.status === "published") {
        throw new Error("Cannot delete published articles. Unpublish first.");
    }
}
```

#### `afterDelete`

Called after a successful deletion.

```typescript
afterDelete: async ({
    id,
    row,
    context
}) => {
    // Cleanup related data
    console.log(`Article ${id} deleted`);
}
```

### Property Callbacks

You can also define callbacks at the property level for field-specific transformations:

```typescript
properties: {
    email: {
        type: "string",
        name: "Email",
        callbacks: {
            beforeSave: ({ value }) => value?.toLowerCase().trim(),
            afterRead: ({ value }) => value // Could decrypt, etc.
        }
    }
}
```

### The `context.data` API

Every callback receives a `context` object that includes `context.data` — a unified data access layer for performing **cross-collection operations** from within lifecycle hooks.

#### Accessing Collections

`context.data` uses a JavaScript Proxy, so you can access any collection by its slug as a property:

```typescript
afterSave: async ({ values, entityId, context }) => {
    // Dynamic property access — works for any collection slug
    const jobs = context.data.jobs;
    const users = context.data.users;

    // Alternatively, use the .collection() method for dynamic slugs
    const collectionName = "jobs";
    const accessor = context.data.collection(collectionName);
}
```

#### Available Methods

Each collection accessor (`context.data.<slug>`) provides these methods:

| Method | Signature | Description |
|--------|-----------|-------------|
| `.find()` | `find(params?: FindParams) → FindResponse` | Query entities with filters, sorting, and pagination |
| `.findById()` | `findById(id: string \| number) → Entity \| undefined` | Fetch a single entity by ID |
| `.create()` | `create(data: Partial<Values>, id?: string) → Entity` | Create a new entity |
| `.update()` | `update(id: string \| number, data: Partial<Values>) → Entity` | Update an existing entity |
| `.delete()` | `delete(id: string \| number) → void` | Delete a entity |
| `.count()` | `count(params?: FindParams) → number` | Count matching entities |
| `.listen()` | `listen(params, onUpdate, onError?) → unsubscribe` | Real-time subscription (where supported) |
| `.listenById()` | `listenById(id, onUpdate, onError?) → unsubscribe` | Listen to a single entity |

#### Querying with `.find()`

The `find()` method supports rich filtering:

```typescript
afterSave: async ({ values, context }) => {
    // Simple equality
    const { data: activeJobs } = await context.data.jobs.find({
        where: { status: "published" },
        limit: 10,
        orderBy: ["created_at", "desc"]
    });

    // PostgREST-style operators
    const { data: recentJobs } = await context.data.jobs.find({
        where: {
            status: "eq.published",
            salary: "gte.50000"
        }
    });

    // Tuple syntax
    const { data: expensiveJobs } = await context.data.jobs.find({
        where: {
            salary: [">=", 100000],
            role: ["in", ["admin", "manager"]]
        }
    });
}
```

#### Creating Entities

```typescript
afterSave: async ({ values, entityId, previousValues, context }) => {
    // Promote an approved submission to a published job
    if (values.status === "approved" && previousValues?.status !== "approved") {
        const newJob = await context.data.jobs.create({
            title: values.title,
            description: values.description,
            company_id: values.company_id,
            status: "published",
            source_submission_id: entityId,
        });

        // Link back to the original submission
        await context.data["job-submissions"].update(entityId, {
            promoted_job_id: newJob.id,
        });
    }
}
```

#### Security: which privileges `context.data` runs with

:::important
**`context.data` inherits the privileges of whatever triggered the callback.** It is not a fixed trust level.

- Triggered by a **user request** (REST, realtime, an admin-panel edit) → **user-scoped**. The callback runs inside the RLS-bound transaction opened for that request, so policies apply to reads *and* writes. A callback cannot see a row its caller could not.
- Triggered by **`rebase.dataAsAdmin` or a cron job** (the same singleton) → **admin-scoped**, not unscoped. That driver is scoped as `{ uid: "service", roles: ["admin"] }`, so the callback still runs on an RLS-bound transaction — your policies are evaluated, against that identity.
- Triggered by **the base driver** (built-in auth flows, migrations) → **unscoped**. It runs on the owner connection and bypasses RLS.
:::

This matters most in the direction that fails quietly. RLS *filters*, it does not raise — so a callback that reads a sibling row will find it when an admin task saves and may find nothing when an end user saves, with no error either way. Write callbacks that tolerate an empty result, or reach for the admin plane deliberately:

```typescript
afterSave: async ({ context }) => {
    // User-scoped when a user triggered this save: RLS applies.
    await context.data.audit_logs.create({ action: "approved" });

    // Deliberately admin-scoped — for work the caller genuinely may not see,
    // such as an audit trail they must not be able to read or edit. Note this
    // is an admin's reach, not a bypass: a collection whose only rule is
    // `policy.serverContext()` stays closed to it, since that compiles to
    // `auth.uid() IS NULL` and this accessor's uid is `service`.
    await context.client.dataAsAdmin.audit_logs.create({ action: "approved" });
}
```

:::caution[This page used to say the opposite]
Earlier versions of this page stated that callbacks always bypass RLS and have "full database access regardless of the triggering user's permissions". That was wrong, and wrong in the unsafe direction — it invited callbacks written on the assumption that they could always see everything.

The behaviour above is verified end-to-end against Postgres by the `"scopes context.data to the caller when a callback runs on a user request"` case in `@rebasepro/server-postgres`' RLS-enforcement suite.
:::

#### Transaction Semantics

:::warning
**`context.data` operations are NOT automatically wrapped in the same transaction as the triggering save.**

The original entity save completes its database transaction first. Then `afterSave` runs and any `context.data` calls open **separate transactions**. If a `context.data` operation fails in `afterSave`, the original save is **not rolled back**.
:::

This means:

- ✅ The triggering save always succeeds independently
- ⚠️ Side-effect writes may fail without affecting the original operation
- ⚠️ There is no atomicity guarantee between the original save and subsequent `context.data` calls

For operations that must be atomic, wrap them in error handling:

```typescript
afterSave: async ({ values, entityId, context }) => {
    try {
        await context.data.jobs.create({
            title: values.title,
            status: "published",
        });
    } catch (error) {
        // Log the failure — the original save already succeeded
        console.error(`Failed to promote job from submission ${id}:`, error);
        // Optionally: mark the submission as "promotion_failed"
        await context.data["job-submissions"].update(id, {
            promotion_status: "failed",
            promotion_error: String(error),
        });
    }
}
```

### Syncing Data Between Collections

One of the most powerful uses of callbacks is **syncing data across collections** using `context.data`:

```typescript

type Submission = {
    title: string;
    description: string;
    company_id: string;
    status: string;
    promoted_job_id: string;
};

const submissionsCollection: PostgresCollectionConfig<Submission> = {
    slug: "job_submissions",
    name: "Job Submissions",
    table: "job_submissions",
    properties: {
        title: { name: "Title", type: "string" },
        description: { name: "Description", type: "string" },
        company_id: { name: "Company", type: "string" },
        status: { name: "Status", type: "string" },
        promoted_job_id: { name: "Promoted job", type: "string" }
    },
    callbacks: {
        afterSave: async ({ values, id, previousValues, context }) => {
            // When a submission is approved, create a published job
            if (values.status === "approved" && previousValues?.status !== "approved") {
                const newJob = await context.data.collection<Record<string, unknown>>("jobs").create({
                    title: values.title,
                    description: values.description,
                    company_id: values.company_id,
                    status: "published",
                    source_submission_id: id,
                });

                // Update the submission with the promoted job reference
                await context.data.collection<Record<string, unknown>>("job_submissions").update(id, {
                    promoted_job_id: newJob.id,
                });
            }
        }
    },
    properties: { /* ... */ }
});
```

Other cross-collection patterns:

- **Cascade delete**: Use `afterDelete` to remove related records in child collections
- **Denormalization**: Use `afterSave` to update summary fields in a parent collection
- **Audit logging**: Use `afterSave` / `afterDelete` to write to an audit log collection
- **Counters**: Use `afterSave` / `afterDelete` to update count fields on related entities

### Full Context Reference

Every callback receives a `context` object of type `RebaseCallContext`:

```typescript
interface RebaseCallContext {
    /** The authenticated user, if any */
    user?: User;
    /** The underlying data driver (PostgresBackendDriver) */
    driver: DataDriver;
    /** Unified data access — context.data.<slug>.create/update/find/delete */
    data: RebaseData;
}
```

### Next Steps

- **[Security Rules](/docs/collections/security-rules)** — Row Level Security
- **[Entity History](/docs/backend/history)** — Audit trail
- **[Custom Functions](/docs/backend/custom-functions)** — Add custom API endpoints

## Security Rules (RLS)

### Overview

Security rules let you define **Row Level Security (RLS)** policies for your PostgreSQL tables directly in your collection definitions. When the Drizzle schema is generated, Rebase creates the corresponding `CREATE POLICY` statements.

```typescript

const postsCollection = defineCollection({
    slug: "posts",
    name: "Posts",
    table: "posts",
    properties: { /* ... */ },
    securityRules: [
        { operation: "select", access: "public" },
        { operations: ["insert", "update", "delete"], ownerField: "author_id" }
    ]
});
```

### How It Works

1. You define `securityRules` on a collection
2. `rebase schema generate` creates Drizzle schema with RLS enabled
3. `rebase db push` or `rebase db migrate` applies the policies to PostgreSQL
4. Every query is filtered by the current user's context automatically

The authenticated user's identity is available in SQL via:

| Function | Returns |
|----------|---------|
| `rebase.uid()` | The current user's ID |
| `rebase.roles()` | Comma-separated app role IDs |
| `rebase.jwt()` | Full JWT claims as JSONB |

These are set automatically per-transaction by the Rebase backend.

### Convenience Shortcuts

#### Owner-based Access

The simplest pattern — users can only access rows they own:

```typescript
securityRules: [
    { operation: "all", ownerField: "user_id" }
]
```

This generates: `USING (user_id = rebase.uid())`

#### Public Access

Allow anyone (including unauthenticated users) to read:

```typescript
securityRules: [
    { operation: "select", access: "public" }
]
```

This generates: `USING (true)`

#### Authenticated Access

Allow any authenticated user:

```typescript
securityRules: [
    { operation: "select", access: "authenticated" }
]
```

#### Role-based Access

Restrict operations to specific roles:

```typescript
securityRules: [
    { operation: "all", roles: ["admin"] },
    { operation: "select", roles: ["editor", "viewer"] }
]
```

#### Membership / Relational Access

To scope access by membership in a *related* collection — e.g. "only rows whose
team the caller belongs to" — use the structured `condition` with
`policy.existsIn`. It compiles to a single correlated `EXISTS` subquery (no
per-row lookups), and is the safe, first-class alternative to hand-writing the
raw SQL shown below.

```typescript

// documents visible only to members of the document's team:
securityRules: [
    {
        operation: "select",
        condition: policy.existsIn({
            collection: "team_members",         // the join / membership collection
            where: policy.and(
                // correlate to the row being checked:
                policy.compare(policy.field("team_id"), "eq", policy.outerField("team_id")),
                // …and to the caller:
                policy.compare(policy.field("user_id"), "eq", policy.authUid()),
            ),
        }),
    },
]
```

Inside `where`, `policy.field(...)` refers to a column of the joined collection
(`team_members`), while `policy.outerField(...)` refers to a column of the row
being checked (`documents`). Combine with `policy.authUid()` to scope to the
current user. Because it is enforced by the database, the admin UI treats it as
server-authoritative.

### Raw SQL Expressions

For complex logic, use `using` and `withCheck`:

```typescript
securityRules: [
    {
        operation: "select",
        using: "EXISTS (SELECT 1 FROM org_members WHERE org_members.org_id = {org_id} AND org_members.user_id = rebase.uid())"
    }
]
```

- **`using`** — Filters which existing rows are visible (applies to SELECT, UPDATE, DELETE)
- **`withCheck`** — Validates new row values (applies to INSERT, UPDATE)

Column references use `{column_name}` syntax which gets resolved to the full table-qualified column.

### Combining Shortcuts and SQL

Mix convenience shortcuts with raw SQL:

```typescript
securityRules: [
    // Admins can do anything
    { operation: "all", roles: ["admin"], using: "true" },
    // Regular users can only see their own rows
    { operation: "select", ownerField: "user_id" },
    // Users can insert, but only for themselves
    { operation: "insert", withCheck: "{user_id} = rebase.uid()" },
    // Locked rows cannot be updated
    { operation: "update", mode: "restrictive", using: "{is_locked} = false" }
]
```

### Permissive vs Restrictive

PostgreSQL has two policy modes:

- **Permissive** (default) — Multiple permissive policies are **OR'd** together. If any one passes, access is granted.
- **Restrictive** — Restrictive policies are **AND'd** together. All must pass.

```typescript
securityRules: [
    // Permissive: owners can access their rows
    { operation: "all", ownerField: "user_id" },
    // Restrictive: but locked rows cannot be updated
    { operation: "update", mode: "restrictive", using: "{is_locked} = false", withCheck: "{is_locked} = false" }
]
```

### Operations

| Operation | SQL Equivalent | Description |
|-----------|---------------|-------------|
| `"select"` | `SELECT` | Read rows |
| `"insert"` | `INSERT` | Create new rows |
| `"update"` | `UPDATE` | Modify existing rows |
| `"delete"` | `DELETE` | Remove rows |
| `"all"` | All of the above | Shorthand for all operations |

You can also use `operations` (plural) to apply one rule to multiple operations:

```typescript
{ operations: ["insert", "update", "delete"], ownerField: "author_id" }
```

### Full SecurityRule Interface

```typescript
interface SecurityRule {
    name?: string;              // Human-readable policy name
    operation?: SecurityOperation;   // Single operation
    operations?: SecurityOperation[]; // Multiple operations
    mode?: "permissive" | "restrictive"; // Default: "permissive"
    access?: "public" | "authenticated";
    ownerField?: string;        // Column containing the owner user ID
    roles?: string[];           // App roles that this policy applies to
    using?: string;             // Raw SQL USING expression
    withCheck?: string;         // Raw SQL WITH CHECK expression
}
```

### Examples

#### Blog Platform

```typescript
securityRules: [
    // Anyone can read published posts
    { operation: "select", using: "{status} = 'published'" },
    // Authors can see their own drafts
    { operation: "select", ownerField: "author_id" },
    // Authors can create and edit their own posts
    { operations: ["insert", "update"], ownerField: "author_id" },
    // Only admins can delete
    { operation: "delete", roles: ["admin"] }
]
```

#### Multi-Tenant SaaS

```typescript
securityRules: [
    {
        operation: "all",
        using: "EXISTS (SELECT 1 FROM org_members WHERE org_members.org_id = {org_id} AND org_members.user_id = rebase.uid())"
    }
]
```

### Anonymous Access (Public Inserts)

A common need is allowing **unauthenticated users** to submit data — contact forms, newsletter signups, public applications. Rebase provides a clean pattern for this.

#### Recommended: a raw `withCheck` rule

```typescript

const contactMessagesCollection: PostgresCollectionConfig = {
    slug: "contact_messages",
    name: "Contact Messages",
    table: "contact_messages",
    securityRules: [
        // Anyone can submit a contact message
        {
            operation: "insert",
            // A raw rule carries `using` (which rows are visible) and `withCheck`
            // (what a write must satisfy); an insert only exercises the latter.
            using: "true",
            withCheck: "true"
        },
        // Only admins can read, update, or delete messages
        { operations: ["select", "update", "delete"], roles: ["admin"] }
    ],
    properties: {
        email: { name: "Email", type: "string" }
    }
};
```

The `access: "public"` shortcut generates a policy that allows the operation without requiring authentication.

#### For Lead Capture / Signups

```typescript

const leadSignupsCollection: PostgresCollectionConfig = {
    slug: "lead_magnet_signups",
    name: "Lead Magnet Signups",
    table: "lead_magnet_signups",
    securityRules: [
        // Allow anonymous inserts
        { operation: "insert", using: "true", withCheck: "true" },
        // Admins can view all signups
        { operation: "select", roles: ["admin"] }
    ],
    properties: {
        email: { name: "Email", type: "string" }
    }
};
```

#### How Anonymous Requests Work

When a request arrives without a JWT token, the Rebase backend sets the PostgreSQL session variables to:

| Variable | Value |
|----------|-------|
| `app.user_id` | `'anonymous'` |
| `app.user_roles` | `''` (empty) |

This means:

- `rebase.uid()` returns `'anonymous'`
- `rebase.roles()` returns an empty string
- `access: "public"` policies pass because they generate `USING (true)` / `WITH CHECK (true)`
- `access: "authenticated"` policies fail because they check for a real user ID
- `ownerField` policies fail because no row will have `user_id = 'anonymous'` (unless explicitly set)

#### Advanced: Raw SQL for Anonymous

If you need more granular control, use raw SQL:

```typescript
securityRules: [
    {
        operation: "insert",
        withCheck: "rebase.uid() = 'anonymous' OR rebase.uid() IS NOT NULL"
    }
]
```

:::tip
Avoid the legacy pattern of checking `string_to_array(rebase.roles(), ',')` for anonymous access. The `access: "public"` shortcut is simpler and generates the correct policy automatically.
:::

### Next Steps

- **[Relations](/docs/collections/relations)** — Foreign keys and joins
- **[Entity Callbacks](/docs/collections/callbacks)** — Lifecycle hooks
- **[Custom Functions](/docs/backend/custom-functions)** — Custom API endpoints

## Backend Overview

### Overview

The Rebase backend is a **Node.js server** built on [Hono](https://hono.dev/) that provides:

- **REST API** — Auto-generated CRUD endpoints for each collection
- **Authentication** — JWT tokens, Google OAuth, user/role management
- **Storage** — File upload/download with local filesystem or S3
- **WebSocket** — Real-time data sync via PostgreSQL LISTEN/NOTIFY
- **Entity History** — Audit trail for every data change
- **Database Branching** — Instant, isolated database copies for dev/staging/testing
- **Cron Jobs** — Scheduled background tasks with monitoring dashboard

Everything is initialized with a single function:

```typescript

const instance = await initializeRebaseBackend({
    app,
    server,
    collectionsDir: "./config/collections",
    database: createPostgresAdapter({
        connection: db,
        schema: { tables, enums, relations }
    }),
    auth: {
        jwtSecret: env.JWT_SECRET,
    },
    storage: { type: "local", basePath: "./uploads" },
    history: true,
    enableSwagger: env.NODE_ENV !== "production"
});
```

### What Gets Created

After initialization, these routes are mounted:

| Path | Purpose |
|------|---------|
| `/api/auth/*` | Authentication (signup, login, refresh, Google OAuth) |
| `/api/admin/*` | User and role management (admin-only) |
| `/api/storage/*` | File upload, download, and deletion |
| `/api/data/collections` | Collection metadata endpoint |
| `/api/data/:slug` | CRUD operations per collection (GET, POST, PUT, DELETE) |
| `/api/data/:slug/:id/history` | Entity change history (when enabled) |
| `/api/data/docs` | OpenAPI spec (when `enableSwagger: true`) |
| `/api/data/swagger` | Swagger UI (dev mode, when `enableSwagger: true`) |
| `/api/functions/*` | Custom function routes (when `functionsDir` is set) |
| `/api/cron/*` | Cron job management (admin-only, when `cronsDir` is set) |
| WebSocket on upgrade | Real-time subscriptions |

---

### The Initialization Lifecycle

When you invoke `initializeRebaseBackend()`, the framework triggers a sequential, 5-stage boot sequence:

```
[Start Boot]
     │
     ▼
1. ENV validation (Zod parsing of jwt, databases, cors)
     │
     ▼
2. Dynamic Collection Loading (Chokidar watches .ts files, AST parsing)
     │
     ▼
3. Database Bootstrapping (Acquires advisory lock, creates schemas/auth/helper SQL functions)
     │
     ▼
4. Service Initialization (Auth, Storage S3/Local client instances, Cron store seeding)
     │
     ▼
5. Route Mounting & Edge Loading (Hono controllers, custom functions, WebSocket binding)
     │
     ▼
[Boot Complete]
```

---

### Startup Fail-Closed Protection

Rebase enforces a strict **fail-closed security posture** during database connection outages. 

If the database is unreachable during boot (e.g., PostgreSQL is starting or network routes are severed):
- The server does **not** crash or enter a restart loop. Instead, the bootstrapper transitions the backend into a **degraded status mode**.
- The HTTP server starts successfully to preserve health check endpoints, but all REST and WebSocket controllers are immediately locked.
- Any client attempting to read or write data gets a uniform `503 Service Unavailable` response:
  ```json
  {
    "error": {
      "message": "Database connection is not ready.",
      "code": "service-unavailable",
      "status": 503
    }
  }
  ```
- The framework attempts to re-establish the connection pool in the background, recovering automatically when the database becomes healthy.

---

### Configuration Reference

```typescript
interface RebaseBackendConfig {
    // HTTP framework
    app: Hono;               // Hono application instance
    server: Server;           // Node.js HTTP server (for WebSocket attachment)
    basePath?: string;        // Route prefix (default: "/api")

    // Collections
    collections?: CollectionConfig[];  // Your collection definitions
    collectionsDir?: string;  // Auto-load collections from a directory

    // Database adapter (PostgreSQL, SQLite, etc.)
    database?: DatabaseAdapter;

    // Authentication configuration or custom adapter
    auth?: RebaseAuthConfig | AuthAdapter;

    // File storage
    storage?: BackendStorageConfig | Record<string, BackendStorageConfig>;

    // Entity history
    history?: boolean | HistoryConfig;

    // OpenAPI/Swagger
    enableSwagger?: boolean;

    // Custom API endpoints
    functionsDir?: string;    // Auto-load Hono routes from a directory

    // Scheduled tasks
    cronsDir?: string;        // Auto-load cron jobs from a directory

    // Logging
    logging?: { level?: "error" | "warn" | "info" | "debug" };
}
```

### The Backend Instance

`initializeRebaseBackend` returns a `RebaseBackendInstance` with access to internal services:

```typescript
const instance = await initializeRebaseBackend(config);

// Internal service access
instance.driver              // Default data driver
instance.driverRegistry      // All drivers (for multi-database)
instance.realtimeService     // Default realtime service
instance.auth?.userService       // User management
instance.auth?.roleService       // Role management
instance.storageController   // Default storage
instance.storageRegistry     // All storage backends
instance.collectionRegistry  // Collection metadata
instance.history?.historyService // Entity history
instance.cronScheduler       // Cron job scheduler (when cronsDir is set)
```

> **Note:** While the `instance` exposes these internal services, application code (such as custom functions and cron jobs) should use the global `rebase` singleton from `@rebasepro/server` to interact with the backend API.

### REST API

The REST API is auto-generated from your collections. Every collection gets these endpoints:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/data/:slug` | List entities (with filter, sort, limit, search) |
| `GET` | `/api/data/:slug/:id` | Get a single entity |
| `POST` | `/api/data/:slug` | Create a new entity |
| `PUT` | `/api/data/:slug/:id` | Update a entity |
| `DELETE` | `/api/data/:slug/:id` | Delete a entity |

#### Query Parameters

| Param | Description | Example |
|-------|-------------|---------|
| `filter` | JSON-encoded filter conditions | `?filter={"active":["==",true]}` |
| `orderBy` | Sort field | `?orderBy=created_at` |
| `order` | Sort direction | `?order=desc` |
| `limit` | Page size | `?limit=25` |
| `startAfter` | Cursor for pagination | `?startAfter=encodedCursor` |
| `search` | Full-text search | `?search=laptop` |

### WebSocket

The WebSocket server attaches to the same HTTP server and provides real-time subscriptions:

- Subscribe to **collection changes** — get notified when any entity in a collection is created, updated, or deleted
- Subscribe to **entity changes** — get notified when a specific entity changes
- Automatic **reconnection** handling in the client SDK

The backend uses PostgreSQL `LISTEN/NOTIFY` internally. For multi-instance deployments, provide a `connectionString` in your `PostgresBootstrapper` to enable cross-instance broadcasting.

### Error Handling

The backend includes an error handler that catches all exceptions and returns structured error responses:

```json
{
    "error": {
        "message": "Entity not found",
        "code": "not-found",
        "status": 404
    }
}
```

If initialization fails (e.g., database connection error), the server still starts but returns 503 for all API requests, with a descriptive error message in the logs.

### Next Steps

- **[Authentication](/docs/backend/authentication)** — JWT, Google OAuth, user management
- **[Storage](/docs/backend/storage)** — Local and S3 file storage
- **[Entity Callbacks](/docs/collections/callbacks)** — Lifecycle hooks and `context.data` API
- **[Entity History](/docs/backend/history)** — Audit trail
- **[Custom Functions](/docs/backend/custom-functions)** — Add custom API endpoints
- **[Cron Jobs](/docs/backend/cron-jobs)** — Scheduled background tasks
- **[Database Branching](/docs/backend/branching)** — Instant database copies for dev/staging

## REST API

### Overview

Rebase automatically generates a complete API from your collection definitions:

- **REST API** — CRUD endpoints for every collection at `/api/data/:slug`
- **OpenAPI spec** — Machine-readable spec at `/api/docs`
- **Swagger UI** — Interactive API explorer at `/api/swagger` (dev mode only)

No code is required — define your collections and the API appears automatically.

### REST Endpoints

For each collection, the following endpoints are generated:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/data/:slug` | List entities |
| `GET` | `/api/data/:slug/count` | Count entities |
| `GET` | `/api/data/:slug/:id` | Get a single entity |
| `POST` | `/api/data/:slug` | Create a entity |
| `PATCH` | `/api/data/:slug/:id` | Update a entity (partial — only the properties you send are written) |
| `PUT` | `/api/data/:slug/:id` | Same handler as `PATCH`, kept because every shipped SDK sends it |
| `DELETE` | `/api/data/:slug/:id` | Delete a entity |
| `POST` | `/api/data/:slug/bulk` | Create many entities in one transaction |
| `PATCH` | `/api/data/:slug/bulk` | Update many entities in one transaction |
| `POST` | `/api/data/:slug/bulk/delete` | Delete many entities in one transaction |

#### Subcollection Routes

Nested relations are accessible via URL paths:

```
GET    /api/data/authors/42/posts         → list author's posts
GET    /api/data/authors/42/posts/7       → get a specific post by author
POST   /api/data/authors/42/posts         → create a post for author
PATCH  /api/data/authors/42/posts/7       → update the post (PUT also accepted)
DELETE /api/data/authors/42/posts/7       → delete the post
```

##### Routing Mechanics & Segment Parsing

To handle arbitrary nested subcollection depths, Rebase routes incoming requests using Hono's `:rest{.+}` parameter regex. The internal segment parsing engine analyzes paths by counting slash-separated segments:
- **Odd segment count** (e.g., `authors/42/posts` -> 3 segments) represents a collection list request.
- **Even segment count** (e.g., `authors/42/posts/7` -> 4 segments) represents an operation on a specific entity ID. The last segment is popped as the target `entityId`.

The engine filters out reserved system namespaces (e.g., `history`) from the path segment analysis to prevent collisions with built-in endpoints.

### Authentication

All data endpoints require authentication by default. Include a Bearer token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer <access-token>" \
     https://api.example.com/api/data/products
```

For server-to-server calls, use the service key:

```bash
curl -H "Authorization: Bearer <service-key>" \
     https://api.example.com/api/data/products
```

### Filtering

Use PostgREST-style query parameters to filter results. The format is `?field=operator.value`:

```bash
# Exact match
GET /api/data/products?active=eq.true

# Comparison operators
GET /api/data/products?price=gt.100
GET /api/data/products?price=lte.50

# Multiple filters (AND)
GET /api/data/products?active=eq.true&price=gt.10

# IN operator — match any value in a set
GET /api/data/products?status=in.(draft,published)

# NOT IN
GET /api/data/products?status=nin.(archived,deleted)

# Array contains
GET /api/data/products?tags=cs.electronics

# Array contains any
GET /api/data/products?tags=csa.(electronics,books)
```

#### Filter Operators

| Operator | Meaning | Example |
|----------|---------|---------|
| `eq` | Equals (`==`) | `?active=eq.true` |
| `neq` | Not equals (`!=`) | `?status=neq.draft` |
| `gt` | Greater than (`>`) | `?price=gt.100` |
| `gte` | Greater or equal (`>=`) | `?price=gte.100` |
| `lt` | Less than (`<`) | `?price=lt.50` |
| `lte` | Less or equal (`<=`) | `?price=lte.50` |
| `in` | In array | `?status=in.(a,b,c)` |
| `nin` | Not in array | `?status=nin.(a,b)` |
| `cs` | Array contains | `?tags=cs.value` |
| `csa` | Array contains any | `?tags=csa.(a,b)` |

#### Logical Operators

Use `or` and `and` for complex conditions:

```bash
# OR: match products that are either cheap or on sale
GET /api/data/products?or=(price.lt.10,on_sale.eq.true)

# AND: explicit conjunction
GET /api/data/products?and=(active.eq.true,price.gt.0)
```

### Sorting

Use `orderBy` with the format `field:direction`:

```bash
# Sort by price descending
GET /api/data/products?orderBy=price:desc

# Sort by name ascending (default)
GET /api/data/products?orderBy=name:asc
```

### Pagination

Use `limit` and `offset`, or `page`:

```bash
# Limit and offset
GET /api/data/products?limit=20&offset=40

# Page-based (uses default limit of 20)
GET /api/data/products?page=3
```

The default limit is **20**, the maximum is **100**.

#### Response Format

List responses include pagination metadata:

```json
{
    "data": [
        { "id": 1, "name": "Widget", "price": 29.99 },
        { "id": 2, "name": "Gadget", "price": 49.99 }
    ],
    "meta": {
        "total": 150,
        "limit": 20,
        "offset": 0,
        "hasMore": true
    }
}
```

Single entity responses return a flat object:

```json
{
    "id": 1,
    "name": "Widget",
    "price": 29.99,
    "created_at": "2026-01-15T10:30:00Z"
}
```

### Text Search

Use `searchString` for full-text search across string fields:

```bash
GET /api/data/products?searchString=wireless%20keyboard
```

### Vector Search

If a collection defines a property with a type of `vector`, you can perform high-speed similarity searches using pgvector distance operations compiled directly in the database query.

```bash
GET /api/data/products?vector_search=embedding&vector=[0.15,0.22,-0.05]&vector_distance=cosine&vector_threshold=0.8
```

#### Vector Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `vector_search` | `string` | The name of the vector property to query against. |
| `vector` | `string` | A JSON-serialized array of floats representing the query vector. |
| `vector_distance` | `string` | The distance metric to evaluate. Supported values: `cosine` (default, `<=>`), `l2` (`<->`), `inner_product` (`<#>`). |
| `vector_threshold` | `number` | Maximum distance threshold. Only records with distance less than this threshold are returned. |

### Relation Inclusion

Use the `include` parameter to embed related entities:

```bash
# Include specific relations
GET /api/data/articles?include=author,categories

# Include all relations
GET /api/data/articles?include=*
```

Included relations are embedded directly in the response:

```json
{
    "id": 1,
    "title": "Getting Started",
    "author_id": 42,
    "author": {
        "id": 42,
        "name": "Jane Doe",
        "email": "jane@example.com"
    }
}
```

### Field Selection

Use `fields` to select specific columns:

```bash
GET /api/data/products?fields=id,name,price
```

### Lifecycle Hook Pipeline

Every REST mutation operation (`POST`, `PUT`, `DELETE`) runs through a strict, sequential hook execution pipeline:

```
Request ──► beforeSave/beforeDelete (blocking) ──► DB Operation ──► afterSave/afterDelete (deferred) ──► Response
```

#### Blocking vs. Deferred Hooks

1. **Blocking Hooks (`beforeSave`, `beforeDelete`)**
   These hooks are executed synchronously in the main request cycle *before* committing the database transaction. They can modify incoming payloads, run custom validations, or abort the request entirely by throwing an error.

2. **Deferred Hooks (`afterSave`, `afterDelete`)**
   These hooks execute asynchronously after the database transaction has successfully committed. They use deferred promises (fire-and-forget), meaning they run in the background and do not block the client's HTTP response. Ideal for sending webhooks, triggering push notifications, or queuing external tasks.

### OpenAPI / Swagger

- **OpenAPI spec**: `GET /api/docs` — Returns the full OpenAPI 3.0 JSON specification
- **Swagger UI**: `GET /api/swagger` — Interactive API explorer (dev mode only)

The OpenAPI spec is auto-generated from your collection definitions: it describes the list, read, create, update, delete and bulk endpoints of every collection the backend serves, with their query parameters and response schemas. It is not a complete map of the HTTP surface — the auth, storage, functions and cron routes are documented on this site only — and columns marked `excludeFromApi` are left out of it.

### API Keys

API keys provide machine-to-machine authentication for agents, MCP servers, CI pipelines, and external integrations. They support per-collection permission scoping and optional full admin access.

#### Creating an API Key

```bash
# Via CLI
rebase api-keys create --name "My Integration" \
  --permissions '[{"collection":"orders","operations":["read","write"]}]'

# Via REST (requires admin auth)
curl -X POST http://localhost:3000/api/admin/api-keys \
  -H "Authorization: Bearer <service-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "permissions": [{ "collection": "orders", "operations": ["read", "write"] }]
  }'
```

The response includes the full plaintext key (`rk_live_...`) **exactly once** — store it immediately.

#### Using an API Key

```bash
curl http://localhost:3000/api/data/orders \
  -H "Authorization: Bearer rk_live_abc123..."
```

#### Permissions and RLS: two independent gates

An API key's request passes through **two** authorization checks, and both must allow it:

1. **The key's permission list** — collection × operation, checked at the route layer.
2. **Row-Level Security** — API keys do *not* bypass RLS. A key runs as
   `uid: "api-key:<id>"` with the `service` role (plus `admin` when
   `admin: true`). Admin keys pass via the built-in admin policies; a
   non-admin key only sees rows that a security rule explicitly grants to
   the `service` role or to the public. Owner-style rules
   (`owner_id = rebase.uid()`) never match an API key.

So a non-admin key with `"*"` permissions can still get empty results — that's
RLS working, not a bug. Either grant the `service` role in the relevant
collections' security rules, or use an admin key.

#### Custom Functions

Function invocations are scoped like collections, under the `functions`
namespace: `{"collection": "functions", "operations": ["write"]}` grants every
function, `"functions/<name>"` grants one, and the global `"*"` wildcard grants
all. A key without such an entry cannot invoke functions at all.

#### Storage

Storage works the same way, under the `storage` namespace:
`{"collection": "storage", "operations": ["read", "write"]}` lets the key
download/list (`read`), upload and create folders (`write`), and delete files
(`delete`). The global `"*"` wildcard also grants storage. A key without such
an entry cannot touch storage. TUS resumable-upload routes count as `write`
for every step (including the offset check and cancel), so a write-scoped key
can complete an upload on its own.

#### Agents and MCP Servers

An agent wants the *narrowest* key that does its job, not an admin one. Start
scoped, and give it an expiry:

```bash
rebase api-keys create -n "My Agent" \
  --permissions '[{"collection":"articles","operations":["read"]}]' \
  --expires 30d
```

Operations are `read`, `write` and `delete`, derived from the HTTP method:
`GET`/`HEAD`/`OPTIONS` → `read`, `POST`/`PUT`/`PATCH` → `write`, `DELETE` →
`delete`.

##### A scoped key reads zero rows until a rule grants `service`

This is the step that makes a correctly scoped key look broken. A non-admin key
runs as `uid: "api-key:<id>"` with the roles `["service"]`, and the RLS policy
injected into every collection by default compiles to:

```sql
rebase.uid() IS NULL OR (string_to_array(rebase.roles(), ',') && ARRAY['admin'])
```

— the server context, or an admin. A non-admin key matches neither arm, so on a
collection with no `securityRules` the request succeeds with an empty result set
and no error explaining why. Grant the role explicitly:

```ts
securityRules: [
    { operation: "select", roles: ["service"], using: "true" }
]
```

Because `rebase.uid()` carries the key's id, a rule can also scope rows to one
specific key:

```ts
securityRules: [
    {
        operation: "select",
        condition: policy.compare(policy.authUid(), "eq", policy.literal("api-key:<id>"))
    }
]
```

##### Don't use `"*"` for a read-only key

The `"*"` wildcard is not "every collection" — it also matches the `functions`
namespace and `storage`. A `GET` counts as `read`, and a custom function's
handler is arbitrary code that can write, so a wildcard "read-only" key can
mutate through a function. Naming collections explicitly gives the key no
function access at all.

##### `--admin --full-access`: CI, migrations, first-party tooling

`"admin": true` grants the key the admin role — `/api/admin/*` routes for schema
management, user management, and more, plus cron, backups, and logs. Combined
with `--full-access` (`{"collection": "*", "operations": ["read", "write",
"delete"]}`) the key holds every collection plus all storage and every custom
function. That is the right shape for CI, migrations, and trusted first-party
tooling — not for agents.

```bash
# CLI
rebase api-keys create -n "CI" --admin --full-access

# REST
curl -X POST http://localhost:3000/api/admin/api-keys \
  -H "Authorization: Bearer <service-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI",
    "admin": true,
    "permissions": [{ "collection": "*", "operations": ["read", "write", "delete"] }]
  }'
```

##### No realtime over API keys

The realtime WebSocket does not parse `rk_` tokens — it accepts user JWTs and
the service key only. An agent authenticated with an API key polls the REST
endpoints instead of subscribing.

#### Key Options

| Field | Type | Description |
|---|---|---|
| `name` | `string` | Human-readable label |
| `permissions` | `ApiKeyPermission[]` | Per-collection access (`"*"` = everything; `"functions/<name>"` = one function; `"storage"` = file storage) |
| `admin` | `boolean` | Grant admin role — admin routes + RLS admin policies |
| `rate_limit` | `number \| null` | Requests per 15-min window (`null` = the server default, 1000) |
| `expires_at` | `string \| null` | ISO-8601 expiration timestamp |

The CLI requires an explicit scope: pass `--permissions '<json>'` or opt into
`--full-access` — there is no silent full-access default.

Keys can be listed, updated, and revoked via `/api/admin/api-keys` or the
`rebase api-keys` CLI commands — but not by an API key. Any request to
`/api/admin/api-keys` authenticated with an `rk_` key is refused with `403
API_KEY_SELF_MANAGEMENT_FORBIDDEN`, whatever its `admin` flag. Key management
requires an admin user's session or the service key.

### Metadata Endpoint

Get a list of all available collections and their structure:

```bash
GET /api/collections
```

### Next Steps

- **[Client SDK](/docs/sdk)** — Type-safe client for the REST API
- **[Collections](/docs/collections)** — Define your data schema
- **[Security Rules (RLS)](/docs/collections/security-rules)** — Control access per row

## Authentication

### Overview

Rebase includes a complete backend authentication system:

- **JWT tokens** — Access and refresh token flow with configurable expiration
- **OAuth providers** — Google, LinkedIn, GitHub, Microsoft, Apple, and more
- **SMTP email** — Password reset and email verification flows
- **Auth hooks** — Lifecycle hooks for user creation and more
- **Custom auth adapters** — Plug in Firebase Auth, Auth0, Clerk, or any external provider
- **Service key** — Static key for server-to-server authentication
- **Auto-bootstrapping** — First user automatically gets the admin role

### Configuration

The `auth` block in `initializeRebaseBackend` controls all backend authentication:

```typescript no-verify
const backend = await initializeRebaseBackend({
    // ...
    auth: {
        collection: usersCollection,         // Your users collection definition
        jwtSecret: env.JWT_SECRET,           // Required — signing secret
        accessExpiresIn: "1h",               // Access token lifetime (default: 1h)
        refreshExpiresIn: "30d",             // Refresh token lifetime (default: 30d)
        serviceKey: env.REBASE_SERVICE_KEY,  // Optional — for server-to-server calls
        allowRegistration: true,             // Allow new signups (default: false)

        // OAuth providers
        google: env.GOOGLE_CLIENT_ID
            ? { clientId: env.GOOGLE_CLIENT_ID }
            : undefined,

        // SMTP email (for password reset, email verification)
        email: env.SMTP_HOST
            ? {
                from: env.SMTP_FROM || `${env.APP_NAME} <noreply@example.com>`,
                smtp: {
                    host: env.SMTP_HOST,
                    port: env.SMTP_PORT,              // 587 for TLS, 465 for SSL
                    secure: env.SMTP_SECURE,           // true for port 465
                    auth: env.SMTP_USER
                        ? { user: env.SMTP_USER, pass: env.SMTP_PASS! }
                        : undefined,
                    name: env.SMTP_NAME,               // Optional EHLO/HELO hostname
                },
                appName: env.APP_NAME,
                resetPasswordUrl: env.FRONTEND_URL,    // URL for password reset page
            }
            : undefined,

        // Lifecycle hooks
        hooks: {
            afterUserCreate: async (user) => {
                console.log(`New user registered: ${user.email}`);
            }
        }
    }
});
```

:::caution[Collection callbacks do not fire for auth users]
User creation and updates through the auth system — registration, admin user
management, and OAuth — write **directly** to the user store and bypass the
collection save pipeline. A `beforeSave`/`afterSave`/`beforeDelete`/`afterDelete`
callback on the auth (users) collection will **not** run for these paths. For
side effects like provisioning a personal team on signup, use the auth lifecycle
hooks (`afterUserCreate`, `beforeUserCreate`, `afterUserDelete`, …), which
receive the fully-populated user record.
:::

#### OAuth Providers

Each OAuth provider is configured with at minimum a `clientId`. Some providers require a `clientSecret`:

```typescript
auth: {
    google:    { clientId: "..." },
    linkedin:  { clientId: "...", clientSecret: "..." },
    github:    { clientId: "...", clientSecret: "..." },
    microsoft: { clientId: "...", clientSecret: "...", tenantId: "..." },
    apple:     { clientId: "...", teamId: "...", keyId: "...", privateKey: "..." },
    facebook:  { clientId: "...", clientSecret: "..." },
    twitter:   { clientId: "...", clientSecret: "..." },
    discord:   { clientId: "...", clientSecret: "..." },
    gitlab:    { clientId: "...", clientSecret: "..." },
    bitbucket: { clientId: "...", clientSecret: "..." },
    slack:     { clientId: "...", clientSecret: "..." },
    spotify:   { clientId: "...", clientSecret: "..." },
}
```

#### Account Linking Across Sign-In Methods

What happens when someone registers with email/password as `ada@example.com`,
then later clicks "Sign in with Google" on a Google account with that same
address? Rebase **links the two into one account** — but only when the provider
asserts the email as verified. It never silently creates a second account for
the same address.

On `POST /api/auth/<provider>` the resolution order is:

1. **Known provider identity** — if this exact provider identity has signed in
   before, that user is returned. The email is not consulted.
2. **Existing account with the same email, provider verified it** — the
   identity is attached to the existing account and the user is signed in to
   it. One account, two ways in.
3. **Existing account with the same email, provider did NOT verify it** —
   rejected with `403 EMAIL_NOT_VERIFIED`. Nothing is created or modified.
4. **No account with that email** — a new account is created.

Step 3 is the security-critical case. If an unverified provider email were
enough to link, anyone who could get a provider to emit an address they don't
own could take over the matching Rebase account. Google always asserts
`email_verified` for real Google accounts, so step 2 is the normal path for
Google sign-in; step 3 mostly catches providers that let users supply an
arbitrary unconfirmed address.

This behavior is not configurable — there is deliberately no option to link on
unverified emails.

To recover from a step-3 rejection, the user signs in with their existing
method and calls the explicit link endpoint:

```http
POST /api/auth/link/google
Authorization: Bearer <access token>

{ "idToken": "..." }
```

Linking while authenticated intentionally does **not** require a verified
email, and does not require the emails to match at all — a user's Google
address is often not their app address. The asymmetry is deliberate: on
sign-in the provider's email is the only evidence tying the incoming identity
to an account, whereas here the caller has already proven ownership by holding
a valid session. It returns `409 IDENTITY_ALREADY_LINKED` if that provider
identity belongs to another user, and is idempotent if it is already linked to
the caller.

##### The reverse direction

A user who signed up with Google and has no password:

- **Registering with the same email** is refused with `409 EMAIL_EXISTS`.
- **`POST /api/auth/change-password`** returns `400 INVALID_ACCOUNT` — there is
  no existing password to verify against.
- **`forgot-password` → `reset-password` is the supported way to add one.**
  It re-proves ownership of the address by email, after which the account has
  both sign-in methods.

### Auth Endpoints

All auth endpoints are mounted at `/api/auth/`:

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/auth/register` | Create a new account |
| `POST` | `/api/auth/login` | Login with email/password |
| `POST` | `/api/auth/refresh` | Refresh the access token |
| `POST` | `/api/auth/<provider>` | OAuth sign-in (e.g., `/api/auth/google`, `/api/auth/linkedin`) |
| `POST` | `/api/auth/link/<provider>` | Link an OAuth provider to the authenticated account |
| `POST` | `/api/auth/logout` | Revoke refresh token |
| `POST` | `/api/auth/forgot-password` | Send password reset email |
| `POST` | `/api/auth/reset-password` | Reset password with token |
| `POST` | `/api/auth/find-user` | Resolve an email to a minimal public profile (opt-in) |
| `POST` | `/api/auth/mfa/enroll` | Start TOTP enrolment (returns the secret and recovery codes) |
| `POST` | `/api/auth/mfa/verify` | Confirm an enrolment with a code from the authenticator |
| `GET` | `/api/auth/mfa/factors` | List the caller's enrolled factors |
| `POST` | `/api/auth/mfa/challenge` | Open a challenge against a verified factor |
| `POST` | `/api/auth/mfa/challenge/verify` | Answer a challenge — this is what issues the session |
| `DELETE` | `/api/auth/mfa/unenroll` | Remove a factor (requires an `aal2` session) |

All data API endpoints require a valid `Authorization: Bearer <token>` header when `requireAuth: true` (the default).

#### Multi-factor authentication (TOTP)

**A second factor gates sign-in, not just individual operations.** Once an
account has one *verified* TOTP factor, no route issues it a session until a
code is presented — password login, every OAuth provider, magic link and
anonymous-link all refuse with `401 MFA_REQUIRED`:

```json
{
  "error": {
    "code": "MFA_REQUIRED",
    "message": "Multi-factor authentication is required to complete sign-in.",
    "details": {
      "mfaToken": "<short-lived pre-auth token>",
      "factors": [{ "id": "…", "factorType": "totp", "friendlyName": "Phone" }]
    }
  }
}
```

`mfaToken` is **not a session**: it is purpose-scoped, expires in five minutes,
and is rejected by every authenticated route. Send it as the bearer token to
`POST /api/auth/mfa/challenge` (with a `factorId`) and then to
`POST /api/auth/mfa/challenge/verify` (with the `challengeId` and the six-digit
code, or a recovery code). That last call is what mints the access and refresh
tokens, at `aal2`; the level is stored on the session and carried across
`POST /api/auth/refresh`.

Enrolment is gated too. The first factor on an account may be enrolled from an
ordinary session, but once one is verified, `enroll`, `verify` and `unenroll`
all require an `aal2` session — otherwise a stolen password could enrol a
factor of its own, step up on it, and delete the real one.

Verification is bounded on both axes: a challenge dies after five failed
guesses, each account is limited to ten verification attempts per 15 minutes
(counted per user, so rotating IPs does not help), and an accepted code is
recorded against the factor so it cannot be replayed for the rest of its
±1-step window.

Set `MFA_ENCRYPTION_KEY` (32+ random characters) to encrypt stored TOTP
secrets. Without it the server falls back to `JWT_SECRET` and warns. Set it
**before** anyone enrols: stored secrets carry no key id, so changing the key
afterwards leaves existing factors undecryptable and their owners unable to
complete a challenge.

#### Inviting teammates by email

Invite flows need to turn an email address into a user id, but the `users`
collection is RLS-protected from the client. Instead of hand-rolling an admin
server function, opt into the built-in lookup:

```typescript no-verify
await initializeRebaseBackend({
    auth: {
        // ...
        allowUserLookup: true,   // enables POST /api/auth/find-user
    },
});
```

Then, from the client:

```typescript
const profile = await rebase.auth.findUserByEmail("teammate@example.com");
// → { uid, displayName, photoURL } | null   (never email/roles/metadata)
if (profile) {
    await rebase.data.team_members.create({ team_id, user_id: profile.uid });
}
```

The endpoint is **authenticated-only** and returns just `uid`, `displayName`,
and `photoURL` — never the email, roles, or metadata of the looked-up user. It
is **off by default** because it lets any signed-in user probe which emails have
accounts; enable it only when your invite UX needs it.

### Auto-Created Tables

On first startup, Rebase automatically provisions the `auth` schema and the following tables in the database (bound to the schema defined in your collection, e.g., `rebase`):

- **`rebase.users`** — User accounts with email, password hash, metadata, and a `roles` text[] column (roles are stored as inline text arrays to optimize queries and avoid joins).
- **`rebase.refresh_tokens`** — Long-lived sessions carrying hashed refresh tokens, user agents, and IP addresses. Includes a unique index on `token_hash` and a unique constraint on `(user_id, user_agent, ip_address)` to track active device sessions.
- **`rebase.password_reset_tokens`** — Expirable single-use tokens for password recovery flows.
- **`rebase.mfa_factors`** — Enrolled multi-factor authentication methods (e.g. TOTP secrets encrypted with AES-256).
- **`rebase.mfa_challenges`** — Verification logs tracking active MFA verification attempts.
- **`rebase.recovery_codes`** — Hashed multi-factor backup/recovery codes.
- **`rebase.app_config`** — Key-value store for system configurations.

### Row-Level Security (RLS) Database Context

Rebase bridges request authentication directly down to PostgreSQL Row-Level Security (RLS). Every database query executed through a user-scoped driver runs inside a database transaction (`db.transaction()`) that configures transaction-local configuration parameters:

*   `app.user_id` — The authenticated user's unique ID (`uid`). Defaults to `'anon'` for unauthenticated requests.
*   `app.user_roles` — A comma-separated string listing the user's assigned roles.
*   `app.jwt` — A JSON string containing the full JWT claims payload (`{"sub": "<uid>", "roles": [...]}`).

These parameters are configured locally for the duration of the transaction using Postgres's `set_config` function:
```sql
SELECT 
    set_config('app.user_id', $1, true),
    set_config('app.user_roles', $2, true),
    set_config('app.jwt', $3, true);
```

#### PostgreSQL Policy Helper Functions

To make writing Row-Level Security policies simple, Rebase creates helper functions under the `auth` schema during database bootstrapping:

*   **`rebase.uid()`** — Returns the authenticated user's ID as `text`, or `NULL` if not set:
    ```sql
    CREATE OR REPLACE FUNCTION rebase.uid() RETURNS text AS $$
        SELECT NULLIF(current_setting('app.user_id', true), '');
    $$ LANGUAGE sql STABLE;
    ```
*   **`rebase.roles()`** — Returns the comma-separated roles string:
    ```sql
    CREATE OR REPLACE FUNCTION rebase.roles() RETURNS text AS $$
        SELECT COALESCE(NULLIF(current_setting('app.user_roles', true), ''), '');
    $$ LANGUAGE sql STABLE;
    ```
*   **`rebase.jwt()`** — Returns the full JWT payload as a `jsonb` object:
    ```sql
    CREATE OR REPLACE FUNCTION rebase.jwt() RETURNS jsonb AS $$
        SELECT COALESCE(NULLIF(current_setting('app.jwt', true), ''), '{}')::jsonb;
    $$ LANGUAGE sql STABLE;
    ```

You can use these helpers directly in your custom security rules or database migrations:
```sql
CREATE POLICY owner_access ON posts
    FOR ALL
    TO public
    USING (author_id = rebase.uid() OR string_to_array(rebase.roles(), ',') && ARRAY['admin']);
```

### First User Bootstrap

When no users exist in the database, the first person to register automatically becomes an admin. After that, registration is controlled by the `allowRegistration` setting.

This ensures you can always bootstrap a fresh deployment without needing to seed the database manually. To prevent concurrent runs and schema generation race conditions on hot reloading (HMR) or startup, bootstrapping operations are synchronized using a Postgres advisory lock:
```sql
SELECT pg_advisory_xact_lock(hashtext('rebase_auth_functions_init'));
```

### Collection-Level Auth Configuration

Instead of relying solely on the default database auth rules, you can mark any Postgres collection (such as `users.ts` or a custom `members.ts` collection) as the authentication collection. This is configured via the `auth` property on the collection itself:

```typescript

const membersCollection = defineCollection({
  name: "Members",
  slug: "members",
  table: "members",
  auth: {
    enabled: true,
    
    // Customize what happens when an admin creates a user via the REST API
    onCreateUser: async (values, ctx) => {
      const hash = await ctx.hashPassword("welcome123");
      return {
        values: { ...values, passwordHash: hash, emailVerified: true },
        temporaryPassword: "welcome123"
      };
    },

    // Customize what happens when an admin resets a user's password in the admin panel
    onResetPassword: async (userId, ctx) => {
      const tempPassword = "reset_" + Math.random().toString(36).substring(2, 8);
      return {
        temporaryPassword: tempPassword,
        invitationSent: false
      };
    },

    // Inject/override auth-specific actions (e.g. show/hide the reset password button)
    actions: {
      resetPassword: true // Or false to disable, or a custom EntityAction
    }
  },
  properties: { ... }
});
```

When custom hooks (`onCreateUser`, `onResetPassword`) are called, they receive an `AuthCollectionContext` facade containing:
- `hashPassword(password: string): Promise<string>` — Hash password using the configured hashing algorithm (e.g. scrypt).
- `sendEmail?: (options) => Promise<void>` — Send an email (only available when email service is configured).
- `emailConfigured: boolean` — Whether email service is configured.
- `appName: string` — The app name from email config.
- `resetPasswordUrl: string` — The password reset link base URL.

### Service Key Authentication

For server-to-server communication (e.g., cron jobs, external services), configure a static service key:

```typescript
auth: {
    serviceKey: process.env.REBASE_SERVICE_KEY,
    // ...
}
```

Clients authenticate with the `Authorization: Bearer <service-key>` header. 

#### Internal Per-Boot Key

If `REBASE_SERVICE_KEY` is not provided in your configuration, Rebase automatically generates a random **internal per-boot key**. 

This key is never logged and never leaves the process. It is used by the `rebase` singleton to authenticate against the server's own control-plane APIs (auth, storage, etc.). This ensures that administrative tasks (like sending a welcome email or generating a storage URL) always function out-of-the-box in development and production without requiring manual key management.

#### Timing-Attack Protection & Key Requirements

To prevent timing attacks, Rebase validates both the user-configured service key and the internal key using constant-time string comparison (`safeCompare`). The user-configured service key **must be at least 32 characters long**; if a key shorter than 32 characters is configured, Rebase will throw a configuration error on startup and fail-closed.

### Custom Auth Adapters

Rebase allows complete replacement of the built-in authentication system via a pluggable authentication architecture. This decouples authentication verification from the database and REST/WebSocket layers, enabling seamless integration with external providers such as **Clerk**, **Auth0**, **Firebase Auth**, or custom JWT identity services.

#### The AuthAdapter Contract

You can implement the `AuthAdapter` interface directly for complete control. The interface definition is as follows:

```typescript

export interface AuthAdapter {
  /** Unique identifier for this auth adapter (e.g., "clerk", "custom") */
  readonly id: string;

  /**
   * Verifies an incoming HTTP request and returns the authenticated user payload.
   * Called by Hono authentication middleware on every REST endpoint.
   */
  verifyRequest(request: Request): Promise<AuthenticatedUser | null>;

  /**
   * Verifies a raw token string (e.g. for WebSocket connection handshake phase 1).
   * If omitted, a synthetic request is automatically constructed.
   */
  verifyToken?(token: string): Promise<AuthenticatedUser | null>;

  /** Optional user management operations (CRUD) for the Admin Dashboard panel */
  userManagement?: UserManagementAdapter;

  /** Optional: Mount adapter-specific custom public routes (e.g. callback paths) */
  createAuthRoutes?(): Hono<any, any, any> | undefined;

  /** Optional: Mount adapter-specific admin-only routes */
  createAdminRoutes?(): Hono<any, any, any> | undefined;

  /** Advertise supported capabilities (to customize Admin Dashboard UI visibility) */
  getCapabilities(): AuthAdapterCapabilities | Promise<AuthAdapterCapabilities>;

  /** Lifecycle hooks called during backend start and graceful shutdown */
  initialize?(): Promise<void>;
  destroy?(): Promise<void>;

  /** Custom user lifecycle hooks (e.g., hash passwords before collection writes) */
  prepareUserCreation?(
    values: Record<string, unknown>,
    collectionAuth?: unknown
  ): Promise<UserCreationPrepareResult>;

  finalizeUserCreation?(
    entity: { id: string; values: Record<string, unknown> },
    clearPassword?: string
  ): Promise<UserCreationFinalizeResult>;

  /** Static service key to bypass checks for server-to-server calls */
  serviceKey?: string;
}
```

#### The Authenticated User Payload

Regardless of the external authentication provider chosen, your adapter must resolve successful token verifications to a uniform `AuthenticatedUser` object. The Rebase RLS Scope Injector maps these values directly to PostgreSQL session variables inside transactions:

```typescript
export interface AuthenticatedUser {
  uid: string;                    // Maps to pg local 'app.user_id' -> rebase.uid()
  email: string;                  // User email address
  displayName?: string | null;    // Optional display name
  photoUrl?: string | null;        // Optional avatar URL
  roles: string[];                // Maps to pg local 'app.user_roles' -> rebase.roles()
  isAdmin: boolean;               // Grants global superuser privileges if true
  rawToken?: string;              // The original token string (for downstream forwarding)
  claims?: Record<string, any>;   // Custom claims/metadata (available in rebase.jwt())
}
```

---

#### Quick Integration via `createCustomAuthAdapter`

For standard scenarios (such as validating JWTs from a third-party service), you can use the `createCustomAuthAdapter` utility. This utility handles capabilities defaults and implements WebSocket token validation out-of-the-box by wrapping your `verifyRequest` implementation.

##### Example: Integrating with Clerk

To connect a Rebase backend with **Clerk**, you can verify Clerk JWT tokens using Clerk's JSON Web Key Set (JWKS):

```typescript no-verify

// Clerk JWKS URL
const CLERK_JWKS_URL = "https://clerk.your-domain.com/.well-known/jwks.json";
const JWKS = createRemoteJWKSet(new URL(CLERK_JWKS_URL));

const clerkAuthAdapter = createCustomAuthAdapter({
    serviceKey: process.env.REBASE_SERVICE_KEY,
    verifyRequest: async (request) => {
        const authHeader = request.headers.get("Authorization");
        const token = authHeader?.replace("Bearer ", "");
        if (!token) return null;

        try {
            // Verify Clerk JWT token against JWKS
            const { payload } = await jwtVerify(token, JWKS);
            
            const metadata = payload.metadata as Record<string, unknown> | undefined;
            const roles = Array.isArray(metadata?.roles) ? metadata.roles as string[] : [];
            
            return {
                uid: payload.sub!,
                email: (payload as Record<string, unknown>).email as string || "",
                displayName: (payload as Record<string, unknown>).name as string || null,
                roles: roles,
                isAdmin: roles.includes("admin"),
                claims: payload as Record<string, unknown>
            };
        } catch (error) {
            console.error("Clerk token verification failed:", error);
            return null; // Fail-closed
        }
    },
    capabilities: {
        hasBuiltInAuthRoutes: false, // Login is managed by Clerk UI
        emailPasswordLogin: false,
        registration: false,
        passwordReset: false,
        profileUpdate: false,
        sessionManagement: false
    }
});

const backend = await initializeRebaseBackend({
    auth: clerkAuthAdapter,
    // ...
});
```

##### Example: Integrating with Firebase Auth

To verify Firebase Auth tokens using Firebase's public certificates:

```typescript no-verify

const FIREBASE_JWKS_URL = "https://www.googleapis.com/robot/v1/metadata/jwk/securetoken@system.gserviceaccount.com";
const JWKS = createRemoteJWKSet(new URL(FIREBASE_JWKS_URL));
const FIREBASE_PROJECT_ID = "my-firebase-project-id";

const firebaseAuthAdapter = createCustomAuthAdapter({
    serviceKey: process.env.REBASE_SERVICE_KEY,
    verifyRequest: async (request) => {
        const authHeader = request.headers.get("Authorization");
        const token = authHeader?.replace("Bearer ", "");
        if (!token) return null;

        try {
            const { payload } = await jwtVerify(token, JWKS, {
                issuer: `https://securetoken.google.com/${FIREBASE_PROJECT_ID}`,
                audience: FIREBASE_PROJECT_ID
            });

            const roles = Array.isArray((payload as Record<string, unknown>).roles) ? (payload as Record<string, unknown>).roles as string[] : [];

            return {
                uid: payload.sub!,
                email: (payload as Record<string, unknown>).email as string || "",
                displayName: (payload as Record<string, unknown>).name as string || null,
                photoUrl: (payload as Record<string, unknown>).picture as string || null,
                roles: roles,
                isAdmin: roles.includes("admin"),
                claims: payload as Record<string, unknown>
            };
        } catch (error) {
            console.error("Firebase token verification failed:", error);
            return null;
        }
    }
});

const backend = await initializeRebaseBackend({
    auth: firebaseAuthAdapter,
    // ...
});
```

---

#### Mounting Auth Routes and Admin UI Actions

If your custom auth provider requires mounting redirect endpoints (like OAuth callback routes or SAML login loops), implement the `createAuthRoutes` method on your adapter:

```typescript
const myOauthAdapter: AuthAdapter = {
    id: "custom-oauth",
    verifyRequest: async (req) => ({
        // validate the token, then return the caller
        uid: "…",
        email: "user@example.com",
        roles: [],
        isAdmin: false
    }),
    getCapabilities: () => ({
        hasBuiltInAuthRoutes: true,
        emailPasswordLogin: false,
        registration: false,
        passwordReset: false,
        adminPasswordReset: false,
        sessionManagement: false,
        profileUpdate: false,
        emailVerification: false,
        magicLink: false,
        enabledProviders: []
    }),
    createAuthRoutes: () => {
        const app = new Hono<HonoEnv>();
        
        // Mounted automatically under /api/auth/callback
        app.get("/callback", async (c) => {
            const code = c.req.query("code");
            // Exchange code for provider tokens and set cookies/redirect
            return c.redirect("/dashboard");
        });
        
        return app;
    }
};
```

If you wish to allow user CRUD operations directly inside the Rebase Admin Dashboard, implement the `userManagement` helper within the adapter options, which provides hooks for `listUsers`, `createUser`, `updateUser`, and `deleteUser`.

### Next Steps

- **[Frontend Authentication](/docs/frontend/authentication)** — Login UI, auth controller, user management
- **[Security Rules (RLS)](/docs/collections/security-rules)** — Row-level access control
- **[Client SDK Authentication](/docs/sdk/authentication)** — Auth methods in the client SDK

## Storage Configuration

### Overview

Rebase supports three storage backends:

- **Local filesystem** — Files stored on disk (great for development)
- **S3-compatible** — AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces
- **Google Cloud Storage / Firebase Storage** — Native GCS support via `@google-cloud/storage`

### Configuration

Storage is configured in the `storage` block of `initializeRebaseBackend`:

#### Local Storage

```typescript no-verify
const backend = await initializeRebaseBackend({
    // ...
    storage: {
        type: "local",
        basePath: "./uploads"   // Directory for file storage
    }
});
```

#### S3 Storage

```typescript no-verify
const backend = await initializeRebaseBackend({
    // ...
    storage: {
        type: "s3",
        bucket: env.S3_BUCKET!,
        region: env.S3_REGION || "auto",
        accessKeyId: env.S3_ACCESS_KEY_ID || "",
        secretAccessKey: env.S3_SECRET_ACCESS_KEY || "",
        endpoint: env.S3_ENDPOINT,          // For MinIO, R2, etc.
        forcePathStyle: env.S3_FORCE_PATH_STYLE  // Required for MinIO
    }
});
```

#### GCS / Firebase Storage

```typescript no-verify
const backend = await initializeRebaseBackend({
    // ...
    storage: {
        type: "gcs",
        bucket: env.GCS_BUCKET!,
        projectId: env.GCS_PROJECT_ID,
    }
});
```

On GCP (Cloud Run, GCE, GKE), the default service account credentials are used automatically. Outside GCP, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file.

#### Multiple Storage Backends

You can configure multiple named backends and route different fields to different storage:

```typescript
storage: {
    "(default)": { type: "local", basePath: "./uploads" },
    "media": { type: "s3", bucket: "media-bucket", region: "us-east-1", ... }
}
```

Then in your collection properties, reference a specific backend:

```typescript
image: {
    type: "string",
    name: "Image",
    storage: {
        storagePath: "products",
        storageSource: "media"  // Routes to the "media" S3 backend
    }
}
```

### Storage Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/storage/upload` | Direct file upload |
| `POST` | `/api/storage/upload?storageId=<key>` | Upload to a specific named backend |
| `GET` | `/api/storage/files/:path` | Retrieve a file |
| `GET` | `/api/storage/files/:path?storageId=<key>` | Retrieve a file from a specific backend |
| `DELETE` | `/api/storage/files/:path` | Delete a file |
| `OPTIONS` | `/api/storage/tus` | Query supported TUS protocol capabilities |
| `POST` | `/api/storage/tus` | Initiate a resumable TUS upload session |
| `HEAD` | `/api/storage/tus/:id` | Check upload progress (byte offset) |
| `PATCH` | `/api/storage/tus/:id` | Append data chunk to temporary file |
| `DELETE` | `/api/storage/tus/:id` | Terminate/abort TUS upload session |

### On-the-Fly Image Transformations

Rebase includes a built-in image processing pipeline powered by **Sharp**. When serving image assets from storage, you can apply dynamic operations using query parameters:

```bash
# Serve image scaled to 300px width in webp format
GET /api/storage/files/products/laptop.jpg?width=300&format=webp
```

#### Supported Parameters

- `width`, `height`: Resize bounds, `1`–`4096` (the image is never enlarged).
- `quality`: `1`–`100`.
- `format`: Converts the image format. Supported formats: `webp`, `jpeg`, `png`, `avif`.
- `fit`: `cover`, `contain`, `fill`, `inside` or `outside`.

A parameter outside these bounds is a **400**, not a silently clamped value —
`?width=99999` used to return a 4096px image and `?format=tiff` a webp one, and
neither said so.

#### Performance & LRU Caching

Transforming is CPU- and memory-heavy, and on a public object the endpoint is
reachable anonymously, so the work is bounded rather than merely cached:
- **Capacity**: an LRU capped at **500 entries** globally, keyed by storage
  source, bucket and canonical key.
- **TTL (Time to Live)**: Cached variants expire after **1 hour**.
- Concurrent requests for the same uncached variant produce **one** transform,
  not one each.
- A small number of transforms run at once; beyond a bounded backlog the server
  answers **503 `TRANSFORM_OVERLOADED`** rather than accepting work it will not
  get to.

#### What gets served

The stored content type is whatever the uploader declared — nothing sniffs the
bytes — so `/api/storage/file/*` will only render a **narrow allowlist** inline:
images (except SVG), video, audio, `application/pdf` and `text/plain`. Anything
else, `text/html` and `image/svg+xml` included, is served as
`application/octet-stream` with `Content-Disposition: attachment`, and every
response carries `X-Content-Type-Options: nosniff`. Storage is not a web host:
an uploaded page rendered on the API origin can read that origin's cookies and
call its endpoints.

### TUS Resumable Upload Protocol

For uploading large files (up to **5GB**) or handling unstable network conditions, Rebase implements the **TUS v1.0.0** open protocol including the `Creation` and `Termination` extensions.

```
Client                                                   Rebase Server
  │                                                           │
  │─── POST /api/storage/tus (Upload-Length: 50000000) ──────>│ (Generates session ID)
  │<── 201 Created (Location: /api/storage/tus/uuid-abc) ────│
  │                                                           │
  │─── PATCH /api/storage/tus/uuid-abc (Upload-Offset: 0) ───>│ (Appends chunk via open/write)
  │<── 204 No Content (Upload-Offset: 1500000) ───────────────│
  │                                                           │
  │─── PATCH /api/storage/tus/uuid-abc (Upload-Offset: 1.5M) ─>│ (Upload finishes)
  │<── 204 No Content (Upload-Offset: 50000000) ──────────────│ (Copies to storage, unlinks temp)
```

#### Upload Lifecycle Mechanics

1. **Session Initialisation (`POST`)**: The client sends the total file size in the `Upload-Length` header and base64 metadata via `Upload-Metadata`. The server creates an empty placeholder file under a hidden temporary directory `.tus-uploads/` and returns the upload URL.
2. **Progress Inquiries (`HEAD`)**: If an upload is interrupted, the client queries the upload URL using a `HEAD` request. The server returns the current byte position in the `Upload-Offset` header.
3. **Data Appending (`PATCH`)**: The client resumes sending binary data starting at the returned offset with `Content-Type: application/offset+octet-stream`. The server writes incoming chunks directly to the temporary file using Node's low-level `open` and `write` file system APIs at the specified byte offset.
4. **Finalisation**: When the accumulated `Upload-Offset` matches the declared `Upload-Length`, Rebase reads the completed temporary file, wraps it as a standard JavaScript `File` object, and saves it to the configured storage backend (local disk or S3). The temporary file is then deleted.
5. **Periodic Sweep**: A background cleaner runs every **60 seconds** to delete orphaned, incomplete temporary uploads that have exceeded the **24-hour** retention threshold.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `STORAGE_TYPE` | `"local"`, `"s3"`, or `"gcs"` |
| `STORAGE_PATH` | Local storage directory (default: `./uploads`) |
| `S3_BUCKET` | S3 bucket name |
| `S3_REGION` | AWS region (default: `"auto"`) |
| `S3_ACCESS_KEY_ID` | AWS access key |
| `S3_SECRET_ACCESS_KEY` | AWS secret key |
| `S3_ENDPOINT` | Custom S3 endpoint (for MinIO, R2) |
| `S3_FORCE_PATH_STYLE` | Use path-style URLs (required for MinIO) |
| `GCS_BUCKET` | Google Cloud Storage bucket name |
| `GCS_PROJECT_ID` | GCP project ID for GCS |
| `GCS_KEY_FILENAME` | Path to a GCP service account key file (omit on GKE — Workload Identity/ADC supplies credentials) |
| `GOOGLE_APPLICATION_CREDENTIALS` | Standard ADC variable, read by the Google SDK itself (not needed on GCP with default credentials) |
| `FORCE_LOCAL_STORAGE` | Allow `STORAGE_TYPE=local` in production — see below |

### Several Buckets

A project can have more than one bucket. Declare them in `rebase.json` — the one
place the platform, the runtime and the console all read:

```json
{
  "rebase": "^1",
  "storage": {
    "(default)": { "engine": "s3" },
    "media": { "engine": "s3", "label": "Media" }
  },
  "apps": {}
}
```

Each source is configured from the **same variable names carrying its own
suffix**. The default source takes no suffix, so a single-bucket project keeps
using the plain names above and needs to declare nothing at all:

```bash
S3_BUCKET=app-uploads             # (default)
S3_BUCKET__MEDIA=app-media        # media
S3_ACCESS_KEY_ID__MEDIA=…
S3_SECRET_ACCESS_KEY__MEDIA=…
```

The suffix is derived from the key: uppercased, non-alphanumerics collapsed to
underscores, behind a **double** underscore (`media-cdn` → `__MEDIA_CDN`). A
single underscore would collide with real variable names — `S3_BUCKET_NAME`
would parse as bucket `name`.

Route a property to a source with `storageSource`:

```ts
{
    name: "Cover",
    dataType: "string",
    storage: { storageSource: "media", acceptedFiles: ["image/*"] }
}
```

A source you declare but never configure is **skipped**, not fatal: uploads
routed to it answer `501 STORAGE_NOT_CONFIGURED`. Declaring a bucket usually
happens before anyone attaches storage to it, and a boot error there would
crash-loop the backend until someone did. A source the environment configures
*wrongly* — a type with no bucket, or a bucket with no credentials — is refused
at boot, because that is a mistake rather than an absence.

### Frontend Storage Sources

When using multiple storage backends, pass `storageSources` to the `<Rebase>` provider so the frontend knows how to route uploads directly:

```tsx

<Rebase
    apiUrl="https://api.example.com"
    storageSources={[
        // `engine` names the provider, `transport` says who talks to it:
        // "server" proxies through the Rebase backend, "direct" goes
        // client-to-provider (and needs a `source` implementation).
        { key: "media", engine: "s3", transport: "server", label: "Media CDN" },
        { key: "firebase", engine: "firebase", transport: "server", label: "Firebase Storage" },
    ]}
>
    {() => <MyApp />}
</Rebase>
```

Each source's `key` must match a backend key registered in the server's `storage` map. The `StorageSourcesContext` React context resolves the active source for each upload field.

### Production Tips

:::caution
**In production, `type: "local"` disables file storage instead of using it.** On an ephemeral platform (Cloud Run, Heroku, a Kubernetes pod) the filesystem is wiped on every deploy, restart and eviction — so uploads would succeed, read back fine, and be gone at the next rollout, with no error at any point.

So no storage backend is registered, and `/api/storage/*` answers **`501 STORAGE_NOT_CONFIGURED`**. Uploads fail loudly and recoverably; the rest of the app keeps serving. File storage is opt-in in production: it exists once a bucket does.

Set `STORAGE_TYPE=s3` or `gcs`. If a **durable volume** really is mounted at `STORAGE_PATH`, set `FORCE_LOCAL_STORAGE=true` to say so explicitly.
:::

- Mount a **persistent volume** if using local storage on Docker/Kubernetes, and set `FORCE_LOCAL_STORAGE=true`
- Use **S3** or compatible (R2, MinIO), or **GCS**, for production deployments
- Configure a **CDN** (CloudFront, Cloudflare) in front of your bucket for performance
- **Any app with storage in production must declare an access model** — see below.
  Not just multi-tenant ones: the server *refuses to boot* without one.

### Per-Object Authorization

`requireAuth` and `publicRead` are *global* switches: they decide whether a caller must be signed in, not what that caller may touch. Without an authorization hook, **any authenticated user can read any key they can name** — the only thing separating two tenants' files is key unguessability, which is not an access-control model. Worse, they can `GET /storage/list?prefix=` first, so the keys do not even have to be guessed.

:::caution[Storage will not boot in production without one]
Collections are protected by row-level security; storage is not. There is no
per-object equivalent in the bucket, so this hook *is* the model — and
`initializeRebaseBackend` **throws at startup** under `NODE_ENV=production` when
storage is configured and none of these is set:

- `storageAuthorize` — a hook, per object. Recommended.
- `storagePublicRead: true` — the bucket genuinely is a public read-only CDN.
- `storageInsecureAllowAnyAuthenticated: true` — a single-tenant app where every
  signed-in user is trusted with every file. Named to be read twice.

In development it logs a warning instead, so a project can be wrong about this and
work fine locally right up until it is deployed. A scaffolded project ships a hook in
`config/storage.ts` already — read it before you replace it, and note that it models
a CMS's *shared content library*, which is not the same shape as per-user files.
:::

`storageAuthorize` is the storage analogue of a collection's security rules, and runs after authentication on every storage route:

```typescript no-verify
await initializeRebaseBackend({
    storage: { type: "s3", bucket: "app-files", /* ... */ },
    storageAuthorize: async ({ key, bucket, operation, user }) => {
        if (!user) return false;
        // Keys are laid out as `{teamId}/{docId}/...`
        const [teamId] = key.split("/");
        return isTeamMember(user.uid, teamId);
    }
});
```

| Field | Description |
|-------|-------------|
| `key` | Object key, bucket prefix stripped and traversal sanitized |
| `bucket` | Resolved bucket (`"default"` when unspecified) |
| `operation` | `"read"`, `"write"`, `"delete"` or `"list"` |
| `user` | `{ userId, email?, roles? }`, or `null` where the route allows anonymous access |
| `storageId` | The named backend, when the request targeted one |

Return `false` to deny with a **403**. Throwing also denies — an ownership lookup that fails does not fall open.

Worth knowing:

- **The metadata route is where read access is really decided.** It mints the short-lived path-scoped download token that the file route trusts, so the hook gates it there. Requests already carrying such a token, or hitting a declared public path, skip the hook — the token was minted under it and is valid only for its own path.
- **`list` is gated on the prefix.** Listing is how you discover keys nobody told you about.
- **Resumable (TUS) uploads are gated at create time**, so a denied upload leaves no temp file behind.
- Omitting the hook preserves the previous behaviour, so single-tenant apps are unaffected.

### Next Steps

- **[Frontend Storage & File Uploads](/docs/frontend/storage)** — File upload fields and hooks
- **[Properties](/docs/collections/properties)** — Storage property configuration

## Multiple Databases and Buckets

### Overview

A project is not limited to one database and one bucket. Collections already
route by `dataSource`, and file properties route by `storageSource`; this page is
about how each named source gets its configuration.

Two steps: **declare** the sources in your config package, then **configure**
each one with environment variables derived from its key.

### Declaring sources

Export `dataSources` and `storageSources` from your config package's `index.ts`.
They are shared with the frontend, which uses the same declarations to decide
whether it talks to a source through the Rebase API or directly.

```ts
// config/index.ts

export const dataSources: DataSourceDefinition[] = [
    { key: "(default)", engine: "postgres" },
    { key: "analytics", engine: "postgres", label: "Analytics warehouse" }
];

export const storageSources: StorageSourceDefinition[] = [
    { key: "(default)", engine: "local", transport: "server" },
    { key: "media", engine: "s3", transport: "server", label: "Public media" }
];
```

Then point a collection at one:

```ts

const pageViewsCollection = defineCollection({
    name: "Page Views",
    slug: "page_views",
    table: "page_views",
    dataSource: "analytics",
    properties: { /* … */ }
});
```

...or a file property:

```ts
coverImage: {
    name: "Cover image",
    type: "string",
    storage: { storageSource: "media", acceptedFiles: ["image/*"] }
}
```

### Configuring each source

Environment variable names are derived from the source key, so there is nothing
to keep in sync by hand:

```
<VARIABLE>              the default source     DATABASE_URL, S3_BUCKET
<VARIABLE>__<KEY>       a named source         DATABASE_URL__ANALYTICS, S3_BUCKET__MEDIA
```

The key is upper-cased and non-alphanumeric characters become underscores, so
`media-cdn` reads `S3_BUCKET__MEDIA_CDN`.

The separator is a **double** underscore on purpose. A single one would collide
with real variable names — `S3_BUCKET_NAME` would parse as the bucket for a
source called `name`.

#### Databases

```bash
DATABASE_URL=postgres://localhost/app
DATABASE_URL__ANALYTICS=postgres://warehouse.internal/analytics

# Optional, per source:
DB_POOL_MAX__ANALYTICS=5
ADMIN_CONNECTION_STRING__ANALYTICS=postgres://…
REBASE_DRIVER__ANALYTICS=@rebasepro/server-postgres
```

The driver is chosen from the declared `engine` (`postgres` and `mongodb` are
known), and `REBASE_DRIVER__<KEY>` overrides it for anything else.

#### Storage

```bash
STORAGE_TYPE__MEDIA=s3
S3_BUCKET__MEDIA=my-media-bucket
S3_REGION__MEDIA=eu-central-1
S3_ACCESS_KEY_ID__MEDIA=…
S3_SECRET_ACCESS_KEY__MEDIA=…
```

`STORAGE_TYPE__<KEY>` may be omitted when the declaration already names the
engine.

### Failure behaviour

A declared server-transport data source with no connection string **fails the
boot**, naming the variable to set. This is deliberate and worth understanding:
the alternative is that collections routed to the missing source quietly fall
back to the default database. That is data landing in the wrong place behind a
server that reports itself healthy — far worse than a container that refuses to
start.

Two keys that would derive the same variable name are also rejected, because one
of them would silently read the other's configuration.

Sources declared with `transport: "direct"` are skipped entirely: the client
talks to those itself, so the backend holds no connection and demands no
configuration for them.

### Storage access control

Storage keys share one flat namespace and are not under row-level security, so
without an explicit access-control model the default would be "any signed-in user
may read, overwrite, delete or list any object". Production refuses to boot
rather than assume that.

The way to say what access means for your project is a `storageAuthorize` export
from the config package — a function, because no environment variable can express
"this user may read this key":

```ts
// config/index.ts

export const storageAuthorize: StorageAuthorize = async ({ key, user, operation }) => {
    if (!user) return false;
    const [ownerId] = key.split("/");
    return ownerId === user.uid || operation === "read";
};
```

Two environment escapes exist for the cases where that really is the model:

- `STORAGE_PUBLIC_READ=true` — the bucket is a public, read-only CDN. Writes,
  deletes and listing still require authentication.
- `STORAGE_ALLOW_ANY_AUTHENTICATED=true` — every signed-in user is trusted with
  every file. Defensible for a single-tenant app, never for a multi-tenant one.

### Storage in production

With no bucket configured, storage is **off** in production and uploads answer
`501`. Local disk is the container filesystem, so files written there vanish on
the next restart — an upload that fails loudly can be retried, one that succeeded
into a disk about to be wiped cannot. Set `FORCE_LOCAL_STORAGE=true` only when a
durable volume really is mounted.

One consequence worth knowing if you declare storage sources explicitly: no
default bucket is invented for you. Declaring only a `media` source means there
is no `(default)` source, and a property that does not name one has nowhere to
go — deliberately, and identically in development and production. Declare
`(default)` too if you want one.

## Realtime & WebSocket

Rebase includes a built-in realtime engine that pushes data changes to connected clients over WebSocket.
When any record is created, updated, or deleted, every subscriber watching that collection or entity receives the update instantly — no polling required.

### How It Works

The realtime pipeline has three stages:

1. **Database trigger** — A mutation hits the PostgreSQL database (via REST API, SDK, or Studio).
2. **Server fan-out** — The Rebase server detects the change and fans it out to every active WebSocket subscription that matches the affected collection or entity.
3. **Client callback** — The client SDK fires your `onUpdate` callback with the fresh data.

```
┌──────────────┐      ┌────────────────────┐      ┌──────────────┐
│  PostgreSQL   │─────▶│  Rebase Server     │─────▶│  Client SDK  │
│  LISTEN/NOTIFY│      │  RealtimeService   │      │  WebSocket   │
└──────────────┘      └────────────────────┘      └──────────────┘
```

For multi-instance deployments, Rebase uses PostgreSQL's `LISTEN/NOTIFY` to broadcast changes across server instances. This is handled automatically — a dedicated PostgreSQL connection listens on the `rebase_entity_changes` channel and relays updates to local subscribers.

#### Zero Configuration

Realtime is enabled out of the box. There is no flag to flip or service to start — if your Rebase server is running, the WebSocket endpoint is available.

> By default, Rebase also emits realtime events for writes made **outside** the API (via `psql`, another service, or Studio's SQL editor) whenever the database connection supports it — see [database-level change capture](#database-level-change-capture-cdc).

### Client SDK Subscriptions

The Rebase client SDK exposes two subscription methods on every collection accessor:

- **`listen()`** — Subscribe to an entire collection (with optional filters).
- **`listenById()`** — Subscribe to a single entity by its ID.

Both methods return an **unsubscribe function** you call to stop receiving updates.

#### Subscribing to a Collection

Use `listen()` to receive updates whenever records in a collection change:

```typescript
const unsubscribe = client.data.products.listen(
  undefined, // FindParams — pass undefined for all records
  (response) => {
    console.log("Products updated:", response.data);
    console.log("Total:", response.meta.total);
  },
  (error) => {
    console.error("Subscription error:", error);
  }
);
```

The callback receives a `FindResponse<M>` containing:
- `data` — Array of `Entity<M>` objects.
- `meta` — Pagination info (`total`, `limit`, `offset`, `hasMore`).

#### Subscribing to a Collection with Filters

Pass `FindParams` as the first argument to filter the subscription:

```typescript
const unsubscribe = client.data.products.listen(
  {
    where: { status: ["==", "published"] },
    orderBy: ["created_at", "desc"],
    limit: 50,
  },
  (response) => {
    console.log("Published products:", response.data);
  }
);
```

The server respects these filters — only matching records are included in updates.

#### Subscribing to a Single Entity

Use `listenById()` to watch a specific record:

```typescript
const unsubscribe = client.data.products.listenById(
  "product-123",
  (entity) => {
    if (entity) {
      console.log("Product updated:", entity.values);
    } else {
      console.log("Product was deleted");
    }
  },
  (error) => {
    console.error("Subscription error:", error);
  }
);
```

The callback receives `Entity<M> | undefined`. A value of `undefined` means the entity was deleted.

#### Unsubscribing

Both `listen()` and `listenById()` return an unsubscribe function. Call it to stop receiving updates and clean up server-side resources:

```typescript
const unsubscribe = client.data.products.listen(undefined, (response) => {
  // handle updates
});

// Later, when you no longer need updates:
unsubscribe();
```

:::tip
Always call the unsubscribe function when a component unmounts or a page navigates away. This prevents memory leaks and unnecessary server-side work.
:::

### Query Builder `.listen()`

The fluent query builder also supports realtime subscriptions. Chain your filters, then call `.listen()` instead of `.find()`:

```typescript
const unsubscribe = client.data.orders
  .where("status", "==", "pending")
  .orderBy("created_at", "desc")
  .limit(20)
  .listen(
    (response) => {
      console.log("Pending orders:", response.data);
    },
    (error) => {
      console.error("Error:", error);
    }
  );
```

:::note
The `.listen()` method on the query builder is only available when the `RebaseClient` is configured with a `websocketUrl`. If the WebSocket connection is not configured, calling `.listen()` will throw an error.
:::

### Update Delivery: Instant Patch + Correctness Refetch

Rebase uses a two-phase update strategy for collection subscriptions to combine extreme speed with absolute correctness:

1. **Phase 1 — Instant entity patch:** When a single entity changes (created, updated, deleted), the server immediately pushes a lightweight `collection_patch` message containing the modified entity values directly to subscribers. The client merges this into its cached collection data for near-instant cross-tab feedback — bypassing the database entirely for sub-millisecond perceived updates.

2. **Phase 2 — Debounced RLS refetch:** After a short delay of **300ms** (`REFETCH_DEBOUNCE_MS`), the server performs an authoritative database refetch of the collection matching your original filters and sort order. This is critical because field mutations might alter the entity's visibility (e.g. if its status changed and no longer matches a `where` filter).
   
   To maintain strict security boundaries, this refetch query is executed inside a transaction setting the transaction-local variables `app.user_id` and `app.user_roles` mapped from the subscriber's `SubscriptionAuthContext`. This ensures PostgreSQL Row-Level Security (RLS) constraints are evaluated correctly under the client's auth session, and only the records the user is authorized to see are sent in the final `collection_update`.

This approach guarantees that list filters and access policies remain perfectly consistent while maintaining high UI responsiveness.

### Broadcast Channels

Broadcast channels let clients send arbitrary messages to each other in real time — useful for features like typing indicators, cursor positions, or custom notifications.

Broadcast is managed at the WebSocket protocol level. The server supports these message types:

| Message Type     | Direction       | Description                              |
|-----------------|-----------------|------------------------------------------|
| `join_channel`    | Client → Server | Join a named channel                     |
| `leave_channel`   | Client → Server | Leave a channel                          |
| `broadcast`       | Client → Server | Send a message to all channel members    |
| `broadcast`       | Server → Client | Receive a message from another member    |
| `channel_history` | Client → Server | Request retained messages after a sequence |
| `channel_history` | Server → Client | The retained messages a client missed    |

When a client sends a `broadcast` message, the server relays it to **all other members** of that channel (the sender does not receive its own message).

```typescript
// Broadcast message structure (sent by client)
{
  type: "broadcast",
  payload: {
    channel: "room-42",
    event: "typing",
    payload: { userId: "user-1", isTyping: true }
  }
}

// Received by other clients in the channel
{
  type: "broadcast",
  channel: "room-42",
  event: "typing",
  payload: { userId: "user-1", isTyping: true }
}
```

### Channel Retention

By default a broadcast reaches currently-connected members and is then gone. That is the right trade for notifications and cursors, and it costs nothing.

For an operation stream — collaborative editing, anything where a silent gap causes divergence — a channel can be configured to **retain** its messages. Retained broadcasts are given a per-channel sequence number and stored, so a client that reconnects can ask for everything after the last one it saw.

Retention is opt-in and configured here, on the server:

```typescript

await initializeRebaseBackend({
    app,
    server,
    database: createPostgresAdapter({
        connection: db,
        schema: { tables, enums, relations },
        realtime: {
            channels: [
                // Most specific first — the first match wins.
                { match: "doc:draft:*", limit: 100 },
                { match: "doc:*", limit: 500, ttl: "24h" }
            ]
        }
    })
});
```

| Field   | Description                                                                 |
|---------|-----------------------------------------------------------------------------|
| `match` | Exact channel name (`"doc:42"`) or a trailing-`*` prefix (`"doc:*"`)        |
| `limit` | Keep at most this many of the most recent messages per channel               |
| `ttl`   | Keep messages for at most this long — `"30s"`, `"15m"`, `"24h"`, `"7d"`, or milliseconds |

A rule needs at least one of `limit` or `ttl`. One with neither is ignored and logged, because unbounded retention is almost never intended and cannot be walked back once the table has grown.

:::note[Why not let clients ask for history?]
A channel is created by whoever names it. If a client could choose its own history depth, any visitor could commit your backend to unbounded storage. Configuring it here also means presence and notification channels — the overwhelming majority — pay nothing: with no rules configured, no table is created and broadcast runs the same synchronous path it always did.
:::

#### Storage

Retained channels use two tables in the `rebase` schema, created automatically on startup when at least one rule is configured:

| Table                     | Contents                                                        |
|---------------------------|-----------------------------------------------------------------|
| `rebase.channel_messages` | The retained messages, keyed by `(channel, seq)`                 |
| `rebase.channel_cursors`  | The highest sequence issued per channel                          |

Pruning happens as messages arrive, throttled per channel so cost tracks elapsed time rather than write volume. It only ever removes rows from `channel_messages` — cursors are kept indefinitely (they are one small row per channel), because restarting a channel's sequence would change what a client's saved resume point means.

#### Delivery guarantees

- **Ordered.** Sequence numbers are allocated per channel, and delivery order matches sequence order.
- **Durable before delivered.** A message that cannot be stored is not delivered to anyone, and the sender is told. Delivering it would put it in front of live subscribers while leaving it out of every future replay, and no later message could repair that gap.
- **At-least-once on catch-up.** A replay range may overlap messages a client already received; the SDK discards ones it has already delivered.

:::caution[History has the same access model as the channel]
A client that has joined a channel may replay its retained messages, including those broadcast before it arrived — membership is the only check, and joining is open to any client that can name the channel. Retention is opt-in per channel pattern, so enabling it makes that channel's past readable to any visitor who guesses the name. Retained channels are the case where this becomes durable rather than momentary, so treat a retained channel's contents as public to your users.
:::

### Presence Tracking

Presence tracks which users are currently online in a channel and lets each user share custom state (e.g., cursor position, status).

| Message Type       | Direction       | Description                                          |
|-------------------|-----------------|------------------------------------------------------|
| `presence_track`  | Client → Server | Start tracking presence with custom state            |
| `presence_untrack`| Client → Server | Stop tracking presence                               |
| `presence_state`  | Client → Server | Request the full presence state for a channel        |
| `presence_state`  | Server → Client | Full entity of all presences in a channel          |
| `presence_diff`   | Server → Client | Incremental update (joins and leaves)                |

When a client sends `presence_track`, the server automatically joins them to the channel (no separate `join_channel` needed) and broadcasts a `presence_diff` to all channel members.

```typescript
// Track presence
{
  type: "presence_track",
  payload: {
    channel: "document-edit-42",
    state: { name: "Alice", cursor: { line: 10, col: 5 } }
  }
}

// Presence diff received by other clients
{
  type: "presence_diff",
  channel: "document-edit-42",
  joins: { "client-abc": { name: "Alice", cursor: { line: 10, col: 5 } } },
  leaves: {}
}

// Full presence state response
{
  type: "presence_state",
  channel: "document-edit-42",
  presences: {
    "client-abc": { name: "Alice", cursor: { line: 10, col: 5 } },
    "client-def": { name: "Bob", cursor: { line: 22, col: 0 } }
  }
}
```

Stale presences are automatically cleaned up after 30 seconds of inactivity.

### Auto-Reconnect

The client SDK automatically reconnects when the WebSocket connection drops:

- **Exponential backoff** — Reconnect delays start at 1 second and double on each attempt, capping at 30 seconds.
- **Maximum 5 attempts** — After 5 failed reconnection attempts, the client stops trying.
- **Automatic resubscription** — On successful reconnect, all active subscriptions are re-registered with the server. No manual intervention needed.
- **Message queuing** — Messages sent while disconnected are queued and delivered after reconnection.

You can listen to connection lifecycle events:

```typescript
const ws = client.ws; // Access the WebSocket client

ws.on("connect", () => console.log("Connected"));
ws.on("disconnect", () => console.log("Disconnected"));
ws.on("reconnect", () => console.log("Reconnected"));
ws.on("error", (error) => console.error("Error:", error));
```

### Authentication & RLS

WebSocket subscriptions automatically respect Row-Level Security (RLS) policies. When the client is authenticated:

1. The WebSocket connection authenticates using the same JWT token as the REST API.
2. Every subscription refetch runs inside a PostgreSQL transaction with `set_config('app.user_id', ...)` and `set_config('app.user_roles', ...)` — ensuring RLS policies are enforced.
3. If a token expires during an active session, the client automatically re-authenticates and re-subscribes.

This means each user only receives updates for records they have permission to see.

### Cross-Instance Broadcasting & LISTEN/NOTIFY Architecture

For multi-instance cluster environments (e.g., running inside Kubernetes or Docker containers behind a load balancer), Rebase relies on PostgreSQL `LISTEN/NOTIFY` to synchronize **row changes** across instances. Collection and entity subscriptions therefore span instances with no configuration — that is what this section describes.

**Broadcast channels and presence are separate**, and are per-instance until you turn on a channel bus. See [Channels and presence across instances](#channels-and-presence-across-instances) below.

#### Bypassing pgBouncer Pools

Because connection poolers like **pgBouncer** do not support the persistent connection model required for long-lived SQL `LISTEN` sessions, the real-time supervisor opens a dedicated, unpooled Postgres client (`PgClient`) directly to the database. This direct connection utilizes the `DATABASE_DIRECT_URL` environment variable if configured, ensuring stability and preventing pool exhaustion or abrupt drops.

#### Notification Mechanics & Payload Layout

When a entity is modified on Instance A, it broadcasts a notification on the `rebase_entity_changes` channel. To minimize database overhead and network bandwidth, the notification payload is kept extremely compact:

```json
{
  "sid": "inst_7a9c1b",
  "p": "posts",
  "eid": "45",
  "db": null
}
```

*Note: `sid` represents the server's unique random instance ID generated at startup, `p` is the collection slug (path), and `eid` is the target entity ID.*

- **Self-Filtering**: Upon receiving a message, each instance reads the `sid`. If it matches its own instance ID, the server discards the notification to prevent infinite routing loops.
- **Relay and Fan-out**: If the notification came from another instance, the server schedules a debounced refetch and relays the update to its locally connected WebSocket subscribers.
- **Supervisor Reconnection Loop**: If the database connection drops, a background connection supervisor monitors the state and triggers an auto-reconnect sequence after a fixed **3-second** delay, restoring the `LISTEN` loop without affecting the main Hono application lifecycle.

### Channels and presence across instances

Row changes cross instances on their own (above). Broadcast channels and presence do **not**: by default they fan out only to the clients connected to the instance that received them.

On a single instance that is exactly right and costs nothing. Behind a load balancer it is a bug you will not see in development: two collaborators land on different replicas, join the same channel, and see an empty room while broadcasting to each other perfectly. Nothing errors.

The fix is a **channel bus** — an opt-in transport that carries channel frames and presence between instances:

```typescript
database: createPostgresAdapter({
    connection: db,
    schema: { tables, enums, relations },
    realtime: {
        bus: { type: "postgres" }
    }
})
```

| Bus          | When to use it                                                                                       |
|--------------|--------------------------------------------------------------------------------------------------------|
| `memory`     | **Default.** Single instance. No cross-instance delivery, no overhead.                                   |
| `postgres`   | Two or more instances. Uses `LISTEN/NOTIFY` on the database you already have — no new service to deploy. |

The transport can also be set per deployment with `REALTIME_CHANNEL_BUS=memory|postgres`, which overrides the configured value.

#### Why there is no Redis option in the box

Rebase deploys as Postgres + backend + frontend. A bus that needed a message broker would put a second stateful service into every `docker-compose.yml` the CLI scaffolds, for a feature most applications never use — so the bar for adding one is that the database genuinely cannot carry the load.

It can. Measured across two backend instances against a single Postgres container, the Postgres bus delivered **~10,000 cross-instance messages per second with no losses**, and stayed flat out to **eight instances** (14,000 deliveries, no losses). Twenty people dragging cursors at 60 fps generate around 1,200 messages per second — roughly an eighth of that.

The limit worth watching is not capacity, it is that every notification is a query against your primary database, competing with your application's real queries. The Postgres bus therefore **coalesces** outgoing frames (see below), which is what keeps that cost proportional to elapsed time rather than message count.

Per client, the socket accepts up to **7,200 channel frames a minute** (120/s — 60 fps of cursor broadcasts plus the presence update each one carries), counted separately from the budget queries and subscriptions share. Frames past that are refused with a `RATE_LIMITED` error rather than queued.

If you are still pushing it after that, throttle cursor-grade events on the client (last-write-wins state does not need 60 updates a second), and consider routing a document's collaborators to the same instance — sticky routing drops cross-instance traffic to nearly nothing regardless of user count. Only past that is another transport worth it, and then the answer is a transport package, not a fork. See [Writing your own transport](#writing-your-own-transport).

#### Coalescing

Frames published while a short window is open leave together in a single notification. The window is **leading-edge**: a frame arriving when no window is open is sent immediately, so an idle channel pays no added latency and only a sustained stream is ever batched.

Measured across two instances, 3,000 broadcasts, all delivered in every case:

| Traffic shape | Coalescing off | Coalescing on | Reduction |
|---|---|---|---|
| Burst (as fast as possible) | 3,000 queries | 68 queries | **44×** |
| Paced (~500 msg/s, spread out) | 3,000 queries | 240 queries | **12.5×** |

The burst case also finished ~11× faster in wall-clock, because the database round-trips were the bottleneck rather than the work.

The window defaults to 10 ms and is not a sensitive setting — 5 ms, 10 ms and 20 ms produced identical query counts in both shapes, because a batch is bounded by the 8 KB payload ceiling or by the natural shape of the traffic well before the timer matters. Change it only if you have a reason:

```typescript
realtime: {
    bus: { type: "postgres", batchWindowMs: 20 }   // 0 disables coalescing
}
```

One deployment note: a batch travels in a different wire shape from a single frame, and an instance running an older build does not understand it. Single frames are always sent unwrapped, so a rolling deploy only risks dropped frames if the cluster is under sustained load *during* the restart — and retained channels repair themselves through history replay regardless.

### Writing your own transport

`realtime.bus` accepts any object implementing the `ChannelBus` interface, so a transport can ship as its own package — `@rebasepro/types` declares the contract, and nothing else is required to implement it:

```typescript

export class MyChannelBus implements ChannelBus {
    readonly kind = "my-transport";
    readonly maxFrameBytes = Infinity;

    async start(handler: ChannelBusHandler): Promise<void> {
        // Connect. Reject if you cannot — the caller falls back to in-process
        // delivery, which is far better than a cluster that believes it is
        // connected and silently is not.
    }

    async publish(frame: ChannelBusFrame): Promise<void> {
        // Reach every other instance, or reject.
    }

    async stop(): Promise<void> {
        // Idempotent; release anything holding the event loop open.
    }
}
```

Pass the instance where a built-in name would go:

```typescript
database: createPostgresAdapter({
    connection: db,
    schema: { tables, enums, relations },
    realtime: { bus: new MyChannelBus(process.env.MY_TRANSPORT_URL!) }
})
```

**What your implementation must guarantee:** `start()` rejects when the transport is unusable; `publish()` reaches every other instance or rejects; `stop()` is idempotent; and a malformed message is dropped and logged rather than thrown, so one bad frame cannot take the listener down.

**What it does not have to guarantee:** ordering (retained channels carry `seq` and the SDK orders by it), durability (a lost frame is a missed live update, repaired by the client's history replay), or exactly-once delivery (retained frames are deduped by `seq`; presence diffs are idempotent).

`maxFrameBytes` is how the framework knows whether to send a large retained message inline or as a pointer. Return `Infinity` when your transport has no meaningful ceiling, so the pointer path is never taken needlessly.

Delivery to local clients is not your concern — the realtime service owns which subscribers receive a frame. A transport only moves frames between instances.

#### The 8 KB limit on the Postgres bus

`pg_notify` refuses a payload of 8000 bytes or more. Cursors and presence fit with room to spare; a document snapshot does not. Rebase handles this the same way it handles large entity changes — by sending an address instead of a body:

- **On a retained channel** (see [Channel Retention](#channel-retention)) the message is already stored with a sequence number, so the notification carries only `(channel, seq)` and each receiving instance reads the body back. There is no size limit at all.
- **On an ephemeral channel** there is nothing to point at. The broadcast is delivered locally, the sender receives a `CHANNEL_BUS_PAYLOAD_TOO_LARGE` error, and a warning names the channel — rather than the message silently reaching half the cluster.

If you broadcast large messages, give that channel a retention rule. That is the whole fix.

#### Presence is shared state, not just fan-out

`presence_state` has to answer "who is in this channel?" for the whole cluster, which per-instance memory cannot do. When a bus is active, Rebase keeps the roster in `rebase.channel_presence` (created automatically) and answers roster requests from it.

| Column        | Contents                                       |
|---------------|------------------------------------------------|
| `channel`     | Channel name                                   |
| `client_id`   | The tracked client                             |
| `instance_id` | Which backend instance it is connected to      |
| `state`       | The client's presence state                    |
| `last_seen`   | Refreshed by the SDK's presence heartbeat      |

The SDK heartbeats presence every ~20 seconds against a 30-second timeout. Rows that stop being refreshed are reaped, and the departures announced to every instance — which doubles as crash recovery: a pod that dies leaves rows behind that look, after one timeout window, exactly like any other client that went quiet. A graceful shutdown clears its own rows immediately, so a rolling deploy does not show a window of ghosts.

:::caution[The LISTEN connection must bypass your pooler]
`LISTEN` is session state, so the Postgres bus needs a direct connection — not pgBouncer or any transaction-mode pooler. Rebase uses `DATABASE_DIRECT_URL` when it is set; behind a pooler, point it at the database service itself. Without a usable direct URL the bus logs a warning and stays in memory mode.
:::

### Database-Level Change Capture (CDC)

**Change Data Capture is on by default.** Rebase captures changes at the database and emits realtime events for **every committed write, regardless of how it was made** — REST, SDK, Studio, `psql`, a cron job in another service, raw Drizzle/SQL, or Studio's **SQL editor**. This is the same model as Supabase Realtime tailing the write-ahead log.

No configuration is required. On a database connection that supports it, CDC self-provisions at startup; on one that doesn't (e.g. a restricted role that can't create triggers), Rebase quietly uses application-level realtime instead — nothing to turn on, nothing that breaks.

#### Configuration

CDC is controlled by the `REALTIME_CDC` environment variable:

| Value | Behavior |
| --- | --- |
| `auto` *(default)* | Enable database-level capture where the connection supports it; **silently fall back** to application-level realtime otherwise. Zero-config. |
| `trigger` | Force trigger-based capture. Works on any PostgreSQL, including managed instances without logical replication. Warns (rather than silently falling back) if it can't provision. |
| `wal` | Prefer WAL logical replication. Not yet bundled — degrades to `trigger` and logs the active mode. |
| `off` | Application-level realtime only. Use this to avoid the per-write trigger overhead on write-heavy workloads. |

On boot you'll see a log line stating the active mode, e.g.:

```
📡 [CDC] Realtime source = database-level change capture (mode: trigger).
   All writes now emit realtime events regardless of origin.
```

If the connection can't support it, `auto` logs an informational line instead and continues with application-level realtime:

```
ℹ️ [CDC] Database-level change capture unavailable (likely insufficient
   privileges to create triggers…) — using app-level realtime.
```

#### How It Works

1. **Self-provisioning** — At startup (server/owner context), Rebase installs an idempotent `AFTER INSERT/UPDATE/DELETE` trigger on each managed table. The trigger emits a compact change notification on the `rebase_cdc` channel. A payload that would exceed PostgreSQL's 8&nbsp;KB `NOTIFY` limit falls back to an identity-only message, so CDC can never abort the triggering write.
2. **Capture** — A dedicated, unpooled `LISTEN` client per instance consumes `rebase_cdc`, maps the changed table back to its collection, and feeds the change into the same `RealtimeService` pipeline used by API mutations. Like the cross-instance listener, it prefers `DATABASE_DIRECT_URL` and auto-reconnects.
3. **RLS-safe delivery** — The raw row from the change stream is **never** forwarded to subscribers. The change is marked invalidated, and each subscription re-reads the row under its **own** auth context. Filtering is therefore per subscriber, never per publisher: a client only ever receives rows its RLS policies permit.
4. **Cross-instance** — Because every instance observes every commit through the change stream, CDC also *is* the cross-instance channel; the legacy per-mutation `rebase_entity_changes` broadcast is not used while CDC is active.
5. **De-duplication** — A mutation made through the Rebase API is delivered locally the instant it commits and is also echoed back through the change stream. The originating instance suppresses that echo (a short-lived record of its own emits), so subscribers never see an API write twice.

#### Requirements & Notes

- CDC requires a direct connection string (`DATABASE_DIRECT_URL` or the primary connection) for the `LISTEN` client — connection poolers in transaction mode do not support long-lived `LISTEN` sessions.
- Triggers are installed only on tables backed by a registered collection. Writes to unmapped tables are ignored.
- A collection whose table has not yet been migrated is skipped with a warning rather than blocking CDC for the rest.
- Native WAL logical-replication streaming (`wal2json`/`pgoutput`) is planned; today `REALTIME_CDC=wal` degrades to the trigger-based path, which provides equivalent database-level coverage.

### Pending Request Timeout

To prevent client requests from hanging indefinitely, all pending WebSocket operations that expect a server response (such as one-shot collection fetches `FETCH_COLLECTION`, single entity fetches `FETCH_ONE`, creating/updating `SAVE`, deletes `DELETE`, counts `COUNT`, and uniqueness checks `CHECK_UNIQUE_FIELD`) have a default timeout of 30 seconds.

If the server does not respond within this 30-second window, the client automatically deletes the pending request and rejects the promise with an `ApiError` with the message `"Request timed out"`.

One-way messages that do not expect a response (like `subscribe_collection`, `subscribe_one`, `unsubscribe`, `join_channel`, `leave_channel`, `broadcast`, `presence_track`, `presence_untrack`, and `presence_state`) resolve immediately upon transmission and do not trigger timeouts.

### Next Steps

- [Client SDK](/docs/sdk) — Full SDK reference including typed collection accessors.
- [Authentication](/docs/backend/authentication) — Set up JWT auth and RLS policies.
- [Backend Architecture](/docs/backend) — Overview of the Rebase server architecture.

## Search

`.search("term")` works on every collection without configuration. What it
compiles to depends on whether the collection has asked for anything more.

### The default

With no configuration, `.search()` is a **case-insensitive substring match**,
OR-ed across the collection's top-level `string` properties:

```sql
WHERE name ILIKE '%term%' OR description ILIKE '%term%'
```

This is enough for a small collection with its text in plain columns. It has
three limits that no setting inside it can fix:

- **It cannot see inside `map` or `array` properties.** A collection that keeps
  its searchable content in JSONB — tags, certifications, a questionnaire — has
  a search box that silently matches nothing.
- **It has no relevance.** Rows come back in `orderBy` order, so the best match
  can be on page seven.
- **It cannot use an index.** A leading `%` defeats a B-tree, so every search is
  a sequential scan. Fine at a thousand rows; a cliff at a million.

The term is matched **literally**: `%` and `_` are LIKE metacharacters, and they
are escaped before the pattern is built, so searching for `50%` searches for
`50%` rather than returning every row. If you want wildcards, the `like` filter
operator takes a pattern (`.where("title", "like", "post-%")`); `.search()` does
not.

The default does not change, and a collection that has not opted in compiles to
exactly the SQL it always did.

### Opting in

Declare a `search` block on a Postgres collection, naming the fields you want
indexed:

```typescript

const talents: PostgresCollectionConfig = {
    slug: "talents",
    table: "talents",
    name: "Candidates",
    properties: {
        id: { name: "ID", type: "string", isId: "uuid" },
        full_name: { name: "Full name", type: "string" },
        bio: { name: "Bio", type: "string" },
        interests: { name: "Interests", type: "array", of: { name: "Interest", type: "string" } },
        questionnaire: { name: "Questionnaire", type: "map", properties: {} }
    },
    search: {
        language: "spanish",
        unaccent: true,
        fields: [
            { path: "full_name", weight: "A" },
            { path: "bio", weight: "D" },
            "interests",
            "questionnaire.certifications"
        ]
    }
};
```

Nothing is inferred. A field is searched if and only if you name it, and a path
that does not resolve fails at boot rather than being quietly skipped — a search
field you believe is live and is not is exactly the failure this block exists to
prevent.

`.search()` then compiles to a ranked full-text match, and rows come back with a
`_score`:

```typescript
const { data } = await client.data.talents
    .search("auditor iso 14001")
    .orderBy("_score", "desc")
    .find();
```

#### What declaring it creates

One `tsvector` column, `GENERATED ALWAYS AS … STORED`, and one GIN index on it.
Postgres recomputes the column on every write of a source field and refuses any
attempt to write it directly, so the index cannot drift from the row. The column
is never returned by the API.

They are generated into `drizzle/search.sql`, next to `schema.sql` and
`policies.sql`, and `rebase db push` applies them for you — nothing extra to
run. They get their own file because a generated `tsvector` column needs an
`IMMUTABLE` helper function to exist first (`unaccent` is only `STABLE`, and
flattening a `jsonb` document needs a set-returning function), and Atlas — the
engine behind `db push` — cannot manage functions on its free tier.

One consequence worth knowing if you deploy by migration rather than by push:
adding a `search` block on its own produces no migration, because the schema
Atlas compares has not changed. `rebase db generate` says so when it happens.
The block is still applied by `rebase db push` and by the boot-time schema
ensure; to put it in a migration explicitly, append `drizzle/search.sql` to one.

#### Changing the block later

A generated column carries its expression, and Postgres cannot alter that
expression in place — so adding a field, moving a weight, changing the language
or turning `unaccent` on is **not** something `ADD COLUMN IF NOT EXISTS` can
apply to a column that already exists.

Rebase records a fingerprint of the expression on the column when it creates it,
and compares it on every boot and every `db push`. A change is refused, loudly,
with the two statements that apply it — a `DROP COLUMN` and an `ADD COLUMN`,
which rewrite the table and rebuild the GIN index. Run them at a time you
choose; nothing rewrites a live table on your behalf. (Turning `fuzzy` on is
additive — a second column — and applies without any of this.)

Boot refuses rather than serving, because the alternative is what this check
replaced: a column that keeps indexing the previous field set, and a search that
returns nothing for content plainly in the row.

### What you can name in `fields`

| Path | Resolves to | Example |
|------|-------------|---------|
| A `string` property | the column | `"full_name"` |
| A `string[]` property | every element | `"interests"` |
| A `map` property | every string value in the document | `"questionnaire"` |
| A path inside a `map` | every string value at or below that point | `"questionnaire.certifications"` |

A path into a map indexes **string values at any depth** below it — arrays of
strings, nested objects, arrays of objects. JSON *keys* are never indexed, only
values, so a field name common to every row does not become a term that matches
every row.

Naming an enum, a UUID, a `json` (rather than `jsonb`) column, or an array of
numbers is a boot-time error explaining why. Enums in particular are a fixed
vocabulary: filter on them with `where`, which is exact and uses an index.

### Options

#### `language`

The Postgres text search configuration, which decides stemming and stopwords.
`"spanish"` stems `auditores` to `auditor` and drops `de`; the default,
`"simple"`, does neither.

`"simple"` is the default because it is the only choice that is never wrong — a
stemmer applied to the wrong language silently mangles lexemes. Set it to your
content's language to get stemming.

#### `unaccent`

Fold accents before indexing, so `auditoria` matches `auditoría`.

This is not cosmetic in an accented language. Postgres stems the two spellings
to **different lexemes** — `to_tsvector('spanish', 'auditoría')` yields
`auditor` while `'auditoria'` yields `auditori` — so without it, a query typed
without accents misses every row that carries them, which is most queries most
users type.

Requires the `unaccent` extension.

#### `fuzzy`

Also match on trigram similarity, so near-misses still rank: `iso14000` reaching
`ISO 14001`, which no amount of stemming will do because they are simply
different lexemes.

```typescript
search: {
    fields: ["full_name", "questionnaire.certifications"],
    fuzzy: true,
    fuzzyThreshold: 0.3   // default
}
```

Adds a second generated column and a trigram index, and requires `pg_trgm`.
Costs write time and disk; buys the most common class of failed search.

#### `weight`

Each field carries one of Postgres's four weight classes, `A` (strongest)
through `D`. `ts_rank` scores an `A` hit far above a `D` one, which is how a
name outranks a passing mention in a long description. Fields default to `B`.

#### `column`

The generated column is named `search_vector`. Change it only if that collides
with a column you already have — it is part of your schema once created, and
renaming it later is a drop and recreate, which rewrites the table.

### Ranking

`_score` is `ts_rank` against the same query the rows were matched with, and is
present only when the collection opted in *and* the request carried a search
string.

With `fuzzy` on, the trigram similarity is **added** to that rank. This is not a
refinement — it is what makes `fuzzy` a ranking at all. A typo matches nothing on
the exact path, so every row it finds has a `ts_rank` of exactly zero; ordering
by rank alone would return the best match in whatever order the table felt like.
The two terms are summed rather than weighted, so a row that matched exactly
contributes both and outranks a merely-similar row without needing a coefficient
to say so. Outside those two conditions `orderBy: "_score"` is an unknown field and
returns 400 rather than silently returning unsorted rows.

`_score` cannot be combined with cursor pagination (`startAfter`). Relevance is
computed per query rather than stored, so there is no value on the cursor row to
compare the next page against, and two requests with different search strings
produce scores that are not on the same scale. Use `limit`/`offset` for
relevance-ordered pages.

### Why did this row match?

A ranked list tells you *which* rows, never *why* one is there. Ask each row to
explain itself:

```typescript
const { data } = await client.data.talents
    .search("iso 14001", { explain: true })
    .orderBy("_score", "desc")
    .find();

data[0]._matches;
// [{ field: "questionnaire.certifications",
//    snippet: "<mark>ISO</mark> <mark>14001</mark> Lead Auditor" }]
```

`field` is the path exactly as declared in `fields`, so you can map it to a
label for display. Fields come back in the order you declared them.

Per-query, not per-collection, because the cost is per-query: one `ts_headline`
per declared field per returned row, and `ts_headline` re-parses the document
rather than reading the index. Right for a page of results, wrong for an export.

**The snippet contains markup by construction** — each hit is wrapped in
`<mark>`. Render it as HTML or strip the tags, but do not treat it as plain
text, and do not trust the surrounding text: it is whatever the user typed.
Splitting on `<mark>` and rendering the parts is safer than
`dangerouslySetInnerHTML`.

With `unaccent` on, snippets read with accents folded — `Auditoria`, not
`Auditoría`. `ts_headline` over the original text cannot find a hit that an
unaccented query produced, so it would return the text with nothing marked at
all; a readable snippet that highlights beats a prettier one that silently
doesn't.

### Adding the block to a live collection

The generated column is added by the boot-time schema ensure, like any other
column, and its index is built with `CREATE INDEX CONCURRENTLY` so writes are
not blocked. Adding a *stored* generated column does rewrite the table, so on a
large one, plan it like any other rewrite.

### Which engines

The `search` block is Postgres-only, and is rejected at boot on other engines
rather than silently ignored. MongoDB collections keep their regex-based
matching; Firestore collections use the external text-search controller.

## Cron Jobs

### Overview

Rebase includes a built-in **cron job scheduler** for running recurring background tasks — data cleanup, report generation, health checks, external API syncs, and more.

Cron jobs follow the same **file-based discovery** pattern as custom functions: drop a TypeScript file in your `crons/` directory, and Rebase automatically registers and schedules it.

- **Zero dependencies** — No external scheduler libraries required
- **Admin API** — REST endpoints to list, trigger, enable/disable, and view logs
- **Studio dashboard** — Monitor all jobs, view execution history, and trigger runs manually
- **Database persistence** — Execution logs stored in PostgreSQL, surviving restarts
- **In-memory cache** — Fast ring buffer (last 50 runs) for the dashboard, backed by the DB

### Defining a Cron Job

Create a file in your `backend/crons/` directory that default-exports a cron definition. Use the `defineCron` helper from `@rebasepro/server` for type inference and autocomplete:

```typescript
// backend/crons/health-check.ts

export default defineCron({
    schedule: "*/5 * * * *",     // every 5 minutes
    name: "System Health Check",
    description: "Monitors uptime and memory usage",

    async handler(ctx) {
        ctx.log("Running health check...");

        const uptime = process.uptime();
        const mem = process.memoryUsage();

        ctx.log(`Uptime: ${Math.round(uptime)}s`);
        ctx.log(`Heap: ${Math.round(mem.heapUsed / 1024 / 1024)}MB`);

        return {
            uptimeSeconds: Math.round(uptime),
            heapUsedMB: Math.round(mem.heapUsed / 1024 / 1024),
        };
    },
});
```

:::note
`defineCron` is an identity function — it returns the same object you pass in. A plain default-exported `CronJobDefinition` object works identically; `defineCron` simply provides compile-time type checking and editor autocomplete.
:::

The **filename** (without extension) becomes the job's unique ID — e.g., `health-check`.

### Configuration

Enable cron jobs by adding `cronsDir` to your backend config:

```typescript no-verify
const instance = await initializeRebaseBackend({
    // ... other config
    functionsDir: path.resolve(__dirname, "../functions"),
    cronsDir: path.resolve(__dirname, "../crons"),  // ← add this
});
```

That's it. Rebase will:

1. Scan the directory for `.ts` / `.js` files
2. Register each default export as a cron job
3. Auto-create the `rebase.cron_logs` table in PostgreSQL (if the driver supports SQL)
4. Start the scheduler and seed counters from existing DB logs
5. Mount admin REST routes at `/api/cron`

### Schedule Syntax

Cron expressions use the standard **5-field format**:

```
┌───────────── minute (0–59)
│ ┌─────────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌─────── month (1–12)
│ │ │ │ ┌───── day of week (0–6, Sunday = 0)
│ │ │ │ │
* * * * *
```

| Expression | Meaning |
|------------|---------|
| `* * * * *` | Every minute |
| `0 * * * *` | Every hour |
| `0 3 * * *` | Daily at 3:00 AM |
| `0 0 * * 1` | Every Monday at midnight |
| `0 9 1 * *` | First day of each month at 9:00 AM |
| `0,30 * * * *` | Every 30 minutes (on :00 and :30) |
| `0 9-17 * * 1-5` | Hourly, 9 AM–5 PM, weekdays only |

Step values (`*/n`), ranges (`a-b`), and lists (`a,b,c`) are all supported.

### CronJobDefinition Reference

```typescript
interface CronJobDefinition {
    // Cron schedule expression (5-field format)
    schedule: string;

    // Human-readable name shown in Studio
    name: string;

    // Optional description shown in Studio
    description?: string;

    // Whether the job starts enabled (default: true)
    enabled?: boolean;

    // Max execution time in seconds (default: 300)
    timeoutSeconds?: number;

    // How far back to look on startup for a slot that elapsed while no
    // instance was ticking (default: off). See "Recovering Missed Slots".
    catchUpWindowSeconds?: number;

    // The function to run on each tick
    handler: (ctx: CronJobContext) => Promise<unknown> | unknown;
}
```

### Handler Context

Each handler receives a `CronJobContext` containing utility methods and the Rebase Client instance:

```typescript
interface CronJobContext {
    // The job's unique ID (derived from filename)
    jobId: string;

    // The scheduled tick timestamp
    scheduledAt: Date;

    // Logger — captured lines appear in Studio and the logs API
    log: (...args: unknown[]) => void;

    // Backing RebaseClient instance running with full admin privileges
    client: RebaseClient;
}
```

Use `ctx.log()` to emit structured output. These lines are captured in the execution log and visible in Studio and via the REST API.

#### Interacting with Database & Services via `ctx.client`

The `ctx.client` parameter provides direct, server-side access to all Rebase services under administrative privileges. This means database operations run with bypass of Row-Level Security (RLS) policies:

```typescript
// backend/crons/expire-users.ts

export default defineCron({
    schedule: "0 0 * * *", // Daily at midnight
    name: "Expire Inactive Accounts",
    
    async handler(ctx) {
        ctx.log("Checking for expired trial users...");

        // Fetch using the pre-initialized data driver. `collection<Row>(slug)`
        // gives the query builder the row type — `where` keys are checked
        // against it. Every filter is an `[operator, value]` tuple; a bare
        // value is passed straight through and builds a malformed query.
        const users = ctx.client.data.collection<{
            id: string;
            email: string;
            trial_status: string;
            trial_ends_at: string;
            status: string;
        }>("users");

        const { data: trials } = await users.find({
            where: {
                trial_status: ["==", "active"],
                trial_ends_at: ["<", new Date().toISOString()]
            }
        });

        ctx.log(`Found ${trials.length} users with expired trials.`);

        for (const user of trials) {
            await users.update(user.id, {
                trial_status: "expired",
                status: "disabled"
            });
            
            // Send email notification using Rebase email service
            if (ctx.client.email) {
                await ctx.client.email.send({
                    to: user.email,
                    subject: "Your trial has expired",
                    html: "<p>Please upgrade your subscription to continue.</p>"
                });
            }
        }
    }
});
```

:::tip
The handler can return any JSON-serializable value. It will be stored in the log entry as `result` and displayed in Studio's execution history.
:::

### REST API

All cron routes require **admin authentication** (`requireAuth` + `requireAdmin`).

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/cron` | List all registered cron jobs |
| `GET` | `/api/cron/:id` | Get a single job's status |
| `POST` | `/api/cron/:id/trigger` | Manually trigger a job |
| `GET` | `/api/cron/:id/logs` | Get execution history (`?limit=N`) |
| `PUT` | `/api/cron/:id` | Enable/disable a job (`{ "enabled": true }`) |

#### Example: List All Jobs

```bash
curl -H "Authorization: Bearer $TOKEN" http://localhost:3001/api/cron
```

```json
{
    "jobs": [
        {
            "id": "health-check",
            "name": "System Health Check",
            "schedule": "*/5 * * * *",
            "enabled": true,
            "state": "idle",
            "totalRuns": 12,
            "totalFailures": 0,
            "lastRunAt": "2026-04-24T08:15:00.000Z",
            "nextRunAt": "2026-04-24T08:20:00.000Z",
            "lastDurationMs": 3
        }
    ]
}
```

#### Example: Trigger a Job Manually

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
    http://localhost:3001/api/cron/health-check/trigger
```

### Client SDK

The Rebase client SDK exposes a `cron` namespace for all operations:

```typescript

const client = createRebaseClient({ baseUrl: "http://localhost:3001" });

// List all jobs
const { jobs } = await client.cron.listJobs();

// Get a single job
const { job } = await client.cron.getJob("health-check");

// Trigger manually
const { log, job: updated } = await client.cron.triggerJob("health-check");

// View execution history
const { logs } = await client.cron.getJobLogs("health-check", { limit: 10 });

// Enable or disable
await client.cron.toggleJob("health-check", false); // pause
await client.cron.toggleJob("health-check", true);  // resume
```

### Studio Dashboard

When cron jobs are configured, a **Cron Jobs** tool appears in Rebase Studio under the **Automation** section. The dashboard provides:

- **Job list** — All registered jobs with live status indicators
- **Detail panel** — Schedule, next/last run, duration, and error information
- **Execution history** — Expandable log entries with captured output and results
- **Manual trigger** — Run any job on demand with one click
- **Enable/disable** — Pause and resume jobs without restarting the server

The dashboard auto-refreshes every 15 seconds.

### Schedule Validation & AST Parsing

At backend initialization, Rebase parses all registered cron schedules using a zero-dependency JS-based cron expander:
- **Syntax Check**: Verifies that the string contains exactly 5 whitespace-separated fields (`minute`, `hour`, `day of month`, `month`, `day of week`).
- **Range Expansion**: Deconstructs steps (`*/15`), ranges (`9-17`), and comma-separated lists (`0,30`) into explicit arrays of valid integers mapped to their respective bounds (e.g., minutes `0-59`, hours `0-23`, months `1-12`).
- If any cron expression fails validation, Rebase rejects the definition, logs a startup error, and refuses to register the job to prevent runtime execution failures.

---

### Under the Hood: Clock-Drift Correction

Standard interval-based schedulers (such as `setInterval`) drift over time and cause significant CPU spikes due to OS-level event loop scheduling delays. To guarantee execution accuracy, Rebase implements a **dynamic target-time calculation loop**:
1. **Candidate Calculation**: Upon completing a job or starting the scheduler, Rebase calculates the exact timestamp of the *next* matching candidate minute.
2. **Dynamic Sleep**: It calculates the difference in milliseconds (`nextRun.getTime() - now.getTime()`) and schedules a single `setTimeout`.
3. **Drift Safety Threshold**: A minimum sleep buffer (`MIN_SCHEDULE_INTERVAL_MS`) of **5,000ms** is enforced. If a scheduler tick completes extremely quickly, this threshold prevents near-instant double-firing.
4. **Shutdown Friendliness**: Timer handles are explicitly detached from the Node.js event loop using `timer.unref()`, ensuring background cron schedulers do not block clean process terminations during deployments.

---

### Recovering Missed Slots

Because the scheduler computes the next slot from *now* on every boot, a slot only fires if some instance was alive and ticking when it came round. Anything that replaces the process during a slot — a rolling deploy, a crash, a platform recycling the container — drops that run, and the replacement schedules the slot *after* it. Nothing errors; the run simply never happens.

This is **not** only a scale-to-zero problem. A service pinned to a warm instance still loses runs, because a platform is free to retire the instance holding the timer and start a fresh one.

Set `catchUpWindowSeconds` to a window comfortably wider than a restart, and startup will run a slot it finds unclaimed inside that window:

```typescript
export default defineCron({
    schedule: "0 6 * * *",       // daily at 06:00
    name: "Scrape Listings",
    catchUpWindowSeconds: 3600,  // tolerate an hour of downtime around 06:00
    handler: async (ctx) => { /* … */ }
});
```

Three things to know:

- **Off by default.** Without `catchUpWindowSeconds`, behaviour is unchanged.
- **Only the most recent missed slot runs.** Booting after a six-hour outage catches an hourly job up once, not six times. Catch-up stops a run going missing; it does not replay history.
- **A claims-capable store is required.** Catch-up claims the slot through the same `(job_id, slot)` key the scheduled path uses, which is the only thing distinguishing "this slot never ran" from "this slot already ran on the instance being replaced". With no store attached, catch-up is skipped and a warning is logged — otherwise an instance recycled every 30 minutes would re-run the same hourly job every time it booted.

In the ordinary case — a restart minutes after a slot ran normally — the most recent slot is already claimed, so catch-up costs one claim check per job per boot and does nothing.

A recovered run is a normal entry in `cron_logs` (`manual` is `false`), with a first log line recording the slot it recovered and how late it was:

```
⏰ Catch-up run for missed slot 2026-07-29T06:00:00.000Z (612s late)
```

---

### Concurrency Guarding

To ensure stability when executing resource-heavy operations, Rebase implements a strict **single-concurrency execution lock** per job ID:
- **Scheduled Overlaps**: If a job's scheduled tick fires while the previous execution is still running, the scheduler skips the tick, logs a warning, and immediately schedules the next candidate run.
- **Manual Trigger Collisions**: If an operator manually triggers a running job via Rebase Studio or the REST API, the request returns immediately with a skipped payload, protecting the active worker:
  ```json
  {
    "jobId": "expire-users",
    "success": true,
    "result": { "skipped": true, "reason": "already_executing" },
    "logs": ["Skipped: job is already running"]
  }
  ```

---

### Timeouts & Error Isolation

- **Forced Timeout Race**: Execution blocks are wrapped in a `Promise.race` against a timeout timer derived from `timeoutSeconds` (default: `300` seconds / 5 minutes). If the handler hangs past this threshold, the promise is rejected, throwing:
  `Error: Cron job "<id>" timed out after <N>ms`
- **Fail-Safe Try/Catch**: Each job handler runs inside an isolated wrapper. Any uncaught exceptions are intercepted, formatting the error traceback into a string, setting the job status to `"error"`, and updating the `rebase.cron_logs` failure counters. A crash inside a single cron task will never crash the scheduler loop or the primary Hono HTTP web server.
- **In-Memory Ring Buffer**: The scheduler maintains a ring buffer containing the last **50 runs** per job. This buffer is kept in memory to allow near-instant reads from the Rebase Studio UI.

---

### Database Persistence Schema

When database adapters supporting SQL (e.g. PostgreSQL) are active, Rebase provisions the `rebase.cron_logs` table:

```sql
CREATE SCHEMA IF NOT EXISTS rebase;

CREATE TABLE IF NOT EXISTS rebase.cron_logs (
    id           TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
    job_id       TEXT NOT NULL,
    started_at   TIMESTAMPTZ NOT NULL,
    finished_at  TIMESTAMPTZ NOT NULL,
    duration_ms  INTEGER NOT NULL,
    success      BOOLEAN NOT NULL DEFAULT true,
    error        TEXT,                                 -- Stack trace or error message
    result       JSONB,                                -- Return value of handler
    logs         JSONB,                                -- Ring buffer array of ctx.log outputs
    manual       BOOLEAN NOT NULL DEFAULT false        -- True if triggered from Studio/REST
);

CREATE INDEX IF NOT EXISTS idx_cron_logs_job ON rebase.cron_logs(job_id, started_at DESC);
```

On startup, the scheduler reads stats from this table via aggregate queries (`COUNT(*)`, `SUM(CASE WHEN success = false THEN 1 ELSE 0 END)`) to populate `totalRuns` and `totalFailures` history. Log insertions are executed in a non-blocking asynchronous sweep; if a database flush fails, the scheduler logs the error and continues normal execution using the in-memory ring buffer as a fallback.

### Example: Daily Cleanup Job

```typescript
// backend/crons/cleanup-sessions.ts

const job: CronJobDefinition = {
    schedule: "0 3 * * *",  // daily at 3 AM
    name: "Cleanup Expired Sessions",
    description: "Removes user sessions older than 30 days",

    async handler(ctx) {
        ctx.log("Starting session cleanup...");

        // Use the rebase singleton for admin-level database access
        // const { data: expired } = await rebase.data.findMany("sessions", { ... });
        const count = Math.floor(Math.random() * 50); // placeholder

        ctx.log(`Cleaned up ${count} expired sessions`);

        return { deletedSessions: count };
    },
};

export default job;
```

### Next Steps

- **[Backend Overview](/docs/backend)** — Full backend configuration reference
- **[Entity Callbacks](/docs/collections/callbacks)** — Run logic on data changes
- **[Webhook Integration](/docs/recipes/webhooks)** — Send notifications on events

## Custom Functions

### Overview

Custom functions let you add **arbitrary Hono API routes** alongside Rebase's auto-generated CRUD endpoints. They follow the same **file-based discovery** pattern as collections and cron jobs: drop a TypeScript file in your `functions/` directory, and Rebase mounts it automatically.

Use custom functions for:

- **Business logic endpoints** — approvals, promotions, custom workflows
- **Third-party integrations** — Stripe webhooks, Slack commands, external API proxies
- **Public endpoints** — contact forms, lead capture, health checks
- **Aggregate queries** — dashboard stats, reports, analytics

### Defining a Custom Function

Create a file in your `backend/functions/` directory that default-exports a Hono app:

```typescript
// backend/functions/hello.ts

const app = new Hono<HonoEnv>();

app.get("/", (c) => {
    return c.json({ message: "Hello from custom function!" });
});

export default app;
```

This mounts at **`/api/functions/hello`**. The filename (without extension) becomes the route prefix.

### Configuration

Enable custom functions by adding `functionsDir` to your backend config:

```typescript no-verify

const instance = await initializeRebaseBackend({
    // ... other config
    functionsDir: path.resolve(__dirname, "../functions"),
});
```

Rebase will:

1. Scan the directory for `.ts` / `.js` files
2. Validate each default export is a Hono app (duck-typed via `.fetch()` + `.routes`)
3. Mount each app at `/api/functions/<filename>`
4. Apply the auth middleware (see [Authentication](#authentication) below)

### File Naming and Route Mapping

| File | Mount Path |
|------|-----------|
| `functions/hello.ts` | `/api/functions/hello/*` |
| `functions/send-invoice.ts` | `/api/functions/send-invoice/*` |
| `functions/webhooks.ts` | `/api/functions/webhooks/*` |

Functions are discovered at the **top level of the directory only** — there is no recursion. `functions/admin/users.ts` is compiled by `rebase build` but never mounted; flatten the name instead (`functions/admin-users.ts`). A subdirectory is reported at boot and counted on the listing endpoint rather than ignored silently.

Files that are **skipped**:

- `index.ts` / `index.js` — reserved
- `*.test.ts` / `*.test.js` — test files
- `*.d.ts` — type declarations
- Subdirectories, and `.mts` / `.cts` / `.tsx` / `.jsx` / `.mjs` / `.cjs` files — reported as problems, since the build compiles more than the runtime loads

### Export Formats

The loader accepts two export formats:

#### Hono App (recommended)

```typescript

const app = new Hono<HonoEnv>();
app.get("/status", (c) => c.json({ ok: true }));
export default app;
```

#### Factory Function

```typescript

export default function () {
    const app = new Hono<HonoEnv>();
    app.get("/status", (c) => c.json({ ok: true }));
    return app;
}
```

---

### Under the Hood: The Duck-Typing Loader

When compiling codebases with multiple nested directories or in monorepos, you may run into **Hono package duplication**. 

If the Rebase framework depends on one Hono version and your local function directory resolves to another, standard class inheritance checks (`exported instanceof Hono`) will fail because their prototypes exist in separate memory spaces.

To prevent false negatives and reject loading functioning routers, Rebase uses a duck-typed validator (`isHonoLike`):
- It verifies the exported object is a non-null `object`.
- It checks that the object exposes a `.fetch` method (required to route requests).
- It verifies that `.routes` is an `array`.

```typescript
function isHonoLike(obj: unknown): boolean {
    if (!obj || typeof obj !== "object") return false;
    const record = obj as Record<string, unknown>;
    return typeof record.fetch === "function" && Array.isArray(record.routes);
}
```

#### ES Module Compiler Escape

To import TypeScript and JavaScript files dynamically on both Windows and Posix systems, the loader converts file paths to standard file URIs via `pathToFileURL(filePath).href`. 

To prevent TypeScript compilation from rewriting native ESM dynamic imports (`import(url)`) into CommonJS `require()` calls (which would throw errors at runtime under ESM runtimes), Rebase executes a runtime compiler escape:

```typescript
const dynamicImport = new Function("url", "return import(url)");
const mod = await dynamicImport(fileUrl);
```

---

### Authentication & Context Propagation

Custom functions are mounted with the **same auth middleware** as the data routes, but with `requireAuth: false`. This means:

- The user's JWT is **parsed and injected** into the context if present
- But requests are **not rejected** if no JWT is provided
- You must **explicitly protect** routes that need authentication

#### Protecting Routes

Use Rebase's built-in auth helpers:

```typescript

const app = new Hono<HonoEnv>();

// Public endpoint — no auth required
app.get("/public", (c) => {
    return c.json({ message: "Anyone can access this" });
});

// Protected endpoint — requires a valid JWT
app.post("/protected", async (c) => {
    // Narrowed: the env types every variable the middleware may set.
    const user = c.get("user") as { uid: string; roles?: string[] } | undefined;
    if (!user) {
        return c.json({ error: "Unauthorized" }, 401);
    }
    return c.json({ message: `Hello, ${user.uid}` });
});

// Admin-only endpoint
app.post("/admin-only", async (c) => {
    const user = c.get("user") as { uid: string; roles?: string[] } | undefined;
    const roles: string[] = user?.roles ?? [];
    if (!roles.includes("admin")) {
        return c.json({ error: "Admin access required" }, 403);
    }
    return c.json({ message: "Admin operation succeeded" });
});

export default app;
```

:::important
Rebase's JWT middleware is scoped to the built-in API routes (`/api/data`, `/api/auth`, etc.). Custom function routes get the **parsed user context** (e.g. `c.get("user")`), but you must enforce access control yourself.
:::

#### Service Key Authentication

Rebase supports a static `REBASE_SERVICE_KEY` defined in your `.env` for script or server-to-server calls. 

When an external request passes the service key via the Authorization header (`Authorization: Bearer <service_key>`), the auth middleware automatically:
1. Validates the key using constant-time comparison to prevent timing attacks.
2. Grants admin-level access, setting `c.get("user")` with:
   ```json
   {
     "uid": "service",
     "roles": ["admin"]
   }
   ```
3. Injects a `DataDriver` into `c.get("driver")` scoped as that same service identity. Row-Level Security still applies — it is evaluated as `{ uid: "service", roles: ["admin"] }`, not skipped.

#### Internal Self-Authentication

If you haven't configured a `REBASE_SERVICE_KEY`, Rebase generates a random **internal per-boot key**. The `rebase` singleton uses this key automatically when calling the server's own control-plane APIs (like `rebase.auth` or `rebase.storage`). This means your server-side logic can always perform administrative tasks even without a manually configured service key.

### Accessing the Database & Services

Custom functions run alongside Rebase, providing multiple ways to interact with your data depending on your security requirements:

#### 1. Via the User-Scoped Data Driver (Recommended for User Requests)

Rebase automatically injects the `driver` into the Hono request context (`c.get("driver")`). This driver is **scoped to the authenticated user** and automatically respects all PostgreSQL Row-Level Security (RLS) policies.

Using the driver ensures that users can only query or update records they are authorized to access under your database security policies:

```typescript
// backend/functions/my-products.ts

const app = new Hono<HonoEnv>();

app.get("/", async (c) => {
    const driver = c.get("driver")!; // Injected scoped driver
    const user = c.get("user");       // Authenticated user context

    if (!user) {
        return c.json({ error: "Unauthorized" }, 401);
    }

    // Queries respect Row-Level Security
    const myProducts = await driver.fetchCollection({
        path: "products",
        limit: 10
    });

    return c.json(myProducts);
});

export default app;
```

#### 2. Via the Rebase Singleton (Admin-Scoped Access)

The `@rebasepro/server` package provides a `rebase` singleton whose `dataAsAdmin` accessor runs as the service identity `{ uid: "service", roles: ["admin"] }`. Use this for background processing, system updates, integrations, or cases where a request needs to read or write to tables that the end-user has no direct permissions for:

```typescript
// backend/functions/approve-job.ts

const app = new Hono<HonoEnv>();

app.post("/:id/approve", async (c) => {
    const id = c.req.param("id");

    // Use the admin-level data API (RLS is evaluated as the `admin` role)
    await rebase.dataAsAdmin.collection<Record<string, unknown>>("jobs").update(id, {
        status: "published",
        approved_at: new Date().toISOString(),
    });

    return c.json({ success: true });
});

export default app;
```

#### RLS-Scoped Driver vs. Rebase Singleton

|                     | `c.get("driver")` (request-scoped)             | `rebase.dataAsAdmin` (service identity)                          |
| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
| **Runs as**         | The caller (`uid`, their roles)                | `{ uid: "service", roles: ["admin"] }`                            |
| **RLS enforcement** | ✅ Yes (evaluated against the caller)          | ✅ Yes (evaluated against the service identity)                   |
| **Performance**     | Native (direct driver call)                     | Native (direct driver call)                                       |
| **Ideal for...**    | General user CRUD, search, and queries          | Background jobs, system triggers, webhooks                        |
| **API style**       | Driver-level methods (`fetchCollection`, `saveEntity`) | Fluent collection accessors (`rebase.dataAsAdmin.jobs.find`) |

##### What `dataAsAdmin` is, precisely

`rebase.dataAsAdmin` is **admin-scoped, not RLS-bypassing**. The driver is scoped once, at boot, with `withAuth({ uid: "service", roles: ["admin"] })`, so every read and write runs inside a transaction that has switched to the restricted `rebase_user` role with `app.uid = 'service'`. Your policies are evaluated — against that identity.

For most projects the distinction never surfaces, because the default policies Rebase injects onto every collection admit `serverContext() OR rolesOverlap(['admin'])`, and the service identity clears the second arm. It surfaces the moment you write your own policies:

- **`policy.serverContext()` is false for it.** That helper compiles to `auth.uid() IS NULL`, and this accessor's `uid` is `'service'`. A collection with `disableDefaultPolicies: true` whose only write rule is `serverContext()` will refuse a `dataAsAdmin` write with Postgres error `42501`, and a read against such a collection returns **zero rows with HTTP 200** — the silent direction. Write `rolesOverlap(["admin"])` (or add it alongside) when you mean "my backend".
- **Its reach equals an `admin` user's reach.** Granting the `admin` role to an application user grants them exactly the rows this accessor sees. It is not a private channel.

If you genuinely need an unconditional bypass, `rebase.sql()` is it: raw SQL on the owner connection, no policies, every row. It is the most privileged thing in a function's context — more so than the accessor with "admin" in its name.

#### 3. Via Direct Drizzle Access

If you need raw SQL or complex custom queries, you can access your Drizzle database instance directly:

```typescript
// backend/functions/reports.ts

const app = new Hono<HonoEnv>();

app.get("/stats", async (c) => {
    const result = await db.execute(sql`
        SELECT COUNT(*) as total FROM jobs WHERE status = 'published'
    `);
    return c.json({ totalJobs: result.rows[0]?.total });
});

export default app;
```

:::tip
The Drizzle `db` instance used by Rebase is the same one you pass to `createPostgresBootstrapper`. You can share it freely between custom functions and Rebase.
:::

### Route Registration Order

Custom functions are loaded and mounted **after** `initializeRebaseBackend()` completes the core setup. The initialization order is:

1. **Bootstrappers** — Database connections, auth tables, realtime services
2. **Auth routes** — `/api/auth/*`, `/api/admin/*`
3. **Storage routes** — `/api/storage/*`
4. **Data routes** — `/api/data/*` (CRUD for collections)
5. **Custom functions** ← `/api/functions/*`
6. **Cron jobs** — `/api/cron/*`
7. **WebSocket** — Realtime subscriptions

This means your custom functions have access to all initialized services. Register any routes that need to run **before** Rebase on the Hono app directly, prior to calling `initializeRebaseBackend()`:

```typescript no-verify
const app = new Hono<HonoEnv>();

// This runs BEFORE Rebase routes
app.get("/health", (c) => c.json({ status: "ok" }));

// Rebase initialization — registers all /api/* routes
const instance = await initializeRebaseBackend({ app, /* ... */ });
```

### Example: Webhook Handler

```typescript
// backend/functions/stripe-webhook.ts

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const app = new Hono<HonoEnv>();

app.post("/", async (c) => {
    const sig = c.req.header("stripe-signature")!;
    const body = await c.req.text();

    const event = stripe.webhooks.constructEvent(
        body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET!
    );

    if (event.type === "checkout.session.completed") {
        const session = event.data.object;
        await instance.driver.data.subscriptions.create({
            user_id: session.client_reference_id,
            stripe_id: session.subscription,
            status: "active",
        });
    }

    return c.json({ received: true });
});

export default app;
```

### Debugging

When a function is loaded successfully, you'll see:

```
⚡ Loaded function route: hello
```

If loading fails, the loader provides diagnostic output:

```
[functions] broken-function.ts: default export is not a Hono app or factory. Skipping.
  export type: object (SomeClass)
  prototype methods: constructor, someMethod
  Hint: ensure the function exports a Hono app created with the same hono version as the server.
```

The router is mounted for the **directory**, not for the functions in it. If every file fails to import — one missing environment variable at module scope is enough to take all of them down — `GET /api/functions` still answers `200` with an empty list plus a `skipped` count, so "nothing loaded" is distinguishable from "this build shipped no functions". The reasons stay in the boot log.

### Timeouts and Rate Limits

Two ceilings apply to `/api/functions/*`:

- **Request timeout** — 30 seconds by default, answering `504` with code `FUNCTION_TIMEOUT`. Configure with `functionsTimeoutMs` (or `REBASE_FUNCTIONS_TIMEOUT_MS`); `0` disables it. The handler cannot be cancelled from the outside, so give outbound HTTP calls an `AbortSignal` — the timeout frees the client and the socket, not the work.
- **Rate limit** — API-key and signed-in callers share the data API's buckets. Anonymous callers get their own, much looser allowance (3000 per window) because this router is public by default for webhook receivers. Override with `rateLimit.anonymousFunctions`; `null` switches it off.

Unhandled promise rejections are logged rather than fatal: a fire-and-forget call in one function would otherwise end the whole process. Set `REBASE_EXIT_ON_UNHANDLED_REJECTION=1` for Node's default behaviour.

### Next Steps

- **[Backend Overview](/docs/backend)** — Full backend configuration reference
- **[Entity Callbacks](/docs/collections/callbacks)** — Run logic on data changes
- **[Cron Jobs](/docs/backend/cron-jobs)** — Scheduled background tasks

## Global Backend Hooks

### Overview

Rebase provides two levels of entity lifecycle callbacks — both use the same `CollectionCallbacks` type from `@rebasepro/types`:

- **[Per-collection callbacks](/docs/collections/callbacks)**: Defined on individual collection configurations. They run only for that collection.
- **Global callbacks**: Defined on `initializeRebaseBackend({ callbacks })`. They fire on **every** collection, on every data path (REST API, WebSocket / realtime, server-side `rebase.data`).

Use global callbacks for:
- **PII masking** — redact sensitive fields for non-admin callers across all collections.
- **Unified audit logging** — log every create, update, or delete in one place.
- **Cross-cutting validation** — enforce invariants that span multiple collections.

:::note
**Execution order**: global callbacks → collection callbacks → property callbacks.
:::

---

### Configuration

Pass the `callbacks` key to `initializeRebaseBackend`:

```typescript no-verify

const instance = await initializeRebaseBackend({
    // ... other config
    callbacks: {
        afterRead({ row, context }) {
            // Runs after every entity read, across all collections
            return row;
        },
        beforeSave({ values, context }) {
            // Runs before every entity save
            return values;
        }
    }
});
```

---

### `CollectionCallbacks` Type

```typescript
type CollectionCallbacks = {
    afterRead?(props):   Record<string, unknown>;  // Transform row before returning to caller
    beforeSave?(props):  Partial<Values>;           // Modify values before writing to DB
    afterSave?(props):   void;                      // Side-effects after successful save
    afterSaveError?(props): void;                   // Side-effects after a failed save
    beforeDelete?(props): boolean | void;           // Return false or throw to block deletion
    afterDelete?(props): void;                      // Side-effects after successful deletion
};
```

All callbacks may return a `Promise` (async) or a plain value (sync).

---

### Callback Props

Each callback receives a single props object. Common fields:

| Field | Type | Present in |
|-------|------|------------|
| `collection` | `ResolvedCollection` | All callbacks |
| `path` | `string` | All callbacks |
| `row` | `Record<string, unknown>` | `afterRead`, `beforeDelete`, `afterDelete` |
| `id` | `string` | `beforeSave` (optional), `afterSave`, `afterSaveError`, `beforeDelete`, `afterDelete` |
| `values` | `EntityValues` | `beforeSave`, `afterSave`, `afterSaveError` |
| `previousValues` | `EntityValues` (optional) | `beforeSave`, `afterSave`, `afterSaveError` |
| `status` | `"new" \| "existing"` | `beforeSave`, `afterSave`, `afterSaveError` |
| `context` | `RebaseCallContext` | All callbacks |

`context.user` contains the authenticated user (`uid`, `roles`, etc.), or is `undefined` for public requests.

---

### Execution Pipeline

```
[Client Request]
       │
       ▼
 [Hono Router]
       │
 ┌─────┴───────────────────────────────────────────────────────┐
 │ 1. Global Callback: beforeSave (Blocking)                   │
 │ 2. Collection Callback: beforeSave (Blocking)               │
 └─────┬───────────────────────────────────────────────────────┘
       │
 [Database Driver]
 ┌─────┴───────────────────────────────────────────────────────┐
 │ 3. Start PostgreSQL Transaction                             │
 │ 4. Set Config: app.user_id = '<uid>', app.user_roles = ...  │
 │ 5. Drizzle SQL execution & Postgres RLS evaluation          │
 │ 6. Commit Transaction                                       │
 └─────┬───────────────────────────────────────────────────────┘
       │
 ┌─────┴───────────────────────────────────────────────────────┐
 │ 7. Global Callback: afterSave                               │
 │ 8. Collection Callback: afterSave                           │
 └─────┬───────────────────────────────────────────────────────┘
       │
       ▼
[Client Response]
```

---

### Blocking vs. Async Semantics

- **`beforeSave`, `beforeDelete`** — blocking. If the callback throws, the operation is rejected with an HTTP 400 error response. The database write never happens.
- **`afterRead`** — blocking. The returned row (or transformed row) is what the caller receives.
- **`afterSave`, `afterDelete`, `afterSaveError`** — run after the transaction commits. They do not block the HTTP response.

---

### Examples

#### PII Masking

Redact email addresses for non-admin callers across every collection:

```typescript no-verify

const instance = await initializeRebaseBackend({
    // ... other config
    callbacks: {
        afterRead({ row, context }) {
            const isAdmin = context.user?.roles?.includes("admin");
            if (!isAdmin && row.email) {
                return { ...row, email: "********" };
            }
            return row;
        }
    }
});
```

#### Global Audit Logging

Log all deletions across every collection:

```typescript no-verify

const instance = await initializeRebaseBackend({
    // ... other config
    callbacks: {
        afterDelete({ collection, id, context }) {
            console.log(
                `[AUDIT] User ${context.user?.uid} deleted ${collection.slug}/${id}`
            );
        }
    }
});
```

#### Collection-Specific Logic

Global callbacks fire for all collections. To scope logic to a single collection, check `collection.slug` or `path`:

```typescript
callbacks: {
    beforeSave({ collection, values, context }) {
        if (collection.slug === "orders") {
            if (!values.total || values.total <= 0) {
                throw new Error("Order total must be positive");
            }
        }
        return values;
    }
}
```

For callbacks that only apply to a single collection, prefer [per-collection callbacks](/docs/collections/callbacks) instead.

## Entity History

### Overview

Entity history records a entity of entity values on every create, update, and delete. This gives you a full audit trail with diffs.

### Enabling History

#### Backend

Enable history in `initializeRebaseBackend`:

```typescript no-verify
await initializeRebaseBackend({
    // ...
    history: true
});
```

Or with custom retention settings:

```typescript
history: {
    maxEntries: 200,     // Per entity, oldest pruned first (default: 200)
    ttlDays: 90          // Entries older than this are pruned (default: 90)
}
```

#### Per Collection

Mark which collections should track history:

```typescript

const ordersCollection = defineCollection({
    slug: "orders",
    name: "Orders",
    table: "orders",
    history: true,       // Enable for this collection
    properties: { /* ... */ }
});
```

### How It Works

1. The backend creates a `rebase.entity_history` table automatically.
2. On every create, update, or delete, a entity is recorded with:
   - Entity ID, collection slug, and table name
   - The full entity values (before and after)
   - Timestamp and user ID
   - Operation type (`create`, `update`, `delete`)
   - An array of `changed_fields` showing which columns were modified

#### Diff Tracking & Structural Deep Equality

To avoid recording redundant logs where fields are saved but no values change, the `HistoryService` performs a structural deep equality comparison on the top-level keys of the old and new values:
- It ignores system metadata properties starting with `__`.
- If differences are found, the names of the modified properties are saved in the `changed_fields` (`text[]`) column.
- If the deep equality check detects zero changes, the history insertion is entirely skipped.

#### Non-Blocking Post-Save Pruning

Unlike traditional systems that rely entirely on slow periodic batch scripts, Rebase enforces your retention policies continuously:
- Right after a entity is saved or deleted, the server schedules an **inline asynchronous sweep** in a non-blocking, fire-and-forget promise.
- This sweep immediately checks retention limits for that specific entity ID and prunes older entries exceeding `maxEntries` or `ttlDays`.

### REST Endpoint

```
GET /api/data/:slug/:entityId/history
```

Returns a list of history entries for a specific entity, ordered by most recent first:

```json
{
    "data": [
        {
            "id": 42,
            "entity_id": "123",
            "collection_slug": "orders",
            "operation": "update",
            "values": { "status": "shipped", "total": 99.99 },
            "previous_values": { "status": "pending", "total": 99.99 },
            "user_id": "admin-user-id",
            "created_at": "2025-01-15T10:30:00Z"
        }
    ]
}
```

### Retention Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| `maxEntries` | 200 | Maximum entries retained per individual entity ID. Oldest entries are deleted. |
| `ttlDays` | 90 | Entries older than this duration (in days) are deleted. |

#### Pruning Lifecycle Mechanics

1. **Inline Pruning (Continuous)**: Executed asynchronously immediately after any CRUD operation. It prunes entries for the active entity using a sub-select query with an `OFFSET` equivalent to your `maxEntries` setting, deleting everything beyond that threshold.
2. **Global Pruning (Periodic)**: A background cleanup cron sweep (`pruneExpired`) runs every **6 hours** to evaluate global `ttlDays` thresholds and clean up orphaned logs across all collections.

### Next Steps

- **[Entity Callbacks](/docs/collections/callbacks)** — Lifecycle hooks
- **[Backend Overview](/docs/backend)** — Full backend configuration

## Database Branching

### Overview

Database branching allows you to create **instant, isolated copies** of your entire database (both schema and data) to safely perform development, migration tests, and QA procedures. 

By leveraging native PostgreSQL templates, Rebase provisions clone databases at the filesystem level. This means you get a full-fidelity replica containing all tables, indexes, custom types, constraints, and Row-Level Security (RLS) policies without any network transfer overhead or schema setup delays.

```
                  ┌────────────────────────┐
                  │ Production DB (rebase) │
                  └───────────┬────────────┘
                              │
               (CREATE DATABASE ... TEMPLATE)
                              │
            ┌─────────────────┴─────────────────┐
            ▼                                   ▼
┌───────────────────────┐           ┌───────────────────────┐
│ rb_feature_auth (Dev) │           │ rb_staging (Staging)  │
└───────────────────────┘           └───────────────────────┘
```

---

### Under the Hood: PostgreSQL Templating

When a database branch is created, the Rebase `BranchService` executes the following SQL:

```sql
CREATE DATABASE "rb_feature_auth" TEMPLATE "rebase";
```

PostgreSQL processes this operation by copying the underlying filesystem directories containing the source database files. This provides:
- **Sub-Second Clones**: No SQL generation or data loading is performed.
- **Identical Schemas and Data**: Every row, index, and constraint is duplicated instantly.
- **Complete Isolation**: Altering the schema or inserting records into the branch has no impact on the source database.

#### The Connection Limitation Guard

PostgreSQL requires that **no other active connections** exist on the template (source) database when running a `CREATE DATABASE ... TEMPLATE` command. 

To prevent failures, the Rebase `DatabasePoolManager` executes an active eviction process before cloning or dropping a branch:
1. **Eviction Loop**: It automatically closes and disconnects all idle pools pointing to the targeted database within the Rebase application context.
2. **External Connections Block**: If external clients (such as DBeaver, pgAdmin, or external backend processes) maintain active transactions on the source database, PostgreSQL will reject the template operation with a `"being accessed by other users"` error. In this scenario, those connections must be closed manually.

---

### Metadata Schema

Branch configurations are stored in the default database under the `rebase.branches` table, which is provisioned during bootstrapping:

```sql
CREATE SCHEMA IF NOT EXISTS rebase;

CREATE TABLE IF NOT EXISTS rebase.branches (
    name         TEXT PRIMARY KEY,              -- Sanitize user branch name (alphanumeric & underscores)
    db_name      TEXT NOT NULL UNIQUE,          -- Actual PostgreSQL database name (prefixed with 'rb_')
    parent_db    TEXT NOT NULL,                 -- Source database cloned from
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    metadata     JSONB DEFAULT '{}'
);
```

---

### Programmatic API

The branching API is exposed via the backend's `BranchService`. Below is a reference of the core interface:

#### Create a Database Branch

Generates a new branch database from the default database or an explicit source template.

```typescript no-verify

const backend = await initializeRebaseBackend({ /* ... */ });
const admin = backend.driver.admin;

// Create a branch from the default database
const newBranch = await admin.createBranch("feature_oauth");

// Create a branch from a specific staging database
const stagingBranch = await admin.createBranch("pr_review_42", { 
    source: "rb_staging" 
});
```

#### List Active Branches

Retrieves list of registered branches along with their physical sizes queried via the PostgreSQL `pg_database_size` system function.

```typescript
const branches = await admin.listBranches();
/*
Output:
[
  {
    name: "feature_oauth",
    parentDatabase: "rebase",
    createdAt: 2026-06-20T22:00:00.000Z,
    sizeBytes: 83886080 // 80 MB
  }
]
*/
```

#### Get Branch Information

Fetches metadata for a single branch. If the branch exists, the service attempts to query its current physical disk usage:

```typescript
const info = await admin.getBranchInfo("feature_oauth");
```

#### Delete a Branch

Drops the target database from the server and cleans up its record in the `rebase.branches` metadata table.

```typescript
await admin.deleteBranch("feature_oauth");
```

> [!CAUTION]
> Safety Guard: The main database (default database name configured in connection strings) is protected. If you attempt to delete the parent database, the `BranchService` throws a `"Cannot delete the main database"` error and aborts.

---

### CLI Integration

Database branches can be managed directly using the Rebase CLI.

```bash
# Create a new branch named 'dev_sandbox'
rebase db branch create dev_sandbox

# List all branches and disk utilization
rebase db branch list

# Delete a branch
rebase db branch delete dev_sandbox
```

When you create or switch to a branch, the CLI updates your local development configuration. The `DatabasePoolManager` dynamically instantiates a new connection pool for the chosen branch database name (e.g. `rb_dev_sandbox`), letting you test migrations or seed data without manual connection string edits.

---

### Best Practices and Limitations

#### Disk Usage
Because PostgreSQL duplicates the files on disk, each branch consumes space equal to the source database. If you have a 100GB production database, creating 5 branches will consume an additional 500GB of storage. 
* *Recommendation*: Use subsetted databases or thin dev-templates as your clone sources instead of full production clones.

#### pgBouncer Compatibility
When deploying behind pgBouncer or connection poolers, ensure the pooler supports administrative database operations. Creating and dropping databases bypasses standard transaction-level pools and requires direct connections to the Postgres server (using elevated user privileges) via the `adminConnectionString` configuration.

#### Cross-Database Queries
Because branches are separate PostgreSQL databases, you cannot perform SQL `JOIN` statements across branch boundaries. All relations must be contained within the scope of the single active branch database.


## Custom Server Integration

## Custom Server Integration

Rebase was built to be completely modular. While the `initializeRebaseBackend` coordinator provides a full batteries-included backend using Hono, you can completely bypass it and embed the core **Database Adapter** and **Realtime WebSockets** directly into your own custom Node.js application (like Express, Fastify, or plain Node.js HTTP).

The `@rebasepro/server-postgres` package is completely framework-agnostic. It depends only on Drizzle ORM and standard Node.js `http.Server`.

### Environment Configuration

Rebase provides a centralized `loadEnv()` utility in `@rebasepro/server` that validates your environment variables against a strict Zod schema. Call it **after** loading your `.env` file:

```typescript

dotenv.config({ path: "../../.env" });

// Basic — just Rebase env vars:
export const env = loadEnv();

// Extended — add your own typed vars:

export const env = loadEnv({
    extend: z.object({
        SMTP_HOST: z.string().optional(),
        SMTP_PORT: z.string().default("587").transform(Number),
        STRIPE_SECRET_KEY: z.string(),
    })
});
// env.SMTP_HOST  → string | undefined  (fully typed)
// env.STRIPE_SECRET_KEY → string        (validated, required)
```

**Key behaviors:**
- Auto-generates ephemeral `JWT_SECRET` and `REBASE_SERVICE_KEY` in development so you can start without manual setup.
- Blocks auto-generated secrets in production — you must set them explicitly.
- Validates that `CORS_ORIGINS` or `FRONTEND_URL` is set in production.

See `.env.example` in the scaffolded app for the full list of supported variables.

### Using Rebase with Express

Here is a complete example of how to initialize the Rebase PostgreSQL adapter and Realtime WebSockets inside a standard Express application, manage read replicas, access Drizzle directly, and implement clean server terminations.

#### 1. Installation

Install the required core packages along with Express:

```bash
npm install @rebasepro/server-postgres @rebasepro/types express pg
```

#### 2. Initialization and Graceful Shutdown Example

```typescript

async function startServer() {
    const app = express();
    
    // 1. WebSocket Upgrade Guard
    // WebSockets require hijacking the HTTP Upgrade header. You must bind
    // Rebase to a raw Node.js http.Server instance.
    const server = createServer(app);

    // 2. Configure the connection pool
    const pool = new pg.Pool({
        connectionString: process.env.DATABASE_URL,
        max: 20, // Max concurrent database connections
        idleTimeoutMillis: 30000
    });

    // 3. Initialize the Postgres Bootstrapper
    const bootstrapper = createPostgresBootstrapper({
        connection: pool,
        connectionString: process.env.DATABASE_URL,
        adminConnectionString: process.env.ADMIN_CONNECTION_STRING, // Required for branching
        schema: {
            tables: {},   // Place your custom Drizzle tables here
            relations: {} // Place your custom Drizzle relations here
        }
    });

    // 4. Initialize the Driver and Services
    // Connects to Postgres, verifies connection, starts cross-instance listeners
    const { driver, realtimeProvider, internals } = await bootstrapper.initializeDriver({
        collections: [] // Pass Rebase CollectionConfigs if using schema-as-code
    });

    // Access the underlying schema-aware Drizzle client if needed.
    // `internals` is an *opaque handle* on the DatabaseAdapter contract — the shape is
    // the driver's business, so narrow it to what the Postgres bootstrapper puts there.
    // (named `driverInternals` rather than `pg`, which is the node-postgres import)
    const driverInternals = internals as {
        db: any;                                    // Drizzle NodePgDatabase
        readDb?: any;                               // Read replica, when DATABASE_READ_URL is set
        poolManager?: { destroy(): Promise<void> };
    };
    const db = driverInternals.db;
    const readDb = driverInternals.readDb;

    // 5. Mount Realtime WebSockets
    await bootstrapper.initializeWebsockets(server, realtimeProvider, driver, {
        requireAuth: true // Enforces authentication token checks
    });

    app.use(express.json());

    app.get("/api/health", (req, res) => {
        res.json({ status: "healthy" });
    });

    // Direct Driver CRUD Operation
    app.post("/api/products", async (req, res) => {
        try {
            const result = await driver.save({
                path: "products",
                values: req.body,
                status: "new"   // required: "new" | "existing" | "copy"
            });
            res.status(201).json({ success: true, data: result });
        } catch (error) {
            res.status(500).json({ error: error instanceof Error ? error.message : "Internal Server Error" });
        }
    });

    // Raw Drizzle SQL Execution (RLS bypass)
    app.get("/api/stats", async (req, res) => {
        try {
            const countResult = await db.select().from(...); // Perform standard Drizzle operations
            res.json(countResult);
        } catch (error) {
            res.status(500).json({ error: error instanceof Error ? error.message : "Internal Server Error" });
        }
    });

    // Start listening (Using the HTTP Server, NOT app.listen)
    const port = process.env.PORT || 3000;
    server.listen(port, () => {
        console.log(`🚀 Server and WebSocket engine running on port ${port}`);
    });

    // 6. Graceful Shutdown Handler
    // Terminate listeners and drain connection pools on process termination signals
    const handleShutdown = async (signal: string) => {
        console.log(`\nShutdown triggered via ${signal}. Cleaning up resources...`);
        
        server.close(async () => {
            console.log("✔ HTTP Server closed.");
            try {
                // Terminate cross-instance pg LISTEN/NOTIFY client
                if (realtimeProvider && typeof realtimeProvider.stopListening === "function") {
                    await realtimeProvider.stopListening();
                    console.log("✔ Realtime listeners stopped.");
                }

                // Disconnect dynamic branch connection pools
                if (driverInternals.poolManager) {
                    await driverInternals.poolManager.destroy();
                    console.log("✔ Branch connection pools evicted.");
                }

                // End the main database pool
                await pool.end();
                console.log("✔ Database connection pool drained.");

                process.exit(0);
            } catch (err) {
                console.error("❌ Error during graceful shutdown:", err);
                process.exit(1);
            }
        });
    };

    process.on("SIGTERM", () => handleShutdown("SIGTERM"));
    process.on("SIGINT", () => handleShutdown("SIGINT"));
}

startServer();
```

> **Standard path:** if your server uses `initializeRebaseBackend` (like the scaffolded template does), don't hand-roll the shutdown handler above — use the built-in helper instead. It drains HTTP, stops the cron scheduler, tears down realtime services, guards against repeated signals, and force-exits if shutdown hangs:
>
> ```ts
> import { installShutdownHandlers } from "@rebasepro/server";
>
> const backend = await initializeRebaseBackend({ ... });
> installShutdownHandlers(backend, { onCleanup: () => pool.end() });
> ```
>
> Do **not** combine it with your own `server.close()` — `backend.shutdown()` already closes the server, and a second close deadlocks. The manual handler shown in the example above is only for fully custom setups that bypass `initializeRebaseBackend`.

---

### Key Backend Concepts

#### Read Replica Connections
If you define the `DATABASE_READ_URL` environment variable, Rebase automatically spawns a secondary connection pool targeting your read replica. The bootstrapper registers this under `internals.readDb`. The core `EntityFetchService` routes all SELECT queries to the replica pool to optimize performance, while mutation queries remain on the primary pool.

#### Drizzle Integration
You do not have to choose between Rebase and Drizzle. The bootstrapper compiles your schemas dynamically. You can access the compiled Drizzle NodePgDatabase client via `internals.db`, allowing you to run raw SQL migrations or invoke type-safe Drizzle builders alongside Rebase's REST services.

#### Graceful Connection Draining
In serverless environments or orchestrators (like Kubernetes), terminating pods can result in broken connections. Always implement signal handlers that invoke `realtimeProvider.stopListening()` (which terminates the dedicated pg LISTEN client) and `pool.end()` to prevent leaking connection slots in your database server.


## Frontend Overview

### Overview

The Rebase frontend is a **React framework** that renders your admin panel. It reads your collection definitions and generates tables, forms, navigation, and routing automatically.

In the default scaffold, the admin panel **is** the frontend: it's served at the root of your deployed URL. If you build your own product app instead, you can mount the admin under a prefix like `/admin` in the same deployment — see [Changing the Base URL](/docs/getting-started/deployment#changing-the-base-url).

The key components that make up a Rebase frontend:

```tsx
<Rebase
    client={rebaseClient}
    authController={authController}
>
    {({ loading }) => (
        <Scaffold>
            <AppBar />
            <Drawer title="My App" />
            <Outlet />
            <SideDialogs />
        </Scaffold>
    )}
</Rebase>
```

### The Rebase Provider

`<Rebase>` is the root provider that makes all Rebase functionality available to child components via context. It accepts:

| Prop | Description |
|------|-------------|
| `client` | `RebaseClient` instance for data, auth, and storage |
| `authController` | Authentication state and methods |
| `dataSources` | Additional data sources (see [Multiple sources](/docs/backend/multiple-sources)) |
| `storageSource` / `storageSources` | File storage operations, and named storage sources |
| `userConfigPersistence` | Local UI preferences (column widths, etc.) |
| `entityViews` | Global custom entity view tabs |
| `entityActions` | Global entity actions |
| `plugins` | Plugin instances |
| `slots` | Slot contributions declared directly, without a plugin |
| `basePath` / `baseCollectionPath` | URL prefixes when the admin is not at the site root |
| `components` | Component overrides |

The navigation, URL and collection-registry controllers are **not** `<Rebase>`
props — they are built by the hooks below and consumed inside the admin tree
(`<RebaseShell>` wires them for you in the default scaffold).

### Two data shapes

There are two data layers, and they are **not** interchangeable. Passing one
where the other is expected is a type error, so this is worth knowing before you
wire a controller by hand.

| | Shape | Where you get it | What a row looks like |
|---|---|---|---|
| **SDK** | `RebaseSdkData` — flat rows | `client.data`, and `context.data` in backend callbacks | `row.title` |
| **Admin** | `RebaseData` — `Entity` view-model | `useData()`, inside the `<Rebase>` tree | `entity.values.title` |

The SDK layer is the public, symmetric surface: identical on the frontend client
and in backend callbacks. The `Entity` layer is the admin's view-model — it adds
the `id` / `path` / `values` wrapper that the collection views and forms render
against. `CollectionAccessor` and `FindResponse` belong to it and are marked
`@internal` for that reason.

`<Rebase>` is the boundary between them: it takes your flat `client.data` and
wraps it with `wrapAsEntityData()` before providing it as the admin's
`RebaseData`. You never call that yourself — you just take the shape you need
from the right place:

```tsx
// Flat rows — anywhere, including outside React.
const { data: posts } = await client.data.posts.find();
posts[0].title;

// Entity view-model — inside the <Rebase> tree only.
// `data.posts` also works at runtime; `collection()` is the typed accessor.
const data = useData();
const { data: entities } = await data.collection("posts").find();
entities[0].values.title;
```

### Controllers

Controllers are React hooks that configure specific aspects of the framework:

#### `useBuildNavigationStateController`

The main controller that wires everything together:

Its `data` is the **Entity-shaped** `RebaseData`, so it comes from `useData()`
— not from `rebaseClient.data`, which is the flat-row SDK layer. `<Rebase>`
converts one to the other for you (see [Two data shapes](#two-data-shapes)
below), so this hook must be called inside the `<Rebase>` tree.

```typescript
const data = useData();

const navigationStateController = useBuildNavigationStateController({
    collections: () => [...collections],  // Collection definitions
    views: customViews,                   // Custom navigation views
    plugins,                              // Plugin instances
    authController,
    data,
    collectionRegistryController,
    urlController,
    adminMode: adminModeController.mode
});
```

#### `useBuildCollectionRegistryController`

Manages how collections are resolved from URL paths:

```typescript
const collectionRegistryController = useBuildCollectionRegistryController({
    userConfigPersistence
});
```

#### `useBuildUrlController`

Configures URL generation:

```typescript
const urlController = useBuildUrlController({
    basePath: "/",
    baseCollectionPath: "/c",
    collectionRegistryController
});
```

#### `useBuildModeController`

Manages light/dark theme:

```typescript
const modeController = useBuildModeController();
// Provides: modeController.mode ("light" | "dark"), modeController.toggleMode()
```

#### `useBuildAdminModeController`

Toggles between Studio and Content modes:

```typescript
const adminModeController = useBuildAdminModeController();
// Provides: adminModeController.mode ("studio" | "content")
```

### Scaffold Components

| Component | Description |
|-----------|-------------|
| `<Scaffold>` | Main layout container with responsive sidebar |
| `<AppBar>` | Top navigation bar with search, mode toggle, user menu |
| `<Drawer>` | Side navigation with collection list and view links |
| `<SideDialogs>` | Container for side panel entity editors |
| `<RebaseRoutes>` | Route container that integrates with React Router |
| `<RebaseRoute>` | Handles collection routes (`/c/*`) |
| `<ContentHomePage>` | Default home page showing collection cards |
| `<StudioHomePage>` | Studio mode home page with developer tools |

### Custom Views

Add top-level navigation views for dashboards, tools, or custom pages:

```tsx
const views: AppView[] = [
    {
        slug: "dashboard",
        name: "Dashboard",
        view: <MyDashboard />
    },
    {
        slug: "settings",
        name: "App Settings",
        view: <AppSettings />,
        nestedRoutes: true  // Support sub-paths,
        admin: {
            icon: "dashboard",
            group: "Analytics",
            icon: "settings"
        }
    }
];

```

### Styling

Rebase uses **Tailwind CSS v4** and supports light/dark modes. Customize via:

- **CSS custom properties** — Override design tokens
- **`ModeControllerProvider`** — Control light/dark mode
- **Tailwind config** — Standard Tailwind customization

```css
/* Override design tokens */
:root {
    --font-sans: "Instrument Sans", sans-serif;
    --font-headers: "Instrument Sans", sans-serif;
    --font-mono: "JetBrains Mono", monospace;
}
```

### Next Steps

- **[Custom Fields](/docs/frontend/custom-fields)** — Build custom form fields
- **[Entity Views](/docs/frontend/entity-views)** — Add tabs to entity editors
- **[View Modes](/docs/frontend/view-modes)** — List, Table, Cards, Kanban
- **[Plugins](/docs/plugins)** — Extend the framework

## Extending Rebase

### Overview

Rebase offers roughly a dozen extension mechanisms — plugins, slots, component overrides, entity views, actions, custom fields, and more. Each one targets a different scope (app-wide, per-collection, per-entity, per-property) and a different part of the UI.

This guide helps you pick the right mechanism for your use case, then links to the detailed reference for each.

### Decision Table

| I want to… | Mechanism | Scope | Reference |
|---|---|---|---|
| Replace the app bar | `components` (`Shell.AppBar`) | app | [Component Overrides](/docs/frontend/component-overrides) |
| Replace the login page | `components` (`Auth.LoginView`) | app | [Component Overrides](/docs/frontend/component-overrides) |
| Replace the home page | `components` (`HomePage`) | app | [Component Overrides](/docs/frontend/component-overrides) |
| Change how one collection's form looks entirely | `formView` | collection | [below](#formview) |
| Swap one component inside one collection | `collection.components` | collection | [Component Overrides](/docs/frontend/component-overrides) |
| Set default component overrides for all collections | `components` (collection-scoped names) | app | [Component Overrides](/docs/frontend/component-overrides) |
| Add a button to the collection toolbar | collection `Actions` | collection | [Entity Actions](/docs/frontend/entity-actions#collection-actions) |
| Inject UI at a collection toolbar slot | `collection.actions` slot | app/plugin | [Slots](/docs/frontend/slots) |
| Add a computed column to a table | `additionalFields` | collection | [Additional Columns](/docs/frontend/additional-columns) |
| Add a custom field widget for a property type | `propertyConfigs` | property type | [Custom Fields](/docs/frontend/custom-fields) |
| Add a entity tab | `entityViews` | entity | [Entity Views](/docs/frontend/entity-views) |
| Add a row/context action or entity button | `entityActions` | entity | [Entity Actions](/docs/frontend/entity-actions) |
| Inject UI at a specific chrome location | `slots` | app/plugin | [Slots](/docs/frontend/slots) |
| Ship several extensions as one installable unit | `plugins` | app | [Plugins](/docs/plugins) |

### Mechanisms in Detail

#### Plugins

**Scope:** app.

A plugin bundles collections, views, component overrides, slot contributions, auth, data sources, providers, hooks, and lifecycle callbacks into a single installable unit. All other mechanisms listed here can be contributed through a plugin's interface.

→ [Plugins reference](/docs/plugins)

#### Slots

**Scope:** app (contributed per-slot).

Slots are named UI extension points scattered throughout the CMS chrome. You register a React component targeting a slot name, and it renders at that location. There are 29 slots covering the home page, navigation, collection views, forms, entity rows, dashboards, and more.

→ [Slots reference](/docs/frontend/slots)

#### Component Overrides (Swizzling)

**Scope:** app-level defaults or per-collection.

Two modes: **Eject** (full replacement) or **Wrap** (augment the original).

19 overridable component names in two tiers:

**App-only (7):**
- `Shell.AppBar`
- `Shell.Drawer`
- `Shell.DrawerNavigationItem`
- `Shell.DrawerNavigationGroup`
- `HomePage`
- `HomePage.CollectionCard`
- `Auth.LoginView`

**Collection-scoped (12):**
- `Collection.View`
- `Collection.Table`
- `Collection.Card`
- `Collection.EmptyState`
- `Collection.Actions`
- `Collection.FilterField`
- `Entity.Form`
- `EditView.FormActions`
- `DetailView`
- `Entity.SidePanel`
- `EntityPreview`
- `Entity.MissingReference`

**Precedence:** Collection-level `components` override app-level defaults for the same component name (simple object spread — collection values overwrite global values). App-only component names (`Shell.*`, `HomePage`, `Auth.*`) can only be overridden at the `<Rebase>` level.

→ [Component Overrides](/docs/frontend/component-overrides)

#### Entity Views

**Scope:** entity (adds tabs).

Custom views that appear as tabs in the entity detail page. Can be defined globally on `<Rebase>` or per-collection.

→ [Entity Views](/docs/frontend/entity-views)

#### Entity Actions

**Scope:** entity.

Custom action buttons on individual entities (publish, archive, clone, etc.). Can be defined globally or per-collection.

→ [Entity Actions](/docs/frontend/entity-actions)

#### Collection `Actions`

**Scope:** collection.

Toolbar-level React components that receive `CollectionActionsProps` (selected entities, table controller, collection context). Rendered in the collection toolbar alongside built-in actions.

**Relationship with `collection.actions` slot:** Both are additive — `Actions` components render first in the toolbar, then slot contributions from `collection.actions`. They do not replace each other.

→ [Entity Actions — Collection Actions](/docs/frontend/entity-actions#collection-actions)

#### `formView` {#formview}

**Scope:** collection.

Replaces the entire default entity form with a custom component. Set on a collection definition:

```typescript
const collection = {
    slug: "products",
    admin: {
        formView: {
            Builder: MyCustomProductForm,
            includeActions: true  // show save/delete bar (default: true)
        }
    }
};

```

Use when you need a completely custom layout for one collection's entity editing experience. For smaller tweaks, prefer `collection.components` with `Entity.Form` override instead.

#### `additionalFields`

**Scope:** collection.

Computed/virtual columns displayed in the collection table. These don't correspond to stored properties — they're calculated at render time.

→ [Additional Columns](/docs/frontend/additional-columns)

#### `propertyConfigs`

**Scope:** property type.

Custom field widgets for specific property types, providing custom form fields and preview components.

→ [Custom Fields](/docs/frontend/custom-fields)

### Precedence Summary

- **`collection.components` beats global `components`** inside that collection (simple spread merge in `DataCollectionView`).
- **Collection `Actions` and `collection.actions` slot are additive** — `Actions` render first, then slot contributions.
- **Collection-level `entityActions` and `entityViews` extend (not replace) global ones.**
- **Plugin contributions are merged in `key` order.**

## Component Overrides (Swizzling)

### Overview

Rebase allows you to override default UI components with your own custom implementations. This implements a Docusaurus-style component swizzling model that supports two customization patterns:
- **Eject mode** (default): Your component fully replaces the built-in one.
- **Wrap mode** (`wrap: true`): Your component wraps the original. The built-in component is passed as the `OriginalComponent` prop so you can render it inside your custom layout/logic.

Component overrides can be applied **globally** at the application level (on the `<Rebase>` provider) or **locally** at the collection level (inside individual collection definitions).

---

### Global Component Overrides

To override components globally across your entire application, pass a `components` object to the root `<Rebase>` provider.

```tsx

function App() {
    return (
        <Rebase
            client={rebaseClient}
            components={{
                // Eject Mode: Replace the default AppBar entirely
                "Shell.AppBar": { Component: MyAppBar },

                // Wrap Mode: Wrap the login view to insert branding
                "Auth.LoginView": {
                    // `OriginalComponent` is injected at runtime when `wrap: true`; the override
                    // slot's type does not model it, hence the annotation.
                    Component: (({ OriginalComponent, ...props }: {
                        OriginalComponent: React.ComponentType<Record<string, unknown>>
                    }) => (
                        <div className="login-branding-container">
                            <header className="branding-header">My Custom Brand</header>
                            <OriginalComponent {...props} />
                        </div>
                    )) as unknown as React.ComponentType<Record<string, unknown>>,
                    wrap: true
                }
            }}
        >
            {/* your app */}
            …
        </Rebase>
    );
}
```

---

### Collection-Level Component Overrides

To override components only for a specific collection, add a `components` object to its definition. This is useful for customizing empty states, cards, or detail views for particular models.

```tsx

const productsCollection = defineCollection({
    name: "Products",
    slug: "products",
    table: "products",
    properties: { /* ... */ },
    admin: {
        components: {
            // Eject Mode: Replace the default entity form view
            "Entity.Form": { Component: ProductCustomForm },

            // Wrap Mode: Wrap the empty state to add quick links
            "Collection.EmptyState": {
                // `OriginalComponent` is injected at runtime when `wrap: true`; the override
                    // slot's type does not model it, hence the annotation.
                    Component: (({ OriginalComponent, ...props }: {
                        OriginalComponent: React.ComponentType<Record<string, unknown>>
                    }) => (
                    <div className="empty-state-wrapper">
                        <OriginalComponent {...props} />
                        <button onClick={() => importDemoProducts()}>
                            Load Demo Products
                        </button>
                    </div>
                )) as unknown as React.ComponentType<Record<string, unknown>>,
                wrap: true
            }
        }
    }
});

```

---

### Overridable Components Scopes

#### App-Scoped Components (`AppComponentName`)

These components can only be overridden at the root `<Rebase>` provider level since they represent shell-level structure.

| Component Key | Description |
|---|---|
| `"Shell.AppBar"` | The header bar at the top of the page |
| `"Shell.Drawer"` | The collapsible main sidebar navigation drawer |
| `"Shell.DrawerNavigationItem"` | Individual links inside the sidebar |
| `"Shell.DrawerNavigationGroup"` | Collapsible navigation group headers in the sidebar |
| `"HomePage"` | The default content-mode home landing page |
| `"HomePage.CollectionCard"` | Individual collection cards on the home page |
| `"Auth.LoginView"` | The overlay shown when requesting authentication |

#### Collection-Scoped Components (`CollectionComponentName`)

These components can be overridden globally (acting as defaults for all collections) or on individual collections.

| Component Key | Original Props | Description |
|---|---|---|
| `"Collection.View"` | `CollectionViewProps` | The entire collection landing page |
| `"Collection.Table"` | `CollectionTableProps` | The default spreadsheet tabular view |
| `"Collection.Card"` | `CollectionCardProps` | The card view item wrapper |
| `"Collection.EmptyState"` | `CollectionEmptyStateProps` | View shown when a collection is empty |
| `"Collection.Actions"` | `CollectionActionsProps` | Toolbar buttons above the table/cards |
| `"Collection.FilterField"` | `FilterFieldBindingProps` | Custom filter input for a column |
| `"Entity.Form"` | `EntityFormProps` | The detail form for creating/updating |
| `"EditView.FormActions"` | `EntityFormActionsProps` | Form submission/cancel button bar |
| `"DetailView"` | `EntityDetailViewProps` | Read-only detail view |
| `"Entity.SidePanel"` | `EntitySidePanelProps` | The side panel container for form/detail |
| `"EntityPreview"` | `EntityPreviewProps` | Inline reference/relation chip preview |
| `"Entity.MissingReference"` | `MissingReferenceProps` | Rendered when a referenced entity is missing |

## Authentication & Login

### Overview

Rebase provides ready-to-use React components and hooks for authentication:

- **`useRebaseAuthController`** — Manages auth state, tokens, and session persistence
- **`LoginView`** — Pre-built login/signup form with OAuth support
- **Role simulation** — Test different roles without logging out

### Auth Controller

The `useRebaseAuthController` hook is the core of frontend authentication. It manages the current user, tokens, and session:

```typescript

const client = createRebaseClient({ baseUrl: API_URL, websocketUrl: WS_URL });

const authController = useRebaseAuthController({
    client,
    googleClientId: GOOGLE_CLIENT_ID  // Optional — enables Google OAuth
});

// Available properties:
authController.user           // Current user object (or null)
authController.initialLoading // True while checking stored session
authController.signOut()      // Log out
authController.getAuthToken() // Get current JWT for API calls
```

Pass the `authController` to the Rebase navigation controller to gate the entire admin panel behind authentication.

### Login View

The `LoginView` component provides a complete login and registration form:

```tsx

function App() {
    if (!authController.user) {
        return (
            <LoginView
                authController={authController}
                googleClientId={GOOGLE_CLIENT_ID}
            />
        );
    }
    return <MyApp />;
}
```

The login view handles:
- Email/password login and registration
- Google OAuth sign-in (when configured)
- Password reset flow
- Form validation and error states

### Roles Model

Roles are stored as a `text[]` array column directly on the `rebase.users` table. You define available roles as an enum in your users collection definition:

```typescript title="config/collections/users.ts" no-verify
roles: {
    name: "Roles",
    type: "array",
    columnType: "text[]",
    of: {
        name: "Role",
        type: "string",
        enum: {
            admin: "Admin",
            editor: "Editor",
            viewer: "Viewer"
        }
    },
    admin: {
        readOnly: false
    }
}
```

To add or remove role options, update the `enum` map in your users collection and regenerate the schema.

### Role Simulation (Dev Mode)

In developer mode, you can simulate different roles without logging out. This is useful for testing RLS policies:

```typescript

const effectiveRoleController = useBuildEffectiveRoleController();

// When active, the UI behaves as if the current user has this role
effectiveRoleController.setEffectiveRole("editor");
```

### Next Steps

- **[Backend Authentication](/docs/backend/authentication)** — JWT, OAuth providers, SMTP configuration
- **[Security Rules (RLS)](/docs/collections/security-rules)** — Row-level access control per collection
- **[Client SDK Authentication](/docs/sdk/authentication)** — Programmatic auth methods

## Storage & File Uploads

### Overview

Rebase provides built-in file upload support in collection forms:

- **Drag-and-drop** file upload fields
- **Image previews** in forms and table cells
- **Multiple file uploads** via array properties
- **MIME type filtering** and size limits
- **Custom filenames** via callback functions

### File Upload Fields

To add file uploads to a collection, use the `storage` config on a string property:

```typescript
properties: {
    image: {
        type: "string",
        name: "Product Image",
        storage: {
            storagePath: "products",       // Subdirectory in storage
            acceptedFiles: ["image/*"],    // MIME type filter
            maxSize: 5 * 1024 * 1024,      // 5MB max
            fileName: (context) => {        // Custom filename
                return context.entityId + "_" + context.file.name;
            }
        }
    }
}
```

#### Storage Config Options

| Property | Type | Description |
|----------|------|-------------|
| `storagePath` | `string` | Subdirectory within the storage backend |
| `storageSource` | `string` | Named storage source — routes uploads to a specific backend (e.g., `"firebase"`, `"media"`). See [Multi-Backend Storage](#multi-backend-storage). |
| `public` | `boolean` | Store files under the `public/` prefix and serve them via stable, token-less, permanent, CDN-cacheable URLs (safe to persist and hotlink). Defaults to `false` (private files use short-lived signed URLs). |
| `acceptedFiles` | `string[]` | Allowed MIME types (e.g., `["image/*"]`, `["application/pdf"]`) |
| `maxSize` | `number` | Maximum file size in bytes |
| `fileName` | `function` | Custom filename generator |
| `metadata` | `object` | Additional metadata to store with the file |
| `storeUrl` | `boolean` | Store the full URL instead of the relative path |

### Multiple File Uploads

Wrap the storage property in an array for multiple file uploads:

```typescript
photos: {
    type: "array",
    name: "Photos",
    of: {
        type: "string",
        storage: {
            storagePath: "photos",
            acceptedFiles: ["image/*"]
        }
    }
}
```

### Document Uploads

Upload non-image files like PDFs:

```typescript
documents: {
    type: "array",
    name: "Documents",
    of: {
        type: "string",
        storage: {
            storagePath: "documents",
            acceptedFiles: ["application/pdf", "image/*"]
        }
    }
}
```

### Multi-Backend Storage

When your backend has multiple storage backends configured (e.g., local + S3 + GCS), you can route individual properties to specific backends using `storageSource`:

```typescript
image: {
    type: "string",
    name: "Product Image",
    storage: {
        storageSource: "firebase",     // Routes to the "firebase" backend
        storagePath: "products/{entityId}",
        acceptedFiles: ["image/*"],
    }
}
```

#### Frontend Direct Sources

For **direct** storage backends (e.g., Firebase Storage where the browser uploads straight to the cloud), register them via the `storageSources` prop on `<Rebase>`:

```tsx

<Rebase
    client={rebaseClient}
    storageSources={[
        { key: "firebase", engine: "firebase", transport: "direct", source: firebaseStorageSource }
    ]}
>
    {/* your app */}
    …
</Rebase>
```

| Property | Type | Description |
|----------|------|-------------|
| `key` | `string` | Unique identifier — must match `storageSource` in property configs |
| `engine` | `string` | Storage engine name (e.g., `"firebase"`, `"gcs"`, `"s3"`) |
| `transport` | `"server" \| "direct"` | `"server"` proxies through the backend; `"direct"` uploads from the browser |
| `source` | `StorageSource` | Client-side `StorageSource` implementation (required for `"direct"` transport) |

The system automatically resolves the correct source per-property — collection properties with `storageSource: "firebase"` will use the matching direct source, while properties without `storageSource` (or with `transport: "server"`) will proxy through the Rebase backend.

### useStorageSource Hook

For programmatic file operations outside of collection forms:

```typescript

// Returns the default storage source
const storageSource = useStorageSource();

// Upload a file — the object is addressed by `key`
const result = await storageSource.putObject({
    file,
    key: "documents/my-file.pdf"
});

// Get a download URL
const { url } = await storageSource.getSignedUrl(result.key);
```

:::tip
`useStorageSource()` returns the **default** storage source. For multi-backend setups, the per-property resolution is handled automatically by the form field bindings and the `StorageSourcesContext`. You don't need to manually resolve sources in most cases.
:::

### Next Steps

- **[Backend Storage Configuration](/docs/backend/storage)** — S3, GCS, and local storage setup
- **[Properties](/docs/collections/properties)** — All property types including storage

## View Modes

### Overview

Every collection can be displayed in four view modes:

- **List** — Simple, clean list view (the classic CMS default)
- **Table** — Spreadsheet-style grid with inline editing, sorting, filtering
- **Cards** — Card grid for visual content (images, previews)
- **Kanban** — Drag-and-drop board grouped by an enum property

### Configuration

```typescript

const productsCollection = defineCollection({
    slug: "products",
    // `orderProperty` and `kanban.columnProperty` are checked against these
    // keys — with an empty `properties` block they narrow to `never`.
    properties: {
        id: { name: "ID", type: "string", isId: "uuid" },
        status: { name: "Status", type: "string" },
        sort_order: { name: "Order", type: "number" }
    },
    name: "Products",
    table: "products",
    admin: {
        defaultViewMode: "table",            // Default view
        enabledViews: ["list", "table", "kanban"],    // Available views
        orderProperty: "sort_order",         // Property for drag-and-drop ordering
        kanban: {
            columnProperty: "status"         // Enum property for columns
        }
    }
});

```

### List View

![List View screenshot placeholder](/img/features/list-view.png)

The list view is the classic, clean CMS default view mode, showing entities in a straightforward list format without the density of a spreadsheet.

### Table View

![Table View screenshot placeholder](/img/features/table-view.png)

The default view is a high-performance virtualized spreadsheet with:

- **Inline editing** — Click any cell to edit in-place
- **Column resizing** — Drag column headers
- **Column reordering** — Drag to rearrange
- **Sorting** — Click column headers
- **Text search** — Full-text search across string fields
- **Filtering** — Per-column filters
- **Multi-select** — Select entities for bulk actions

#### Row Height

Control row height with `defaultSize`:

| Size | Pixels | Best for |
|------|--------|----------|
| `"xs"` | 40 | Dense data tables |
| `"s"` | 54 | Default |
| `"m"` | 80 | With image thumbnails |
| `"l"` | 120 | Cards with previews |
| `"xl"` | 260 | Rich content previews |

### Kanban View

![Kanban View screenshot placeholder](/img/features/kanban-view.png)

Configure a Kanban board by specifying which enum property to use as columns:

```typescript

const tasksCollection = defineCollection({
    slug: "tasks",
    name: "Tasks",
    table: "tasks",
    properties: {
        title: { type: "string", name: "Title" },
        status: {
            type: "string",
            name: "Status",
            enum: [
                { id: "backlog", label: "Backlog", color: "gray" },
                { id: "in_progress", label: "In Progress", color: "blue" },
                { id: "review", label: "Review", color: "orange" },
                { id: "done", label: "Done", color: "green" }
            ]
        },
        sort_order: { type: "number", name: "Sort Order" }
    },
    admin: {
        defaultViewMode: "kanban",
        orderProperty: "sort_order",
        kanban: {
            columnProperty: "status"
        }
    }
});

```

Drag-and-drop between columns automatically updates the enum field and sort order.

### Cards View

![Cards View screenshot placeholder](/img/features/cards-view.png)

Cards display entities as visual cards — useful for image-heavy content:

```typescript

const articlesCollection = defineCollection({
    slug: "articles",
    name: "Articles",
    table: "articles",
    properties: {
        title: { type: "string", name: "Title" },
        cover: {
            type: "string",
            name: "Cover Image",
            storage: { storagePath: "covers", acceptedFiles: ["image/*"] }
        }
    },
    admin: {
        defaultViewMode: "cards"
    }
});

```

### Next Steps

- **[Entity Views](/docs/frontend/entity-views)** — Custom tabs on entity forms
- **[Entity Actions](/docs/frontend/entity-actions)** — Custom entity actions

## Custom Fields

<video className="intro_video" loop autoPlay muted>
    <source src="/img/custom_fields_dark.mp4" type="video/mp4"/>
</video>

### Overview

Rebase generates form fields automatically based on property types. For custom behavior, you can build your own fields.

### Creating a Custom Field

A custom field is a React component that receives `FieldProps`:

```tsx

function ColorPickerField({ value, setValue, error, showError }: FieldProps<StringProperty>) {
    return (
        <div>
            <input
                type="color"
                value={value ?? "#000000"}
                onChange={(e) => setValue(e.target.value)}
            />
            {showError && error && <span className="text-red-500">{error}</span>}
        </div>
    );
}
```

#### FieldProps

| Prop | Type | Description |
|------|------|-------------|
| `value` | `T` | Current field value |
| `setValue` | `(value: T) => void` | Update the field value |
| `error` | `string` | Validation error message |
| `showError` | `boolean` | Whether to display the error |
| `isSubmitting` | `boolean` | Form is being saved |
| `property` | `Property` | The property configuration |
| `context` | `FormContext` | Full form context with all entity values |
| `disabled` | `boolean` | Field is readonly |
| `minimalistView` | `boolean` | Rendering inside the spreadsheet (compact mode) |

### Registering a Custom Field

#### Per-Property

Register on a single property:

```typescript
properties: {
    brand_color: {
        type: "string",
        name: "Brand Color",
        admin: {
            Field: ColorPickerField
        }
    }
}
```

#### When the collection file is also read by the server

In the default scaffold, `config/collections/` is loaded by **both** the admin panel and the backend — the backend reads the same files to derive the schema and the API. A direct component reference is only safe when nothing on the server loads that file, because importing `ColorPickerField` also imports React, your CSS and everything else the component pulls in, into the server's module graph.

Point at the component with a lazy import instead. It is type-checked exactly the same way, and the backend never calls it:

```ts no-verify
// config/collections/products.ts
properties: {
    brand_color: {
        type: "string",
        name: "Brand Color",
        admin: {
            Field: () => import("../../frontend/src/ColorPickerField"),
            Preview: () => import("../../frontend/src/ColorPreview")
        }
    }
}
```

The module must have a **default export** — the thunk resolves to `default`, and a named-only export renders nothing. The admin wraps it in `React.lazy` on first render, so the component is also a separate chunk rather than part of the initial bundle.

#### Global Property Config

Register a reusable field type:

```tsx
const colorPropertyConfig: PropertyConfig = {
    key: "color_picker",
    name: "Color Picker",
    property: {
        type: "string",
        admin: {
            Field: ColorPickerField
        }
    }
};

// Register globally — keyed by the config's `key`
<Rebase propertyConfigs={{ color_picker: colorPropertyConfig }}>…</Rebase>
```

Then use it in any collection:

```typescript
properties: {
    color: {
        type: "string",
        name: "Color",
        propertyConfig: "color_picker"
    }
}
```

### Accessing Form Context

Custom fields can access the full entity values:

```tsx
function PriceWithTaxField({ value, setValue, context }: FieldProps<NumberProperty>) {
    const taxRate = Number(context.values.tax_rate ?? 0.1);
    const priceWithTax = value ? value * (1 + taxRate) : 0;

    return (
        <div>
            <input
                type="number"
                value={value ?? 0}
                onChange={(e) => setValue(Number(e.target.value))}
            />
            <p>With tax: ${priceWithTax.toFixed(2)}</p>
        </div>
    );
}
```

### Table Mode

When rendering inside the spreadsheet view, fields should be compact. Check `minimalistView`:

```tsx
function MyField({ value, setValue, minimalistView }: FieldProps<StringProperty>) {
    if (minimalistView) {
        return <span onClick={() => { /* open editor */ }}>{value}</span>;
    }

    return (
        <div>
            <label>Full Editor</label>
            <textarea value={value ?? ""} onChange={(e) => setValue(e.target.value)} />
        </div>
    );
}
```

### Custom Previews

For custom rendering in the table (non-editing mode), use the `Preview` component:

```tsx
function ColorPreview({ value }: { value: string }) {
    return (
        <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
            <div style={{
                width: 24, height: 24,
                borderRadius: 4,
                backgroundColor: value
            }} />
            <span>{value}</span>
        </div>
    );
}

// Register it
properties: {
    color: {
        type: "string",
        name: "Color",
        admin: {
            Field: ColorPickerField,
            Preview: ColorPreview
        }
    }
}
```

### Next Steps

- **[Entity Views](/docs/frontend/entity-views)** — Custom tabs in the entity editor
- **[Entity Actions](/docs/frontend/entity-actions)** — Custom action buttons
- **[Additional Columns](/docs/frontend/additional-columns)** — Computed table columns

## Form Layout

### Overview

The entity form is generated from your properties. By default it derives a
two-column layout from the property types, so a collection that says nothing
about layout still gets a form that reads like a form rather than one long run
of full-width inputs:

- the id and the `createdAt` / `updatedAt` timestamps go to a metadata rail, read-only
- short enums, booleans, dates and numbers take a narrow span
- long text, markdown, arrays, maps and storage fields take the full width
- everything else takes half

Use `admin.form` when the derived answer is wrong for your domain.

### Field width

A field's width is a **span** over a four-column grid. `4` is the full width of
the main column.

```typescript

const productsCollection = defineCollection({
    slug: "products",
    table: "products",
    name: "Products",
    properties: {
        sku: {
            name: "SKU",
            type: "string",
            admin: { span: 1 }
        },
        name: {
            name: "Product name",
            type: "string",
            admin: { span: 3 }
        },
        description: {
            name: "Description",
            type: "string",
            admin: { markdown: true, span: 4 }
        }
    }
});
```

Spans snap to a shared grid, which is what makes two fields line up regardless
of the order they were declared in. They replaced `admin.widthPercentage`,
whose raw percentages could not line up with anything; a collection still
carrying one should pick the nearest span (≤30 → `1`, ≤55 → `2`, ≤80 → `3`,
otherwise `4`).

On layouts too narrow for two columns — the side panel, the split pane, a phone
— the grid collapses to a single column and spans are ignored.

### Sections

`sections` groups the main column under headings. A titled section can be
collapsed; an untitled one cannot.

```typescript

const ordersCollection = defineCollection({
    slug: "orders",
    table: "orders",
    name: "Orders",
    properties: {
        reference: { name: "Reference", type: "string" },
        placed_at: { name: "Placed at", type: "date" },
        address: { name: "Address", type: "string" },
        carrier: { name: "Carrier", type: "string" },
        tracking_number: { name: "Tracking number", type: "string" },
        notes: { name: "Notes", type: "string" }
    },
    admin: {
        form: {
            sections: [
                { key: "identity", properties: ["reference", "placed_at"] },
                {
                    key: "shipping",
                    title: "Shipping",
                    properties: ["address", "carrier", "tracking_number"]
                },
                {
                    key: "internal",
                    title: "Internal notes",
                    properties: ["notes"],
                    collapsed: true
                }
            ]
        }
    }
});
```

A property no section names is never dropped: it lands in the last untitled
section, or in an untitled trailing group if there is none. Adding a column to
the database therefore cannot make a field silently disappear from the form.

A validation error inside a collapsed section expands it, so an error can never
hide behind a closed heading.

### The metadata rail

`sidebar` moves fields out of the main column and into a narrow rail beside it —
status, ownership, publication dates, flags.

```typescript

const postsCollection = defineCollection({
    slug: "posts",
    table: "posts",
    name: "Posts",
    properties: {
        title: { name: "Title", type: "string" },
        body: { name: "Body", type: "string", admin: { markdown: true } },
        status: { name: "Status", type: "string" },
        published_at: { name: "Published at", type: "date" },
        author: { name: "Author", type: "string" }
    },
    admin: {
        form: {
            sidebar: ["status", "published_at", "author"],
            showRecordMeta: true
        }
    }
});
```

The rail does not use the grid, so `span` is ignored for the fields in it. Where
there is no room for a rail it renders as an ordinary leading section, so
nothing is lost on a phone or in the side panel.

`showRecordMeta` puts the read-only record block — id, created, updated — at the
foot of the rail. It defaults to `true` whenever a rail is shown, and is what
replaces `hideIdFromForm` for most collections: the id stops being a field in
the middle of the form and becomes a copyable line of metadata.

Set `sidebar: []` to suppress the derived rail entirely and keep every field in
the main column.

### Reference

| Property | Type | Description |
|----------|------|-------------|
| `admin.span` | `1 \| 2 \| 3 \| 4` | Field width over the four-column form grid |
| `admin.form.sidebar` | `string[]` | Property keys shown in the metadata rail |
| `admin.form.sections` | `FormSection[]` | Titled groups for the main column |
| `admin.form.showRecordMeta` | `boolean` | Show id/created/updated at the foot of the rail |

`FormSection` is `{ key, title?, properties, collapsed?, collapsible? }`.

## Entity Views

### Overview

Entity views let you add custom **tabs** to the entity detail page alongside the default form. Use them for:

- Live **previews** (website preview, rendered content)
- **Related data** views (order items, child entities)
- **Analytics** or charts
- **Custom editors** (rich text, map editors)

### Adding Entity Views

```typescript

const articlesCollection = defineCollection({
    slug: "articles",
    table: "articles",
    name: "Articles",
    properties: { /* ... */ },
    admin: {
        entityViews: [
            {
                key: "preview",
                name: "Preview",
                Builder: ArticlePreview
            },
            {
                key: "related",
                name: "Related Articles",
                Builder: RelatedArticlesView
            }
        ]
    }
});

```

### Building a entity View

```tsx

function ArticlePreview({
    entity,
    modifiedValues,
    formContext
}: EntityCustomViewParams) {
    // modifiedValues has the unsaved, live form values. Both it and
    // entity.values are open records, so narrow before rendering.
    const title = String(modifiedValues?.title ?? entity?.values?.title ?? "");
    const content = String(modifiedValues?.content ?? entity?.values?.content ?? "");

    return (
        <div className="p-8 max-w-2xl mx-auto">
            <h1 className="text-xl font-semibold tracking-[-0.01em]">{title}</h1>
            <div dangerouslySetInnerHTML={{ __html: content }} />
        </div>
    );
}
```

#### EntityCustomViewParams

| Prop | Type | Description |
|------|------|-------------|
| `entity` | `Entity` | The saved entity (null for new entities) |
| `modifiedValues` | `EntityValues` | Current unsaved form values (live as user types) |
| `formContext` | `FormContext` | Full form context |
| `collection` | `CollectionConfig` | Collection definition |

![Entity view with secondary form](/img/entity_view_secondary_form.png)

### Controlling Position

Views appear as tabs. You can configure their position:

```typescript
entityViews: [
    {
        key: "preview",
        name: "Preview",
        Builder: ArticlePreview,
        position: "start"  // Appears before the default form tab
    }
]
```

### Next Steps

- **[Custom Fields](/docs/frontend/custom-fields)** — Build custom form fields
- **[Entity Actions](/docs/frontend/entity-actions)** — Custom action buttons

## Entity Actions

### Overview

Entity actions are custom buttons that appear on individual entities. Use them for operations like publishing, archiving, cloning, or triggering external workflows.

### Defining Entity Actions

```typescript

const articlesCollection = defineCollection({
    slug: "articles",
    name: "Articles",
    table: "articles",
    properties: {
        id: { name: "ID", type: "number", isId: "increment" },
        name: { name: "Name", type: "string" },
        status: { name: "Status", type: "string" },
        published_at: { name: "Published At", type: "date" }
    },
    admin: {
        entityActions: [
            {
                name: "Publish",
                icon: <Upload size={iconSize.small}/>,
                onClick: async ({ entity, context }) => {
                    await context.data.collection<Record<string, unknown>>(entity.path)
                            .update(entity.id, { status: "published", published_at: new Date() });
                    context.snackbarController.open({
                        type: "success",
                        message: "Article published!"
                    });
                }
            },
            {
                name: "Clone",
                icon: <Copy size={iconSize.small}/>,
                onClick: async ({ entity, context }) => {
                    const { id, ...values } = entity.values;
                    await context.data.collection<Record<string, unknown>>(entity.path)
                            .create({ ...values, name: values.name + " (Copy)" });
                }
            }
        ]
    }
});

```

### Collection Actions

For toolbar-level actions that work on the collection or selected entities:

```tsx

function PublishSelectedAction({ selectionController, context }: CollectionActionsProps) {
    const handlePublish = async () => {
        const selected = selectionController.selectedEntities;
        for (const entity of selected) {
            await context.data.save({
                path: entity.path,
                entityId: entity.id,
                values: { status: "published" },
                collection: context.collection
            });
        }
    };

    return (
        <button onClick={handlePublish}>
            Publish {selectionController.selectedEntities.length} selected
        </button>
    );
}

// Register — `Actions` is an array, so several can be composed.
const collection = defineCollection({
    slug: "products",
    name: "Products",
    table: "products",
    properties: { /* … */ },
    admin: {
        Actions: [PublishSelectedAction]
    }
});
```

![Collection actions](/img/collection_actions.png)

### Next Steps

- **[Additional Columns](/docs/frontend/additional-columns)** — Computed table columns
- **[Custom Fields](/docs/frontend/custom-fields)** — Custom form fields

## Additional Columns

### Overview

Additional columns let you display computed or derived data in the collection table without storing it in the database.

### Defining Additional Columns

```typescript

const ordersCollection = defineCollection({
    slug: "orders",
    name: "Orders",
    table: "orders",
    properties: {
        items: {
            name: "Items",
            type: "array",
            of: {
                name: "Item",
                type: "map",
                properties: {
                    price: { name: "Price", type: "number" },
                    quantity: { name: "Quantity", type: "number" }
                }
            }
        },
        status: { name: "Status", type: "string" }
    },
    admin: {
        additionalFields: [
            {
                key: "total_display",
                name: "Total",
                Builder: ({ entity }) => {
                    const total = entity.values.items?.reduce(
                        (sum, item) => sum + (item.price * item.quantity), 0
                    ) ?? 0;
                    return <span>${total.toFixed(2)}</span>;
                }
            },
            {
                key: "status_badge",
                name: "Status",
                Builder: ({ entity }) => {
                    const color = entity.values.status === "completed" ? "green" : "orange";
                    return (
                        <span style={{ color }}>
                            {entity.values.status}
                        </span>
                    );
                },
                dependencies: ["status"]  // Re-render when these fields change
            }
        ]
    }
});

```

### Builder Props

| Prop | Type | Description |
|------|------|-------------|
| `entity` | `Entity` | The entity for this row |
| `context` | `RebaseContext` | Full Rebase context |

### Next Steps

- **[Entity Actions](/docs/frontend/entity-actions)** — Custom action buttons
- **[Custom Fields](/docs/frontend/custom-fields)** — Custom form fields

## Slots

### Overview

Slots are named UI extension points where you can inject custom React components. Each slot has typed props specific to its location in the UI. Rebase ships with 29 built-in slots covering the home page, navigation, collection views, entity forms, dashboards, and more.

### Usage

#### Via `<Rebase>` prop

```tsx no-verify
<Rebase
    client={client}
    slots={[
        {
            slot: "navigation.footer",
            Component: MyNavigationFooter,
            order: 10
        },
        {
            slot: "collection.actions",
            Component: BulkExportButton
        }
    ]}
>
```

#### Via plugin

```typescript
const myPlugin: RebasePlugin = {
    key: "my-plugin",
    slots: [
        {
            slot: "home.cards",
            Component: AnalyticsCard,
            order: 20
        }
    ]
};
```

:::note
`order` controls rendering order — lower values render first. The default is `50`.
:::

### Available Slots

##### Home Page

| Slot | Props Type | Description |
|------|-----------|-------------|
| `home.actions` | `PluginGenericProps` | Actions in the home page header |
| `home.cards` | `PluginHomePageAdditionalCardsProps` | Additional cards on the home page |
| `home.children.start` | `PluginGenericProps` | Content at the start of the home page |
| `home.children.end` | `PluginGenericProps` | Content at the end of the home page |
| `home.card.insight` | `HomeCardInsightSlotProps` | Compact insight widget inside a home page collection card |
| `home.collection.actions` | `PluginHomePageActionsProps` | Actions on home page collection cards |

##### Navigation

| Slot | Props Type | Description |
|------|-----------|-------------|
| `navigation.header` | `NavigationSlotProps` | Below the logo in the sidebar drawer |
| `navigation.footer` | `NavigationSlotProps` | Above the collapse toggle at the bottom of the drawer |

##### Collection View

| Slot | Props Type | Description |
|------|-----------|-------------|
| `collection.actions` | `CollectionActionsProps` | End-side toolbar actions (after collection `Actions`) |
| `collection.actions.start` | `CollectionActionsProps` | Start-side toolbar actions (alongside filters) |
| `collection.header.action` | `CollectionHeaderActionProps` | Column header action buttons |
| `collection.add-column` | `CollectionAddColumnProps` | "Add column" area in table header |
| `collection.error` | `CollectionErrorProps` | Error state display for a collection |
| `collection.toolbar` | `CollectionToolbarProps` | Extra widgets inside the collection toolbar row |
| `collection.empty-state` | `CollectionEmptyStateProps` | Custom empty-state when collection has no data |
| `collection.insights` | `CollectionInsightsSlotProps` | Insight widgets above the collection table |
| `collection.filter-panel` | `CollectionFilterPanelProps` | Custom filter sidebar alongside the table. **Not yet rendered** — declared, but nothing in the admin renders it today. |

##### Entity / Form

| Slot | Props Type | Description |
|------|-----------|-------------|
| `form.actions` | `PluginFormActionProps` | Actions in the entity form action bar |
| `form.actions.top` | `PluginFormActionProps` | Actions above the form action bar |
| `form.before` | `PluginFormActionProps` | Content before the form title/field list |
| `form.after` | `PluginFormActionProps` | Content after the form field list |
| `entity.row.actions` | `EntityRowActionsProps` | Per-row actions in entity tables. **Not yet rendered** — declared, but nothing in the admin renders it today. |
| `entity.field.before` | `EntityFieldSlotProps` | UI injected before an individual form field. **Not yet rendered** — declared, but nothing in the admin renders it today. |
| `entity.field.after` | `EntityFieldSlotProps` | UI injected after an individual form field. **Not yet rendered** — declared, but nothing in the admin renders it today. |

##### Dashboard

| Slot | Props Type | Description |
|------|-----------|-------------|
| `dashboard.widget` | `DashboardWidgetProps` | Widgets on the dashboard/home page. **Not yet rendered** — declared, but nothing in the admin renders it today. |

##### Global

| Slot | Props Type | Description |
|------|-----------|-------------|
| `global.search` | `GlobalSearchProps` | Cross-collection search bar component. **Not yet rendered** — declared, but nothing in the admin renders it today. |
| `shell.toolbar` | `ShellToolbarProps` | Top-level toolbar actions in the app bar. **Not yet rendered** — declared, but nothing in the admin renders it today. |

##### Kanban

| Slot | Props Type | Description |
|------|-----------|-------------|
| `kanban.setup` | `KanbanSetupProps` | Kanban board setup UI |
| `kanban.add-column` | `KanbanAddColumnProps` | "Add column" in kanban view |

### Slot Props Reference

All slot prop types are exported from `@rebasepro/types` and can be imported for type-safe slot components:

```typescript

```

Each props type provides access to the context relevant to the slot's location — collection metadata, entity data, navigation state, and more. Refer to the individual type definitions for full property details.

## Data Import & Export

### Overview

Rebase includes built-in data import and export tools accessible directly from the admin panel. Import supports CSV, JSON, and Excel files with a column-mapping wizard. Export supports CSV and JSON with optional computed fields.

Both features are enabled by default on all collections and can be configured or disabled per collection.

### Importing Data

#### How to Import

1. Open a collection in the admin panel
2. Click the **Import** button in the toolbar
3. Select or drag-and-drop your file
4. Map file columns to collection properties
5. Preview the data and resolve any validation errors
6. Click **Import** to save all entities

#### Supported Formats

| Format | Extensions | Notes |
|--------|-----------|-------|
| CSV | `.csv` | Auto-detects delimiters |
| JSON | `.json` | Expects an array of objects |
| Excel | `.xlsx` | Reads the first sheet |

#### Column Mapping

The import wizard automatically attempts to match file columns to collection properties by name. You can manually adjust mappings before importing:

- **Exact matches** are mapped automatically (e.g. `name` → `name`)
- **Unmatched columns** can be mapped manually or skipped
- **Type coercion** handles string-to-number, string-to-boolean, and date parsing

#### Validation

Before importing, the wizard validates all rows against your collection's property definitions:

- Required fields must be present
- Enum values must match defined options
- Data types must be compatible (e.g. a text value for a number field is flagged)
- Validation errors are shown per-row so you can fix them before importing

#### Import Configuration

Import is enabled by default. To disable it on a specific collection, use the `admin` sub-object:

```typescript

const productsCollection = defineCollection({
    slug: "products",
    table: "products",
    name: "Products",
    properties: { /* ... */ },
    // Import is enabled by default
});
```

### Exporting Data

#### How to Export

1. Open a collection in the admin panel
2. Optionally apply filters to export a subset of data
3. Click the **Export** button in the toolbar
4. Choose the format: **CSV** or **JSON**
5. The file downloads immediately

#### Export Formats

| Format | Description |
|--------|-------------|
| CSV | Comma-separated values, compatible with Excel and Google Sheets |
| JSON | Array of objects, useful for programmatic consumption |

#### Filtering Before Export

Any active filters in the collection view are applied to the export. This lets you export only a subset of your data:

- Apply column filters or search terms in the collection view
- Click **Export** — only the filtered rows are included

#### Export Configuration

Export is enabled by default. You can configure it with additional computed fields:

```typescript

const productsCollection = defineCollection({
    slug: "products",
    table: "products",
    name: "Products",
    properties: { /* ... */ },
    admin: {
        exportable: true            // Enable (default: true)
    }
});

```

To disable export:

```typescript

const productsCollection = defineCollection({
    slug: "products",
    table: "products",
    name: "Products",
    properties: { /* ... */ },
    admin: {
        exportable: false
    }
});

```

#### Adding Computed Fields

Use the `ExportConfig` object to add custom computed columns to your exports. These columns don't exist in the database — they are calculated at export time:

```typescript

const productsCollection = defineCollection({
    slug: "products",
    table: "products",
    name: "Products",
    properties: { /* ... */ },
    admin: {
        exportable: {
            additionalFields: [
                {
                    key: "computed_margin",
                    builder: ({ entity }) => {
                        const price = entity.values.price as number;
                        const cost = entity.values.cost as number;
                        return String(price - cost);
                    }
                },
                {
                    key: "full_url",
                    builder: ({ entity }) => {
                        return `https://mystore.com/products/${entity.id}`;
                    }
                }
            ]
        }
    }
});

```

Each `additionalFields` entry has:

| Property | Type | Description |
|----------|------|-------------|
| `key` | `string` | Column name in the export |
| `builder` | `({ entity, context }) => string \| Promise<string>` | Function that computes the value |

The `builder` function receives the current `entity` and the `RebaseContext` (which includes the authenticated user), so you can compute values based on both data and permissions.

#### Async Computed Fields

The `builder` function can be async, which is useful when the computed value requires a database lookup or API call:

```typescript
exportable: {
    additionalFields: [
        {
            key: "author_name",
            builder: async ({ entity, context }) => {
                const author = await context.data.users.findById(
                    entity.values.author_id as string
                );
                return author?.values.displayName ?? "Unknown";
            }
        }
    ]
}
```

### Next Steps

- **[Collections](/docs/collections)** — Define your data model
- **[Frontend Overview](/docs/frontend)** — Admin panel and UI components
- **[Client SDK](/docs/sdk)** — Programmatic data access

## Plugin System

### Overview

Plugins are the primary extension mechanism in Rebase. They can:

- Wrap the entire app with a **provider** (context, state management)
- Add **home page actions** and widgets
- Inject **collection view** components (toolbar, column builders)
- Add **form** components (field builders, additional panels)
- **Inject or modify collections** dynamically

### Plugin Interface

```typescript
interface RebasePlugin {
    key: string;                    // Unique identifier
    loading?: boolean;              // Hold admin content until the plugin is ready

    // UI contributions — a flat array, each entry naming its slot.
    // This replaced the old per-area objects (homePage, collectionView, form).
    slots?: SlotContribution[];

    // HOC providers. `scope: "root"` wraps the whole admin below
    // RebaseContext; `scope: "form"` wraps each entity form / edit view.
    providers?: PluginProvider[];

    // Behavioural (non-UI) hooks: collection modification and injection,
    // column reordering, navigation entries.
    hooks?: PluginHooks;

    // Custom field rendering (e.g. data enhancement).
    fieldBuilder?: FieldBuilderConfig;

    // Views added to the navigation automatically.
    views?: AppView[];

    lifecycle?: PluginLifecycle;
}
```

Every one of these is optional except `key`. The full slot-name list lives on
the **[Slots](/docs/frontend/slots)** page.

### Using Plugins

Pass plugin instances to the navigation controller:

```typescript
const dataEnhancementPlugin = useDataEnhancementPlugin();

const plugins = [dataEnhancementPlugin];

const navigationStateController = useBuildNavigationStateController({
    plugins,
    collections: () => collections,
    // These four are required — the controller resolves navigation against them.
    authController,
    data,
    collectionRegistryController,
    urlController
});
```

### Building a Plugin

Here's a minimal plugin that adds a toolbar action to every collection:

```tsx

function useMyPlugin(): RebasePlugin {
    return {
        key: "my_plugin",

        // `slots` is a flat array of contributions, each naming its slot.
        // See the Slots page for the full list of slot names.
        slots: [
            { slot: "collection.actions", Component: MyToolbarAction }
        ],

        // `fieldBuilder` is top-level and takes a `wrap` function that returns
        // a *component* (or null to leave the default field alone) — it is not
        // a render function and no longer lives under `form`.
        fieldBuilder: {
            wrap: ({ property }) =>
                property.propertyConfig === "my_custom_field" ? MyCustomField : null
        }
    };
}
```

### Built-in Plugins

#### Data Enhancement Plugin

AI-powered field autocompletion:

```typescript

const enhancementPlugin = useDataEnhancementPlugin();
```

![Data enhancement](/img/data_enhancement.png)

### Collection Injection

Plugins can dynamically add new collections:

```typescript
hooks: {
    // Receives the resolved collections and returns the full list to use.
    injectCollections: (collections) => [...collections, auditLogCollection]
}
```

### Collection Modification

Plugins can modify existing collections:

```typescript
hooks: {
    // Receives one collection, returns the modified one.
    // Use `modifyCollectionAsync` when the change needs a fetch.
    modifyCollection: (collection) => ({
        ...collection,
        properties: {
            ...collection.properties,
            last_modified_by: {
                type: "string",
                name: "Modified By",
                admin: { readOnly: true }
            }
        }
    })
}
```

### Next Steps

- **[Studio Tools](/docs/studio)** — SQL console, JS console, RLS editor
- **[Custom Fields](/docs/frontend/custom-fields)** — Building custom form fields

## Hooks Reference

### Overview

Rebase provides React hooks to access framework functionality from any component within the `<Rebase>` provider tree.

### `useRebaseContext`

The master hook — access everything:

```typescript

function MyComponent() {
    const context = useRebaseContext();

    context.data                      // Data operations (flat rows)
    context.client                    // The full SDK client
    context.storageSource             // File operations
    context.authController            // Auth state
    context.navigationStateController // Navigation state
    context.sidePanelController       // Side panel control
    context.snackbarController        // Toast notifications
}
```

### `useAuthController`

Access authentication state and capabilities:

```typescript

function UserMenu() {
    const auth = useAuthController();

    auth.user            // Current user (or null)
    auth.authLoading     // True when auth operation is in progress
    auth.initialLoading  // Loading initial session on app startup
    auth.signOut()       // Log out (returns Promise<void>)
    auth.getAuthToken()  // Get JWT for API calls (returns Promise<string>)
    auth.extra           // Additional user data (roles, etc.)
    auth.capabilities    // Capabilities advertised by auth provider (e.g. registration, reset)
}
```

### `useCollection`

Fetch and subscribe to a list of entities in a collection. It automatically establishes a real-time WebSocket subscription if supported by the driver, falling back to REST fetches.

```typescript

function ProductList() {
    // The row shape drives `filterValues`, `sortBy` and `entity.values` — without it
    // TypeScript infers M from whichever key it sees first.
    type Product = { name: string; price: number; active: boolean; created_at: string };

    const { data, dataLoading, dataLoadingError, noMoreToLoad } = useCollection<Product, User>({
        path: "products",
        collection: productsCollection,
        itemCount: 20,
        filterValues: {
            active: ["==", true],
            price: [">=", 100]
        },
        sortBy: ["created_at", "desc"],
        searchString: "laptop"
    });

    if (dataLoading) return <p>Loading products...</p>;
    if (dataLoadingError) return <p>Error: {dataLoadingError.message}</p>;

    return (
        <ul>
            {data.map(product => (
                <li key={product.id}>{product.values.name} (${product.values.price})</li>
            ))}
        </ul>
    );
}
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `string` | Absolute collection path (e.g., `"products"`). |
| `collection` | `CollectionConfig` | The collection definition object. |
| `itemCount` | `number` | Optional. Number of entities to fetch (SQL limit). |
| `offset` | `number` | Optional. Number of items to skip. |
| `page` | `number` | Optional. Page number (1-indexed), alternative to offset. |
| `filterValues` | `FilterValues` | Optional. Query filters. Supports shorthand equality, tuples `[op, val]`, and PostgREST operator strings. |
| `sortBy` | `[string, "asc" \| "desc"]` | Optional. Sort field and order direction tuple. |
| `searchString` | `string` | Optional. Query for full-text search. |

#### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `data` | `Entity[]` | Array of fetched entities. |
| `dataLoading` | `boolean` | True if the initial load is in progress. |
| `dataLoadingError` | `Error` | Error object if the fetch fails. |
| `noMoreToLoad` | `boolean` | True if there are no more records beyond the current page/limit. |
| `totalCount` | `number` | Optional. The total count of records matching the filter in the database. |

### `useFetch`

Fetch and subscribe to a single entity by ID. It renders instantly using cached data if already loaded via a collection fetch, then updates in the background.

```typescript

function ProductDetail({ productId }) {
    const { entity, dataLoading, dataLoadingError } = useFetch({
        path: "products",
        entityId: productId,
        collection: productsCollection
    });

    if (dataLoading) return <p>Loading product...</p>;
    if (dataLoadingError) return <p>Error: {dataLoadingError.message}</p>;
    if (!entity) return <p>Product not found</p>;

    return (
        <div>
            <h1>{entity.values.name}</h1>
            <p>{entity.values.description}</p>
        </div>
    );
}
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `string` | Absolute collection path. |
| `entityId` | `string \| number` | The ID of the entity to fetch. |
| `collection` | `CollectionConfig` | The collection definition object. |
| `useCache` | `boolean` | Optional. If `true` and entity is in cache, skips background refresh. (Default: `false`). |

#### Caching Utilities

Rebase maintains a global memory cache to prevent UI flashing. You can manipulate this cache directly:

- `populateFetchCache(path, entities)`: Pre-populates the cache with a list of entities (e.g. after a bulk action or custom API call).
- `clearFetchCache()`: Clears the cache. Recommended to call this upon user logout to prevent data leakage.

### `usePermissions`

Hook to evaluate roles and permissions for the current user. It abstracts away the need to manually pass the `authController` to permission checking functions.

```typescript

function CreateProductButton() {
    const { canCreate } = usePermissions();

    const allowedToCreate = canCreate(productsCollection, "products");

    return (
        <button disabled={!allowedToCreate}>
            Create Product
        </button>
    );
}
```

#### Return Value

| Method | Signature | Description |
|--------|-----------|-------------|
| `canCreate` | `(collection, path) => boolean` | Checks if the user is allowed to create entities in the collection. |
| `canEdit` | `(collection, path, entity) => boolean` | Checks if the user is allowed to edit the given entity. |
| `canDelete` | `(collection, path, entity) => boolean` | Checks if the user is allowed to delete the given entity. |
| `canRead` | `(collection) => boolean` | Checks if the user is allowed to read the collection. |

### `useClipboard`

Utility hook to copy or cut text to the clipboard, with automatic support for fallback mechanisms on older browsers.

> [!NOTE]
> Note the exact spelling of `isCoppied` (with two `p`s) in the return payload.

```typescript

function CopyButton({ text }) {
    const { copy, isCoppied } = useClipboard({ copiedDuration: 2000 });

    return (
        <button onClick={() => copy(text)}>
            {isCoppied ? "Copied!" : "Copy Text"}
        </button>
    );
}
```

#### Parameters

| Option | Type | Description |
|--------|------|-------------|
| `copiedDuration` | `number` | Optional. Time in milliseconds before resetting `isCoppied` back to `false`. |
| `onSuccess` | `(text) => void` | Optional. Callback triggered on successful copy. |
| `onError` | `(err) => void` | Optional. Callback triggered on error. |

#### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `ref` | `MutableRefObject` | React ref to attach to input/textarea elements to copy from. |
| `copy` | `(text?: string) => void` | Triggers copy of the given text, or the ref element's content. |
| `cut` | `() => void` | Triggers cut of the ref element's content. |
| `isCoppied` | `boolean` | True if text was recently copied. |
| `clipboard` | `string` | The current copied text value. |
| `clearClipboard` | `() => void` | Clears the clipboard. |

### `useSidePanel`

Programmatically open entities in a side panel:

```typescript

function OpenProductButton({ productId }) {
    const sidePanel = useSidePanel();

    return (
        <button onClick={() => {
            sidePanel.open({
                path: "products",
                entityId: productId,
                collection: productsCollection
            });
        }}>
            Open Product
        </button>
    );
}
```

Methods:

| Method | Description |
|--------|-------------|
| `open({ path, entityId, collection })` | Open a entity in a side panel |
| `close()` | Close the current side panel |
| `replace({ path, entityId, collection })` | Replace the current side panel content |

### `useSnackbarController`

Show toast notifications:

```typescript

function SaveButton() {
    const snackbar = useSnackbarController();

    const handleSave = async () => {
        try {
            await saveData();
            snackbar.open({ type: "success", message: "Saved successfully!" });
        } catch (error) {
            snackbar.open({ type: "error", message: "Save failed" });
        }
    };
}
```

`open()` takes `{ type, title?, message, autoHideDuration?, action? }`.

The `action` slot renders a button next to the message, which is where undo
belongs — the window in which undo means anything is the window the snackbar is
on screen:

```typescript
const rejectApplication = async (application: Application) => {
    const previous = application.status;
    await setStatus(application.id, "rejected");

    snackbar.open({
        type: "success",
        message: `Rejected ${application.name}`,
        action: {
            label: "Undo",
            onClick: () => setStatus(application.id, previous)
        }
    });
};
```

The snackbar dismisses itself once the action is clicked, so the same undo
cannot fire twice. Two snackbars carrying the same message both appear when
each has an action — rejecting two applications in a row leaves you a way back
from each.

### `useStorageSource`

Access file storage operations:

```typescript

function FileUploader() {
    const storage = useStorageSource();

    const upload = async (file: File) => {
        const result = await storage.putObject({
            file,
            key: `documents/${file.name}`
        });
        const { url } = await storage.getSignedUrl(result.key);
        return url;
    };
}
```

### `useModeController`

Control light/dark theme:

```typescript

function ThemeToggle() {
    const mode = useModeController();

    return (
        <button onClick={() => mode.setMode(mode.mode === "dark" ? "light" : "dark")}>
            Current: {mode.mode} {/* "light" | "dark" */}
        </button>
    );
}
```

### `useSelectionDialog`

Open a side dialog for selecting entities from a collection. This is the same hook used internally when a relation property is rendered:

```typescript

function SelectProduct() {
    const selectionDialog = useSelectionDialog({
        path: "products",
        collection: productsCollection,
        onSingleEntitySelected: (entity) => {
            console.log("Selected:", entity);
        }
    });

    return <button onClick={selectionDialog.open}>Select Product</button>;
}
```

### `useNavigationController`

Access navigation state and resolved collections:

```typescript

function MyComponent() {
    const navigation = useNavigationStateController();

    navigation.views              // Custom views
    navigation.adminViews         // Admin-mode views
    navigation.topLevelNavigation // Resolved top-level entries
}
```

### `useRelationSelector`

Manage complex relation selections with built-in search, debouncing, and pagination.

```typescript

function CategorySelector({ onSelect }) {
    const { items, isLoading, search, loadMore, hasMore } = useRelationSelector({
        path: "categories",
        collection: categoriesCollection,
        pageSize: 10
    });

    return (
        <div>
            <input type="text" onChange={(e) => search(e.target.value)} placeholder="Search..." />
            <ul>
                {items.map(item => (
                    <li key={item.id} onClick={() => onSelect(item.relation)}>
                        {item.label}
                    </li>
                ))}
            </ul>
            {hasMore && <button onClick={loadMore} disabled={isLoading}>Load More</button>}
        </div>
    );
}
```

#### Parameters

| Option | Type | Description |
|--------|------|-------------|
| `path` | `string` | Absolute collection path. |
| `collection` | `CollectionConfig` | Target collection definition. |
| `fixedFilter` | `FilterValues` | Optional. Static filters to restrict search results. |
| `pageSize` | `number` | Optional. Number of items per page. (Default: `10`). |
| `getLabelFromEntity` | `(entity) => string` | Optional. Customize the display label text. |
| `getDescriptionFromEntity` | `(entity) => string` | Optional. Customize the description text. |

### `useRebaseClient`

Retrieve the backing client SDK instance (`RebaseClient`) from the React context. This is useful for invoking raw SDK operations (like calling custom endpoints or manual uploads) within your components.

```typescript

function CustomAction() {
    const client = useRebaseClient();

    const handleAction = async () => {
        const result = await client.call("functions/send-invoice", { invoiceId: "123" });
        console.log(result);
    };

    return <button onClick={handleAction}>Process Invoice</button>;
}
```

### `useUnsavedChangesDialog`

Prevent navigation or page unload when form data has unsaved changes. It automatically intercepts internal React Router navigation via `useBlocker` as well as browser-level reloads via `beforeunload`.

```typescript

function EditForm() {
    const [isDirty, setIsDirty] = useState(false);

    const { dialogProps, triggerDialog } = useUnsavedChangesDialog(
        isDirty,
        () => console.log("Navigation allowed (discarded or saved changes)")
    );

    // dialogProps contains { open, handleOk, handleCancel, body }
}
```

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `when` | `boolean` | Flag to activate page/router navigation blocking. |
| `onOk` | `() => void` | Callback triggered when the user confirms discarding changes. |

#### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `dialogProps` | `UnsavedChangesDialogProps` | Modal props to pass directly to an `UnsavedChangesDialog` UI component. |
| `triggerDialog` | `() => void` | Triggers manual dialog display programmatically. |

### `useEffectiveRoleController`

Switch roles at runtime to preview permissions and test Row-Level Security (RLS) policies locally without signing out.

```typescript

function RoleSwitcher() {
    const { effectiveRole, setEffectiveRole } = useEffectiveRoleController();

    return (
        <select value={effectiveRole || ""} onChange={(e) => setEffectiveRole(e.target.value || null)}>
            <option value="">Default (No Simulation)</option>
            <option value="admin">Admin</option>
            <option value="editor">Editor</option>
            <option value="user">Standard User</option>
        </select>
    );
}
```

### `useAdminModeController`

Switch the admin layout view modes within the admin panel.

```typescript

function ModeToggle() {
    const { mode, setMode } = useAdminModeController(); // mode is "content" | "studio" | "settings"

    return <button onClick={() => setMode("studio")}>Switch to Studio View</button>;
}
```

### `useDialogsController`

Open dialog screens imperatively from anywhere in the component tree.

```typescript

function OpenModalButton() {
    const dialogs = useDialogsController();

    return (
        <button onClick={() => dialogs.open({
            key: "my-custom-modal",
            Component: MyCustomDialog,
            props: { title: "Custom Title" }
        })}>
            Open Custom Dialog
        </button>
    );
}
```

### `useAnalyticsController`

Capture CMS UI actions and user events globally.

```typescript

function AnalyticsLogger() {
    const analytics = useAnalyticsController();

    useEffect(() => {
        analytics.onAnalyticsEvent = (event, data) => {
            console.log(`CMS Event: ${event}`, data);
        };
    }, [analytics]);
}
```

### Next Steps

- **[Frontend Overview](/docs/frontend)** — React framework reference
- **[Client SDK](/docs/sdk)** — Data operations SDK

## Client SDK — Getting Started

### Overview

The `@rebasepro/client` package provides a type-safe JavaScript SDK for interacting with your Rebase backend. It handles:

- **Data operations** — CRUD with filtering, sorting, and pagination
- **Relation fetching** — Include related entities with `.include()`
- **Real-time subscriptions** — WebSocket-based live updates
- **Offline & local-first sync** — Opt-in local row database, instant offline writes, live queries
- **Authentication** — Token management, login, signup, OAuth
- **Storage** — File upload, download, and management
- **Custom functions** — Call custom server endpoints

### Installation

```bash
pnpm add @rebasepro/client
```

### Creating a Client

```typescript

const client = createRebaseClient({
    baseUrl: "http://localhost:3001",
});
```

The `websocketUrl` is derived automatically from `baseUrl` (`http → ws`, `https → wss`). You can override it explicitly if needed:

```typescript
const client = createRebaseClient({
    baseUrl: "http://localhost:3001",
    websocketUrl: "ws://localhost:3001",
});
```

#### Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `baseUrl` | `string` | Backend URL (e.g. `http://localhost:3001`) |
| `websocketUrl` | `string` | WebSocket URL — auto-derived from `baseUrl` if omitted |
| `token` | `string` | Static JWT token for server-to-server calls |
| `apiPath` | `string` | API prefix (default: `"/api"`) |
| `fetch` | `typeof fetch` | Custom fetch implementation (e.g. for SSR) |
| `onUnauthorized` | `() => Promise<boolean>` | Custom 401 handler — return `true` to retry |
| `realtime` | `boolean` | Open the WebSocket (default `true`) — set `false` in one-shot scripts |
| `collections` | `Record<string, string>` | Maps accessor names to collection slugs |
| `offline` | `boolean \| OfflineConfig` | [Local-first sync](/docs/sdk/offline) — off by default |

### Typed SDK Generation

Generate a fully typed client from your collection definitions:

```bash
rebase generate-sdk
```

Then pass the `Database` type parameter to `createRebaseClient` for full autocomplete:

```typescript

const client = createRebaseClient<Database>({
    baseUrl: "http://localhost:3001",
    collections: collectionsDictionary,
});

// Full autocomplete on collection names and field types
const { data } = await client.data.products.find();
```

When `Database` is supplied, `createRebaseClient` returns a `CreateRebaseClientResult<DB>` instance. This maps camelCase collection accessors directly on `client.data` to their corresponding types, giving you full autocomplete on collection operations and types (e.g. `client.data.products.find()`).

`collectionsDictionary` maps each accessor back to the slug the wire uses. Pass it whenever a slug is not already a valid property name — `my-notes` is reachable as `client.data.myNotes` only because the dictionary says so.

#### Field names

Columns keep their real names in the generated types: a `created_at` column is `row.created_at`, and a relation's foreign key is `author_id`. `where` and `orderBy` are keyed off the same `Row` type, so what compiles is what the backend answers to.

`Row` describes a read, `Insert` a `create()` and `Update` an `update()` — they are not the same shape. Nullable columns are `T | null` on `Row`, the primary key is always present on a read and never settable on an update, and a `belongsTo` target can be written either as the relation (`{ author: 5 }`) or as its foreign key (`{ author_id: 5 }`).

### Quick Example

```typescript
// Create
const product = await client.data.products.create({
    name: "Camera",
    price: 299,
});

// Query with filters
const { data } = await client.data.products
    .where("price", ">=", 100)
    .orderBy("created_at", "desc")
    .limit(10)
    .find();

// Real-time subscription
const unsubscribe = client.data.products.listen(
    { where: { active: ["==", true] } },
    (response) => console.log("Updated:", response.data)
);
```

### Using with React

In a Rebase frontend, the client is created once and shared via context:

```tsx no-verify

const client = createRebaseClient({ baseUrl: API_URL });

<Rebase client={client} ...>
```

Access it from any component:

```tsx

function MyComponent() {
    const client = useRebaseClient();
    // client.data, client.auth, client.storage, client.functions
}
```

### Next Steps

- **[Querying Data](/docs/sdk/querying)** — CRUD, filters, pagination, and relations
- **[Authentication](/docs/sdk/authentication)** — Sign in, sign up, OAuth, sessions
- **[Realtime Subscriptions](/docs/sdk/realtime)** — Live data with WebSockets
- **[Offline & Local-First Sync](/docs/sdk/offline)** — Work without a connection, and sync when it returns
- **[Storage & Files](/docs/sdk/storage)** — Upload, download, and manage files

## Querying Data

### Accessing Collections

Access any collection through `client.data.<collectionName>` (camelCase, auto-converted to snake_case) or `client.data.collection<Record<string, unknown>>("slug")` (explicit slug):

```typescript
// Property-style access (camelCase → snake_case slug)
client.data.blogPosts       // → slug "blog_posts"
client.data.users           // → slug "users"

// Dynamic access by slug
client.data.collection<Record<string, unknown>>("blog_posts")
```

> **Strict mode (generated SDK):** When you pass the generated `collectionsDictionary` to `createRebaseClient`, the data proxy validates property accesses at access time. A typo like `client.data.prodcuts` will throw immediately with a helpful error and a nearest-match suggestion instead of producing a confusing 404 later. Use `client.data.collection<Record<string, unknown>>("slug")` to bypass validation for dynamic or runtime-determined slugs.

### CRUD Operations

#### Find (List)

```typescript
// All products (default limit: 50)
const { data, meta } = await client.data.products.find();

// With pagination, filtering, and sorting
const { data, meta } = await client.data.products.find({
    where: { active: ["==", true], price: [">=", 100] },
    orderBy: ["created_at", "desc"],
    limit: 25,
    offset: 0
});

// data is Entity<M>[]  — each item has { id, values, path }
// meta has { total, limit, offset, hasMore }
```

#### Find by ID

```typescript
const product = await client.data.products.findById(42);
// Returns Entity<M> | undefined
```

#### Create

```typescript
const newProduct = await client.data.products.create({
    name: "New Product",
    price: 29.99,
    active: true
});

// With a specific ID
const newProduct = await client.data.products.create(
    { name: "Custom ID Product" },
    "my-custom-id"
);
```

#### Update

```typescript
const updated = await client.data.products.update(42, {
    name: "Updated Name",
    price: 39.99
});
```

#### Delete

```typescript
await client.data.products.delete(42);
```

#### Count

```typescript
const total = await client.data.products.count();

// With filters
const activeCount = await client.data.products.count({
    where: { active: ["==", true] }
});
```

### Batch Writes

Three operations write many rows in a **single request and a single
transaction**. Every row still runs the normal pipeline — callbacks, relations,
row-level security — so a batch is not a shortcut past your own rules; the win
is one round trip and one transaction instead of N of each.

All three are **all-or-nothing**. If any row is rejected, none of them land and
the error names the offending index.

```typescript
// Create
await client.data.products.createMany([
    { name: "Widget", price: 9.99 },
    { name: "Gadget", price: 19.99 }
]);

// Update — each entry names its row and the fields to change
await client.data.orders.updateMany([
    { id: "o-1", data: { status: "shipped" } },
    { id: "o-2", data: { status: "shipped" } }
]);

// Delete — by id
await client.data.sessions.deleteMany(["s-1", "s-2"]);
```

#### Why `{ id, data }` rather than flat rows

`createMany` takes flat rows because a row being created *is* its columns.
`updateMany` names the address separately, because on a table keyed on something
other than `id` — a `sku`, a composite key — a flat row cannot say whether a
column is the address or a value to write. This mirrors single-row
`update(id, data)` exactly.

#### Why `deleteMany` takes ids, not a filter

A filter-shaped bulk delete is a different and far more dangerous operation: the
failure mode is an omitted or mistyped condition emptying a table, and it cannot
be reviewed at the call site the way an explicit list can. Read first, then pass
the ids you meant:

```typescript
const stale = await client.data.sessions.findAll({
    where: { expires_at: ["<", cutoff] }
});
await client.data.sessions.deleteMany(stale.map(s => s.id as string));
```

#### Retries and duplicates

A client that never sees the response cannot know whether the batch committed,
so it retries — and without a key the server cannot tell that retry from a
second genuine batch. Pass an idempotency key on anything that may be resent:

```typescript
const attemptKey = crypto.randomUUID();
await client.data.products.createMany(rows, { idempotencyKey: attemptKey });
```

A key names one request, not a job: it is recorded against the method, the path
and the body it was sent with. Re-sending that exact request replays its answer;
the same key on a different request is refused with `IDEMPOTENCY_KEY_REUSED`
(422). So mint one per call rather than reusing a business id — an `importId`
shared by the `createMany` and the `deleteMany` of one import would leave the
delete silently unperformed.

A retry that arrives while the first attempt is still being answered gets
`IDEMPOTENCY_KEY_IN_PROGRESS` (409): send it again, and it will be answered with
the first attempt's result once that lands. Keys are honoured for 24 hours, and
only for a signed-in caller — there is no principal to scope one to otherwise.

The offline queue sets a key automatically on every replay.

#### Limits

Batches are capped server-side (1000 rows by default), because one batch holds
its locks for the whole transaction. Going over is a `BULK_TOO_LARGE` error that
names both the limit and your row count, so chunk to it:

```typescript
for (const chunk of chunks(rows, 1000)) {
    await client.data.products.createMany(chunk, { upsert: true });
}
```

A data source that cannot write atomically reports `BULK_UNSUPPORTED` rather
than quietly looping single writes — which would give you neither the atomicity
nor the single round trip you reached for a batch to get.

### Fluent Query Builder

Chain methods for more expressive queries:

```typescript
const { data } = await client.data.products
    .where("price", ">=", 100)
    .where("active", "==", true)
    .orderBy("created_at", "desc")
    .limit(10)
    .find();
```

#### Available Methods

| Method | Description | Example |
|--------|-------------|---------|
| `.where(field, op, value)` | Add a filter condition | `.where("age", ">=", 18)` |
| `.orderBy(field, dir)` | Sort results | `.orderBy("name", "asc")` |
| `.limit(n)` | Limit result count | `.limit(25)` |
| `.offset(n)` | Skip first N results | `.offset(50)` |
| `.search(text)` | Text search — see [Search](/docs/backend/search) | `.search("laptop")` |
| `.vectorSearch(prop, vector, opts?)` | Nearest-neighbour search over a `vector` property | `.vectorSearch("embedding", vec)` |
| `.include(...relations)` | Include related entities | `.include("author", "tags")` |
| `.find()` | Execute the query | Returns `FindResponse<M>` |
| `.listen(onUpdate, onError?)` | Subscribe to real-time updates | Returns `unsubscribe()` |

#### Filter Operators

| Operator | Alias | Description |
|----------|-------|-------------|
| `"=="` | `"eq"` | Equal |
| `"!="` | `"neq"` | Not equal |
| `">"` | `"gt"` | Greater than |
| `">="` | `"gte"` | Greater than or equal |
| `"<"` | `"lt"` | Less than |
| `"<="` | `"lte"` | Less than or equal |
| `"in"` | | Value in array |
| `"not-in"` | `"nin"` | Value not in array |
| `"array-contains"` | `"cs"` | Array field contains value |
| `"array-contains-any"` | `"csa"` | Array field contains any of values |

#### Where Clause Syntaxes

The `where` parameter in `find()` supports two formats:

```typescript no-verify
// 1. Tuple syntax — [operator, value] (recommended)
await client.data.products.find({
    where: {
        status: ["==", "active"],
        featured: ["==", true],
        price: [">=", 100],
        category: ["in", ["electronics", "gadgets"]],
        deleted_at: ["!=", null]
    }
});

// 2. Pre-serialized PostgREST string syntax (advanced)
await client.data.products.find({
    where: { status: "eq.published", price: "gte.100" }
});
```

> **Note:** Pre-serialized PostgREST strings (format 2) are an escape hatch for passing filter values that are already in wire format. Prefer tuple syntax for type safety and readability.

### Pagination

```typescript
// Offset-based pagination
const page1 = await client.data.products.find({ limit: 20, offset: 0 });
const page2 = await client.data.products.find({ limit: 20, offset: 20 });

// Check if more pages exist
if (page1.meta.hasMore) {
    // fetch next page
}

// Page-number pagination (1-indexed)
const page = await client.data.products.find({ page: 2, limit: 20 });
```

`limit` must be a whole number between 1 and 1000. A larger one — or a zero,
negative, or fractional one — is refused with a 400 `INVALID_LIMIT` rather than
clamped, because a silently smaller page cannot be told apart from the last one.
To read past that ceiling, walk the pages with `iterate()` or `findAll()`.

### Sorting

```typescript
// Sort by field (format: ["field", "direction"])
const { data } = await client.data.products.find({
    orderBy: ["created_at", "desc"]
});

// Fluent style
const { data } = await client.data.products
    .orderBy("price", "asc")
    .find();
```

### Text Search

```typescript
// Via find params
const { data } = await client.data.products.find({
    searchString: "wireless headphones"
});

// Fluent style
const { data } = await client.data.products
    .search("wireless headphones")
    .limit(10)
    .find();
```

By default this is a **case-insensitive substring match** across the
collection's top-level `string` properties. It is not full-text search: it does
not reach inside `map` or `array` properties, does not stem or rank, and cannot
use an index.

A Postgres collection can opt in to real full-text search by declaring a
`search` block, which also makes results rankable by `_score`. See
[Search](/docs/backend/search).

### Vector Search

For collections with a `vector` property, order rows by similarity to a query
embedding. Rows come back closest-first, each carrying a `_distance`.

```typescript
const { data } = await client.data.docs
    .vectorSearch("embedding", queryVector, { threshold: 0.35 })
    .where("status", "==", "published")
    .limit(10)
    .find();
```

`where` and `orderBy` on the same query act as filters applied *before* the
ordering — this returns the nearest rows that also match, not the nearest rows
filtered afterwards. Producing `queryVector` is your job: Rebase stores and
searches embeddings, it does not compute them.

#### What you have to provide

- **pgvector.** A `vector` property compiles to a `VECTOR(n)` column, and that
  type comes from the `vector` extension. Rebase does not install it — an
  extension needs a server image that carries it and a role allowed to create
  it. The scaffold's `postgres:18-alpine` does **not** ship pgvector; use an
  image that does (for example `pgvector/pgvector:pg18`) and run
  `CREATE EXTENSION vector;` once. Without it the first boot fails, naming this.
- **An index, if you want one.** Rebase creates no HNSW or IVFFlat index, so
  every `vectorSearch` computes the distance for every row and sorts: exact
  results, sequential cost. Create the index yourself in a migration
  (`CREATE INDEX … USING hnsw (embedding vector_cosine_ops)`) if your table is
  large enough to need one.

`vectorSearch` is a query, not a subscription: `.listen()` on one is refused
rather than served as a plain listing, because nothing recomputes distances on a
write.

### Fetching Relations

Relations can be included so that related entities are returned alongside the primary data, instead of just their foreign key IDs.

#### Using `include()` (Fluent)

```typescript
// Include specific relations
const { data } = await client.data.posts
    .include("author", "categories")
    .find();

// Include all defined relations
const { data } = await client.data.posts
    .include("*")
    .find();
```

#### Using `find({ include })` (Params)

```typescript
const { data } = await client.data.posts.find({
    include: ["author", "categories"]
});
```

#### Combining with Filters

```typescript
const { data } = await client.data.posts
    .where("status", "==", "published")
    .include("author")
    .orderBy("published_at", "desc")
    .limit(10)
    .find();
```

#### Reading Relation Data

When relations are included, the response contains **both** the scalar foreign key and the hydrated relation object:

```typescript
const { data } = await client.data
    .collection<{ author_id: string; author?: { name: string } }>("posts")
    .include("author")
    .find();

for (const post of data) {
    // Scalar foreign key — always present
    console.log(post.author_id);    // "uuid-1234"

    // Hydrated relation — present when included
    console.log(post.author?.name); // "Jane Doe"
}
```

> **Note:** Without `.include("author")`, only the scalar `author_id` field is returned. The hydrated `author` object will be `undefined`.

#### Relation Names

The relation names you pass to `include()` must match the `relationName` defined in the collection's `relations` array:

```typescript
// Collection definition
relations: [
    { relationName: "author", target: () => usersCollection, ... },
    { relationName: "categories", target: () => categoriesCollection, ... }
]

// SDK usage — names must match
client.data.articles.include("author", "categories").find()
```

### Custom Endpoints

Call custom server endpoints registered via the functions system:

```typescript
// Using client.functions.invoke()
const result = await client.functions.invoke<{ summary: string }>(
    "generate-summary",
    { articleId: 42 }
);

// With options
const result = await client.functions.invoke<{ status: string }>(
    "process-order",
    { orderId: 123 },
    { method: "POST", path: "status/check" }
);

// Shorthand via client.call()
const result = await client.call<{ summary: string }>(
    "functions/generate-summary",
    { articleId: 42 }
);
```

### Next Steps

- **[Authentication](/docs/sdk/authentication)** — Sign in, sign up, OAuth, sessions
- **[Realtime Subscriptions](/docs/sdk/realtime)** — Live data with WebSockets
- **[Storage & Files](/docs/sdk/storage)** — Upload, download, and manage files
- **[Relations](/docs/collections/relations)** — Define relations between collections

## Authentication

### Overview

The `client.auth` module handles user authentication, token management, and session persistence. Once a user signs in, all subsequent data requests automatically include the JWT.

The SDK persists sessions to `localStorage` by default and automatically refreshes tokens before they expire.

### Email / Password

#### Sign In

```typescript
const { user, accessToken, refreshToken } = await client.auth.signInWithEmail(
    "user@example.com",
    "password"
);
console.log(user.uid, user.email);
```

#### Sign Up

```typescript
const { user } = await client.auth.signUp(
    "user@example.com",
    "password",
    "Jane Doe"   // optional displayName
);
```

### OAuth Providers

The SDK includes dedicated methods for popular OAuth providers, plus a generic `signInWithOAuth()` for any custom provider.

#### Google

Supports three invocation styles:

```typescript
// ID-token flow (One Tap / Sign In With Google button)
await client.auth.signInWithGoogle({ idToken: googleIdToken });

// Access-token flow (popup)
await client.auth.signInWithGoogle({ accessToken: googleAccessToken });

// Authorization code flow (most secure, server-side exchange)
await client.auth.signInWithGoogle({ code: authCode, redirectUri: "https://..." });
```

#### Other Providers

Each provider follows the authorization code flow with `(code, redirectUri)`:

```typescript
await client.auth.signInWithGitHub(code, redirectUri);
await client.auth.signInWithMicrosoft(code, redirectUri);
await client.auth.signInWithFacebook(code, redirectUri);
await client.auth.signInWithLinkedin(code, redirectUri);
await client.auth.signInWithDiscord(code, redirectUri);
await client.auth.signInWithGitLab(code, redirectUri);
await client.auth.signInWithBitbucket(code, redirectUri);
await client.auth.signInWithSlack(code, redirectUri);
await client.auth.signInWithSpotify(code, redirectUri);
```

Apple and Twitter require additional parameters:

```typescript
// Apple — optional user info from first sign-in
await client.auth.signInWithApple(code, redirectUri, {
    name: { firstName: "Jane", lastName: "Doe" },
    email: "jane@example.com"
});

// Twitter — requires PKCE code verifier
await client.auth.signInWithTwitter(code, redirectUri, codeVerifier);
```

#### Generic OAuth

For any provider registered on the backend:

```typescript
await client.auth.signInWithOAuth("custom-provider", {
    code: authCode,
    redirectUri: "https://myapp.com/callback"
});
```

### Sign Out

```typescript
await client.auth.signOut();
```

This revokes the refresh token on the server, clears the local session, and emits a `SIGNED_OUT` event.

### Session Management

#### Get Current Session

```typescript
const session = client.auth.getSession();
// { accessToken, refreshToken, expiresAt, user } | null
```

#### Get Current User (Server-Verified)

```typescript
const user = await client.auth.getUser();
// Fetches the user from the backend (GET /auth/me)
```

#### Update User Profile

```typescript
const updatedUser = await client.auth.updateUser({
    displayName: "Jane Doe",
    photoURL: "https://example.com/avatar.jpg"
});
```

#### Refresh Token

Token refresh happens automatically, but you can trigger it manually:

```typescript
const session = await client.auth.refreshSession();
```

### Auth State Listener

React to authentication changes across your application:

```typescript
const unsubscribe = client.auth.onAuthStateChange((event, session) => {
    // event: "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "USER_UPDATED"
    console.log("Auth event:", event);
    console.log("Session:", session?.user?.email);
});

// Stop listening
unsubscribe();
```

### Password Management

#### Forgot Password

```typescript
const { success, message } = await client.auth.resetPasswordForEmail(
    "user@example.com"
);
```

#### Reset Password (with Token)

```typescript
const { success, message } = await client.auth.resetPassword(
    resetToken,
    "newSecurePassword"
);
```

#### Change Password (Authenticated)

```typescript
const { success, message } = await client.auth.changePassword(
    "oldPassword",
    "newPassword"
);
```

### Email Verification

```typescript
// Send verification email to the current user
await client.auth.sendVerificationEmail();

// Verify with the token from the email link
await client.auth.verifyEmail(token);
```

### Session Management (Multi-Device)

```typescript
// List all active sessions
const sessions = await client.auth.getSessions();

// Revoke a specific session
await client.auth.revokeSession(sessionId);

// Revoke ALL sessions (logs out everywhere)
await client.auth.revokeAllSessions();
```

### Auth Configuration

Query the backend's authentication configuration:

```typescript
const config = await client.auth.getAuthConfig();
// {
//   needsSetup: boolean,
//   registrationEnabled: boolean,
//   emailServiceEnabled?: boolean,
//   passwordReset?: boolean,
//   emailVerification?: boolean,
//   enabledProviders: string[]
// }
```

### Custom Session Storage

By default, sessions are stored in `localStorage`. You can customize this with the `auth` option:

```typescript

// Use cookies instead of localStorage
const client = createRebaseClient({
    baseUrl: "http://localhost:3001",
    auth: {
        storage: createCookieStorage({
            path: "/",
            sameSite: "Lax",
            secure: true
        }),
        autoRefresh: true,       // default: true
        persistSession: true     // default: true
    }
});
```

### User Object Shape

```typescript
// Canonical type — import from @rebasepro/types
interface User {
    uid: string;
    email: string | null;
    displayName: string | null;
    photoURL: string | null;
    providerId: string;
    isAnonymous: boolean;
    emailVerified?: boolean;
    roles?: string[];          // text[] from the users table
    metadata?: Record<string, unknown>;
}
```

### Next Steps

- **[Querying Data](/docs/sdk/querying)** — CRUD operations and query builder
- **[Realtime Subscriptions](/docs/sdk/realtime)** — Live data with WebSockets
- **[Authentication Backend](/docs/backend/authentication)** — Server-side auth configuration

## Realtime Subscriptions

### Overview

The Rebase Client SDK provides real-time data subscriptions via WebSocket. When records change on the server, your subscribed callbacks fire immediately with the updated data.

The WebSocket connection is established automatically when a `websocketUrl` is available (derived from `baseUrl` by default). Reconnection and token refresh are handled transparently.

### Subscribing to a Collection

Use `listen()` to subscribe to a collection query. The callback fires whenever the matching data set changes:

```typescript
const unsubscribe = client.data.products.listen(
    { where: { active: ["==", true] }, limit: 50 },
    (response) => {
        console.log("Products updated:", response.data);
        console.log("Total:", response.meta.total);
    }
);

// Stop listening when done
unsubscribe();
```

The `listen()` method accepts the same `FindParams` as `find()` — you can filter, sort, and paginate your subscription:

```typescript
const unsubscribe = client.data.orders.listen(
    {
        where: { status: ["==", "pending"] },
        orderBy: ["created_at", "desc"],
        limit: 20
    },
    (response) => {
        renderOrders(response.data);
    },
    (error) => {
        console.error("Subscription error:", error);
    }
);
```

#### Signature

```typescript no-verify
listen(
    params: FindParams | undefined,
    onUpdate: (response: FindResponse<M>) => void,
    onError?: (error: Error) => void
): () => void   // returns unsubscribe function
```

#### Two-Phase Meta

When `listen()` fires, it emits updates in up to two phases:

1. **Immediate (estimated):** The first callback fires instantly with the entities and heuristic pagination metadata (`total` = number of returned entities, `hasMore` = whether the count equals the requested limit). This emission carries `meta.total: true`.

2. **Authoritative (optional):** An async count query runs in the background. If the authoritative `total` or `hasMore` differs from the estimate, a second callback fires with corrected metadata and **no** `estimated` flag. If the values match, the second emission is skipped entirely — your callback fires only once.

If the count query **fails**, no second emission occurs. The first emission's `estimated: true` flag remains as the signal that the metadata is heuristic. This is not treated as a subscription error.

```typescript
client.data.products.listen(
    { where: { active: ["==", true] }, limit: 50 },
    (response) => {
        if (response.meta.total) {
            // First-paint: render immediately, total/hasMore may change
            renderProducts(response.data, { loading: true });
        } else {
            // Authoritative: safe to render final pagination controls
            renderProducts(response.data, { loading: false });
        }
    }
);
```

> **Tip:** If you don't need to distinguish between estimated and authoritative metadata, you can ignore the `estimated` flag — both emissions carry the same `data` array.

### Subscribing to a Single Entity

Use `listenById()` to watch a specific record by its ID:

```typescript
// The SDK hands back a flat row, not an `Entity` — there is no `.values`.
const unsubscribe = client.data
    .collection<{ id: number; name: string }>("products")
    .listenById!(
    42,
    (product) => {
        if (product) {
            console.log("Product changed:", product.name);
        } else {
            console.log("Product was deleted");
        }
    },
    (error) => {
        console.error("Subscription error:", error);
    }
);
```

#### Signature

```typescript no-verify
listenById(
    id: string | number,
    onUpdate: (entity: Entity<M> | undefined) => void,
    onError?: (error: Error) => void
): () => void   // returns unsubscribe function
```

The callback receives `undefined` when the entity is deleted.

### Fluent Query Builder

You can also subscribe through the fluent query builder. This is equivalent to calling `listen()` with params, but lets you chain `.where()`, `.orderBy()`, etc.:

```typescript
const unsubscribe = client.data.products
    .where("active", "==", true)
    .orderBy("created_at", "desc")
    .limit(20)
    .listen(
        (response) => console.log("Updated:", response.data),
        (error) => console.error("Error:", error)
    );
```

### Unsubscribing

Every subscription returns an `unsubscribe` function. Call it to stop receiving updates and clean up the WebSocket listener:

```typescript
const unsubscribe = client.data.products.listen(
    undefined,
    (response) => { /* ... */ }
);

// Later, when the component unmounts or you no longer need updates:
unsubscribe();
```

In React, use `useEffect` cleanup:

```tsx
useEffect(() => {
    const unsubscribe = client.data.products.listen(
        { where: { active: ["==", true] } },
        (response) => setProducts(response.data)
    );
    return () => unsubscribe();
}, []);
```

### Authentication and Reconnection

The WebSocket client handles authentication automatically:

- On **sign-in** or **token refresh**, the new token is sent to an already-open socket via an `authenticate` message. If none is open, nothing happens — signing in is not a request for realtime, and a socket opened later authenticates itself.
- On **sign-out**, the WebSocket connection is disconnected. The client stays usable; a later subscription reconnects anonymously.
- If the connection drops, the client **reconnects automatically** and re-establishes all active subscriptions.

No manual token management is needed — the integration between `client.auth` and the WebSocket layer is handled internally.

#### The connection is lazy

Creating a client opens **no** WebSocket. It is dialled on the first operation that actually needs one — a `listen()` / `listenById()` subscription, or a channel operation such as `join()`, `track()` or `broadcast()`. Obtaining a channel is not using it.

```typescript
const client = createRebaseClient({ baseUrl });   // no socket
const channel = client.realtime.channel("doc:1"); // still no socket
await channel.join();                             // socket opens here
```

This matters for apps with meaningful signed-out traffic — marketing pages, public read-only views, anonymous-first tools — which previously paid a connection on every page load simply to have realtime available.

Two related behaviours:

- `realtime: false` remains a hard opt-out: no socket ever, and `client.realtime.channel()` throws.
- `client.close()` is final. It releases the socket and its reconnect timer, and nothing queued afterwards will redial. In Node, an open socket keeps the event loop alive, so a script that never calls it will not exit on its own.

### Broadcast Channels

Broadcast channels let you send arbitrary messages between connected clients — ideal for chat, notifications, or collaborative features:

```typescript
// Obtain a channel. This alone opens no connection.
const channel = client.realtime.channel("chat-room");

// Listen for broadcasts. Pass an event name to filter, or omit it for all.
channel.onBroadcast("message", (payload) => {
    console.log("New message:", payload);
});

// Send to every other member — the sender never receives its own message.
await channel.broadcast("message", {
    text: "Hello, world!",
    userId: currentUser.id
});

// Leave, releasing handlers and timers.
await channel.leave();
```

Channels are lightweight and ephemeral — they exist as long as at least one client is subscribed. Repeated `channel()` calls with the same name return the **same** object, so two components can attach handlers independently without either cutting the other off by leaving.

Channel and presence frames do not require an account: anonymous visitors can join public channels.

:::caution[Channels have no access rules yet]
The only check the server applies is **membership**: to broadcast into a channel, read its presence roster or replay its history, a client must have joined that channel first. Joining itself is open — any client that can name a channel can join it, whether or not it is signed in.

So a channel name is not a secret and is not a permission. Do not put anything in a channel (including retained history and presence state) that every user of your app may not see, and do not derive a channel name from data you would not hand out. Per-channel authorization rules are not implemented; if you need them today, keep the sensitive half of the exchange on `client.data`, where row-level security applies.
:::

> **By default, broadcasts are not replayed.** They reach currently-connected members only. That is what you want for notifications that self-correct — a "someone saved" nudge is superseded by the next save — and it costs nothing. For an operation stream, where a silent gap causes divergence, enable [message history](#message-history-and-catch-up) on the channel.

### Message History and Catch-Up

A channel can be configured to keep its broadcasts, so a client that reconnects catches up on what it missed instead of resyncing from scratch. This is what makes channels usable as a transport for collaborative editing.

Retention is configured **on the server**, per channel pattern — see [Realtime Backend](/docs/backend/realtime#channel-retention). A client cannot turn it on for itself, because a channel is created by whoever names it, and a client-chosen history depth would let any visitor commit your backend to unbounded storage.

On a retained channel, pass `{ history: true }` and the SDK does the rest:

```typescript
const channel = client.realtime.channel("doc:42", { history: true });

// Handlers receive replayed messages exactly like live ones, in order.
channel.onBroadcast("op", (payload) => {
    applyOperation(payload);
});

await channel.join();
```

On `join()` and after every reconnect, the SDK asks the server for everything after the last sequence number it saw, and delivers the result through the same handlers. There is no second code path to write: a handler that applies an operation correctly when live applies it correctly on catch-up.

#### Sequence numbers

Every broadcast on a retained channel carries a `seq` — per-channel, gapless, and increasing. It is the client's resume point.

```typescript
channel.onBroadcast((event) => {
    console.log(event.seq);       // 1, 2, 3, …
    console.log(event.replayed);  // true when delivered by catch-up
});

console.log(channel.sequence); // highest seq delivered so far
```

Persist `channel.sequence` if you want catch-up to survive a page reload as well as a reconnect, and pass it back via `history({ sinceSeq })`.

#### Fetching history explicitly

```typescript
const { messages, retained, latestSeq } = await channel.history({
    sinceSeq: 0,
    limit: 100
});
```

`retained: false` means the channel keeps no history and never will — an explicit answer, so you can tell "you missed nothing" apart from "this channel has no retention rule". In the second case a client that needs to converge has to fall back to a full resync.

`latestSeq` is the highest sequence the server holds, whether or not this batch reached it. If it is far beyond your last delivered `seq`, you are further behind than one page and resyncing may be cheaper than paging.

:::note[Replays can overlap, and that is fine]
The server cannot know exactly which messages reached you before the socket dropped, so a catch-up range may include some you already applied. The SDK discards anything at or below the sequence it has already delivered, so handlers never see a message twice.

Your own messages are **not** filtered out of a replay: a reconnect assigns a new client id, so the very case catch-up exists for is the one where that filter would fail. Make operations idempotent if re-applying your own would be a problem.
:::

### Presence Tracking

Presence lets you track which users are online and sync shared state across all participants:

```typescript
const channel = client.realtime.channel("editors");

// Publish your presence. This is also what opens the connection.
await channel.track({
    userId: currentUser.id,
    status: "editing",
    cursor: { x: 100, y: 200 }
});

// One handler for every change. `presences` is always the full roster;
// `diff` is what changed, when you only care about the delta.
channel.onPresence((presences, diff) => {
    console.log("Online users:", Object.keys(presences));
    if (diff) {
        console.log("joined:", Object.keys(diff.joins));
        console.log("left:", Object.keys(diff.leaves));
    }
});

// Calling track() again replaces your state — this is how you publish a
// moving cursor.
await channel.track({ userId: currentUser.id, status: "idle" });

// Stop publishing without leaving the channel.
await channel.untrack();
```

The SDK keeps the roster for you, so `presences` is always complete and you never reassemble it from diffs.

It also handles two protocol details that are easy to get wrong when working against the raw WebSocket:

- **The roster is not pushed on join.** A joining client's first `presence_diff` contains only itself; the existing roster must be requested explicitly. `join()` does that for you.
- **Presence expires after 30 seconds.** `track()` is not a durable registration — without a periodic re-send you silently disappear from everyone else's roster while still connected and still on the page. The SDK heartbeats at 20s, and stops on `untrack()` / `leave()`.

A reconnect also drops server-side channel membership and presence; the SDK re-joins, re-requests the roster and re-tracks automatically.

### When to Use Realtime

| Use Case | Method |
|----------|--------|
| Dashboard with live data | `listen()` with filters |
| Chat or messaging | `channel.broadcast()` |
| Collaborative editing / operation streams | `channel(name, { history: true })` |
| Typing indicators / online status | `channel.track()` + `channel.onPresence()` |
| Detail page with live updates | `listenById()` |
| Admin panel monitoring | `listen()` with `orderBy` and `limit` |
| A list that must survive a dropped connection | `observe()` with [offline](/docs/sdk/offline) enabled |

> **Tip:** For one-time data fetches, use `find()` or `findById()` instead. Subscriptions are best for data that changes frequently and needs to be reflected in the UI immediately.

### `listen()` vs `observe()`

Both keep a query current, and both return an unsubscribe function — but they answer different questions.

`listen()` is the socket: it delivers what the server pushes, and delivers nothing when the socket is down.

`observe()` is the query: with [offline](/docs/sdk/offline) enabled it emits from the local database first — before any request — and re-emits on local writes, on queued writes reaching the server, on rollbacks, and on realtime events, which it subscribes to itself unless you pass `{ realtime: false }`. Each result says whether it came from the cache and whether it carries writes the server has not accepted yet.

```typescript
const unsubscribe = client.data.products.observe(
    { where: { active: ["==", true] } },
    (result) => {
        render(result.data);
        setSaving(result.hasPendingWrites);
    }
);
```

Without offline enabled, `observe()` is `find()` plus `listen()` in one call, with those flags always `false`.

### Next Steps

- **[Querying Data](/docs/sdk/querying)** — CRUD operations and query builder
- **[Offline & Local-First Sync](/docs/sdk/offline)** — Live queries that survive a dropped connection
- **[Authentication](/docs/sdk/authentication)** — Sign in and session management
- **[Realtime Backend](/docs/backend/realtime)** — Server-side WebSocket configuration

## Offline & Local-First Sync

### Overview

Offline support turns the SDK's data layer into a **local-first sync engine**. Instead of a cache that remembers responses, the client keeps a small local database of rows, answers queries against it, and treats the network as something that fills it in and eventually accepts your writes.

Three things follow from that:

- **Reads survive the network going away.** A query the client can evaluate locally is evaluated locally — filters, sorting and pagination included — so a list keeps rendering with a dead connection.
- **Writes are decided locally.** A write made offline applies immediately, queues, and replays in order when the connection returns. If the server rejects it, the local change is rolled back.
- **Reads are reactive.** `observe()` emits from the local database first and re-emits whenever anything changes the rows it covers — your own writes, a queued write landing, a rollback, another browser tab, or a realtime event.

It is off by default. Turn it on with one option:

```typescript
const client = createRebaseClient({
    baseUrl: "https://api.example.com",
    offline: true
});
```

In the browser everything persists to IndexedDB, so a reload keeps both the local rows and the unsent writes. Elsewhere (Node, tests) it falls back to memory; other runtimes can supply their own store.

### What changes

Nothing in the API you already use changes shape. `find()`, `findById()`, `create()`, `update()`, `delete()` and the fluent builder keep their signatures and their return types — they just stop failing when the network does.

#### Reads

A successful read merges its rows into the local database and remembers which ids the server returned for that query. When a read cannot reach the server, it is answered locally:

```typescript
const drafts = await client.data.posts
    .where("status", "==", "draft")
    .orderBy("updated_at", "desc")
    .find();
```

Offline, this filters and sorts the rows the client holds. That includes rows fetched by *other* queries — the database is normalized, so a row is stored once no matter how many lists it appeared in — and rows you created offline.

If there is genuinely nothing to answer with (a collection the app has never read), the read throws a recognisable error rather than a bare `TypeError`:

```typescript

try {
    await client.data.posts.find();
} catch (error) {
    if (isOfflineError(error)) showOfflinePlaceholder();
    else throw error;
}
```

#### Writes

While the connection is known to be down, a write is not even attempted — it applies locally and queues, so it costs nothing instead of a timeout:

```typescript
// Returns immediately, offline or not.
const post = await client.data.posts.create({ title: "Draft", status: "draft" });

// Shows up in every matching list, right away.
const drafts = await client.data.posts.where("status", "==", "draft").find();
```

Rows created offline get a client-generated id. If the server assigns its own on replay, the local row and any queued writes still pointing at the temporary id are moved to the real one.

Writes replay in the order you made them, across collections — so a create in one collection still lands before the row in another that references it.

### Live queries

`observe()` is the reactive read, and the one to reach for in a UI:

```typescript
const unsubscribe = client.data.posts.observe(
    { where: { status: ["==", "draft"] }, orderBy: ["updated_at", "desc"] },
    (result) => {
        render(result.data);
        setBadge(result.hasPendingWrites ? "saving…" : null);
    }
);
```

The first emission comes from the local database with no request in the way; a revalidation follows in the background. After that it re-emits on every change to the rows it covers. Emissions are de-duplicated — a refresh that changes nothing does not call back — so it is safe to render straight from it.

Each result carries what a UI needs to describe itself:

| Field | Meaning |
|-------|---------|
| `data`, `meta` | The same shape `find()` returns |
| `fromCache` | The rows came from the local database, not a completed request |
| `hasPendingWrites` | At least one row here carries a write the server has not accepted |
| `partial` | The local database may not hold every matching row — treat as best effort |
| `error` | The last revalidation failed |

`observeById()` does the same for a single row, and passes `undefined` when it is deleted.

Both bind the realtime subscription when the client has one, so changes made by other users stream in too. Pass `{ realtime: false }` for a subscription that only reflects local state and explicit refreshes.

Without `offline` enabled, `observe()` still exists: it fetches once and stays live off realtime, with all three flags `false`.

### Sync state

`client.offline` exposes the engine, which is what a sync indicator is built from:

```typescript
const unsubscribe = client.offline!.onStatusChange((status) => {
    setOnline(status.online);
    setPending(status.pending);
    setSyncing(status.syncing);
});

// Or read it once
const { online, pending, syncing, lastSyncedAt, lastError } = client.offline!.status();
```

| Method | Purpose |
|--------|---------|
| `status()` | Current connectivity, queue depth, sync activity, last error |
| `onStatusChange(fn)` | Subscribe to the above |
| `onQueueChange(fn)` | Just the number of unsent writes, for a badge |
| `pending()` | The queued mutations themselves, oldest first |
| `sync()` | Replay now — resolves with `{ flushed, remaining }` |
| `clear()` | Discard the current user's queued writes **and** local rows |

Replay happens on its own: when the browser fires `online`, when the user signs in, and on an exponential backoff (one second, doubling to a minute) while anything is queued. `sync()` is for a "retry now" button.

### When the server says no

A queued write can be rejected — validation, row-level security, a row someone else deleted. Those never resolve on their own, so the engine rolls the local rows back to what they were before the write, discards the queued edits that were built on top of it, and tells you:

```typescript
const client = createRebaseClient({
    baseUrl: API_URL,
    offline: {
        onSyncError: (error, mutation) => {
            toast(`Couldn't save your change to ${mutation.collection}: ${error.message}`);
        }
    }
});
```

The cascade is narrow: an `update` is discarded along with the write it edited, because it can only fail the same way. A later `create` or `delete` for the same row stands on its own and is kept.

A failure that is merely temporary — a 429, a 503, a dropped connection — is not a rejection. Those stay queued and are retried; only after `maxRetries` deferrals does a write get rolled back.

### Multiple tabs

Tabs of the same app share one IndexedDB database, so they share the local rows and the outbox. A write in one appears in the others, and only one tab at a time replays the queue. Nothing to configure.

### Users

The local database and the outbox are partitioned per signed-in user. Cached rows are whatever row-level security let that user see, and a queued write has to replay as its author — so signing out and back in as someone else never mixes the two. Signing out does not need to clear anything.

### Configuration

```typescript
createRebaseClient({
    baseUrl: API_URL,
    offline: {
        store: myCustomStore,                 // default: IndexedDB in the browser, memory elsewhere
        maxCachedRowsPerCollection: 5000,     // rows with unsent writes are never evicted
        maxCachedQueriesPerCollection: 50,    // remembered server page compositions
        syncIntervalMs: 60_000,               // ceiling for the retry backoff; 0 disables auto-retry
        maxRetries: 5,                        // deferrals before a write is given up on
        crossTab: true,                       // default: on for IndexedDB, off for memory
        onSyncError: (error, mutation) => {}
    }
});
```

#### A custom store

Any environment can persist the local database by implementing `OfflineStore` — a namespaced key/value surface with a read-cache area and a queue area. This is how you back it with AsyncStorage in React Native, or with the filesystem in Electron:

```typescript no-verify

class AsyncStorageOfflineStore implements OfflineStore {
    // Read cache: getCache, setCache, setCacheMany, deleteCache,
    //             listCache, listCacheEntries
    // Outbox:     enqueue, dequeue, listQueue
    // Both:       clear
}
```

The only contract beyond the obvious is that prefix listings come back in lexicographic key order — that is what makes the outbox a FIFO.

### Limits

The client is not a replica of your database, and it does not pretend to be:

- **Only rows the app has read or written are local.** A query the client has never sent can still be answered from what it holds, but the answer may be missing rows the server would have returned. Live results say so via `partial`.
- **`searchString` is approximated** as a case-insensitive substring scan over cached string fields. The server runs real full-text search over the collection's configured columns.
- **`include`d relations cannot be evaluated locally** — the related rows live in collections the query never loaded. Such a query is always marked `partial` when answered from the cache.
- **Replay is at-least-once.** A write that reaches the server but whose response is lost may be sent again. Prefer idempotent writes (`createMany` with `upsert`) where duplicates would matter.
- **Local reads apply Postgres semantics, not the database's data.** Filters are evaluated the way SQL would — comparisons against `NULL` are unknown, `ORDER BY` puts nulls last ascending — but against the client's copy of the rows, which may be stale.

### Recipe: an offline indicator

```tsx

export function SyncIndicator({ client }: { client: CreateRebaseClientResult }) {
    const offline = client.offline!;
    const [status, setStatus] = React.useState(offline.status());
    React.useEffect(() => offline.onStatusChange(setStatus), [offline]);

    if (!status.online) {
        return <span className="badge warning">
            Offline{status.pending ? ` · ${status.pending} unsaved` : ""}
        </span>;
    }
    if (status.syncing) return <span className="badge">Syncing…</span>;
    if (status.pending) return <span className="badge">{status.pending} unsaved</span>;
    return null;
}
```

### See also

- [Querying Data](/docs/sdk/querying) — the query surface `observe()` shares with `find()`
- [Realtime Subscriptions](/docs/sdk/realtime) — server-pushed updates, which live queries build on

## Storage & Files

### Overview

The `client.storage` module provides methods for file management — upload, download, listing, and deletion. It works with both local disk and S3-compatible storage backends, depending on your server configuration.

All storage methods use the shared transport, so authentication tokens are injected automatically.

### Upload a File

Use `putObject()` to upload a file. It accepts a `File` or `Blob` object along with an optional storage key and metadata:

```typescript
const result = await client.storage.putObject({
    file: fileObject,                   // File or Blob
    key: "products/images/camera.jpg",  // Storage path (optional)
    bucket: "uploads",                  // Bucket name (optional)
    public: false,                      // Store public (permanent token-less URL) — optional, default false
    metadata: {                         // Custom metadata (optional)
        description: "Product photo",
        uploadedBy: "user-123"
    }
});

// result: { key: string, url: string, ... }
```

#### From a File Input

```typescript
const input = document.querySelector<HTMLInputElement>("#file-input");
const file = input?.files?.[0];

if (file) {
    const result = await client.storage.putObject({
        file,
        key: `avatars/${userId}/${file.name}`
    });
    console.log("Uploaded to:", result.key);
}
```

### Get a Signed URL

Retrieve a download URL and metadata for a stored file:

```typescript
const { url, metadata, fileNotFound } = await client.storage.getSignedUrl(
    "products/images/camera.jpg"
);

if (url) {
    console.log("Download URL:", url);
    console.log("Content type:", metadata?.contentType);
} else {
    console.log("File not found");
}
```

With a specific bucket:

```typescript
const { url } = await client.storage.getSignedUrl(
    "camera.jpg",
    "product-images"   // bucket
);
```

The SDK caches signed URLs to avoid redundant server calls.

#### Private vs. public URLs

- **Private files** get a URL with a **short-lived, path-scoped download token** (`?token=…`, default 5 min) — never your access token. Because it expires, **don't persist a private URL**; store the file **path** and call `getSignedUrl()` again when you render it.
- **Public files** (stored under the `public/` prefix — set `storage: { public: true }` on the property, or pass `public: true` to `putObject`) get a **stable, token-less, permanent, CDN-cacheable** URL with no server round-trip. These are safe to store in a database and hotlink.

### Download a File

Retrieve a file as a `File` object:

```typescript
const file = await client.storage.getObject("products/images/camera.jpg");

if (file) {
    console.log("File name:", file.name);
    console.log("File type:", file.type);
    console.log("File size:", file.size);

    // Create a download link
    const url = URL.createObjectURL(file);
    window.open(url);
} else {
    console.log("File not found");
}
```

With a specific bucket:

```typescript
const file = await client.storage.getObject("camera.jpg", "product-images");
```

### Delete a File

```typescript
await client.storage.deleteObject("products/images/camera.jpg");

// With bucket
await client.storage.deleteObject("camera.jpg", "product-images");
```

Deleting a non-existent file does not throw an error.

### List Files

List files by prefix, with optional pagination:

```typescript
const result = await client.storage.listObjects("products/images/", {
    bucket: "uploads",
    maxResults: 50,
    pageToken: undefined   // for pagination
});

for (const item of result.items) {
    console.log(item.fullPath, item.name);
}

// Paginate
if (result.nextPageToken) {
    const nextPage = await client.storage.listObjects("products/images/", {
        pageToken: result.nextPageToken
    });
}
```

### Storage Key Formats

The SDK transparently handles storage key prefixes. You can pass keys with or without the protocol prefix:

```typescript
// All equivalent — the SDK strips the prefix internally
await client.storage.getSignedUrl("local://products/image.jpg");
await client.storage.getSignedUrl("s3://products/image.jpg");
await client.storage.getSignedUrl("products/image.jpg");
```

### API Reference

| Method | Description | Returns |
|--------|-------------|---------|
| `putObject({ file, key?, bucket?, metadata? })` | Upload a file | `UploadFileResult` |
| `getSignedUrl(key, bucket?)` | Get download URL + metadata | `DownloadConfig` |
| `getObject(key, bucket?)` | Download as `File` object | `File \| null` |
| `deleteObject(key, bucket?)` | Delete a file | `void` |
| `listObjects(prefix, options?)` | List files by prefix | `StorageListResult` |

### Next Steps

- **[Storage Configuration](/docs/backend/storage)** — Configure S3 or local storage on the server
- **[Querying Data](/docs/sdk/querying)** — CRUD operations and query builder
- **[Authentication](/docs/sdk/authentication)** — Sign in and session management

## CLI Reference

### Overview

The Rebase CLI (`rebase`) manages your project from scaffolding to deployment.

### Installation

```bash
pnpm add -g @rebasepro/cli
```

Or use via `pnpm dlx`:

```bash
pnpm dlx @rebasepro/cli <command>
```

### Commands

#### `rebase init`

Initialize a new Rebase project:

```bash
rebase init [directory]
```

Sets up the project structure with frontend, backend, and shared packages.

#### `rebase dev`

Start the development server:

```bash
rebase dev
```

Starts both frontend and backend with hot reloading.

#### `rebase schema generate`

Generate Drizzle ORM schema from your TypeScript collections:

```bash
rebase schema generate
```

This reads your collections from `config/collections/` and generates `backend/src/schema.generated.ts` with Drizzle table definitions, enums, and relations.

#### `rebase db push`

Push schema changes directly to the database (development only):

```bash
rebase db push
```

:::caution
`db push` modifies the database directly without migration files. Use `db generate` + `db migrate` for production.
:::

#### `rebase db generate`

Generate SQL migration files from schema changes:

```bash
rebase db generate
```

Creates timestamped migration files in `drizzle/` that can be reviewed and committed.

#### `rebase db migrate`

Run pending database migrations:

```bash
rebase db migrate
```

Applies all unapplied migrations to the database.

#### `rebase db studio`

Open Drizzle Studio to browse your database visually:

```bash
rebase db studio
```

#### `rebase generate-sdk`

Generate a typed client SDK from your collection definitions:

```bash
rebase generate-sdk
```

Creates TypeScript types and a type-safe client for all your collections.

#### `rebase doctor`

Run diagnostics to detect drift between your collections, the generated schema, and the current database state:

```bash
rebase doctor
```

#### `rebase auth`

Authentication management commands:

```bash
rebase auth create-user --email admin@example.com --password secret
rebase auth reset-password --email admin@example.com
```

### Migration Workflow

The typical workflow for schema changes:

```bash
# 1. Edit your collection in config/collections/
# 2. Generate the Drizzle schema
rebase schema generate

# 3. Generate SQL migration
rebase db generate

# 4. Review the generated SQL in drizzle/

# 5. Apply the migration
rebase db migrate
```

### Next Steps

- **[Schema as Code](/docs/architecture/schema-as-code)** — How schema generation works
- **[Quickstart](/docs/getting-started/quickstart)** — Get started

## Schema Generation

### Overview

Rebase uses a **schema-as-code** pipeline where your TypeScript collection definitions are the single source of truth. The CLI transforms them through a deterministic pipeline:

```
Collections (TypeScript) → Drizzle Schema → SQL Migrations → PostgreSQL
```

This page covers every CLI command involved in that pipeline.

### The Pipeline

#### 1. Collections → Drizzle Schema

Your collection definitions in `config/collections/` describe tables, columns, types, relations, and enums. The `schema generate` command reads these and outputs a Drizzle ORM schema file.

#### 2. Drizzle Schema → Migrations

From the generated Drizzle schema, `db generate` diffs against the current database state and produces timestamped SQL migration files.

#### 3. Migrations → PostgreSQL

The `db migrate` command applies pending migrations to your PostgreSQL database.

### Commands

#### `rebase schema generate`

Generate a Drizzle ORM schema file from your collection definitions:

```bash
rebase schema generate
```

**What it does:**
- Reads all collections from `config/collections/`
- Generates `backend/src/schema.generated.ts` with Drizzle table definitions, enums, and relations

**Options:**

| Flag | Description |
|------|-------------|
| `--collections, -c` | Path to collections directory (default: `config/collections/`) |
| `--output, -o` | Output path for the generated schema file |
| `--watch, -w` | Watch for changes and regenerate automatically |

**Watch mode** is useful during development — edit a collection file and the schema regenerates instantly:

```bash
rebase schema generate --watch
```

#### `rebase schema introspect`

Reverse-engineer collection definitions from an existing PostgreSQL database:

```bash
rebase schema introspect
```

**What it does:**
- Connects to your database (using the connection string from your `.env`)
- Inspects all tables, columns, types, and foreign keys
- Generates collection definition files

**Options:**

| Flag | Description |
|------|-------------|
| `--output, -o` | Output directory for generated collection files |

This is useful when adopting Rebase on an existing database — introspect first, then customize the generated collections.

#### `rebase db push`

Push schema changes directly to the database without migration files:

```bash
rebase db push
```

**What it does:**
- Reads the generated Drizzle schema
- Applies changes directly to the database (CREATE, ALTER, DROP)
- Applies your collections' RLS policies, and **removes policies an earlier push superseded**
- Does **not** create migration files

:::note[Editing a security rule renames its policy]
A rule without an explicit `name` compiles to `<table>_<op>_<hash>`, where the hash covers the rule's semantics — so *editing* a rule (rather than adding one) produces a policy under a new name and leaves the old one behind.

That used to matter a great deal: Postgres ORs `PERMISSIVE` policies together, so a superseded `USING (rebase.uid() IS NOT NULL)` kept granting everything no matter how tight its replacement was. Tightening a rule had no effect, and push reported success.

`db push` now reconciles this: it drops generated policies that no longer match any rule, and reports — without dropping — any custom-named policy your collections don't describe, since those are indistinguishable from SQL someone wrote deliberately.

To audit a database that was pushed before this landed, run `rebase doctor --policies`. It works as a CI gate: it exits non-zero on drift, and also when it could not run the check at all — no `DATABASE_URL`, a `--collections` path that does not resolve, a `pg_policies` read the CI role is not granted. A gate that could not look has not passed.
:::

:::caution
`db push` modifies the database directly. Use it only in development. For production, use `db generate` + `db migrate` to create reviewable migration files.
:::

#### `rebase db generate`

Generate SQL migration files from schema changes:

```bash
rebase db generate
```

**What it does:**
- Compares the Drizzle schema against the current database state
- Produces timestamped SQL migration files in the `drizzle/` directory
- Files can be reviewed, edited, and committed to version control

The generated migrations are plain SQL files — you can inspect and modify them before applying.

#### `rebase db migrate`

Run all pending migrations:

```bash
rebase db migrate
```

**What it does:**
- Reads the `drizzle/` directory for unapplied migrations
- Applies them in order to the database
- Tracks which migrations have been applied

#### `rebase db studio`

Open Drizzle Studio to browse and edit your database visually:

```bash
rebase db studio
```

#### `rebase db branch`

Database branching for parallel development:

```bash
rebase db branch create feature_auth
rebase db branch list
rebase db branch delete feature_auth
```

#### `rebase doctor`

Detect three-way drift between your collection definitions, the generated Drizzle schema, and the live PostgreSQL database:

```bash
rebase doctor
```

**What it checks:**
- Collections ↔ Generated schema — are they in sync?
- Generated schema ↔ Database — are there unapplied changes?
- Collections ↔ Database — is there any unexpected drift?

Run `doctor` whenever something feels out of sync. It pinpoints exactly where the mismatch is.

The database comparison needs `DATABASE_URL` (or `ADMIN_CONNECTION_STRING`). Without one, that phase is reported as **skipped** rather than passing, and the run never closes with "All schemas are in sync" — a check that did not happen is not a clean bill of health.

#### `rebase generate-sdk`

Generate a typed client SDK from your collection definitions:

```bash
rebase generate-sdk
```

**What it does:**
- Reads collections from `config/collections/` (supports `index.ts` barrel exports or individual files)
- Generates TypeScript types for all entities in `generated/sdk/`
- Produces a `database.types.ts` file for use with `createRebaseClient<Database>()`

**Options:**

| Flag | Description |
|------|-------------|
| `-c`, `--collections-dir` | Path to the collections directory (default: `config/collections/`) |
| `-o`, `--output` | Output directory for the SDK (default: `generated/sdk/`) |
| `--from <link\|url>` | Read the schema from a running project instead of local source. `link` uses this checkout's linked project. |
| `--token` | Bearer token for the contract endpoint (default: `$REBASE_SERVICE_KEY`) |

`--from` is what lets a repository that contains no collections — a separate
frontend, a second web app, a mobile app — generate a typed client from the
project it talks to. `REBASE_SERVICE_KEY` is only sent to the project this
checkout is linked to; pass `--token` explicitly for any other host.

**Usage after generation:**

```typescript

const client = createRebaseClient<Database>({
    baseUrl: "http://localhost:3001",
    collections: collectionsDictionary,
});

// Full type safety and autocomplete
const { data } = await client.data.products.find();
```

Field names in the generated types are the ones the API serves, unchanged — a
`created_at` column is `row.created_at`. Only the collection *accessor* is
turned into a property name (`my-notes` → `client.data.myNotes`), which is what
`collectionsDictionary` maps back to the slug.

### Development Workflow

The fast-iteration workflow for development:

```bash
# 1. Edit your collection in config/collections/
# 2. Generate the Drizzle schema
rebase schema generate

# 3. Push directly to dev database
rebase db push
```

### Production Workflow

The safe, reviewable workflow for production:

```bash
# 1. Edit your collection in config/collections/
# 2. Generate the Drizzle schema
rebase schema generate

# 3. Generate SQL migration files
rebase db generate

# 4. Review the generated SQL in drizzle/
# 5. Commit the migration to version control
git add drizzle/

# 6. Apply in production
rebase db migrate
```

### Troubleshooting

| Symptom | Solution |
|---------|----------|
| `Could not detect an active database plugin` | Install `@rebasepro/server-postgres` in `backend/package.json` |
| Schema file not updating | Check the `--collections` path points to the right directory |
| Migration shows unexpected changes | Run `rebase doctor` to identify drift |
| `db push` fails on production | Use `db generate` + `db migrate` instead |

### Next Steps

- **[Collections](/docs/collections)** — Define your data model
- **[CLI Reference](/docs/cli)** — All CLI commands
- **[Client SDK](/docs/sdk)** — Use the generated SDK

## Studio Tools

### Overview

Rebase has two modes:

- **Content Mode** — For content editors and operations teams. Shows collections and data management.
- **Studio Mode** — For developers. Unlocks developer-facing tools.

Toggle between modes using the admin mode controller or the UI toggle in the app bar.

### Built-in Studio Tools

#### Collection Editor

A visual schema editor that lets you create and modify collections through a drag-and-drop UI. When you save changes, it uses [ts-morph](https://ts-morph.com/) to update your TypeScript source files via AST manipulation — preserving all existing code and custom logic.

![Collection editor](/img/collection_editor.png)

```tsx

// The Collection Editor is automatically enabled when you provide the 
// collectionEditor configuration to your RebaseAdmin component
<RebaseAdmin
    collections={collections}
    collectionEditor={{
        getAuthToken: authController.getAuthToken
    }}
/>
```

#### Built-in tools

These ship with Studio and are **lazy-loaded by `RebaseStudio`** — each is a separate
chunk, fetched the first time you open it. They are not importable on their own:
`@rebasepro/studio` deliberately exports only the orchestrator, so a console you never
open costs nothing.

| Tab | Slug | What it does |
|-----|------|--------------|
| SQL Console | `sql` | Run raw SQL against your PostgreSQL database and read results in a table |
| JS Console | `js` | Write and execute JavaScript through the Rebase SDK |
| RLS Policy Editor | `rls` | Inspect and manage Row Level Security policies for your tables |
| Storage Browser | `storage` | Browse, upload and manage files across your storage backends |

### Adding Studio Views

Studio tools are automatically available when you include the `RebaseStudio` component inside your app:

```tsx

export function App() {
    return (
        <Rebase client={client} authController={authController}>
            {/* Custom views are injected and studio mode is managed automatically */}
            <RebaseStudio />
            {/* ... */}
        </Rebase>
    );
}
```

These views appear in the sidebar navigation when Studio mode is active.

### Next Steps

- **[Plugins](/docs/plugins)** — Extend the framework with plugins
- **[Collections](/docs/collections)** — Collection configuration

## rls-check

## rls-check

`rls-check` reads a PostgreSQL database's catalog and reports what is actually exposed:
tables served with row-level security switched off, policies that evaluate to true for
everyone, views that read straight past the RLS on their base tables, and join tables
that were forgotten while both of their endpoints were locked down.

It works on **any** Postgres — Supabase, Neon, RDS, Cloud SQL, or a server you run
yourself. It does not require Rebase, and it is useful whether or not you ever adopt it.

```bash
npx @rebasepro/rls-check $DATABASE_URL
```

It is read-only by construction: it opens a read-only transaction and issues catalog
queries. It writes nothing, and it sends nothing anywhere — there is no telemetry and no
network call other than the one to your database.

### Running it

```bash
# Explicit connection string
npx @rebasepro/rls-check "postgres://user:pass@host:5432/dbname"

# Or from the environment — DATABASE_URL, then POSTGRES_URL, then a .env in the cwd
npx @rebasepro/rls-check
```

If your password contains `@`, `:`, `/`, `?` or `#`, percent-encode it. That is by far the
most common cause of an authentication failure here, and `rls-check` will say so rather
than letting you guess.

#### Options

| Option | Meaning |
| --- | --- |
| `--json` | Machine-readable output on stdout, and nothing else on stdout |
| `--schema <name>` | Restrict the scan to a schema. Repeatable, or comma-separated |
| `--fail-on <severity>` | Exit 1 at or above this severity. Default `high`; `none` never fails |
| `--only <id>` | Run only these checks. Repeatable, or comma-separated |
| `--skip <id>` | Skip these checks. Repeatable, or comma-separated |
| `--list-checks` | Print the catalog and exit |
| `--timeout <ms>` | Statement timeout, default 15000 |
| `--quiet` | Findings only — no banner, no summary |
| `--no-color` | Disable ANSI colour (also honours `NO_COLOR` and a non-TTY stdout) |

An unknown id passed to `--only` or `--skip` is an error rather than a silent no-op, because
a typo there quietly weakens the scan.

#### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | No findings at or above the `--fail-on` threshold |
| `1` | At least one finding at or above the threshold |
| `2` | The scan could not run — bad arguments, connection refused, auth failure, timeout |

`1` and `2` are deliberately distinct: a broken connection must never look like a clean
database.

#### In CI

```yaml
- name: Audit RLS
  run: npx @rebasepro/rls-check "$DATABASE_URL" --fail-on high
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
```

#### JSON output

`--json` emits a stable object: `scannedAt`, `database` (host and name only — never
credentials), `serverVersion`, `platform`, `scannerIsPrivileged`, `stats`, and `findings`.
Each finding carries `id`, `severity`, `title`, `target`, `detail`, `impact`, `fix`,
`docs` and `confidence`.

### How to read the report

**Confirmed findings come first; heuristic ones are in a separate "worth checking"
section.** A heuristic check cannot see intent — a junction table you deliberately left
open is not a bug — so those are phrased as questions and never mixed in with the
certainties.

**Watch for the privilege note.** If the scan connects as a superuser, a table owner, or a
role with `BYPASSRLS`, it says so. That role sees the true catalog, which is what makes the
audit possible, but it also means nothing in the report describes what *that* connection
experiences. The findings are about what other roles get.

### The checks

Severities below are the defaults; several checks adjust their own severity based on what
they find, and the report always states the reason.

#### rls-disabled

**Table exposed without row-level security.** Critical.

The table has RLS disabled *and* grants `SELECT`/`INSERT`/`UPDATE`/`DELETE` to a role an
untrusted caller can reach (`anon`, `PUBLIC`, `web_anon`, `rebase_user`). Postgres applies
no per-row filter at all, so policies — if any exist — are never consulted.

A table with RLS off but no grant to an exposed role is *not* reported. It is not reachable,
and flagging it would be noise.

```sql
ALTER TABLE "public"."your_table" ENABLE ROW LEVEL SECURITY;
```

Enabling RLS with no policies denies every row to everyone but the owner, so add the policy
you intend in the same migration — otherwise you have traded an exposure for a silent
outage. See [rls-enabled-no-policies](#rls-enabled-no-policies).

#### policy-always-true

**Policy grants unconditional access.** Critical.

A permissive policy whose `USING` or `WITH CHECK` expression is a constant truth — `true`,
`(true)`, `1 = 1`. Permissive policies are ORed together, so a single one of these satisfies
the table's row filter no matter how strict every other policy is.

If a `RESTRICTIVE` policy covers the same command, this is downgraded to medium and
reported as something to verify rather than a certainty, because restrictive policies AND
after the permissive ones OR.

```sql
ALTER POLICY "your_policy" ON "public"."your_table"
    USING (user_id = rebase.uid());
```

#### policy-anonymous-tautology

**Policy only checks that a caller id exists.** Severity depends on the platform.

The expression is `rebase.uid() IS NOT NULL`-shaped (or `auth.uid()` on Supabase, and on a
Rebase database provisioned before 1.0): it separates signed-in from signed-out callers, but
scopes no rows. Every signed-in user reaches every row the policy covers.

The severity is platform-dependent, and this distinction matters:

- **On Supabase**, `auth.uid()` returns `NULL` for anonymous callers, so this is a working
  authenticated-only check. Reported as **low** — a data-scoping gap between signed-in
  users, not an anonymous-access hole.
- **On Rebase or PostgREST**, where a blank caller id is coerced to an `'anonymous'`
  sentinel, the expression is *true for signed-out callers too*. Reported as **critical**.
- **On an unrecognised platform**, reported as **medium**, since whether it is a hole
  depends on whether your stack uses such a sentinel.

```sql
-- Scope to the row's owner rather than to the existence of an id
ALTER POLICY "your_policy" ON "public"."your_table"
    USING (user_id = rebase.uid());

-- Or, if "any signed-in user" really is the intent, reject the sentinel explicitly
--     USING (rebase.uid() IS NOT NULL AND rebase.uid() <> 'anonymous');
```

The suggested SQL is printed with the caller-id function your database actually has:
`rebase.uid()` on a Rebase database, `auth.uid()` on Supabase and PostgREST. Both
spellings are recognised when reading policies, so a Rebase database mid-migration from
the pre-1.0 `auth` schema is still checked.

#### view-bypasses-rls

**View reads past its base table's RLS.** Critical.

A view granted to an untrusted role that selects from an RLS-protected table without
`security_invoker = true`. The view runs with its **owner's** privileges, so it reads the
base table as the owner and the caller's policies never apply. This is the most common way
a carefully locked-down table leaks.

```sql
ALTER VIEW "public"."your_view" SET (security_invoker = true);
```

On PostgreSQL below 15 the option does not exist at all, so every such view behaves this
way. There the finding is reported as heuristic, and the fix is to move the logic into a
function or upgrade.

#### matview-bypasses-rls

**Materialized view exposes RLS-protected data.** High.

Materialized views cannot have row-level security, and the data in them is a stored
snapshot taken by whoever refreshed it. If one is granted to an untrusted role and its
defining query reads an RLS-protected table, no policy can help — revoke the grant, or move
the matview into a schema that untrusted roles cannot reach.

```sql
REVOKE ALL ON "public"."your_matview" FROM "anon";
```

#### anonymous-write-allowed

**Unauthenticated callers can write.** High.

A permissive `INSERT`/`UPDATE`/`DELETE`/`ALL` policy reachable without authentication whose
check expression accepts any row, backed by a matching grant.

The "accepts any row" condition is essential and deliberately narrow. Supabase grants `anon`
and `authenticated` full DML by default, so a policy targeting those roles is not by itself
a problem — a textbook `FOR INSERT TO public WITH CHECK (user_id = auth.uid())` is correct
and is not reported.

#### unqualified-column-in-subquery

**Unqualified column inside a policy subquery.** High, heuristic.

A bare column name inside an `EXISTS`/`IN` subquery that exists on *both* the inner relation
and the policy's own table. Postgres binds it to the **inner** table, so the correlation to
the outer row you meant to write silently disappears and the predicate becomes trivially
satisfiable — or trivially unsatisfiable, denying every row to everyone.

```sql
-- The bug: `id` binds to memberships, not organizations
USING (EXISTS (SELECT 1 FROM memberships WHERE id = organizations.id ...))

-- Qualify it
USING (EXISTS (SELECT 1 FROM memberships m WHERE m.org_id = organizations.id ...))
```

**An absence of this finding is not proof of safety.** `pg_policies.qual` is Postgres's own
re-rendering of the parse tree, and it usually re-qualifies column references — so the
original bare name is frequently no longer visible by the time the catalog is read. When
this check does fire it is strong evidence; when it does not, it has proved nothing.

#### junction-table-unprotected

**Many-to-many join table without RLS.** High, heuristic.

A table that is essentially just the two endpoints of two foreign keys, both pointing at
tables that *do* have RLS, with no row-level security of its own. Both sides of the relation
are locked and the edge between them is open — which is enough to enumerate the relation
even when neither endpoint can be read.

Heuristic because a junction table is inferred from its shape. If yours is deliberately
public, `--skip junction-table-unprotected`.

#### rls-enabled-not-forced

**RLS enabled but not forced for the table owner.** Medium, or high.

Without `FORCE`, the table's owner is exempt from its own policies. That is harmless when the
owner is a provisioning role nothing connects as, and serious when your application connects
as the owner — so this is **high** when the owning role can log in, and **medium** otherwise.

If the owner is a superuser or has `BYPASSRLS`, it stays medium and says so: `FORCE` cannot
constrain such a role, and implying otherwise would be misleading.

```sql
ALTER TABLE "public"."your_table" FORCE ROW LEVEL SECURITY;
```

#### rls-enabled-no-policies

**RLS enabled with no policies.** Medium.

Not a security hole — the opposite. RLS on with zero policies denies every row to everyone
but the owner. It is reported because it is an *invisible* failure: the API returns `[]`, and
an empty table is indistinguishable from a filtered one. This configuration has silently
served empty collections in production for weeks at a time.

#### policy-role-unreachable

**Policies target roles nothing connects as.** Medium.

Every policy on the table names roles that do not exist, cannot log in, and that no login
role inherits transitively. The policies look correct and apply to nobody, so the table reads
as empty.

The classic case is policies written `TO authenticated` — a Supabase role name — on a database
whose requests actually arrive as some other role.

#### grant-to-public

**Table privileges granted to PUBLIC.** Medium.

A DML privilege granted to `PUBLIC`. Even with RLS enabled this widens *who* policies get
evaluated for, and it is almost never deliberate.

```sql
REVOKE ALL ON "public"."your_table" FROM PUBLIC;
```

#### security-definer-mutable-search-path

**SECURITY DEFINER routine with a mutable search_path.** Medium.

The routine executes as its owner — often a superuser — while the caller controls how its
identifiers resolve. That is the standard privilege-escalation shape, and anything the
routine touches is read with the owner's rights, bypassing RLS.

```sql
ALTER FUNCTION "public"."your_function"() SET search_path = pg_catalog, public;
```

#### current-setting-throws

**Policy calls `current_setting()` without `missing_ok`.** Low, heuristic.

`current_setting('app.tenant_id')` with a single argument *raises* when the setting is unset,
rather than returning `NULL`. So instead of denying the row, the request errors — the caller
sees a 500 rather than an empty result, and middleware that retries 5xx will retry a request
that can never succeed.

```sql
ALTER POLICY "your_policy" ON "public"."your_table"
    USING (tenant_id = current_setting('app.tenant_id', true)::uuid);
```

### What this tool does not do

Being clear about the limits is the point — a security tool that overstates its coverage is
worse than none.

- **It is a static catalog audit.** It reads `pg_class`, `pg_policies`, `pg_depend` and
  friends. It does not connect as your `anon` role and try to read your data, so it cannot
  confirm that an exposure is reachable through your API.
- **It cannot prove a policy is correct.** It finds shapes that are known to be wrong. A
  policy that passes every check here can still express the wrong business rule.
- **A clean report is not a security certification.** In particular, see the note on
  [unqualified-column-in-subquery](#unqualified-column-in-subquery): Postgres rewrites policy
  expressions, so some bugs are no longer visible in the catalog at all.
- **It does not check application-level authorization**, API keys, network exposure,
  secrets handling, or anything outside the database.

### Related

- [Security Rules (RLS)](/docs/collections/security-rules) — defining row-level security in
  Rebase collections, which compiles to the policies this tool audits.

## Architecture Overview

### System Architecture

Rebase is a full-stack platform with four layers:

```
┌─────────────────────────────────────────────────────────────────┐
│                        Frontend Layer                           │
│  React Admin UI  •  Custom Views  •  Plugins  •  Your App      │
│  @rebasepro/app  •  @rebasepro/ui  •  @rebasepro/studio       │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP + WebSocket
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Backend Layer                            │
│  Hono HTTP Server  •  REST API  •  Auth  •  Storage  •  WS     │
│  @rebasepro/server                                         │
└───────────────────────────┬─────────────────────────────────────┘
                            │ Drizzle ORM
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Database Layer                            │
│  PostgreSQL  •  Tables  •  RLS Policies  •  Realtime sync       │
└─────────────────────────────────────────────────────────────────┘
```

### Key Components

#### Database Adapter System

The backend initializes through a unified database adapter pattern. Database-specific logic is decoupled into its own package, and the adapter handles connection pooling, schema resolution, and real-time event routing automatically.

```typescript

database: createPostgresAdapter({
    connectionString: process.env.DATABASE_URL!
})
```

Collections automatically resolve against the configured adapter through the internal dependency injection registry.

:::tip
The `createPostgresAdapter` handles database connection pooling, schema resolution, and real-time `LISTEN/NOTIFY` setup automatically.
:::

#### Collection Registry

The `BackendCollectionRegistry` is the runtime index of all collections, their PostgreSQL tables, enums, and Drizzle relations. It's populated at startup from your collection definitions.

#### Realtime Service

Real-time sync uses PostgreSQL's native `LISTEN/NOTIFY` mechanism:

1. A data mutation happens (insert, update, delete)
2. The backend emits a `NOTIFY` on a channel
3. The `RealtimeService` receives the notification
4. It broadcasts the change to all connected WebSocket clients
5. React components re-render with the new data

For **multi-instance deployments** (e.g., Cloud Run with multiple replicas), provide a `connectionString` in your PostgresBootstrapper so all replicas share the same `LISTEN` connection.

#### Storage Registry

Like drivers, storage backends are registered in a registry. You can have multiple storage providers (local, S3) and route different file fields to different backends using `storageId`.

### Package Map

| Package | Role | Used By |
|---------|------|---------|
| `@rebasepro/types` | TypeScript interfaces for collections, properties, entities, plugins | Everything |
| `@rebasepro/server` | Backend server initialization, REST API, auth, storage, WebSocket | Backend |
| `@rebasepro/client` | Client SDK — HTTP transport, WebSocket, auth | Frontend |
| `@rebasepro/app` | React framework — Scaffold, controllers, forms, routes, hooks | Frontend |
| `@rebasepro/ui` | Standalone UI component library (Tailwind v4 + Radix) | Frontend |
| `@rebasepro/app` | Login views, auth controller hooks, user management | Frontend |
| `@rebasepro/studio` | Collection editor, SQL console, JS console, RLS editor, storage browser | Frontend |
| `@rebasepro/cli` | CLI for schema generation, DB migrations, SDK generation | Dev tooling |
| `@rebasepro/forms` | Lightweight React form state management | Frontend |
| `@rebasepro/plugin-ai` | AI-powered field autocompletion plugin | Frontend |
| `@rebasepro/plugin-data-import-export` | CSV/JSON/Excel import and export | Frontend |
| `@rebasepro/inference` | Auto-detect schema from existing database data | Backend/CLI |

### Data Flow

#### Read Flow
1. User opens a collection in the admin UI
2. Client SDK sends `GET /api/data/:slug` + opens a WebSocket subscription
3. Backend queries PostgreSQL via Drizzle ORM
4. Data transformer deserializes database records into entity format
5. Response sent to frontend, components render
6. WebSocket keeps the view synced in real-time

#### Write Flow
1. User edits a entity in the form
2. `beforeSave` callbacks run (validation, transformation)
3. Client SDK sends `PUT /api/data/:slug/:id`
4. Backend serializes values, runs Drizzle `UPDATE`
5. `afterSave` callbacks run (side effects)
6. `NOTIFY` broadcast triggers WebSocket update to all clients
7. If history is enabled, a entity is recorded

### Next Steps

- **[Schema as Code](/docs/architecture/schema-as-code)** — The TypeScript-first approach
- **[Backend Overview](/docs/backend)** — Server configuration
- **[Collections](/docs/collections)** — Define your data schema

## Schema as Code

### The Core Idea

In Rebase, your **TypeScript collection definitions are the single source of truth**. From one set of TypeScript objects, Rebase generates:

- **PostgreSQL tables** via Drizzle ORM schema generation
- **CRUD UI** — forms, tables, validation, field types
- **REST API** endpoints with filtering, sorting, and pagination
- **Client SDK** — type-safe data operations
- **RLS policies** — Row Level Security in Postgres

This means your schema is:
- **Version controlled** — every change is a git commit
- **Type-safe** — TypeScript catches errors at compile time
- **Reviewable** — schema changes go through pull requests
- **Portable** — the same definition works across frontend, backend, and CLI

### Visual Editing with AST Manipulation

Rebase also provides a **visual collection editor** in Studio mode. When a non-developer uses the visual editor to add a field:

1. The Studio does **not** directly modify the database
2. Instead, it uses [ts-morph](https://ts-morph.com/) to parse your TypeScript source file as an AST
3. It inserts the new property definition precisely into the `properties` block
4. **All existing code, callbacks, and custom logic are preserved untouched**
5. The file is saved, triggering hot reload

This "UI as Code Generator" approach means visual edits produce the same clean TypeScript a developer would write by hand.

### Schema Generation Pipeline

```
TypeScript Collections
        │
        ▼
  rebase schema generate
        │
        ▼
  Drizzle Schema (schema.generated.ts)
        │
        ▼
  rebase db generate
        │
        ▼
  SQL Migration Files
        │
        ▼
  rebase db migrate
        │
        ▼
  PostgreSQL Tables
```

#### Example

Given this collection:

```typescript

const productsCollection = defineCollection({
    slug: "products",
    name: "Products",
    table: "products",
    properties: {
        name: { type: "string", name: "Name", validation: { required: true } },
        price: { type: "number", name: "Price", columnType: "numeric" },
        active: { type: "boolean", name: "Active", defaultValue: true },
        created_at: { type: "date", name: "Created", autoValue: "on_create" }
    }
});
```

Rebase generates this Drizzle schema:

```typescript
// schema.generated.ts

export const products = pgTable("products", {
    id: serial("id").primaryKey(),
    name: varchar("name").notNull(),
    price: numeric("price"),
    active: boolean("active").default(true),
    created_at: timestamp("created_at").defaultNow()
});
```

Which produces this SQL:

```sql
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name VARCHAR NOT NULL,
    price NUMERIC,
    active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);
```

### Safety & Unmapped Database Objects

When Rebase updates the database schema, it maps TypeScript collection definitions to database tables. To ensure that **unmapped database objects (e.g., tables, views, enums) are never dropped or modified**, Rebase implements several layers of safety:

1. **Strict Table Filtering (`tablesFilter`)**: The generated Drizzle configuration dynamically restricts synchronization to only the tables exported in the generated schema. Any unrecognized tables or legacy systems' tables existing in the database are ignored by the sync engine.
2. **Schema Restrictions (`schemaFilter`)**: The DB sync is restricted exclusively to the `public` schema. Internal database tables, custom schemas, and extension-specific tables are left untouched.
3. **Roles and Extension Protection**: Drizzle is configured not to manage database roles (`entities.roles: false`) or helper tables from extensions like PostGIS.
4. **Interactive Dev Mode Confirmation**: When running `rebase db push` in development, the CLI executes with `--strict` and `--verbose` flags, which ensures that developers must explicitly review and approve any destructive SQL actions before they are executed.

### Next Steps

- **[Collections](/docs/collections)** — Full collection configuration reference
- **[Properties](/docs/collections/properties)** — Detailed column type mappings

## Runtime and Bundles

### The two halves of a deployment

A Rebase deployment is two things, not one:

- **The bundle** — your project. Compiled collections, hooks, functions and cron
  jobs, plus a generated manifest describing what they need.
- **The runtime** — the engine. `@rebasepro/server`, shipped as the published
  `rebasepro/server` container image.

They are built, versioned and shipped separately. That single decision is what
everything else on this page follows from: because the engine is not baked into
your application image, it can be replaced underneath your project — for a
security fix, a performance improvement, a new feature — without rebuilding
anything you wrote.

```
  your repository                 built artifact              running container
  ───────────────                 ──────────────              ─────────────────
  config/collections/*.ts   ──►   dist-bundle/config/     ──►  rebasepro/server
  backend/functions/*.ts          dist-bundle/backend/         + /bundle mounted
  rebase.json                     dist-bundle/manifest.json
```

The runtime you self-host is the same runtime Rebase Cloud runs. There is no
separate "platform" build, and nothing about the managed tier is unavailable to
someone running `docker compose up`.

### Building a bundle

```bash
rebase build
```

This regenerates the database schema from your collections, type-checks and
compiles them, resolves import specifiers so Node can load the output directly,
and writes `dist-bundle/` containing:

| Path | What it is |
| --- | --- |
| `manifest.json` | Generated. The contract this bundle claims to satisfy. |
| `package.json` | Generated. Your project's runtime dependencies. |
| `config/` | Compiled collections. |
| `backend/functions/` | Compiled server functions. |
| `backend/crons/` | Compiled cron jobs. |
| `backend/src/schema.generated.js` | Compiled database schema. |

The manifest is worth understanding, because it is what a runtime validates
before it agrees to boot:

```jsonc
{
  "bundleFormat": 2,
  "runtime": { "range": "^1", "builtAgainst": "0.13.0", "contract": 1 },
  "schemaVersion": "v1:c5d97d0f96b7f87a",
  "kind": "backend",
  "entry": {
    "config": "config",
    "functions": "backend/functions",
    "static": [{ "path": "/", "dir": "static/admin", "spa": true }]
  },
  "hooks": { "native": false },
  "deps": { "declared": { "zod": "^4.4.3" } }
}
```

`kind` is either `backend` — boot the server, plus any static apps in
`entry.static` — or `static`, which serves those assets and nothing else: no
database, no auth. Whether a backend declares its collections in code or
introspects them from the live database is not a third kind; it is simply
whether `entry.config` is there.

### Running a bundle

```bash
rebase start                       # locally
docker run -v ./dist-bundle:/bundle rebasepro/server   # anywhere
```

`rebase start` loads the bundle in-process, so signals and stack traces reach
you directly. Locally it links your already-installed dependencies into the
bundle so there is no second install; a deployment installs the bundle's own
`package.json` instead.

### Compatibility

Two version numbers govern whether a bundle and a runtime can work together, and
they are deliberately not the package version.

**`bundleFormat`** is the on-disk layout. A runtime accepts any bundle whose
format is less than or equal to its own, and refuses a newer one rather than
half-loading it. An older bundle on a newer runtime must keep working — that is
the entire point of the separation, so a runtime reads every format it has ever
shipped. Format 1 bundles, which named this field `mode` and carried a single
static directory, still boot unchanged.

**`runtime.contract`** is the interface between a bundle and the engine. Within
one contract major, any bundle that validated keeps validating. Patches and
minors are drop-in; a major is not, and a runtime will refuse a bundle from a
different one rather than start and misbehave later.

This is why upgrading Rebase in a self-hosted deployment is a tag change:

```yaml
image: rebasepro/server:0.13.0   # was 0.12.0 — your bundle is untouched
```

### Development uses the same path

`rebase dev` boots the same runtime over your TypeScript source instead of a
compiled bundle. Hot reload still works, and development predicts production
because both go through one boot path rather than two implementations that
drift.

A project that needs something the stock runtime does not do can still write its
own `backend/src/index.ts` and import the server as a library. `rebase dev`
detects it and runs it. See [Custom server](/docs/backend/custom-server/) — you
lose the stock runtime, not the API surface.

### What the runtime reads from the environment

The runtime is configured entirely by environment variables, because that is what
every deployment target agrees on.

| Variable | Meaning |
| --- | --- |
| `DATABASE_URL` | Connection string for the default database. Required. |
| `JWT_SECRET` | Signing secret, at least 32 characters. Required in production. |
| `CORS_ORIGINS` | Comma-separated origins allowed to call the API. Required in production. |
| `PORT` | Port to bind. Default `3001` locally, `8080` in the image. |
| `REBASE_SERVICE_KEY` | Server-to-server key granting admin access. |
| `REBASE_METRICS` | `true` to expose Prometheus metrics at `/metrics`. |
| `REBASE_MIGRATE_ON_BOOT` | `none`, `ensure` or `push`. Defaults to `none` in production. |
| `REBASE_SERVE_STATIC` | Serve the bundle's static assets from this process. Default on. |

Several databases and several buckets are configured by suffixing the variable
with the source key — see [Multiple databases and
buckets](/docs/backend/multiple-sources/).

### Endpoints the runtime always serves

| Path | Purpose |
| --- | --- |
| `GET /health` | Readiness. Performs a database round-trip. |
| `GET /livez` | Liveness. Deliberately does *not* touch the database, so a database blip cannot make an orchestrator kill a healthy process. |
| `GET /api/meta/schema-version` | The current schema version. Unauthenticated — it is a version stamp, not a schema. |
| `GET /api/meta/contract` | The full collection contract. Admin-only. |
| `GET /metrics` | Prometheus metrics, when `REBASE_METRICS=true`. |

## Apps and Repositories

### Projects and apps

A **project** is the backend: the database, auth, storage, realtime and
functions. An **app** is something that talks to it.

| Type | What it is |
| --- | --- |
| `backend` | The collections, hooks and functions that define the API. Exactly one per project. |
| `static` | A built client bundle — an SPA or static site, served at its own path. |

That is the whole list. The admin panel is a `static` app like any other: it is
built in your repository, against your collections, which is why custom fields
and custom views work in it on day one.

Who owns the server process is a property of the backend, not a separate app
type:

| `runtime` | What it means |
| --- | --- |
| `managed` | The platform's runtime image runs your bundle. You supply collections, functions, crons and schema. |
| `custom` | You supply the server: your own Dockerfile and entrypoint. `rebase eject` sets this up. |

This is independent of *where* it runs. Both run on Rebase Cloud and both
self-host — the destination lives in `.rebase/cloud.json`, not in the manifest.

The important part is what *owns* the list. A repository declares only the apps
it contains; the project owns the set of apps that exist. Two repositories never
need to know about each other — they only need to know the project. That is what
makes a separate frontend repository, or a mobile app with no repository
relationship at all, an ordinary thing rather than a special case.

### `rebase.json`

The manifest declares topology, and nothing else. Schema, security rules, hooks
and functions stay in TypeScript where a type system can check them.

```jsonc
{
  "rebase": "^1",
  "apps": {
    "backend": { "type": "backend", "runtime": "managed" },
    "site": {
      "type": "static",
      "root": "frontend",
      "build": "npm run build --workspace frontend",
      "output": "frontend/dist",
      "path": "/"
    },
    "admin": {
      "type": "static",
      "root": "admin",
      "build": "npm run build --workspace admin",
      "output": "admin/dist",
      "path": "/admin"
    }
  }
}
```

One process serves all of it: the API at `/api`, the site at `/`, the admin at
`/admin`. That is the self-hosting story, and a perfectly good small tier on
Rebase Cloud.

`path` is a **build-time** input as well as a serving one. An app mounted at
`/admin` has to be *built* for `/admin`, or `index.html` loads and every asset
404s — a blank page with no error anywhere. `rebase build` passes the value as
`REBASE_APP_BASE`, which your bundler reads as its base path:

```ts
// vite.config.ts
export default defineConfig({
  base: process.env.REBASE_APP_BASE ?? "/",
  // …
});
```

and refuses to ship a build that ignored it.

An existing project does not need one. The CLI infers the same layout from the
directory structure, and `rebase apps init` writes it down when you want it
explicit:

```bash
rebase apps list      # what this repository contributes
rebase apps init      # write an inferred rebase.json
```

### Building and deploying apps

```bash
rebase build              # every app in this repository
rebase build backend      # just the bundle
rebase build admin        # just that app's static assets
```

The backend builds first, because a client app's build may consume an SDK
generated from its collections.

### Multiple repositories

The monorepo stays the default: one repository with a backend and an admin panel
is the simplest thing that works, and `rebase init` scaffolds it. Splitting up is
the graduation step, not a requirement.

In a separate frontend repository you need two things — a manifest declaring
what this repository contributes, and a link to the project:

```jsonc
// rebase.json
{
  "rebase": "^1",
  "apps": {
    "marketing": {
      "type": "static",
      "root": ".",
      "build": "npm run build",
      "output": "dist"
    }
  }
}
```

```bash
rebase cloud link https://api.example.com   # a self-hosted project
rebase cloud link                           # or pick a Rebase Cloud project
```

The link is written to `.rebase/cloud.json` and is **not committed** — it is
per-checkout, like a git remote. The manifest is committed; the link is not.

### Typed clients without the collections

This is the mechanism that makes multi-repo work. A repository that contains no
collections generates its typed SDK from the project itself:

```bash
rebase generate-sdk --from link
rebase generate-sdk --from https://api.example.com --token $REBASE_SERVICE_KEY
```

The CLI fetches `/api/meta/contract`, rebuilds the collection definitions —
including relation targets, which the type generator needs to decide whether a
foreign key is a string or a number — and emits exactly the same output it would
have produced from local source.

The contract endpoint is admin-only. Collection definitions describe every table,
column and relation in the project, including ones no security rule would ever
expose; that is a map of the database, not public API documentation.

### Detecting drift

Splitting repositories costs you one thing worth naming: a schema change and the
frontend that uses it no longer land in the same commit. The backend can deploy a
change that strands a client built against the old shape.

Every generated SDK records the schema it came from:

```ts
// src/rebase/schema.meta.ts — generated
export const SCHEMA_VERSION = "v1:c5d97d0f96b7f87a";
```

And every project publishes its current one, without authentication, because a
version stamp reveals nothing about the schema it stands for:

```bash
curl -s https://api.example.com/api/meta/schema-version
# {"schemaVersion":"v1:c5d97d0f96b7f87a"}
```

Comparing the two in CI turns a silent mismatch into a failed check. The stamp
changes when the generated types could change — a new property, a changed
relation — and deliberately *not* when a hook, a security rule or an icon
changes, so it does not cry wolf.

### Client configuration

```bash
rebase apps config web
```

Prints what a client needs to reach the project. It never prints a secret: the
API URL and an app's publishable identity are meant to ship inside a client
bundle, and anything that is not safe there does not belong in output that will
end up in a committed `.env`.

## Deployment

### What a Deployment Serves

A Rebase project deploys as **one server at one URL** (on Rebase Cloud: `https://<project>.rebase.website`). That server handles:

- **`/api/*`** — the data API, authentication, realtime, and storage
- **everything else** — your built `frontend/` as a static SPA

There is no separate admin URL: the admin panel is part of your frontend, so where it appears depends on what your frontend is.

| Project type | Root URL shows | Admin panel is at |
|--------------|----------------|-------------------|
| Default scaffold (`rebase init`) | The admin panel | `/` — the frontend **is** the admin |
| Custom product frontend | Your app | Wherever you mount it, commonly `/admin` — see [Changing the Base URL](#changing-the-base-url) |
| Backend-only project | Nothing (API only) | Not deployed |

:::note[First visit]
On the first visit to a fresh deployment's admin, Rebase shows a bootstrap screen to **create your admin account**. The first registered account receives admin privileges — claim it right after deploying.
:::

### Docker Compose (Recommended)

The generated project already includes a working `docker-compose.yml` (Postgres + backend + frontend) and the `backend/`/`frontend/` Dockerfiles — that generated file is the source of truth; use it as-is rather than hand-writing one. The shape is:

```yaml title="docker-compose.yml (generated — abridged)"
services:
  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: rebase_app
      POSTGRES_PASSWORD: ${DATABASE_PASSWORD:-changeme}
      POSTGRES_DB: rebase
    ports:
      - "5432:5432"

  backend:
    build:
      # Context is the PROJECT ROOT so the image can copy
      # pnpm-workspace.yaml, backend/, and config/. A `./backend`
      # context would fail — the Dockerfile lives at backend/Dockerfile.
      context: .
      dockerfile: backend/Dockerfile
    ports:
      - "3001:3001"
    env_file: .env
    depends_on:
      - db

volumes:
  postgres_data:
  uploads:
```

```bash
docker compose up -d
```

#### Create the database schema

Bringing the stack up is **not enough on its own.** The backend boots and
auto-creates the **auth** tables, but it does **not** create the tables for
your own collections — you run that once, explicitly, against the production
database. From a checkout of your project (with dependencies installed), set
`DATABASE_URL` to your production database and push the schema:

```bash
pnpm run db:push
```

:::caution[Required — or every collection returns errors]
Skip this step and the app still starts and you can log in, but each of your
collections is empty and its API calls fail with a "missing table" error until
the schema exists. On startup the server logs a boxed warning naming exactly
which tables are missing and the command to run.
:::

`db:push` is the fast option — it applies the schema directly, with no
migration files. For a **versioned, team workflow**, commit migration files
with `pnpm run db:generate` and run `pnpm run db:migrate` as a release step
instead. Whichever you choose, it runs against the production `DATABASE_URL`
from a project checkout (or your CI job), not inside the running container —
the production image ships without the CLI.

### Production Checklist

Before deploying to production, ensure:

| Item | Details |
|------|---------|
| **Database schema** | Run `pnpm run db:push` (or `pnpm run db:migrate` for versioned migrations) against the production database once. The app boots without your collection tables, but every collection errors until they exist. |
| **JWT_SECRET** | Use a cryptographically strong random string (≥ 32 chars). Never reuse across environments. |
| **DATABASE_URL** | Use a managed Postgres instance (Neon, Supabase, RDS) with TLS enabled |
| **CORS** | Configure allowed origins on your backend if frontend and backend are on different domains |
| **Storage volumes** | Mount persistent volumes for file uploads. Or switch to S3 for production. |
| **HTTPS** | Terminate TLS at your reverse proxy (nginx, Cloudflare, load balancer) |
| **Registration** | Set `ALLOW_REGISTRATION=false` after creating your admin account |

### Serving the Frontend

In production, the backend can serve the frontend as a static SPA:

```typescript

// After initializeRebaseBackend()
serveSPA(app, { frontendPath: path.resolve(process.cwd(), "../frontend/dist") });
```

Build the frontend first:

```bash
cd frontend && pnpm build
```

This way you only need to deploy one server that handles both SPA and API.

### Platform Deployment Guides

Detailed step-by-step guides for each platform:

| Platform | Type | Guide |
|----------|------|-------|
| **AWS** | App Runner / ECS + RDS | [Deploy on AWS →](/docs/deployment/aws) |
| **Google Cloud** | Cloud Run + Cloud SQL | [Deploy on GCP →](/docs/deployment/gcp) |
| **Azure** | Container Apps + PostgreSQL | [Deploy on Azure →](/docs/deployment/azure) |
| **Hetzner Cloud** | VPS + Docker Compose | [Deploy on Hetzner →](/docs/deployment/hetzner) |
| **Scaleway** | Serverless Containers | [Deploy on Scaleway →](/docs/deployment/scaleway) |
| **Railway** | PaaS (auto-detect Dockerfile) | [Deploy on Railway →](/docs/deployment/railway) |
| **Fly.io** | Container runtime | [Deploy on Fly.io →](/docs/deployment/flyio) |

:::caution
Cloud Run and other serverless platforms are stateless. Use **S3 storage** instead of local filesystem for file uploads, and set `--min-instances 1` if you use Rebase realtime features (WebSocket connections are terminated when instances scale down).
:::

### Changing the Base URL

If you want Rebase to run at a sub-path (e.g., `/admin`):

**Frontend** — Update the `BrowserRouter` basename:

```tsx title="frontend/src/main.tsx"
<BrowserRouter basename="/admin">
    <App />
</BrowserRouter>
```

**Backend** — Update the base path:

```typescript no-verify
await initializeRebaseBackend({
    // ...
    basePath: "/admin/api"
});
```

:::note[Mounting without a router `basename`]
The `basename` approach above is the recommended one — react-router strips the
prefix from the location, so the admin works unchanged. If instead you embed the
admin inside a **path-prefixed route** of a larger app (e.g. `<Route path="/admin/*">`)
with no `basename`, the current path keeps its `/admin` prefix. Tell the CMS about
it so URL⇄collection resolution accounts for the prefix — otherwise views hang on a
spinner with no data fetch:

```tsx
<RebaseAdmin collections={collections} basePath="/admin" />
```

Set **either** the router `basename` **or** `RebaseAdmin basePath` — not both, or the
prefix is applied twice.
:::

#### Product App + Admin in One Deployment

The common reason to move the admin to `/admin` is shipping your **own product app**
at the root of the same deployment. A single Vite entry can serve both, split by URL,
so each app is lazy-loaded and product visitors never download the admin bundle:

```tsx title="frontend/src/main.tsx"
const isAdmin = window.location.pathname.startsWith("/admin");

const ProductApp = lazy(() => import("./App"));
const AdminApp = lazy(() => import("./AdminApp")); // renders <RebaseAdmin basePath="/admin" />

if (isAdmin) {
    // The admin uses useBlocker → needs a data router
    const router = createBrowserRouter([{ path: "/admin/*", element: <AdminApp /> }]);
    root.render(<RouterProvider router={router} />);
} else {
    root.render(<BrowserRouter><ProductApp /></BrowserRouter>);
}
```

The backend needs no changes for this pattern — the API stays at `/api` and the SPA
catch-all serves `index.html` for both `/` and `/admin/*`.

### Next Steps

- **[Backend Overview](/docs/backend)** — Full backend configuration
- **[Storage Configuration](/docs/backend/storage)** — S3 setup for production

## Self-Hosting

### Overview

Self-hosting Rebase means running two things: a Postgres database, and the
official `rebasepro/server` image with your project's bundle mounted into it.

There is **no application image to build**. Your project travels as a bundle,
the runtime is published, and upgrading Rebase is a tag change rather than a
rebuild. See [Runtime and bundles](/docs/architecture/runtime-and-bundles/) for
why it is split that way.

### Docker Compose

```bash
rebase build                     # produces ./dist-bundle
docker compose up -d db          # start Postgres
rebase db push                   # create the collection tables, once
docker compose up                # start the runtime
```

A minimal `docker-compose.yml`:

```yaml
services:
  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: rebase_app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: rebase
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U rebase -d rebase"]
      interval: 5s
      retries: 12

  api:
    image: rebasepro/server:latest
    depends_on:
      db: { condition: service_healthy }
    environment:
      DATABASE_URL: postgres://rebase:${POSTGRES_PASSWORD}@db:5432/rebase
      JWT_SECRET: ${JWT_SECRET}
      REBASE_SERVICE_KEY: ${REBASE_SERVICE_KEY}
      CORS_ORIGINS: ${CORS_ORIGINS}
    volumes:
      # Writable: the container installs the bundle's declared dependencies into
      # it on first start. See "Dependencies" below for the read-only variant.
      - ./dist-bundle:/bundle
    ports:
      - "8080:8080"

volumes:
  db-data:
```

### Dependencies

`rebase build` writes a `package.json` next to your bundle listing the
dependencies your project declared. The container installs them on first start,
which is why the mount above is writable.

To mount read-only instead — worth doing, because a compromised hook then cannot
rewrite the code that runs after the next restart — install them first:

```bash
npm install --omit=dev --prefix dist-bundle
```

```yaml
    volumes:
      - ./dist-bundle:/bundle:ro
```

For a real deployment, prefer baking both into an image, which also pins exactly
what runs:

```dockerfile
FROM rebasepro/server:0.11.0
COPY dist-bundle /bundle
```

### Creating the schema

The runtime creates its own **auth** tables at boot. **Collection tables are a
separate, deliberate step**, and the runtime image does not do it — a container
restart must not be able to change a schema as a side effect of a deploy.

```bash
rebase db push
```

Run it from a checkout or a CI job, pointed at the deployment's database. It
dry-runs the change first, refuses destructive ones without explicit
confirmation, and can take a backup before applying.

`REBASE_MIGRATE_ON_BOOT` accepts `ensure` (the default — auth tables only) and
`none`.

### Other platforms

The runtime is an ordinary container listening on `$PORT`, so anything that runs
containers works. Two things to get right everywhere:

1. The bundle must be present at `/bundle` (or wherever `REBASE_BUNDLE` points),
   with its dependencies installed beside it — see [Dependencies](#dependencies).
2. Set `CORS_ORIGINS`, `JWT_SECRET` and `DATABASE_URL`. The runtime refuses to
   start in production without them rather than guessing.

#### Fly.io

```toml
[build]
  image = "rebasepro/server:0.11.0"

[http_service]
  internal_port = 8080

[[http_service.checks]]
  path = "/livez"
```

Use the derived-image form above so the bundle ships with the app, then
`fly deploy`.

#### Railway / Render

Point the service at the derived image, set the environment variables, and set
the health check path to `/livez`.

#### A plain VPS

```bash
npm install -g @rebasepro/server @rebasepro/server-postgres
rebase-server /srv/myapp/dist-bundle
```

Run it under systemd, with `Environment=` lines for the variables above.

### Health checks

| Path | Use for |
| --- | --- |
| `/livez` | Liveness. Answers "is this process alive" without touching the database. |
| `/health` | Readiness. Performs a database round-trip and reports latency. |

Point liveness probes at `/livez`. A liveness probe on `/health` restarts a
perfectly healthy process during a brief database hiccup, which is the opposite
of what it is for.

### Metrics

```bash
REBASE_METRICS=true
REBASE_METRICS_TOKEN=<random string>
```

Exposes Prometheus metrics at `/metrics`: request counts and latency histograms
broken down by API surface (data, auth, storage, functions) and collection, plus
process gauges. Without a token the endpoint is readable by anyone who can reach
the port, so set one unless it is on a private network.

### Upgrading

```yaml
image: rebasepro/server:0.12.0
```

Restart. Your bundle is unchanged. Within a runtime contract major, a bundle that
validated keeps working — see
[Compatibility](/docs/architecture/runtime-and-bundles/#compatibility).

## Deploying Rebase on AWS

Amazon Web Services (AWS) provides incredible scale and enterprise-grade security. For a production Rebase deployment, we recommend decoupling the architecture by using **Amazon RDS** for the PostgreSQL database and **AWS App Runner** (or ECS Fargate) to serve the Node.js backend. 

To maintain strict European data compliance, ensure you operate entirely within an EU region, such as **eu-central-1 (Frankfurt)**, **eu-west-1 (Ireland)**, or **eu-west-3 (Paris)**.

### 1. Provision Amazon RDS (PostgreSQL)

1. Navigate to the **RDS** console in your selected EU region.
2. Click **Create database** and select **Standard create**.
3. Choose the **PostgreSQL** engine.
4. Under Templates, choose **Production** or **Free tier/Dev** depending on your load.
5. Create a Master Username (e.g., `rebase_admin`) and securely generate a Master Password.
6. Under Connectivity, ensure the database is placed within a **VPC** that your future App Runner instance can securely access (or make it publicly accessible if strictly controlling ingress IP ranges).
7. Once provisioned, note the **Endpoint endpoint address** and assemble your URI:
   `postgresql://rebase_admin:YOUR_PASSWORD@YOUR_ENDPOINT:5432/postgres`

### 2. Push Image to ECR (Elastic Container Registry)

AWS App Runner pulls directly from ECR. Build your Docker image locally and push it.

1. Navigate to **Elastic Container Registry** and create a new private repository called `rebase-backend`.
2. Grab the push commands provided by AWS in the console (which handle Docker authentication).
3. Build your image locally **from the project root** — the backend Dockerfile needs the whole workspace as its build context (it copies `pnpm-workspace.yaml`, `backend/`, and `config/`), so `./backend` as the context will fail:
   ```bash
   docker build -t rebase-backend -f backend/Dockerfile .
   ```
4. Tag and push it to your newly created ECR repository.

### 3. Deploy via AWS App Runner

App Runner is the simplest way to run containers on AWS without managing orchestrators.

1. Navigate to **AWS App Runner** and click **Create service**.
2. Select **Container registry** and choose **Amazon ECR**.
3. Browse and select your `rebase-backend` image.
4. Under **Service settings**, set the Port to **3001**.
5. Add the necessary Environment Variables under the configuration tab:
   
| Key | Value |
|-----|-------|
| `DATABASE_URL` | Your RDS Connection String |
| `JWT_SECRET` | A secure randomly generated hash (32+ chars) |
| `REBASE_SERVICE_KEY` | A secure randomly generated hash (32+ chars) |
| `NODE_ENV` | `production` |
| `CORS_ORIGINS` | Your frontend domain (e.g., `https://yourdomain.com`) |
| `FRONTEND_URL` | Your frontend URL (used for email links and CORS fallback) |
| `ALLOW_REGISTRATION` | `false` (set to `true` only during initial setup) |

6. (Optional) If your RDS instance is strictly private, configure **Custom VPC** networking in App Runner so the container can securely talk to the database.
7. Click **Create & deploy**.

AWS will handle TLS termination (providing an `https` URL out of the box) and spin up the Rebase server.

### Create the Database Schema

The service is running, but Rebase only auto-creates the **auth** tables on boot — the tables for your own collections are **not** created automatically. Run this once against the production database, or every collection returns a "missing table" error:

```bash
pnpm run db:push
```

Run it from a checkout of your project (or your CI job) with `DATABASE_URL` set to your RDS endpoint. If the instance is private, run it from CI or a bastion host inside the same VPC. The deployed image doesn't include the CLI, so this doesn't run inside the App Runner container. For versioned migrations, commit migration files with `pnpm run db:generate` and run `pnpm run db:migrate` instead.

## Deploying Rebase on Google Cloud Platform

Google Cloud Platform (GCP) offers an incredibly seamless developer experience for containerized applications. For a robust production setup, we leverage **Cloud SQL** for the database and **Cloud Run** for the serverless container backbone.

To maintain strict European data compliance, ensure you operate entirely within an EU region, such as **europe-west3 (Frankfurt)**, **europe-west9 (Paris)**, or **europe-west1 (Belgium)**.

### 1. Provision Cloud SQL (PostgreSQL)

1. Navigate to the **Cloud SQL** console in your preferred EU region.
2. Click **Create Instance** and select **PostgreSQL**.
3. Set your Instance ID and generate a secure built-in password for the `postgres` user.
4. Expand the **Configuration Options** to allocate the correct Machine Type (a standard 2 vCPU machine is a great start).
5. Ensure the database is configured for Private IP or Authorized Public IP networks, depending on your VCP setup with Cloud Run.
6. Assemble your connection URI:
   `postgresql://postgres:YOUR_PASSWORD@YOUR_IP:5432/postgres`

### 2. Build and Deploy to Cloud Run

Cloud Run scales the Rebase Node.js backend automatically down to zero (if desired) and handles TLS out of the box. You can build and deploy the application in a single CLI motion from your local workspace using Google Cloud Build.

Ensure you have the `gcloud` CLI installed and authenticated:

```bash
# Set your active GCP project
gcloud config set project YOUR_PROJECT_ID

# Create an Artifact Registry repository (one-time)
gcloud artifacts repositories create rebase --repository-format=docker --location=europe-west3

# Authenticate Docker to Artifact Registry (one-time)
gcloud auth configure-docker europe-west3-docker.pkg.dev

# Build from the PROJECT ROOT — the backend Dockerfile needs the whole
# workspace as its build context (pnpm-workspace.yaml, backend/, config/),
# so a ./backend context will fail. Then push.
docker build -f backend/Dockerfile -t europe-west3-docker.pkg.dev/YOUR_PROJECT_ID/rebase/backend:latest .
docker push europe-west3-docker.pkg.dev/YOUR_PROJECT_ID/rebase/backend:latest

# Deploy the image to Cloud Run
gcloud run deploy rebase-backend \
  --image europe-west3-docker.pkg.dev/YOUR_PROJECT_ID/rebase/backend:latest \
  --region europe-west3 \
  --port 3001 \
  --set-env-vars DATABASE_URL="postgresql://...",JWT_SECRET="YOUR_SECURE_RANDOM_STRING",REBASE_SERVICE_KEY="YOUR_SERVICE_KEY",NODE_ENV="production",CORS_ORIGINS="https://yourdomain.com",FRONTEND_URL="https://yourdomain.com",ALLOW_REGISTRATION="false" \
  --allow-unauthenticated
```

### 3. Handle File Storage
Since Cloud Run instances are strictly stateless and ephemeral, you cannot use local disk storage for Rebase File Uploads.

1. Navigate to **Google Cloud Storage** and create a new private bucket in your chosen EU region.
2. Follow the [Rebase Storage Documentation](/docs/backend/storage) to configure Rebase to use the S3-compatible API provided by Google Cloud Storage instead of the local filesystem.

Your Rebase instance is now fully serverless and highly scalable natively inside the EU!

### Create the Database Schema

The service is running, but Rebase only auto-creates the **auth** tables on boot — the tables for your own collections are **not** created automatically. Run this once against the production database, or every collection returns a "missing table" error:

```bash
pnpm run db:push
```

Run it from a checkout of your project (or your CI job) with `DATABASE_URL` set to your Cloud SQL instance. From your machine, connect through the [Cloud SQL Auth Proxy](https://cloud.google.com/sql/docs/postgres/sql-proxy) and point `DATABASE_URL` at `localhost`. The deployed image doesn't include the CLI, so this doesn't run inside the Cloud Run container. For versioned migrations, commit migration files with `pnpm run db:generate` and run `pnpm run db:migrate` instead.

## Deploying Rebase on Microsoft Azure

Microsoft Azure offers tight integrations and enterprise compliance. The optimal architecture for running Rebase on Azure involves using **Azure Database for PostgreSQL - Flexible Server** for the data layer and **Azure Container Apps** for hosting the backend container.

To adhere to European data compliance and fast local response times, provision your resources in regions like **West Europe (Amsterdam)**, **North Europe (Ireland)**, or **France Central (Paris)**.

### 1. Provision PostgreSQL Flexible Server

1. From the Azure Portal, search for and select **Azure Database for PostgreSQL servers**.
2. Click **Create** and select **Flexible Server**.
3. Choose your Resource Group and set your preferred EU Region.
4. Select your Compute size (e.g., General Purpose or Burstable `B2s` for smaller deployments).
5. Setup the **Authentication** tab with an Admin username and a secure password.
6. Under **Networking**, ensure "Allow public access from any Azure service within Azure to this server" is checked so your Container App can connect, or configure a secure VNet.
7. Note down your server name and assemble the connection URI:
   `postgresql://your_admin:YOUR_PASSWORD@your-server-name.postgres.database.azure.com:5432/postgres`

### 2. Build and Push to Azure Container Registry (ACR)

Azure Container Apps will pull your Docker image from ACR.
1. Create a new **Container Registry** in your chosen EU region.
2. Login from your CLI:
   ```bash
   az acr login --name YourRegistryName
   ```
3. Build and push the Rebase image **from the project root** — the backend Dockerfile needs the whole workspace as its build context (it copies `pnpm-workspace.yaml`, `backend/`, and `config/`), so `./backend` as the context will fail:
   ```bash
   docker build -t yourregistryname.azurecr.io/rebase-backend:latest -f backend/Dockerfile .
   docker push yourregistryname.azurecr.io/rebase-backend:latest
   ```

### 3. Deploy Azure Container App

Azure Container Apps provides a serverless container environment with built-in HTTPS ingress.

1. Search the portal for **Container Apps** and click **Create**.
2. Create a new Container Apps Environment in your EU region.
3. In the **Container** tab, point to your ACR registry and select the `rebase-backend:latest` image.
4. Set the **Environment variables**:

| Name | Value |
|------|-------|
| `DATABASE_URL` | Your Azure Postgres connection string |
| `JWT_SECRET` | A Secure random 32+ character string |
| `REBASE_SERVICE_KEY` | A Secure random 32+ character string |
| `NODE_ENV` | `production` |
| `CORS_ORIGINS` | Your frontend domain (e.g., `https://yourdomain.com`) |
| `FRONTEND_URL` | Your frontend URL (used for email links and CORS fallback) |
| `ALLOW_REGISTRATION` | `false` (set to `true` only during initial setup) |

5. Under the **Ingress** tab, explicitly Enable Ingress.
6. Set the Target Port to **3001**.
7. Complete the creation. Azure will automatically provision the container and provide you an Application URL secured with TLS!

### Create the Database Schema

The container is running, but Rebase only auto-creates the **auth** tables on boot — the tables for your own collections are **not** created automatically. Run this once against the production database, or every collection returns a "missing table" error:

```bash
pnpm run db:push
```

Run it from a checkout of your project (or your CI job) with `DATABASE_URL` set to your Azure Database for PostgreSQL connection string (add a firewall rule allowing your client IP if needed). The deployed image doesn't include the CLI, so this doesn't run inside the container. For versioned migrations, commit migration files with `pnpm run db:generate` and run `pnpm run db:migrate` instead.

## Deploying Rebase on Hetzner Cloud

Hetzner Cloud is widely recognized for offering incredible performance-to-price ratios and is a top choice for projects requiring strict European data sovereignty and GDPR compliance (with datacenters in Nuremberg, Falkenstein, and Helsinki).

Deploying Rebase on Hetzner is easiest via Docker Compose on a standard Ubuntu cloud instance.

### 1. Provision a Server

1. Log into your Hetzner Cloud Console.
2. Click **Add Server**.
3. Choose your preferred Location (e.g., **Falkenstein** or **Nuremberg**).
4. Choose an Image: Select **Ubuntu 24.04** or **App -> Docker CE** (this pre-installs Docker for you).
5. Choose a Type: A `CPX21` (3 cores, 4GB RAM) or `CX32` (4 cores, 8GB RAM) provides excellent baseline compute for running Rebase + Postgres.
6. Add your SSH key and hit **Create**.

### 2. SSH and Setup

Once your server is provisioned, grab the public IP address.

```bash
ssh root@<your-server-ip>
```

If you didn't choose the Docker image, install Docker and Docker Compose explicitly:

```bash
apt update && apt install docker.io docker-compose-v2 -y
```

### 3. Clone and Configure Rebase

Clone your Rebase project directly onto the server instance. 

```bash
git clone https://github.com/your-username/your-rebase-repo.git /opt/rebase
cd /opt/rebase
```

Rebase provides a `docker-compose.yml` out of the box. You'll need to define your production environment variables. Create a `.env.production` file:

```bash
nano .env.production
```

Add your secrets:

```env
DATABASE_URL=postgresql://rebase_app:your_secure_db_password@postgres:5432/rebase
JWT_SECRET=generate_a_very_long_secure_random_string_here
REBASE_SERVICE_KEY=generate_another_very_long_secure_random_string
NODE_ENV=production
CORS_ORIGINS=https://admin.yourdomain.com
FRONTEND_URL=https://admin.yourdomain.com
ALLOW_REGISTRATION=false
```

*Be sure to update `docker-compose.yml` if you want to pull the Postgres password from an environment variable.*

### 4. Run the Stack

Bring the stack online using detached mode:

```bash
docker compose --env-file .env.production up -d --build
```

Docker will build your Node.js backend from the local `Dockerfile` and spin up the Postgres container. Once completed, your app will be running on `http://localhost:3001` (internal to the server).

### 5. Expose via Caddy or Nginx

You should never expose port 3001 directly to the internet without SSL. We recommend placing **Caddy** in front of your Rebase instance to automatically provision Let's Encrypt certificates.

Install Caddy:
```bash
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy
```

Edit your Caddyfile:
```bash
nano /etc/caddy/Caddyfile
```

Add the following (replace with your domain, which should have its A-Record pointing to this Hetzner IP):

```caddyfile
admin.yourdomain.com {
    reverse_proxy localhost:3001
}
```

Restart Caddy:
```bash
systemctl restart caddy
```

That's it! Your Rebase platform is securely hosted entirely within the EU.

### 6. Create the Database Schema

The stack is running, but Rebase only auto-creates the **auth** tables on boot — the tables for your own collections are **not** created automatically. Run this once against the production database, or every collection returns a "missing table" error. From your project checkout on the server (with dependencies installed), point `DATABASE_URL` at the Postgres container and push the schema:

```bash
pnpm run db:push
```

For versioned migrations, commit migration files with `pnpm run db:generate` and run `pnpm run db:migrate` instead. On startup the server logs a boxed warning naming exactly which tables are missing and the command to run.

## Deploying Rebase on Scaleway

Scaleway is a premier European cloud provider based in France with datacenters in Paris, Amsterdam, and Warsaw. It's an excellent choice for organizations prioritizing EU data sovereignty. 

We recommend utilizing Scaleway's **Managed Database** for reliable Postgres backing and **Serverless Containers** to dynamically scale the Rebase Node.js application.

### 1. Create a Managed Postgres Database

Scaleway's Managed Databases offer automatic backups and high availability.

1. In the Scaleway Console, go to **PostgreSQL**.
2. Click **Create a Database Instance**.
3. Choose a Region (e.g., Paris - `PAR1`).
4. Select a Node Type (a standard **Play2-Pico** or **Pro2-XXS** works well).
5. Add a database name (`rebase_db`) and define an incredibly secure user password.
6. Once deployed, note down the **Connection string** (URI) from the dashboard. It will look like: 
   `postgres://user:password@ip:port/rebase_db`

### 2. Build and Push the Container

Scaleway Serverless Containers run standard Docker images. First, build the Rebase backend locally and push it to the Scaleway Container Registry.

1. Go to **Container Registry** in the Scaleway Console and create a Namespace (e.g., `rebase-apps`).
2. Log in to the registry from your local terminal using the provided instructions.
3. Build your Rebase app using the generated `Dockerfile`, **from the project root** — the backend Dockerfile needs the whole workspace as its build context (it copies `pnpm-workspace.yaml`, `backend/`, and `config/`), so `./backend` as the context will fail:

```bash
docker build -t rg.fr-par.scw.cloud/rebase-apps/rebase-backend:latest -f backend/Dockerfile .
```

4. Push the image:

```bash
docker push rg.fr-par.scw.cloud/rebase-apps/rebase-backend:latest
```

### 3. Deploy Serverless Container

Now deploy the image completely serverless without managing infrastructure.

1. Navigate to **Serverless Containers**.
2. Click **Create a Container**.
3. Choose the image you just pushed from the Container Registry.
4. Set the Port to **3001**.
5. Under Environment Variables, add the following securely:

| Key | Value |
|-----|-------|
| `DATABASE_URL` | The URI from your Managed Postgres step |
| `JWT_SECRET` | A secure 32+ character random string for signing auth tokens |
| `REBASE_SERVICE_KEY` | A secure 32+ character random string |
| `NODE_ENV` | `production` |
| `CORS_ORIGINS` | Your frontend domain (e.g., `https://yourdomain.com`) |
| `FRONTEND_URL` | Your frontend URL (used for email links and CORS fallback) |
| `ALLOW_REGISTRATION` | `false` (set to `true` only during initial setup) |

6. Click **Deploy Container**.

Scaleway will immediately provision the container and provide you with a public endpoint URL (e.g., `https://rebase-backend-xxxx.functions.fnc.fr-par.scw.cloud`). 

*Note: For strict data compliance, verify that your Scaleway Organization details reflect your European corporate entity.*

### 4. Create the Database Schema

The container is running, but Rebase only auto-creates the **auth** tables on boot — the tables for your own collections are **not** created automatically. Run this once against the production database, or every collection returns a "missing table" error:

```bash
pnpm run db:push
```

Run it from a checkout of your project (or your CI job) with `DATABASE_URL` set to your Scaleway Managed Database connection string. The deployed image doesn't include the CLI, so this doesn't run inside the container. For versioned migrations, commit migration files with `pnpm run db:generate` and run `pnpm run db:migrate` instead.

## Deploying Rebase on Railway

Railway is an incredibly popular modern PaaS (Platform as a Service) that takes the pain out of DevOps. It will automatically detect the Rebase Node framework and build it seamlessly. 

Additionally, Railway fully supports European deployment regions (Amsterdam), meaning you still enjoy strict regional hosting compliance.

### 1. Create a Project & EU Region
1. Login to your [Railway Account](https://railway.app/).
2. Click **New Project**.
3. Go to **Settings -> Default Region**, and explicitly set it to **Europe (Amsterdam)**. (If you do this *after* creating services, you may need to manually migrate them).

### 2. Provision PostgreSQL
1. Inside your project, click **New** -> **Database** -> **Add PostgreSQL**.
2. Wait a few seconds for the database to provision.
3. By default, Railway provides an internal `DATABASE_URL` variable. Click on the Postgres widget -> **Variables** to locate this connection string.

### 3. Deploy Rebase Code
1. Click **New** -> **GitHub Repo**.
2. Select your Rebase repository.
3. Railway will immediately detect the repository and look for a `Dockerfile`. Wait for the initial build to begin.

:::caution[Point Railway at the backend Dockerfile]
The scaffold's Dockerfile lives at `backend/Dockerfile`, not the repo root, and its build context must be the **repo root** (it copies `pnpm-workspace.yaml`, `backend/`, and `config/`). In the service's **Settings → Build**, set the **Dockerfile Path** to `backend/Dockerfile` and leave the **Root Directory** at the repository root. Otherwise Railway won't find a Dockerfile — or will build with the wrong context and fail.
:::

### 4. Set Environment Variables
The initial build might fail because it is entirely missing configuration. Let's fix that.

1. Click on the new Rebase GitHub service card.
2. Go to the **Variables** tab. 
3. Click **New Variable** and add:
   - `JWT_SECRET`: Generate a secure 32+ character random string.
   - `REBASE_SERVICE_KEY`: Generate another secure 32+ character random string.
   - `NODE_ENV`: Set to `production`
   - `CORS_ORIGINS`: Your frontend domain (e.g., `https://your-app.up.railway.app`)
   - `FRONTEND_URL`: Same as CORS_ORIGINS
   - `ALLOW_REGISTRATION`: Set to `false` after creating your admin account
4. Click **Reference Variable** and select `DATABASE_URL` from the PostgreSQL service you provisioned. Railway will securely inject the internal Postgres URL at runtime.

### 5. Expose the Domain
1. In the Rebase service card, navigate to the **Settings** tab.
2. Scroll down to **Networking**.
3. Under **Public Networking**, click **Generate Domain**. Railway will provide a `.up.railway.app` testing URL. You can also securely attach a Custom Domain here.

Railway will automatically rebuild safely. Your EU-hosted platform is now entirely live!

### 6. Create the Database Schema

The app is running, but Rebase only auto-creates the **auth** tables on boot — the tables for your own collections are **not** created automatically. Run this once against the production database, or every collection returns a "missing table" error:

```bash
pnpm run db:push
```

Run it from a checkout of your project (or your CI job) with `DATABASE_URL` set to your Postgres service's **public** connection string (found under the Postgres widget → **Connect**; the referenced internal `DATABASE_URL` is only reachable from inside Railway). The deployed image doesn't include the CLI, so this doesn't run inside the container. For versioned migrations, commit migration files with `pnpm run db:generate` and run `pnpm run db:migrate` instead.

## Deploying Rebase on Fly.io

Fly.io allows you to host Docker containers close to your users via their global anycast network. Fly is highly configurable regarding data routing, making it an excellent choice for deploying Rebase applications with a strict European data focus.

Fly.io features data centers in **Amsterdam (ams)**, **Frankfurt (fra)**, **Madrid (mad)**, and **Paris (cdg)**. 

### 1. Initialize the Fly App
From your local Rebase repository, after ensuring the Fly CLI (`flyctl`) is installed, run:

```bash
fly launch
```

1. **App Name:** `my-rebase-app`
2. **Organization:** Personal or your corporate Org.
3. **Region:** When prompted for a region, explicitly choose a European datacenter such as **Frankfurt (fra)** or **Paris (cdg)**.
4. **Database:** When prompted to setup a Postgres database, say **Yes**. Fly will automatically create a Postgres cluster in the *same region* and securely inject the `DATABASE_URL` into your app.
5. **Redis:** Say **No**.

*Do not deploy just yet when prompted.* We need to set a critical environment variable first.

### 2. Set Production Secrets
Before your application spins up in production, you must inject the required secrets and configuration.

Run the following command locally:
```bash
fly secrets set \
  JWT_SECRET=your_super_long_randomly_generated_secure_string \
  REBASE_SERVICE_KEY=another_super_long_randomly_generated_secure_string \
  CORS_ORIGINS=https://my-rebase-app.fly.dev \
  FRONTEND_URL=https://my-rebase-app.fly.dev \
  ALLOW_REGISTRATION=false \
  -a my-rebase-app
```

### 3. Validate Internal Configuration
Fly will have generated a `fly.toml` file at the root of your project. Verify that the internal port explicitly aligns with the Rebase default configuration (`3001`):

```toml
# fly.toml
app = "my-rebase-app"
primary_region = "fra"

[build]
  # The scaffold's Dockerfile lives at backend/Dockerfile, and its build
  # context is the project root (where fly.toml sits) so it can copy
  # pnpm-workspace.yaml, backend/, and config/. Pointing this at a bare
  # "Dockerfile" (repo root) will fail — there is none there.
  dockerfile = "backend/Dockerfile"

[http_service]
  internal_port = 3001 # Make sure this matches your Hono app port
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 1
```

### 4. Deploy

Your data is localized, your database is provisioned, and your secrets are injected. Start the deployment:

```bash
fly deploy
```

Once parsing and uploading completes, your application will come online automatically. Run `fly open` to view your deployed app in the browser!

### 5. Create the Database Schema

The app is running, but Rebase only auto-creates the **auth** tables on boot — the tables for your own collections are **not** created automatically. Run this once against the production database, or every collection returns a "missing table" error:

```bash
pnpm run db:push
```

Run it from a checkout of your project (or your CI job) with `DATABASE_URL` set to your Postgres connection string. For a private Fly Postgres, open a tunnel first with `fly proxy 5432 -a <your-db-app>` and point `DATABASE_URL` at `localhost:5432`. The deployed image doesn't include the CLI, so this doesn't run inside the machine and a `release_command` can't call it either. For versioned migrations, commit migration files with `pnpm run db:generate` and run `pnpm run db:migrate` instead.

## Recipe: Blog CMS

### Overview

Build a blog backend with:
- **Articles** with markdown content and cover images
- **Authors** with profiles
- **Categories** with a many-to-many relation

### Collections

#### Authors

```typescript

export const authorsCollection = defineCollection({
    slug: "authors",
    name: "Authors",
    singularName: "Author",
    table: "authors",
    properties: {
        name: {
            type: "string",
            name: "Name",
            validation: { required: true }
        },
        email: {
            type: "string",
            name: "Email",
            email: true,
            validation: { required: true, unique: true }
        },
        avatar: {
            type: "string",
            name: "Avatar",
            storage: {
                storagePath: "avatars",
                acceptedFiles: ["image/*"],
                maxSize: 2 * 1024 * 1024
            }
        },
        bio: {
            type: "string",
            name: "Bio",
            admin: { multiline: true }
        }
    },
    admin: {
        icon: "person"
    }
});

```

#### Categories

```typescript

export const categoriesCollection = defineCollection({
    slug: "categories",
    name: "Categories",
    singularName: "Category",
    table: "categories",
    properties: {
        name: {
            type: "string",
            name: "Name",
            validation: { required: true }
        },
        slug: {
            type: "string",
            name: "Slug",
            validation: { required: true, unique: true }
        },
        color: {
            type: "string",
            name: "Color",
            enum: [
                { id: "blue", label: "Blue", color: "blue" },
                { id: "green", label: "Green", color: "green" },
                { id: "red", label: "Red", color: "pink" },
                { id: "orange", label: "Orange", color: "orange" }
            ]
        }
    },
    admin: {
        icon: "label"
    }
});

```

#### Articles

```typescript

// The row shape, so callbacks below see typed `values` instead of `unknown`.
type Article = {
    title: string;
    slug: string;
    status: string;
    published_at?: Date | null;
};

export const articlesCollection = defineCollection({
    slug: "articles",
    name: "Articles",
    singularName: "Article",
    table: "articles",
    history: true,
    properties: {
        title: {
            type: "string",
            name: "Title",
            validation: { required: true }
        },
        slug: {
            type: "string",
            name: "URL Slug",
            validation: { required: true, unique: true }
        },
        author: {
            type: "relation",
            name: "Author",
            relationName: "author"
        },
        status: {
            type: "string",
            name: "Status",
            enum: [
                { id: "draft", label: "Draft", color: "gray" },
                { id: "review", label: "In Review", color: "orange" },
                { id: "published", label: "Published", color: "green" }
            ],
            defaultValue: "draft"
        },
        cover_image: {
            type: "string",
            name: "Cover Image",
            storage: {
                storagePath: "articles/covers",
                acceptedFiles: ["image/*"]
            }
        },
        content: {
            type: "string",
            name: "Content",
            admin: { markdown: true }
        },
        excerpt: {
            type: "string",
            name: "Excerpt",
            admin: { multiline: true },
            validation: { max: 300 }
        },
        published_at: {
            type: "date",
            name: "Published At"
        },
        created_at: {
            type: "date",
            name: "Created At",
            autoValue: "on_create",
            admin: { readOnly: true }
        }
    },
    relations: [
        {
            kind: "belongsTo",
            relationName: "author",
            target: () => authorsCollection,
            localKey: "author_id"
        },
        {
            kind: "manyToMany",
            relationName: "categories",
            target: () => categoriesCollection,
            through: {
                table: "article_categories",
                sourceColumn: "article_id",
                targetColumn: "category_id"
            }
        }
    ],
    callbacks: {
        beforeSave: async ({ values, status }) => {
            // Auto-generate slug
            if (values.title && !values.slug) {
                values.slug = values.title
                    .toLowerCase()
                    .replace(/[^a-z0-9]+/g, "-");
            }
            // Set published_at when publishing
            if (values.status === "published" && !values.published_at) {
                // `published_at` is a `date` property, so its value is a Date.
                values.published_at = new Date();
            }
            return values;
        }
    },
    securityRules: [
        { operation: "select", using: "{status} = 'published'" },
        { operation: "select", ownerField: "author_id" },
        { operations: ["insert", "update"], ownerField: "author_id" },
        { operation: "delete", roles: ["admin"] }
    ],
    admin: {
        icon: "article",
        defaultViewMode: "table"
    }
});

```

### Setup

1. Add all three collections to your `config/collections/index.ts`
2. Run `rebase schema generate`
3. Run `rebase db push`
4. Restart the dev server

You now have a fully functional blog CMS with:
- Author management with avatar uploads
- Category tagging via many-to-many relations
- Markdown content editing
- Draft → Review → Published workflow
- Auto-generated URL slugs
- RLS policies limiting authors to their own posts
- Full audit trail via entity history

### Querying from the SDK

Use the client SDK to fetch articles with their relations:

```typescript
// The row shape you expect back — without it every field arrives as `unknown`.
type Article = {
    title: string;
    status: string;
    published_at?: string | null;
    author_id: string;
    author?: { name: string };
    categories?: { name: string }[];
};

// Fetch published articles with author and categories included
const { data: articles } = await client.data
    .collection<Article>("articles")
    .where("status", "==", "published")
    .include("author", "categories")
    .orderBy("published_at", "desc")
    .limit(10)
    .find();

// Rows come back flat — there is no `values` wrapper on the SDK.
for (const article of articles) {
    console.log(article.title);
    console.log(article.author?.name);    // Hydrated relation
    console.log(article.author_id);       // Scalar FK
    console.log(article.categories);      // Array of related entities
}
```


## Recipe: Custom Dashboard

### Overview

Build a custom dashboard view that displays analytics alongside your admin panel.

### Create the Dashboard Component

```tsx

function DashboardView() {
    const context = useRebaseContext();
    const [stats, setStats] = useState({
        totalOrders: 0,
        totalRevenue: 0,
        activeProducts: 0,
        recentOrders: []
    });

    useEffect(() => {
        async function loadStats() {
            // Use the data source to fetch aggregate data
            // `find` resolves to { data, meta } — the rows are on `data`, and they are
            // flat, so it is `o.total` rather than `o.values.total`.
            const { data: orders } = await context.data
                .collection<{ total: number }>("orders")
                .find({ limit: 1000 });

            const { data: products } = await context.data
                .collection<Record<string, unknown>>("products")
                .find({ where: { active: ["==", true] } });

            setStats({
                totalOrders: orders.length,
                totalRevenue: orders.reduce((sum, o) => sum + (o.total ?? 0), 0),
                activeProducts: products.length,
                recentOrders: orders.slice(0, 5)
            });
        }
        loadStats();
    }, []);

    return (
        <div className="p-8">
            <h1 className="text-xl font-semibold tracking-[-0.01em] mb-6">Dashboard</h1>
            <div className="grid grid-cols-3 gap-4 mb-8">
                <StatCard title="Total Orders" value={stats.totalOrders} />
                <StatCard title="Revenue" value={`$${stats.totalRevenue.toFixed(2)}`} />
                <StatCard title="Active Products" value={stats.activeProducts} />
            </div>
            <h2 className="text-sm font-semibold tracking-[-0.01em] mb-4">Recent Orders</h2>
            <ul>
                {stats.recentOrders.map(order => (
                    <li key={order.id}>
                        Order #{order.id} — ${order.values.total}
                    </li>
                ))}
            </ul>
        </div>
    );
}

function StatCard({ title, value }: { title: string; value: string | number }) {
    return (
        <div className="bg-surface-100 dark:bg-surface-800 rounded-lg p-6">
            <p className="text-xs text-surface-500">{title}</p>
            <p className="text-xl font-semibold">{value}</p>
        </div>
    );
}
```

### Register as a Custom View

```tsx
const views: AppView[] = [
    {
        slug: "dashboard",
        name: "Dashboard",
        view: <DashboardView />,
        admin: {
            icon: "dashboard",
            group: "Analytics"
        }
    }
];

```

Pass it to the navigation controller:

```typescript
const navigationStateController = useBuildNavigationStateController({
    views,
    collections: () => collections,
    // These four are required — the controller resolves navigation against them.
    authController,
    data,
    collectionRegistryController,
    urlController
});
```

The dashboard now appears in the sidebar under "Analytics" and is accessible at `/dashboard`.

#### Pinning the group to the bottom

Groups named `"Admin"` or `"Settings"` sink below the others in the drawer, by
string comparison on the name. That is easy to lose — translate the label and
the ordering silently stops happening — so say it explicitly instead:

```tsx
{ slug: "dashboard", name: "Dashboard", view: <DashboardView />, group: "Ajustes", pinToBottom: true }
```

Setting `pinToBottom` on any one view in a group pins the whole group, since
the drawer orders groups rather than individual views.

### Navigating from a custom view

A view component receives no props. To route somewhere — another custom view, a
collection, an entity — reach for `useUrlController`, which is exported from
`@rebasepro/admin`:

```tsx

function DashboardView() {
    const urlController = useUrlController();

    return (
        <>
            <button onClick={() => urlController.navigate(urlController.buildAppUrlPath("reports"))}>
                Reports
            </button>
            <button onClick={() => urlController.navigate(urlController.buildUrlCollectionPath("orders"))}>
                All orders
            </button>
            <button onClick={() => urlController.navigate(urlController.buildUrlCollectionPath("orders/B34SAP8Z"))}>
                Order B34SAP8Z
            </button>
        </>
    );
}
```

Build the path rather than hard-coding it: collection URLs are prefixed
(`orders` → `/c/orders`) and the prefix is not part of the public contract.

`useSidePanel` opens an entity in the side panel instead of navigating, which is
usually what you want for a row in a list.

### Adding Charts

Install a charting library:

```bash
pnpm add recharts
```

Then use it in your dashboard:

```tsx

function RevenueChart({ data }) {
    return (
        <LineChart width={600} height={300} data={data}>
            <CartesianGrid strokeDasharray="3 3" />
            <XAxis dataKey="date" />
            <YAxis />
            <Tooltip />
            <Line type="monotone" dataKey="revenue" stroke="#8884d8" />
        </LineChart>
    );
}
```

### Next Steps

- **[Custom Views](/docs/frontend)** — Frontend overview
- **[Hooks Reference](/docs/hooks)** — Available hooks

## Recipe: Webhook Integration

### Overview

Use `afterSave` and `afterDelete` callbacks to notify external services when data changes in Rebase.

Two things about those callbacks decide how this recipe is written, and neither is optional:

- **They run inside the write's database transaction.** Anything you `await` there holds a pooled
  connection and the row's locks until it comes back. A receiver that takes ten seconds is a
  ten-second transaction; a receiver that never answers is a transaction that never ends.
- **A throw from `afterSave` rolls the write back.** The error reaches the caller as a 500 and the
  row is not saved. Awaiting a third party inside the callback makes their outage your data loss.

So: never `await` an outbound HTTP request in a callback. Queue it.

### Slack Notification on New Order

`WebhookDispatcher` is exported from `@rebasepro/server`. `enqueueEntityChange` returns
immediately — the POST happens after the callback returns, outside the transaction — and the
dispatcher validates the destination, signs the payload, bounds every attempt with a deadline and
retries failures.

```typescript

// The row shape, so `values.customer_name` is a string rather than nothing.
type Order = { customer_name: string; total: number };

const dispatcher = new WebhookDispatcher({
    // Queued deliveries return nothing to the caller, so this is where their
    // failures surface. Without it, a receiver that has been down for a week
    // looks exactly like one that is working.
    onDelivery: (result) => {
        if (!result.success) {
            console.error(`Webhook ${result.webhookId} failed: ${result.statusCode} ${result.responseBody}`);
        }
    }
});

dispatcher.setWebhooks([
    {
        id: "wh_orders_slack",
        url: process.env.SLACK_WEBHOOK_URL!,
        secret: process.env.WEBHOOK_SECRET,
        events: ["INSERT"],
        table: "orders",
        enabled: true
    }
]);

const ordersCollection: PostgresCollectionConfig<Order> = {
    slug: "orders",
    name: "Orders",
    table: "orders",
    callbacks: {
        afterSave: async ({ values, id, status }) => {
            if (status === "new") {
                // Returns void, immediately. The delivery runs after this
                // callback returns, so the transaction is not waiting on it.
                dispatcher.enqueueEntityChange("orders", "INSERT", String(id), values);
            }
        }
    },
    properties: { /* ... */ }
};
```

The queue is in-process and in-memory: a crash or a deploy between the enqueue and the delivery
drops the event, and the receiver may see the notification a few milliseconds before the row is
committed. Call `await dispatcher.flush()` on shutdown. If you need deliveries to survive a
restart, write an outbox row in the same transaction and drain it from a job instead.

#### Calling an endpoint directly

If you are posting a hand-built body to one endpoint and do not want the dispatcher, the same two
rules still apply — bound the request, and never let its failure reach the caller:

```typescript

type Order = { customer_name: string; total: number };

const callbacks: CollectionCallbacks<Order> = {
    afterSave: async ({ values, id, status }) => {
        if (status !== "new") return;
        // No `await`: the transaction must not wait for Slack. `AbortSignal.timeout`
        // because `fetch` has no default timeout at all — without it a black-holed
        // connection holds the transaction until the OS gives up, minutes later.
        void fetch(process.env.SLACK_WEBHOOK_URL!, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                text: `New order #${id}\nCustomer: ${values.customer_name}\nTotal: $${values.total}`
            }),
            signal: AbortSignal.timeout(10_000)
        }).catch((error) => {
            // Swallowed on purpose. A throw here would be an unhandled rejection;
            // a throw *inside* the callback would roll the order back.
            console.error("Slack notification failed", error);
        });
    }
};
```

Never put a URL that came from your database into a bare `fetch`. The dispatcher rejects loopback,
link-local, private and non-`http(s)` destinations before it connects, and refuses to follow
redirects, precisely because a stored URL is attacker-controlled input.

### Sync to External API

`afterDelete` receives the deleted row flat, as `row` — the table's columns, not an entity wrapper.

```typescript

type Product = { name: string; description: string; price: number; shopify_id: string };

const syncQueue: Promise<unknown>[] = [];

const callbacks: CollectionCallbacks<Product> = {
    afterSave: async ({ values, id }) => {
        // Queued, not awaited: Shopify being down must not fail the save.
        syncQueue.push(
            fetch("https://your-shop.myshopify.com/admin/api/2024-01/products.json", {
                method: "PUT",
                headers: {
                    "Content-Type": "application/json",
                    "X-Shopify-Access-Token": process.env.SHOPIFY_TOKEN!
                },
                body: JSON.stringify({
                    product: {
                        id: values.shopify_id,
                        title: values.name,
                        body_html: values.description,
                        variants: [{ price: values.price }]
                    }
                }),
                signal: AbortSignal.timeout(10_000)
            }).catch((error) => console.error(`Shopify sync failed for ${id}`, error))
        );
    },

    afterDelete: async ({ row }) => {
        const shopifyId = row.shopify_id;
        if (!shopifyId) return;
        syncQueue.push(
            fetch(
                `https://your-shop.myshopify.com/admin/api/2024-01/products/${shopifyId}.json`,
                {
                    method: "DELETE",
                    headers: { "X-Shopify-Access-Token": process.env.SHOPIFY_TOKEN! },
                    signal: AbortSignal.timeout(10_000)
                }
            ).catch((error) => console.error(`Shopify delete failed for ${shopifyId}`, error))
        );
    }
};
```

### Error Handling

`afterSaveError` runs when the save — or any `afterSave` callback — throws. It is a notification
hook, not a rescue: **the error is rethrown after it runs**, the transaction rolls back, and the
row is not saved.

```typescript

const callbacks: CollectionCallbacks = {
    afterSave: async ({ values }) => {
        // If this throws, the write is rolled back. That is the right behaviour
        // for a validation or an invariant, and the wrong one for a notification.
        await recordAuditEntry(values);
    },
    afterSaveError: async ({ id, values }) => {
        // Runs, and then the error is rethrown. Use it to alert, not to recover.
        console.error(`Save failed for entity ${id}`, values);
    }
};
```

If a failure should *not* cost the user their write, it must not throw out of `afterSave` — catch
it there, or hand the work to the dispatcher's queue.

### Next Steps

- **[Entity Callbacks](/docs/collections/callbacks)** — Full callback reference
- **[Blog CMS Recipe](/docs/recipes/blog-cms)** — Complete blog example