Imported from rebasepro/rebase (tooling/rebase-agent-skills/skills/rebase-collections/SKILL.md). Install upstream with npx skills add rebasepro/rebase --skill rebase-collections. Copyright stays with the author.

Rebase Collections

Rebase collections are the core building blocks of your data model. They define the structure, validation, and UI configuration of your data — all in TypeScript.

Core Concepts

Collections

A collection is defined as a TypeScript object implementing the PostgresCollectionConfig interface from @rebasepro/types. Each collection maps to a database table (via the table property) and generates:

• Full CRUD REST endpoints at /api/data/{slug}
• Admin panel views (table, forms, cards, kanban, list)

Properties

Properties define the fields of your collection. Rebase supports these built-in property types:

Reference vs Relation

IMPORTANT FOR AGENTS: Understand the difference between reference and relation — they are NOT interchangeable.

Use relation for all new Postgres collections. The reference type exists for backward compatibility with Firestore-style collections.

A string property can also act as a lightweight reference via its reference sub-property (stores just the ID string and renders a reference picker), but this does not create SQL JOINs.

Schema-as-Code

Collections are defined as standalone TypeScript files under config/collections/ relative to the project root, and each one is registered in the collections array exported by that directory's index.ts — a file that is not in the array does not exist as far as the CLI or the runtime is concerned. The visual Studio edits these files via AST manipulation — it never runs raw SQL. This preserves custom callbacks and complex configuration.

Defining a Collection

import { PostgresCollectionConfig } from "@rebasepro/types";

const productsCollection: PostgresCollectionConfig = {
    name: "Products",
    singularName: "Product",
    slug: "products",
    table: "products",
    description: "Product catalog with pricing and inventory",
    history: true,
    properties: {
        id: {
            name: "ID",
            type: "number",
            isId: "increment"
        },
        name: {
            name: "Product Name",
            type: "string",
            validation: { required: true }
        },
        price: {
            name: "Price",
            type: "number",
            validation: { required: true, min: 0 }
        },
        description: {
            name: "Description",
            type: "string",
            admin: { multiline: true }
        },
        published: {
            name: "Published",
            type: "boolean",
            defaultValue: false
        },
        createdAt: {
            name: "Created At",
            type: "date",
            mode: "date_time",
            autoValue: "on_create",
            admin: { readOnly: true, hideFromCollection: true }
        },
        category: {
            name: "Category",
            type: "string",
            enum: [
                { id: "electronics", label: "Electronics", color: "blue" },
                { id: "clothing", label: "Clothing", color: "purple" },
                { id: "books", label: "Books", color: "green" }
            ]
        }
    },
    admin: {
        icon: "ShoppingBag",
        group: "E-Commerce",
        defaultViewMode: "table",
        enabledViews: ["table", "cards"],
        openEntityMode: "split",
        inlineEditing: true,
        exportable: true,
        selectionEnabled: true,
        propertiesOrder: [
            "name", "price", "category", "description",
            "published", "createdAt"
        ]
    }
};

export default productsCollection;

Presentation lives under admin. Keys written admin.x below go inside a nested admin: { … } block, not at the top level. The backend never reads inside it, which is what lets a BaaS or headless project have no React in its dependency tree at all.

There is no AdminCollectionConfig wrapper type — do not import one. The block is typed by a program-level augmentation: put one triple-slash reference in the config package,

/// <reference types="@rebasepro/cms-types" />

and admin is typed on every collection and every property from then on. An augmentation applies to a whole TypeScript program, and config/ and frontend/ are separate programs, which is why the reference belongs in config/. Without it, admin is opaque and a typo compiles.

Collection Options

Kanban boards

A Kanban board is three decisions, not one. Ship all three together; each one missing produces a board that renders, looks configured, and silently does not reorder.

1. kanban and orderProperty are two halves of one feature

import { PostgresCollectionConfig } from "@rebasepro/types";

