palgres 0.3.1 → 0.3.3

package/types/palgres/src/dsl/columns.d.ts

@@ -7,9 +7,21 @@ export type OnUpdateAction = OnDeleteAction;
  * or forget the user (`set null`). Nothing else: a deletion is never blocked.
  */
 export type AuthUserOnDelete = Extract<OnDeleteAction, 'cascade' | 'set null'>;
+/**
+ * The column types `.array()` accepts as elements: `text().array()` is a
+ * `text[]` column. `jsonb` is left out on purpose: a JSON array is already a
+ * `jsonb` value, so keep it in a `jsonb()` column.
+ */
 export type ArrayElementType = 'uuid' | 'text' | 'integer' | 'bigint' | 'numeric' | 'boolean' | 'timestamp' | 'date' | 'enum';
 /** Column type identifiers. */
 export type ColumnType = 'uuid' | 'text' | 'integer' | 'bigint' | 'numeric' | 'boolean' | 'timestamp' | 'date' | 'jsonb' | 'enum' | 'sql' | `${ArrayElementType}[]`;
+/**
+ * Whether the application writes a column. `'readonly'` is a column whose
+ * value only the database sets, such as an `.identity()` that is ALWAYS or a
+ * `.generated()` column: it is on the row type and on no insert or update
+ * type. The default is the union of both, which reads as "writable", so a type
+ * that does not name this parameter still matches every column.
+ */
 export type ColumnWrite = 'write' | 'readonly';
 /** Base column definition shared by all column types. */
 export interface ColumnDef {
@@ -64,9 +76,26 @@ export interface ColumnDef {
      * declared. Without it, renaming a column loses its data.
      */
     renamedFrom?: string;
+    /**
+     * This release's PROMISE that it does not use this column: it neither reads
+     * nor writes it, and never names it in a filter, a sort or a SET. Set by
+     * `.ignored()`.
+     *
+     * Removing a column from a table that holds rows takes two deploys: mark it
+     * ignored and ship, then remove it. A deploy that drops such a column is
+     * refused unless the release already serving carries this mark (a column of
+     * an empty table is simply dropped). While the mark is on, the SQL the engine
+     * writes for you keeps the promise: no projection, `RETURNING` or `with`
+     * object names the column, and the generated row type leaves it out. So the
+     * release still serving does not break when the column is dropped.
+     *
+     * The word is `ignored` and not `deprecated` deliberately: RFC 9745 defines
+     * deprecation as changing NO behaviour, and this changes what a deploy will
+     * accept. Rails calls the same thing `ignored_columns`.
+     */
     ignored?: boolean;
     /**
-     * The per-row fill of a NOT NULL column (`.fillWith()`, D-1): one SQL scalar
+     * The per-row fill of a NOT NULL column (`.fillWith()`): one SQL scalar
      * expression over this row's columns. The deploy fills every row that does not
      * supply the column with it — the rows already in the table and every write of
      * a release that does not know the column yet — and only then makes it NOT
@@ -75,6 +104,10 @@ export interface ColumnDef {
     fill?: string;
     onDeleteAction?: OnDeleteAction;
     onUpdateAction?: OnUpdateAction;
+    /**
+     * Set only when a foreign key explicitly says `index: false`: it turns off
+     * the index created for this foreign key column by default.
+     */
     index?: boolean;
     enumName?: string;
     enumValues?: string[];
@@ -90,23 +123,72 @@ export interface ColumnDef {
      * its own data.
      */
     dbAssigned?: boolean;
+    /** numeric({ precision, scale }): the typmod, which is part of the column's TYPE. */
     precision?: number;
     scale?: number;
+    /** sqlType("…"): the Postgres type, verbatim. The deploy asks Postgres
+     * how it spells the type and refuses any other spelling. */
     sqlType?: string;
+    /** .identity(): a sequence numbers the column. `'always'` refuses any value
+     * the application sends; `'byDefault'` fills it only when none is sent. */
     identity?: 'always' | 'byDefault';
     /** .generated(expr): the column is `expr` over the row — computed when read (virtual) or on write (stored). */
     generated?: {
         expr: string;
         stored: boolean;
     };
+    /**
+     * The named codec this column declares (`.asNumber()` or `.asDecimal()`).
+     * Unlike `transform`, the NAME is kept in the runtime schema object, so the
+     * generated types can use the matching TypeScript type instead of falling
+     * back to the storage type. Not part of the DDL: the column's Postgres type
+     * is unchanged.
+     */
     codec?: CodecName;
+    /**
+     * How the stored value is converted on its way in and out of the
+     * application (`.transform()`).
+     *
+     * NOT part of the DDL: the column's Postgres type is unchanged and this pair
+     * is never written into a migration. It exists so the row type can hand back
+     * the type the application actually works with.
+     */
     transform?: ColumnTransform;
 }
+/**
+ * The read/write pair a column may declare with `.transform()`.
+ *
+ * `fromDb` takes whatever the driver produced for this column and returns the
+ * value the application sees; `toDb` is its inverse on the way out. Not
+ * exported on purpose: a column declares one inline, so nobody needs to name
+ * the shape.
+ */
 interface ColumnTransform<T = unknown> {
     fromDb: (value: unknown) => T;
     toDb: (value: T) => unknown;
 }
+/**
+ * The closed set of named column codecs: `'number'` (`.asNumber()`) and
+ * `'decimal'` (`.asDecimal()`).
+ *
+ * WHY A CLOSED SET rather than `.transform<T>()`: a transform's target type is
+ * a TYPE parameter, erased at runtime, so the generator that reads the bundled
+ * schema object cannot learn it. The generated types would say `string` while
+ * the application is handed a number.
+ *
+ * A codec is NAMED instead of typed: the name is stored on the column
+ * (`_def.codec`), travels with the runtime schema object to every reader, and
+ * BOTH the conversion and the generated TypeScript type come from it. One
+ * declaration, one truth, and no way for the two to disagree.
+ */
 export type CodecName = 'number' | 'decimal';
+/**
+ * What each named codec does: `fromDb` turns the value read from Postgres into
+ * the one the application sees, `toDb` turns it back for a write, and `tsType`
+ * is the TypeScript type the generated row types use. The `'number'` codec
+ * throws on a whole number outside the safe integer range, and on `NaN` and
+ * `Infinity`, instead of storing a different number.
+ */
 export declare const CODECS: Record<CodecName, {
     fromDb: (value: unknown) => unknown;
     toDb: (value: unknown) => unknown;
@@ -175,7 +257,35 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
      * This is for a value something ELSE writes — a trigger in a raw() unit.
      */
     dbAssigned(): ColumnBuilder<K, N, true, E, P, T, W>;
+    /**
+     * An array of this type: `text().array()` is `text[]`, surfaced as `string[]`;
+     * `enumType('Role', [...]).array()` is `"Role"[]`, with the enum's values as
+     * the element type (what Prisma's `roles Role[]` makes). The only default an
+     * array takes is the empty one: `text().array().default([])`.
+     *
+     * Call it before `.default()`, and not after `.asNumber()`, `.asDecimal()` or
+     * `.transform()`: those convert one value, not a list of them.
+     *
+     * Filter with `contains` (every given element is in the array) and
+     * `overlaps` (any of them is).
+     */
     array(): ColumnBuilder<`${K & ArrayElementType}[]`, N, D, K extends 'enum' ? E : never, P, T, W>;
+    /**
+     * The database numbers this column from a sequence: `GENERATED ALWAYS AS
+     * IDENTITY`. Only on integer(), bigint() and sqlType('smallint'); the column
+     * is NOT NULL and takes no default and no fill.
+     *
+     * By default ALWAYS: the column is on no insert or update type, and Postgres
+     * refuses a value the application sends. `{ always: false }` is
+     * `BY DEFAULT`: the sequence fills it only when an insert leaves it out.
+     *
+     * A column's identity does not change after it is created: adding or removing
+     * it on an existing column is refused, because the release still serving
+     * writes the column too — add a new column instead. A NEW identity column on
+     * a table that already holds rows is refused as well (Postgres would rewrite
+     * the table under a lock to number them): add a bigint column with a default
+     * and fill it.
+     */
     identity(): ColumnBuilder<K, false, true, E, P, T, 'readonly'>;
     identity(opts: {
         always: true;
@@ -195,8 +305,23 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
     generated(expr: string, opts?: {
         stored?: boolean;
     }): ColumnBuilder<K, N, true, E, P, T, 'readonly'>;
+    /**
+     * Fill this NOT NULL column for every row that does not supply it: the rows
+     * already in the table AND every write of the release that is still serving,
+     * which does not know the column yet. So one push can add a NOT NULL column,
+     * or make a column NOT NULL, on a table that holds rows, and nothing is
+     * blocked while it runs.
+     *
+     * `expr` is ONE SQL scalar expression over this row's columns. A table,
+     * function or type it names must be schema-qualified (`public.accounts`): it
+     * runs with a pinned search_path. It reads BYPASSING row-level security, and
+     * what it writes is visible to anyone who can read the row.
+     *
+     * Only on a NOT NULL column with no default that is not `.ignored()`;
+     * `defineTable` refuses any other column and names it. For a constant value,
+     * use `.default()`.
+     */
     fillWith(expr: string): ColumnBuilder<K, N, D, E, P, T, W>;
-    /** Add a foreign key reference. */
     /**
      * Declares that this column used to be called `previous`.
      *
@@ -210,20 +335,11 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
      */
     renamedFrom(previous: string): ColumnBuilder<K, N, D, E, P, T, W>;
     /**
-     * See {@link ColumnDef.ignored}.
+     * Marks this column as no longer used by this release: the first step of
+     * removing it from a table that holds rows. See {@link ColumnDef.ignored}.
      *
-     * COPIES the def rather than mutating it. The constructor takes an existing
-     * def BY REFERENCE, so every builder derived from another shares one object —
-     * `const a = slug.unique()` leaves `a._def === slug._def`. An in-place
-     * `ignored = true` therefore marks every column sharing that def, including
-     * one another table actively reads, and the gate would let THAT column be
-     * dropped. Measured before this copy existed.
-     *
-     * The aliasing is older than this method and other fields leak through it too.
-     * The reason this one cannot wait: every other leak produces a VISIBLE schema
-     * difference — the plan shows it, the DDL shows it. This one is invisible by
-     * design (no DDL, no diff, no plan line), so its only effect is to disarm a
-     * safety gate in silence.
+     * It returns a new column and leaves the one it was called on unmarked, so a
+     * column built from a shared base does not mark the others built from it.
      */
     ignored(): ColumnBuilder<K, N, D, E, P, T, W>;
     /**
@@ -231,13 +347,13 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
      *
      * The target is a THUNK, not a direct reference. In a cycle (`x → y`, `y → x`)
      * the second table does not exist yet when the first is built; a direct
-     * reference makes TypeScript chase its own tail (TS7022 — measured, and making
-     * the return type independent of the target does NOT help). The thunk is
+     * reference makes TypeScript report a circular type (TS7022), and making the
+     * return type independent of the target does not help. The thunk is
      * invoked in `defineSchema`, where every binding exists and every table
      * already knows its name.
      *
      * In a cycle, ONE side needs an explicit return type:
-     * `references((): AnyColumn => y.id)`. One side is enough — measured.
+     * `references((): AnyColumn => y.id)`. One side is enough.
      * For a self-reference use `selfReferences(column)`: no thunk, no annotation.
      *
      * `as` names the FORWARD relation (`author_id` → `author` by default);
@@ -252,6 +368,18 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
         onDelete?: OnDeleteAction;
         /** ON UPDATE — what Prisma writes for every relation (cascade). Default: no action. */
         onUpdate?: OnUpdateAction;
+        /**
+         * Whether an index is created for this foreign key column. On by default.
+         *
+         * Postgres does not index a foreign key by itself; only the target side
+         * has its unique constraint. Without an index, every JOIN over the
+         * foreign key and every `ON DELETE CASCADE` pays for it: deleting a
+         * parent scans the whole child table.
+         *
+         * Turn it off (`false`) only for a real need: when the foreign key column
+         * is also updated OFTEN, the index breaks HOT updates. HOT breaks when a
+         * column that CHANGES is indexed, not because the table has indexes.
+         */
         index?: boolean;
     }): ColumnBuilder<K, N, D, E, P, T, W>;
     /**
@@ -260,8 +388,8 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
      *
      * No thunk and no type annotation: the target table is the one being declared,
      * so there is nothing to defer and nothing for TypeScript to chase in a circle.
-     * Drizzle forces an explicit `(): AnyPgColumn =>` here because its reference
-     * always goes through a callback; measured, we do not need one.
+     * Unlike a `references()` callback, it needs no `(): AnyColumn =>`
+     * annotation.
      */
     selfReferences(column: string, opts?: {
         as?: string;
@@ -271,6 +399,32 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
     onDelete(action: OnDeleteAction): ColumnBuilder<K, N, D, E, P, T, W>;
     /** Add a single-column UNIQUE constraint. */
     unique(): ColumnBuilder<K, N, D, E, P, T, W>;
+    /**
+     * Surface this exact-precision column (`bigint()` or `numeric()`) as a JS
+     * `number`.
+     *
+     * `numeric`/`bigint` arrive as strings because a JS number cannot hold their
+     * full range. That is correct, and exactly why this exists: application code
+     * that does arithmetic on the column otherwise repeats the same
+     * `Number(row.x)` / `String(v)` pair in every caller, and each copy is a
+     * place the two directions can drift apart.
+     *
+     * A fraction is written as the number JavaScript holds (`9.99` → `'9.99'`)
+     * and Postgres rounds it to the column's scale; a value read back is a JS
+     * number, so a decimal with more significant digits than a double holds
+     * comes back rounded. Whole numbers are safe below 2^53: writing one past
+     * it throws instead of storing a different number, as do `NaN` and
+     * `Infinity`. For values a double cannot hold, use `.asDecimal()`. A column
+     * has one codec, and not together with `.transform()`.
+     */
+    asNumber(): ColumnBuilder<K, N, D, E, P, number, W>;
+    /**
+     * Surface this exact-precision column (`bigint()` or `numeric()`) as a
+     * `string`: the value Postgres sent, DECLARED rather than left as the
+     * default.
+     */
+    asDecimal(): ColumnBuilder<K, N, D, E, P, string, W>;
+    private withCodec;
     /**
      * Declare how this column's value is projected in and out of the process.
      *
@@ -289,12 +443,29 @@ export declare class ColumnBuilder<K extends ColumnType = ColumnType, N extends
      * A transform is a PROJECTION, never a constraint: it lives only in this
      * process, so it can neither validate nor migrate what is stored.
      */
-    asNumber(): ColumnBuilder<K, N, D, E, P, number, W>;
-    asDecimal(): ColumnBuilder<K, N, D, E, P, string, W>;
-    private withCodec;
     transform<Target>(fns: ColumnTransform<Target>): ColumnBuilder<K, N, D, E, P, Target, W>;
 }
+/**
+ * Extracts the TypeScript value type for a column, respecting nullability.
+ * - "uuid" | "text" | "timestamp" | "bigint" | "numeric" | "date" → string (or string | null when N = true)
+ * - "sql" → the value its sqlType() declares ({@link SqlTypeValue}: string, number or unknown)
+ * - "<type>[]" → an array of the element's value
+ *   Note: bigint/numeric surface as string — JS number loses precision past 2^53,
+ *   and the driver hands int8/numeric over as strings. App code uses
+ *   BigInt(row.amount) for bigint, or a decimal lib for numeric.
+ * - "integer" → number
+ * - "boolean" → boolean
+ * - "jsonb" → P (the dev-supplied payload shape from jsonb<T>(), else unknown)
+ * - "enum" → E (the union of literal values)
+ *
+ * A declared `.transform<T>()` OVERRIDES the table above: the column then
+ * surfaces as T (or T | null when nullable), because that is the value the
+ * application is handed. Nullability is still the column's, not the
+ * transform's — `fromDb` is not called for a NULL.
+ */
 export type ColValue<C> = C extends ColumnBuilder<ColumnType, infer N, boolean, unknown, unknown, infer T> ? [unknown] extends [T] ? ColStoredValue<C> : N extends true ? T | null : T : never;
+/** An array column's element, as the row type hands it over: the same value
+ * as the scalar column of that type, element by element. */
 type ArrayElementValue<K, E> = K extends 'integer[]' ? number : K extends 'boolean[]' ? boolean : K extends 'enum[]' ? E : string;
 /** The value as the DATABASE hands it over — the branch table above, before any
  * transform. This is what a column's `fromDb` receives. */
@@ -314,24 +485,60 @@ export declare function integer(): ColumnBuilder<'integer', false, false, never>
 /**
  * Create a BIGINT column (Postgres int8, max ~9.2×10^18).
  * Surfaces as `string` in row/insert types — JS number loses precision past 2^53
- * and pgx/PostgREST serialize int8 as a JSON string. Use BigInt(row.column) in app code.
+ * and the driver hands int8 over as a string. Use BigInt(row.column) in app code,
+ * or `.asNumber()` below 2^53.
  */
 export declare function bigint(): ColumnBuilder<'bigint', false, false, never>;
 /**
  * Create a NUMERIC column (Postgres `numeric`/`decimal`, arbitrary precision).
  * For exact fractional values (money with cents as a decimal, rates, weights)
  * where int4/int8 don't fit. Surfaces as `string` in row/insert types — JS
- * number can't hold arbitrary-precision decimals without rounding, and
- * pgx/PostgREST serialize numeric as a JSON string. Parse with a decimal lib
- * (or BigInt for scaled integers) in app code.
+ * number can't hold arbitrary-precision decimals without rounding, and the
+ * driver hands numeric over as a string. Parse with a decimal lib (or BigInt
+ * for scaled integers) in app code, or declare `.asNumber()` when a JS number
+ * is precise enough.
  */
 export declare function numeric(opts?: {
     precision: number;
     scale?: number;
 }): ColumnBuilder<'numeric', false, false, never>;
+/**
+ * Create a DATE column: a calendar day, surfaced as `"YYYY-MM-DD"`.
+ *
+ * A string and not a JS `Date`: a `Date` is an instant, and turning a day into
+ * one picks a time zone — `new Date("2026-09-28")` is the 27th in New York.
+ * `.defaultNow()` is today (`CURRENT_DATE`).
+ */
 export declare function date(): ColumnBuilder<'date', false, false, never>;
+/**
+ * A column of a Postgres type the DSL does not offer: `inet`, `interval`,
+ * `citext`, `tsrange`, `character varying(20)`, `double precision`… The
+ * escape hatch: the value is surfaced as the text Postgres prints for it (what
+ * psql shows), except `smallint`/`real`/`double precision`, which are numbers,
+ * and `json`, which is the JSON value. `timestamp without time zone` and
+ * `bytea` are refused: use `timestamp()` (a `timestamptz`), and keep bytes in
+ * Storage.
+ *
+ * A type the DSL has its own builder for (`text`, `int8`, `jsonb`, …) is
+ * refused too: declare it with that builder, so each type has one spelling.
+ *
+ * Spell the type the way Postgres does (`character varying(20)`, not
+ * `varchar(20)`): the deploy asks Postgres and refuses any other spelling,
+ * telling you the right one. Two spellings would read as a type change on
+ * every push.
+ */
 export declare function sqlType<const S extends string>(type: S): ColumnBuilder<'sql', false, false, never, SqlTypeValue<S>>;
+/**
+ * The Postgres types an sqlType() column hands over as a JS NUMBER, as the
+ * driver reads them. Every sqlType() that is not here
+ * or in {@link SQL_JSON_TYPES} is the text Postgres prints for the value. The
+ * names are the canonical spellings the deploy insists on.
+ */
 export declare const SQL_NUMBER_TYPES: ReadonlySet<string>;
+/**
+ * The Postgres types an sqlType() column hands over as a JSON value rather
+ * than as text. The names are the canonical spellings the deploy insists on.
+ */
 export declare const SQL_JSON_TYPES: ReadonlySet<string>;
 /** What an sqlType() column surfaces as, from its Postgres type. */
 export type SqlTypeValue<S extends string> = S extends 'smallint' | 'real' | 'double precision' ? number : S extends 'json' ? unknown : string;

package/types/palgres/src/dsl/foreign-key.d.ts

@@ -1,8 +1,33 @@
 import type { PolicyExprRef } from "./policy.js";
 import type { ColumnMap, TableHandle } from "./schema.js";
+/**
+ * The symbol key under which a reference keeps its target table object (or a
+ * callback that returns it). It is never serialized.
+ *
+ * The target's name is known when the reference is declared, but its schema is
+ * not: `defineSchema` assigns schemas, and it runs after the `defineTable`
+ * callbacks. So the table object itself is carried along, and `defineSchema`
+ * writes the schema-qualified name from it, by the same rule it uses for a
+ * column's `.references()`.
+ *
+ * It is a symbol key because `JSON.stringify` skips symbol keys, so the object
+ * never appears in the serialized schema.
+ */
 export declare const REF_TARGET: unique symbol;
+/** An `ON UPDATE` / `ON DELETE` action: the closed set Postgres accepts. */
 export type FkAction = "cascade" | "restrict" | "set null" | "set default" | "no action";
+/** A foreign key's `MATCH` type. `partial` is left out because Postgres does not implement it yet. */
 export type FkMatch = "simple" | "full";
+/**
+ * A table-level FOREIGN KEY, as `defineTable` stores it: what
+ * `foreignKey(name)` builds, or a plain object you can write under a table's
+ * `foreignKeys` yourself.
+ *
+ * `columns` and `refColumns` pair up by position and must have the same
+ * length. `refTable` is the target table's key: bare for a table in `public`,
+ * `schema.table` otherwise. `onUpdate` and `onDelete` default to
+ * `"no action"`, `match` to `"simple"`.
+ */
 export interface ForeignKeyDef {
     name: string;
     columns: string[];
@@ -14,13 +39,59 @@ export interface ForeignKeyDef {
     /** Only `false`: no index derived for a one-column key (the column's references() has the same option). */
     index?: false;
 }
+/**
+ * Builds one table-level FOREIGN KEY, which can span several columns. Start it
+ * with `foreignKey(name)` inside a table's `foreignKeys` callback.
+ *
+ * ```ts
+ * foreignKeys: (c) => [
+ *   foreignKey("settlement_entry_household")
+ *     .on(c.col("household_id"), c.col("entry_id"))
+ *     .references(entries, "household_id", "id")
+ *     .onDelete("cascade"),
+ * ]
+ * ```
+ *
+ * Why a column's `.references()` is not enough: it covers one column and one
+ * target. What multi-tenant integrity needs is
+ * `FOREIGN KEY (household_id, entry_id) REFERENCES entries (household_id, id)`:
+ * the child's parent must not only exist, it must belong to the SAME tenant. A
+ * per-column reference cannot express that.
+ *
+ * The two can be used together and neither drops the other: a key declared
+ * here is tracked by its own name, a column's by `<table>_<column>_fkey`. One
+ * table can have both.
+ */
 export declare class ForeignKeyBuilder {
     readonly _def: ForeignKeyDef;
     constructor(name: string);
+    /**
+     * The local columns, as `c.col(...)` references. Their order is kept: they
+     * pair up one-to-one with the target columns given to `.references()`. An
+     * expression cannot be part of a foreign key.
+     */
     on(...cols: PolicyExprRef[]): this;
+    /**
+     * The target table and its columns. Pass the table itself, or a callback
+     * that returns it (`() => entries`) for a table declared later in the file
+     * or one that points back at this table.
+     *
+     * Give at least one target column, and exactly as many as `.on()` has. The
+     * count is checked when the table is declared, so a mismatched key fails as
+     * soon as the schema file runs and never reaches a deploy.
+     */
     references<C extends ColumnMap, N extends string>(table: TableHandle<C, N> | (() => TableHandle<C, N>), ...cols: (Extract<keyof C, string>)[]): this;
+    /** The `ON UPDATE` action. Defaults to `"no action"`. */
     onUpdate(action: FkAction): this;
+    /** The `ON DELETE` action. Defaults to `"no action"`. */
     onDelete(action: FkAction): this;
+    /**
+     * Sets the `MATCH` type. With `"full"` (`MATCH FULL`) the constraint is
+     * checked unless ALL referencing columns are NULL. With the default
+     * `"simple"` (`MATCH SIMPLE`) a single NULL column is enough to skip the
+     * check. That can be relied on deliberately, but in an ordinary foreign key
+     * it is usually not what you want.
+     */
     match(m: FkMatch): this;
     /**
      * `.index(false)`: Palgres indexes a one-column foreign key's column unasked
@@ -29,5 +100,24 @@ export declare class ForeignKeyBuilder {
      */
     index(on: false): this;
 }
+/**
+ * Starts a table-level foreign key named `name`, for a table's `foreignKeys`
+ * callback. Constraints are matched by name across deploys.
+ *
+ * @param name The constraint name. It must not be empty.
+ * @returns A {@link ForeignKeyBuilder}: chain `.on()` and `.references()`, and optionally `.onDelete()`, `.onUpdate()`, `.match()`, `.index(false)`.
+ */
 export declare function foreignKey(name: string): ForeignKeyBuilder;
+/**
+ * Turns a `foreignKey(...)` builder, or a plain {@link ForeignKeyDef}, into a
+ * `ForeignKeyDef` and checks that it is consistent. It throws when the key has
+ * no local column (`.on()`), no target (`.references()`), or a different
+ * number of local and target columns.
+ *
+ * `defineTable` calls it for every entry of `foreignKeys`. A deploy refuses a
+ * column-count mismatch as well, but only once it runs against the live
+ * database; here the mistake fails as soon as the schema file runs, and the
+ * broken declaration never leaves your machine. Both checks are kept: one for
+ * the author, one for the deploy.
+ */
 export declare function toForeignKeyDef(b: ForeignKeyBuilder | ForeignKeyDef): ForeignKeyDef;