const tasksCollection: PostgresCollectionConfig = {
    name: "Tasks",
    slug: "tasks",
    table: "tasks",
    properties: {
        id: { name: "ID", type: "string", isId: "uuid" },
        title: { name: "Title", type: "string" },
        status: {
            name: "Status",
            type: "string",
            enum: [
                { id: "todo", label: "To do" },
                { id: "doing", label: "Doing" },
                { id: "done", label: "Done" }
            ]
        },
        // The order key. Machinery, not content — hide it.
        __order: {
            name: "Order",
            type: "string",
            admin: { disabled: true, hideFromCollection: true }
        }
    },
    admin: {
        defaultViewMode: "kanban",
        enabledViews: ["kanban", "table"],
        kanban: { columnProperty: "status" },
        orderProperty: "__order"      // ← never omit this
    }
};

Declaring kanban without orderProperty still gives you a draggable board: moving a card between columns writes columnProperty and sticks. Its position within a column has nowhere to be stored, so it snaps back on the next read, and the board renders an amber "ordering is not configured" bar above the columns. Nothing errors. Reviewing the config will not show you the bug — only opening the board will.

2. The order property is a string

Reordering writes a fractional-indexing key — "i0", "i1", "i0i" — not an index. Keys use the base36, lower-case alphabet 0123456789abcdefghijklmnopqrstuvwxyz: Postgres does the sorting and its default collation is not byte ordering, so the library's default base62 output ("a0", mixing cases) sorts differently in the database than in the key.

Consequences worth knowing before you pick a type:

• type: "number" can never hold a key. A sortOrder number leaves the board permanently asking to be initialised, and the initialisation then fails writing a string into a numeric column.
• A plain counter in a string column — "1", "12", "000001" — is rejected just as hard. fractional-indexing cannot interpolate against it, so the board treats it as absent.
• generateKeyBetween(a, b) without the alphabet argument produces base62 keys the board rejects. Always pass ORDER_KEY_DIGITS.

3. Rows created outside the admin need a key assigned

Nothing assigns an order key on insert — not the REST API, not the SDK, not a cron, not a seed script, not a migration. Those rows land with __order null and the board shows "Some items don't have order values. Initialize to enable drag-and-drop reordering." Clicking Initialize backfills one page; the next cron run brings the bar straight back.

If a backend writes rows into a board collection, it assigns the key.

import { generateKeyBetween } from "fractional-indexing";

const ORDER_KEY_DIGITS = "0123456789abcdefghijklmnopqrstuvwxyz";

const leads = client.data.collection("leads");

// The last key currently in use. `is-not-null` is not optional: a descending
// sort is NULLS FIRST in this driver, so without it this reads back one of the
// very rows that has no key, and every insert lands on the same "i0".
const { data: last } = await leads.find({
    where: { __order: ["is-not-null", null] },
    orderBy: ["__order", "desc"],
    limit: 1
});
let cursor: string | null = (last[0]?.__order as string | undefined) ?? null;

for (const candidate of shortlist) {
    cursor = generateKeyBetween(cursor, null, ORDER_KEY_DIGITS);
    await leads.create({ /* … */ status: "new", __order: cursor });
}

Note the cursor carried across the loop. Calling generateKeyBetween(null, null, …) per row instead hands every row of the batch the same key — valid enough to clear the warning bar, useless as an order. Re-reading the max inside the loop is correct but costs a round-trip per row.

The config validator checks two of these for you

assertCollectionConfigs runs wherever the collections are loaded — server boot, rebase schema generate, rebase doctor — so you do not have to remember:

• kanban (or a kanban entry in enabledViews/defaultViewMode) with no orderProperty → warning, naming the property to add. It boots: the board works, it just does not reorder.
• orderProperty naming a property that does not exist, or one that is not a string → error, and the boot fails. Both are unambiguously broken, and the fix is one line.

Nothing checks decision 3 — no static check can tell which code paths write to a collection. That one is on you.

Checklist

Before calling a Kanban collection done:

• kanban.columnProperty names an enum property
• orderProperty is set, and names a string property
• that property is hidden (admin: { disabled: true, hideFromCollection: true })
• every code path that creates rows in this collection assigns an order key
• the property exists in properties — under defineCollection the key is checked against them, so a missing one narrows to never and fails to typecheck; under PostgresCollectionConfig it is a plain string and a typo goes through silently
• the schema was regenerated and pushed after adding it (Schema Migration Workflow below) — the column has to exist before anything can write a key

Search

By default .search("term") is a case-insensitive substring match OR-ed across the collection's top-level string properties. It cannot see inside map (JSONB) or array properties, does not rank, and cannot use an index.

This is the single most common "search is broken" report. If a collection keeps searchable content in a map — tags, certifications, a questionnaire, an answers blob — none of it is reachable by the default, and the search box returns nothing with no error. When a user says search finds nothing for content they can plainly see on the record, check where that content lives before anything else.

Declare a search block to fix it. Postgres only.

const talents: PostgresCollectionConfig = {
    slug: "talents",
    table: "talents",
    name: "Candidates",
    properties: { /* … */ },
    search: {
        language: "spanish",     // stemming + stopwords; default "simple" (neither)
        unaccent: true,          // `auditoria` matches `auditoría`
        fuzzy: true,             // `iso14000` reaches `ISO 14001`
        fields: [
            { path: "full_name", weight: "A" },
            { path: "questionnaire.certifications", weight: "A" },  // into the JSONB
            "location",                                             // defaults to weight B
            "interests"                                             // a string[]
        ]
    }
};

Rows then come back with a sortable _score:

client.data.talents.search("auditor iso 14001").orderBy("_score", "desc").find()

Rules an agent must not get wrong

• Nothing is inferred. A field is indexed only if named in fields. A path that does not resolve is a boot error, not a warning — so a config that boots is a config whose search fields are all real.
• A path may name a string property, a string[] property, a map, or a dotted path inside a map ("questionnaire.certifications"). A map path indexes every string value at or below it, at any depth. JSON keys are never indexed.
• Enums, UUIDs, json (not jsonb) columns and numeric arrays are refused. Enums are a fixed vocabulary — filter them with where, which is exact and indexed.
• language defaults to "simple", which does no stemming. Set it to the content's language deliberately; a stemmer applied to the wrong language silently mangles lexemes.
• unaccent is not cosmetic in an accented language. Postgres stems auditoría → auditor and auditoria → auditori, different lexemes, so without it a query typed without accents misses every row that has them.
• Weights are A–D, strongest to weakest, defaulting to B. Put names and identifiers at A and long free text at D, or a passing mention in a bio outranks the field the user actually meant.
• Declaring it creates schema: one generated tsvector column plus a GIN index (and, with fuzzy, a second column and a trigram index). Boot-ensure adds them; adding a stored generated column rewrites the table, so on a large live table treat it as a planned migration.
• Do not add it to a Mongo or Firestore collection. It is refused at boot.

Explaining a match

client.data.x.search(term, { explain: true }) returns _matches per row — which declared field matched, plus a <mark>-highlighted snippet. This is usually what someone means by "show me why this result appeared". Per-query, not config: it costs a ts_headline per field per row.

When not to reach for it

If the user wants exact matching on a known field, use where — it is exact, indexed, and needs no schema. The search block is for free-text queries a human types.

Indexes

A collection declares the indexes its queries need, in indexes. Postgres only — refused at boot on another engine, not silently ignored.

const posts: PostgresCollectionConfig = {
    slug: "posts",
    table: "posts",
    name: "Blog posts",
    properties: { /* … */ },
    indexes: [
        // Filter by status, newest first. ONE index serves the filter and the
        // sort, because a btree can be read in order.
        { on: ["status", { prop: "publishDate", direction: "desc" }],
          reason: "admin list: filter by status, newest first" },
        // Partial: the index holds only published rows, and stays small as
        // drafts accumulate.
        { on: ["publishDate"],
          where: { prop: "status", op: "=", value: "published" },
          reason: "public feed is published-only" },
        // `author` is a belongsTo — it resolves to author_id.
        { on: ["author"], reason: "an author's posts, and the ON DELETE cascade" }
    ]
};

Rules an agent must not get wrong

• on takes property keys, never column names. A belongsTo resolves to its localKey, so author → author_id. Writing author_id yourself works for most properties and is refused for a relation — and getting this backwards is how you index nothing on the one case people reach for. A hasMany or many-to-many property is refused: the foreign key is on the other table, so declare the index there.
• reason is required, and it is prose, not SQL. Say what query it serves. It is what gets printed beside "0 scans in 34 days, 412 MB" later, and it is deliberately not part of the index's identity, so rewording it rebuilds nothing.
• Order is the index's identity. Postgres uses a leading subset only: ["ownerId", "createdAt"] serves a filter on ownerId, and on both, and never on createdAt alone. Do not reorder keys to "tidy" a declaration.
• Do not declare a desc twin. A btree is scanned backwards just as fast, so a lone DESC index is redundant with its ASC one. direction earns its place only when an ORDER BY mixes directions.
• Never suggest a plain index for text search or embeddings. Trigram search is the search block; ANN is a vector property's index. Both build their own index, and an index needing gin_trgm_ops or vector_cosine_ops is refused here at build time.
• Do not add unique: true to a single column whose property already has validation.unique — that is the same guarantee declared twice, and it is refused. Single-column uniqueness is validation.unique; unique here is for composites.
• Do not index the primary key. <table>_pkey already covers exactly those columns, and declaring it is refused.
• Changing a declaration is a DROP and a CREATE, no CONCURRENTLY, with a window in between where the index does not exist. Fine on a dev database; on a large live table, say so before suggesting the edit.

The shape

where is structured, never a SQL string: { prop, op, value } with op one of =, !=, <, <=, >, >=, in, is null, is not null, nested under { and: [...] }. There is no or — an OR predicate means the index should probably not be partial; declare two indexes instead.

gin is containment over an array or JSONB map. brin is a naturally-ordered column on an append-only table. Neither takes direction or nulls.

Why hand-written indexes were disappearing

Worth knowing when a user says an index they created is gone. rebase db push is declarative, so an index on a managed table absent from schema.sql was drift, and Atlas planned DROP INDEX — which is not a destructive pattern, so the auto-approved apply took it silently.

Ownership is now decided by the name: <table>_<columns>_ix_<7 hex> (_ux_ if unique), which no other namer produces. A declaration you delete drops as intended; an index Rebase did not create is excluded from the diff and never touched. Do not tell a user to re-create a hand-written index defensively, and do not rename one to look generated — the hash is over the index's semantics and the name is frozen in contracts/derived-names.txt.

Declared indexes are created by rebase db push and by boot-time schema ensure (CREATE INDEX CONCURRENTLY IF NOT EXISTS), so a deployment that never runs db push still gets them.

Data sources & multiple backends

A collection lives in a data source identified by collection.dataSource (default "(default)"). A data source has an engine (postgres, mongodb, firestore, custom → drives editor capabilities) and a transport:

• server — through the Rebase backend/client. Covers Postgres, MongoDB, and any server-mediated engine. This is the default; such collections need no registration.
• direct — straight from the client to an external backend via its SDK (e.g. Firestore). The Rebase backend is not in the data path.
• custom — a developer-supplied DataDriver.

Register the non-default (direct/custom) sources once; server engines ride the client and only need a backend bootstrapper.

// Frontend — register direct/custom sources (Postgres rides the client)
<Rebase
  client={rebaseClient}
  dataSources={[
    { key: "analytics", engine: "firestore", transport: "direct", driver: firestoreDriver }
  ]}
/>

// A collection opts in by key:
{ slug: "events", dataSource: "analytics", properties: { /* … */ } }

// Backend — multiple engines in one instance (Postgres + MongoDB)
// config/resources.ts — declare direct/custom sources so the backend skips
// server routes for them:
//   export const analytics = database("analytics", {
//       engine: "firestore", transport: "direct"
//   });
initializeRebaseBackend({
  bootstrappers: [pgBootstrapper /* isDefault */, mongoBootstrapper],
  collections: [
    { slug: "products" },                  // → Postgres (default)
    { slug: "orders", driver: "mongodb" }  // → MongoDB
  ],
});

Routing is automatic and resolved by collection path: list/entity views, references, board, import/export, and context.data all hit the right backend with no per-collection wiring. The data-source key matches the backend bootstrapper id/type (e.g. "mongodb"). RLS is applied per-engine where supported. The deprecated drivers={{ key: driver }} prop is a shorthand for a single direct database declaration.

Migration note: collection-level driver is deprecated in favor of dataSource. It still works (and provides the engine hint), so existing Firestore collections using driver: "firestore" keep functioning.

Common Property Options (BaseProperty)

All property types share these base options:

UI Options (AdminPropertyOptions)

All property types support a admin object for display configuration:

Form layout

The entity form derives a two-column layout from the property types on its own: the id and the audit timestamps go to a metadata rail, 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. A collection that says nothing about layout still gets a form rather than one long run of full-width inputs.

Reach for admin.form when that answer is wrong for the domain:

import { defineCollection } from "@rebasepro/cms-types";

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" },
        publishedAt: { name: "Published at", type: "date" },
        notes: { name: "Notes", type: "string" }
    },
    admin: {
        form: {
            // Fields beside the main column rather than in it.
            sidebar: ["status", "publishedAt"],
            sections: [
                { key: "content", properties: ["title", "body"] },
                {
                    key: "internal",
                    title: "Internal",
                    properties: ["notes"],
                    collapsed: true
                }
            ],
            // id / created / updated at the foot of the rail. Default `true`.
            showRecordMeta: true
        }
    }
});

A property no section names is never dropped — it lands in a trailing group, so adding a column to the database cannot make a field silently invisible. A validation error inside a collapsed section expands it. On layouts too narrow for a rail (side panel, split pane, phone) the rail renders as a leading section and spans are ignored.

String Properties

title: {
    name: "Title",
    type: "string",
    validation: { required: true, min: 3, max: 200 },
    multiline: false
}

String-Specific Options

String isId Strategies

String Validation

validation: {
    required: true,
    min: 3,            // Minimum string length
    max: 200,          // Maximum string length
    matches: /^[a-z]+$/,  // Regex pattern (string or RegExp)
    matchesMessage: "Only lowercase letters allowed",
    unique: true,
    uniqueInArray: true,
    requiredMessage: "Title is required",
    trim: true,        // Trim whitespace before validation
    lowercase: true,   // Transform to lowercase before validation
    uppercase: false,   // Transform to uppercase before validation
}

Storage Configuration (File Uploads)

When a string property has storage, it becomes a file upload field. The stored value is the file path (or URL) in your storage provider.

avatar: {
    name: "Avatar",
    type: "string",
    storage: {
        storagePath: "avatars/{entityId}",
        acceptedFiles: ["image/*"],
        maxSize: 5 * 1024 * 1024, // 5MB
        fileName: "{rand}_{file.name}.{file.ext}",
        metadata: { cacheControl: "max-age=31536000" },
        imageResize: {
            maxWidth: 400,
            maxHeight: 400,
            mode: "cover",
            format: "webp",
            quality: 80
        },
        previewUrl: (path) => `https://cdn.example.com/${path}`,
        processFile: async (file) => { /* transform before upload */ return file; },
        postProcess: async (pathOrUrl) => { /* transform saved value */ return pathOrUrl; }
    }
}

Per-Property Backend Binding

When using multiple storage backends, use storageSource to route a specific property's uploads to a named backend:

// Route this property's uploads to Firebase Storage
image: {
    type: "string",
    storage: {
        storageSource: "firebase",
        storagePath: "products/{entityId}",
        acceptedFiles: ["image/*"],
    }
}

ImageResize Options

Number Properties

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

Number-Specific Options

Number isId Strategies

Number Validation

validation: {
    required: true,
    min: 0,
    max: 1000,
    lessThan: 1001,
    moreThan: -1,
    positive: true,
    negative: false,
    integer: true,
    unique: true
}

Boolean Properties

published: {
    name: "Published",
    type: "boolean",
    defaultValue: false,
    validation: { required: true }
}

No additional options beyond BaseProperty.

Date Properties

createdAt: {
    name: "Created At",
    type: "date",
    mode: "date_time",
    autoValue: "on_create",
    clearable: false,
    admin: { readOnly: true }
}

updatedAt: {
    name: "Updated At",
    type: "date",
    mode: "date_time",
    autoValue: "on_update",
    admin: { readOnly: true }
}

Date-Specific Options

Date Validation

validation: {
    required: true,
    min: new Date("2020-01-01"),
    max: new Date("2030-12-31")
}

Map Properties (Nested Objects)

Maps store nested objects as JSONB in PostgreSQL. They can define their own inner properties schema.

address: {
    name: "Address",
    type: "map",
    properties: {
        street: { name: "Street", type: "string" },
        city: { name: "City", type: "string", validation: { required: true } },
        zip: { name: "ZIP Code", type: "string" },
        country: { name: "Country", type: "string", enum: [
            { id: "US", label: "United States" },
            { id: "UK", label: "United Kingdom" }
        ]}
    },
    propertiesOrder: ["street", "city", "zip", "country"],
    admin: { expanded: true, spreadChildren: true }
}

Map-Specific Options

Map UI Options

IMPORTANT FOR AGENTS: If validation.required is not set on the map property itself, an empty object {} is considered valid even if inner properties have required: true. Always set validation: { required: true } on the map if the entire object is mandatory.

Array Properties

Arrays can contain any element type (except nested arrays). They map to native Postgres arrays for primitives or JSONB for complex types.

tags: {
    name: "Tags",
    type: "array",
    of: { type: "string" },
    validation: { min: 1, max: 10 }
}

gallery: {
    name: "Gallery",
    type: "array",
    of: {
        type: "string",
        storage: {
            storagePath: "products/{entityId}/gallery",
            acceptedFiles: ["image/*"]
        }
    }
}

metadata: {
    name: "Metadata",
    type: "array",
    of: {
        type: "map",
        properties: {
            key: { name: "Key", type: "string", validation: { required: true } },
            value: { name: "Value", type: "string" }
        }
    },
    admin: { expanded: true }
}

Array-Specific Options

Array UI Options

Array Validation

validation: {
    required: true,
    min: 1,    // Minimum number of elements
    max: 20    // Maximum number of elements
}

oneOf (Discriminated Union Arrays)

Use oneOf for content blocks with different types (e.g. blog content):

content: {
    name: "Content Blocks",
    type: "array",
    oneOf: {
        typeField: "type",   // default: "type"
        valueField: "value", // default: "value"
        properties: {
            text: {
                name: "Text Block",
                type: "string",
                admin: { markdown: true }
            },
            image: {
                name: "Image",
                type: "string",
                storage: { storagePath: "blog/{entityId}/content" }
            },
            quote: {
                name: "Quote",
                type: "map",
                properties: {
                    text: { name: "Quote Text", type: "string" },
                    author: { name: "Author", type: "string" }
                }
            }
        }
    }
}
// Stored as: [{ type: "text", value: "# Hello" }, { type: "image", value: "path/to/img.jpg" }]

Property Validation

Every property supports a validation object with these common options:

Enum Values

Use the enum property on string or number types to define picklist options:

status: {
    name: "Status",
    type: "string",
    defaultValue: "draft",
    enum: [
        { id: "draft", label: "Draft", color: "gray" },
        { id: "published", label: "Published", color: "green" },
        { id: "archived", label: "Archived", color: "red", disabled: true }
    ]
}

Each EnumValueConfig entry supports:

EnumValues can also be a Record<string, string | EnumValueConfig> for simpler definitions:

enum: {
    draft: "Draft",
    published: { label: "Published", color: "green" }
}

PostgreSQL Enum Database Constraints

When rebase schema generate is run, any string property configured with an enum array generates a corresponding PostgreSQL ENUM type (e.g. CREATE TYPE "public"."collection_property" AS ENUM('val1', 'val2')).

If you write custom server functions, backend callback handlers, or perform manual database updates:

1. Validation Constraints: Pushing or inserting a value that is NOT defined in the collection's enum options array will trigger a PostgreSQL database-level check constraint error (e.g., invalid input value for enum).
2. Adding Enum Options: Adding a new enum value in code requires generating and applying a database migration (e.g., pnpm db:generate followed by pnpm db:migrate or raw enum modification SQL). In development, using a raw SQL command to alter the enum may be necessary because modifying PostgreSQL enums dynamically can be restrictive.

Relations (Inline Property API)

Relations are defined directly on the property using type: "relation". The framework automatically extracts these into the collection's internal relations[] at normalization time — you do not need a separate relations[] array.

Many-to-One (Owning)

import { PostgresCollectionConfig } from "@rebasepro/types";
import authorsCollection from "./authors";

const postsCollection: PostgresCollectionConfig = {
    name: "Posts",
    slug: "posts",
    table: "posts",
    properties: {
        author: {
            name: "Author",
            type: "relation",
            relation: { kind: "belongsTo", target: () => authorsCollection }
        }
    }
};

This automatically creates an author_id foreign key column on the posts table, served on the wire as authorId.

Many-to-Many

tags: {
    name: "Tags",
    type: "relation",
    relation: { kind: "manyToMany", target: () => tagsCollection }
}

This automatically creates a posts_tags junction table with post_id and tag_id columns.

One-to-Many

comments: {
    name: "Comments",
    type: "relation",
    relation: {
        kind: "hasMany",
        target: () => commentsCollection,
        foreignKeyOnTarget: "post_id"
    }
}

Relation Property Options

Relation UI Options

Cascade Rules (OnAction)

Unset, onDelete is "restrict" for a required belongsTo and "set null" for an optional one. required says the child cannot exist without a parent, not that deleting the parent should delete the child — ask for "cascade" when that is what you mean. A manyToMany junction row is the exception: it defaults to "cascade", because what it deletes is the link and not the target.

Multi-Hop Joins (joinPath)

Use joinPath for advanced relationships that traverse multiple tables. When set, it overrides localKey, foreignKeyOnTarget, and through.

Each JoinStep defines one JOIN operation:

interface JoinStep {
    table: string;          // Table to join TO
    on: {
        from: string | string[];  // Column(s) on the PREVIOUS table
        to: string | string[];    // Column(s) on THIS table
    };
}

Example: Users → Permissions through Roles (4-table join)

permissions: {
    name: "Permissions",
    type: "relation",
    relation: {
        kind: "via",
        target: () => permissionsCollection,
        cardinality: "many",
        joinPath: [
            {
                table: "user_roles",
                on: { from: "id", to: "user_id" }          // users.id = user_roles.user_id
            },
            {
                table: "roles",
                on: { from: "role_id", to: "id" }          // user_roles.role_id = roles.id
            },
            {
                table: "role_permissions",
                on: { from: "id", to: "role_id" }          // roles.id = role_permissions.role_id
            },
            {
                table: "permissions",
                on: { from: "permission_id", to: "id" }    // role_permissions.permission_id = permissions.id
            }
        ]
    }
}

Example: Composite key join

customer: {
    name: "Customer",
    type: "relation",
    relation: {
        kind: "via",
        target: () => customersCollection,
        cardinality: "one",
        joinPath: [
            {
                table: "customers",
                on: {
                    from: ["company_code", "region_id"],  // orders table columns
                    to: ["code", "region_id"]             // customers table columns
                }
            }
        ]
    }
}

A via relation is read-only: a join chain does not say which row to write.

See full documentation: Relations

Collection Callbacks (Lifecycle Hooks)

IMPORTANT FOR AGENTS: Collections support lifecycle callbacks that let you run custom logic when entities are created, updated, read, or deleted. Use these to sync data between collections, transform data, validate business rules, or trigger side effects. Do NOT use raw SQL triggers, cron jobs, or external scripts when a callback can solve the problem.

Generic Type Parameters

CollectionCallbacks<M, USER> accepts two generic type parameters:

import { PostgresCollectionConfig, CollectionCallbacks } from "@rebasepro/types";

// A `type`, not an `interface`: only a type alias gets the implicit index
// signature that satisfies `Record<string, unknown>`.
type Product = {
    name: string;
    price: number;
    slug: string;
    status: string;
};

const callbacks: CollectionCallbacks<Product> = {
    beforeSave: async ({ values, status }) => {
        // `values` is typed as Partial<Product>
        if (values.name) {
            values.slug = values.name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
        }
        return values;
    }
};

RebaseCallContext<USER>

All callbacks receive a context property of type RebaseCallContext<USER>. This is the subset of the full RebaseContext that is available in both frontend and backend (server-side) execution:

Reserved context.user Values

The context.user object is populated by the auth middleware. In server-side callbacks, it contains one of these reserved identities:

IMPORTANT FOR AGENTS: rebase.dataAsAdmin calls (used in cron jobs, afterSave side-effects, custom functions) run through the native driver scoped as the service identity, so callbacks see uid: "service", roles: ["admin"]. Use this to gate behavior — e.g., skip PII masking for admin/service reads:

afterRead: async ({ row, context }) => {
    // Server-side reads (cron jobs, admin) see real values
    if (context.user?.roles?.includes("admin")) return row;
    // End-user reads get masked values
    return { ...row, email: "***@***.***" };
}

WARNING FOR AGENTS: Do NOT confuse RebaseCallContext (available in callbacks, both client & server) with RebaseContext (full context available only on the frontend, includes authController, snackbarController, sidePanelController, etc.). Entity callbacks always receive RebaseCallContext.

Callback Example

const jobSubmissionsCollection: PostgresCollectionConfig<{
    title: string;
    slug: string;
    status: string;
    description: string;
    company_id: string;
    createdAt: string;
}> = {
    name: "Job Submissions",
    slug: "job_submissions",
    table: "job_submissions",
    callbacks: {
        // Runs BEFORE saving — transform or validate data
        beforeSave: async ({ values, status }) => {
            if (values.title) {
                values.slug = values.title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
            }
            if (status === "new") {
                values.createdAt = new Date().toISOString();
            }
            return values;
        },

        // Runs AFTER saving — trigger side effects, sync other collections
        afterSave: async ({ values, id, previousValues, context }) => {
            if (values.status === "approved" && previousValues?.status !== "approved") {
                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,
                });
            }
        },

        // Runs BEFORE deleting — block or validate
        beforeDelete: async ({ row }) => {
            if (row.status ===

*Truncated - read the full file at https://github.com/rebasepro/rebase/blob/c3456d4d262ac29ba6c7e5c785eb3eb1ea7f1ace/tooling/rebase-agent-skills/skills/rebase-collections/SKILL.md.*