turbine-orm 0.27.0 → 0.28.0

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';

package/dist/query/types.d.ts

@@ -79,9 +79,41 @@ export type WhereClause<T> = {
     /** Relation filters — keyed by relation name, value is { some, every, none } */
     [relationName: string]: unknown;
 };
+/**
+ * Client-level automatic WHERE filters, keyed by table accessor (the name used
+ * in `db[name]` / `client.table(name)`). Each value is AND-merged into the
+ * compiled WHERE of every read and mutation on that table, and into every
+ * relation subquery that targets it — the mechanism behind soft-delete and
+ * multi-tenancy. A function value is evaluated at query-build time (per query),
+ * so a closure over per-request state (e.g. the current tenant id) enables
+ * request-scoped filters. `create`/`createMany` are never filtered.
+ */
+export type GlobalFilters = {
+    [tableAccessor: string]: WhereClause<any> | (() => WhereClause<any>);
+};
+/**
+ * Per-query opt-out of the configured {@link GlobalFilters}. `true` skips the
+ * global filter on the query's own table AND on every relation target it
+ * touches; an array skips only the named table accessors (own table and/or
+ * relation targets). Global filters never satisfy the empty-`where` guard for
+ * `update`/`delete` — that guard always checks the user-supplied `where`.
+ */
+export type SkipGlobalFilters = true | readonly string[];
+/**
+ * Reserved key in a `with` clause that requests correlated relation counts.
+ * `_count: true` counts every to-many relation of the table; a record form
+ * (`_count: { posts: true }`) counts only the named to-many relations. Each
+ * selected relation resolves to a number on the result row's `_count` object.
+ */
+export type WithCount = true | Record<string, true>;
 /**
  * Unparameterized with clause — accepts any relation name.
  * Used internally by the query builder at runtime.
+ *
+ * The reserved `_count` key (see {@link WithCount}) is also accepted at runtime;
+ * the builder reads it via a cast so the narrow `true | WithOptions` element
+ * type is preserved for the relation-subquery machinery. Typed callers get a
+ * fully-typed `_count` through {@link TypedWithClause}.
  */
 export interface WithClause {
     [relation: string]: true | WithOptions;
@@ -98,6 +130,11 @@ export interface WithClause {
  */
 export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
     [K in keyof R]?: true | WithOptions<RelationRelations<R[K]> & object>;
+} & {
+    /** Reserved: correlated relation counts. `true` counts all to-many relations. */
+    _count?: true | {
+        [K in keyof R]?: true;
+    };
 };
 /**
  * Options for an included relation.
@@ -111,7 +148,7 @@ export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ?
 export interface WithOptions<NestedR extends object = {}> {
     with?: TypedWithClause<NestedR>;
     where?: Record<string, unknown>;
-    orderBy?: Record<string, OrderDirection>;
+    orderBy?: Record<string, OrderDirection | OrderBySpec>;
     limit?: number;
     /** Only include these fields from the relation */
     select?: Record<string, boolean>;
@@ -194,11 +231,31 @@ type ApplyCardinality<Rel, Resolved> = Rel extends RelationDescriptor<infer _T,
  * @typeParam W - The `with` clause the user passed (e.g. `{ posts: true }` or
  *                `{ posts: { with: { comments: true } } }`).
  */
-export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : W extends object ? [keyof W & keyof R] extends [never] ? T : T & {
+export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : W extends object ? W extends {
+    _count: infer C;
+} ? // `_count` requested — add the typed count object alongside any relations.
+WithRelationAdditions<T, R, W> & {
+    _count: CountResult<C>;
+} : WithRelationAdditions<T, R, W> : T;
+/**
+ * The relation additions grafted onto `T` by a `with` clause (the `_count`
+ * reserved key is handled separately by {@link WithResult}). Kept as its own
+ * alias so the no-`_count` path stays byte-identical to the pre-`_count` type.
+ */
+type WithRelationAdditions<T, R extends object, W> = [keyof W & keyof R] extends [never] ? T : T & {
     [K in keyof W & keyof R]: W[K] extends true ? ApplyCardinality<R[K], RelationTarget<R[K]>> : W[K] extends {
         with?: infer NestedW;
     } ? NestedW extends object ? ApplyCardinality<R[K], WithResult<RelationTarget<R[K]>, RelationRelations<R[K]> & object, NestedW>> : ApplyCardinality<R[K], RelationTarget<R[K]>> : ApplyCardinality<R[K], RelationTarget<R[K]>>;
-} : T;
+};
+/**
+ * Compute the shape of the `_count` object on a result row. `_count: true`
+ * counts every to-many relation (keys unknown at the type level → an open
+ * `Record<string, number>`); the record form (`_count: { posts: true }`) yields
+ * `{ [K in selected]: number }`.
+ */
+type CountResult<C> = C extends true ? Record<string, number> : C extends object ? {
+    [K in keyof C]: number;
+} : Record<string, number>;
 /** Extract keys from a boolean record where the value is `true`. */
 type TrueKeys<S extends Record<string, boolean>> = {
     [K in keyof S]: S[K] extends true ? K : never;
@@ -230,6 +287,8 @@ export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithCla
     timeout?: number;
     /** Override the client's relation-loading strategy for this query. See {@link RelationLoadStrategy}. */
     relationLoadStrategy?: RelationLoadStrategy;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     where?: WhereClause<T>;
@@ -249,6 +308,8 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     timeout?: number;
     /** Override the client's relation-loading strategy for this query. See {@link RelationLoadStrategy}. */
     relationLoadStrategy?: RelationLoadStrategy;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> extends FindManyArgs<T, R, W, S, O> {
     /**
@@ -349,6 +410,8 @@ export interface UpdateArgs<T, R extends object = {}> {
         field: keyof T & string;
         expected: number;
     };
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 export interface UpdateManyArgs<T> {
     where: WhereClause<T>;
@@ -357,6 +420,8 @@ export interface UpdateManyArgs<T> {
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
     allowFullTableScan?: boolean;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 export interface DeleteArgs<T> {
     where: WhereClause<T>;
@@ -364,6 +429,8 @@ export interface DeleteArgs<T> {
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
     allowFullTableScan?: boolean;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 export interface DeleteManyArgs<T> {
     where: WhereClause<T>;
@@ -371,6 +438,8 @@ export interface DeleteManyArgs<T> {
     timeout?: number;
     /** See {@link UpdateArgs.allowFullTableScan}. */
     allowFullTableScan?: boolean;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 export interface UpsertArgs<T> {
     where: WhereClause<T>;
@@ -378,6 +447,8 @@ export interface UpsertArgs<T> {
     update: Partial<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 /** `connectOrCreate` op: connect to the row matching `where`, or create it. */
 export interface ConnectOrCreateOp<T, TR extends object = {}> {
@@ -434,6 +505,8 @@ export interface CountArgs<T> {
     where?: WhereClause<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 /**
  * Numeric comparison operators usable inside a `having` filter. A bare number
@@ -503,10 +576,12 @@ export interface GroupByArgs<T> {
     _max?: Partial<Record<keyof T & string, boolean>>;
     /** Filter whole groups by their aggregate values (SQL HAVING). */
     having?: HavingClause<T>;
-    /** Order groups */
-    orderBy?: Record<string, OrderDirection>;
+    /** Order groups (supports {@link OrderBySpec} for NULLS placement). */
+    orderBy?: Record<string, OrderDirection | OrderBySpec>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 /** Arguments for the standalone aggregate method */
 export interface AggregateArgs<T> {
@@ -523,6 +598,8 @@ export interface AggregateArgs<T> {
     _max?: Partial<Record<keyof T & string, boolean>>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
+    skipGlobalFilters?: SkipGlobalFilters;
 }
 /** Result type for aggregate queries */
 export interface AggregateResult<T> {
@@ -634,8 +711,36 @@ export interface VectorOrderBy {
     distance: VectorOrderByDistance;
 }
 /**
- * An orderBy clause maps each column to either a plain direction (`'asc'` /
- * `'desc'`) or, for pgvector columns, a KNN distance ordering object.
+ * Explicit ordering spec for a column: a direction plus an optional NULLS
+ * placement. `{ sort: 'desc', nulls: 'last' }` compiles to
+ * `ORDER BY "col" DESC NULLS LAST`. The plain `'asc' | 'desc'` shorthand is
+ * still accepted and unchanged. `nulls` is only emitted on engines that
+ * support the `NULLS FIRST/LAST` grammar (PostgreSQL, SQLite); requesting it
+ * elsewhere throws {@link UnsupportedFeatureError} (E017).
+ */
+export interface OrderBySpec {
+    sort: OrderDirection;
+    nulls?: 'first' | 'last';
+}
+/**
+ * Ordering by a relation, keyed by the relation name in an {@link OrderByClause}:
+ *
+ *  - to-many (hasMany / manyToMany): `{ posts: { _count: 'desc' } }` — orders by
+ *    a correlated `COUNT(*)` of the related rows.
+ *  - to-one (belongsTo / hasOne): `{ author: { name: 'asc' } }` — orders by a
+ *    correlated scalar subquery on the target column (an {@link OrderBySpec} with
+ *    `nulls` is accepted too).
+ */
+export type RelationOrderBy = {
+    _count: OrderDirection;
+} | Record<string, OrderDirection | OrderBySpec>;
+/**
+ * An orderBy clause maps each key to one of:
+ *  - a plain direction (`'asc'` / `'desc'`),
+ *  - an {@link OrderBySpec} (`{ sort, nulls }`) for NULLS placement,
+ *  - for pgvector columns, a KNN distance ordering ({@link VectorOrderBy}),
+ *  - for a relation name, a {@link RelationOrderBy} (`_count` for to-many, a
+ *    target column for to-one).
  */
-export type OrderByClause = Record<string, OrderDirection | VectorOrderBy>;
+export type OrderByClause = Record<string, OrderDirection | OrderBySpec | VectorOrderBy | RelationOrderBy>;
 export {};

package/dist/schema-builder.d.ts

@@ -22,9 +22,19 @@
  * });
  * ```
  */
-import type { SchemaMetadata } from './schema.js';
+import type { ReferentialAction, SchemaMetadata } from './schema.js';
+export type { ReferentialAction } from './schema.js';
 /** Shorthand type names that map to Postgres column types */
-export type ColumnTypeName = 'serial' | 'bigserial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'varchar' | 'boolean' | 'timestamp' | 'timestamptz' | 'date' | 'json' | 'jsonb' | 'uuid' | 'real' | 'double' | 'numeric' | 'bytea';
+export type ColumnTypeName = 'serial' | 'bigserial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'varchar' | 'boolean' | 'timestamp' | 'timestamptz' | 'date' | 'json' | 'jsonb' | 'uuid' | 'real' | 'double' | 'numeric' | 'bytea' | 'enum' | 'vector';
+/** Foreign key reference with optional referential actions. */
+export interface ReferenceDef {
+    /** REFERENCES target in "table.column" form. */
+    target: string;
+    /** `ON DELETE` action. Omit for the Postgres default (`NO ACTION`). */
+    onDelete?: ReferentialAction;
+    /** `ON UPDATE` action. Omit for the Postgres default (`NO ACTION`). */
+    onUpdate?: ReferentialAction;
+}
 /** Column definition as a plain object. This is what users write. */
 export interface ColumnDef {
     /** Column type (required) */
@@ -39,13 +49,24 @@ export interface ColumnDef {
     unique?: boolean;
     /** DEFAULT expression (raw SQL, e.g. 'now()' or "'active'") */
     default?: string;
-    /** REFERENCES target in "table.column" form */
-    references?: string;
+    /**
+     * REFERENCES target. Either the "table.column" string form or an object with
+     * referential actions ({@link ReferenceDef}).
+     */
+    references?: string | ReferenceDef;
     /** Max length for varchar columns */
     maxLength?: number;
+    /** Enum type name — required when `type: 'enum'`. */
+    enumName?: string;
+    /** pgvector dimension count — required when `type: 'vector'`. */
+    dimensions?: number;
+    /** When true, the column is an array of `type` (e.g. `text[]`). */
+    array?: boolean;
+    /** Column-level `CHECK` expression (raw SQL, e.g. `price >= 0`). */
+    check?: string;
 }
 /** Postgres-level column type (uppercase, as used in DDL) */
-export type ColumnType = 'SERIAL' | 'BIGSERIAL' | 'BIGINT' | 'INTEGER' | 'SMALLINT' | 'TEXT' | 'BOOLEAN' | 'TIMESTAMPTZ' | 'JSONB' | 'UUID' | 'REAL' | 'DOUBLE PRECISION' | 'NUMERIC' | 'BYTEA' | 'DATE' | 'VARCHAR';
+export type ColumnType = 'SERIAL' | 'BIGSERIAL' | 'BIGINT' | 'INTEGER' | 'SMALLINT' | 'TEXT' | 'BOOLEAN' | 'TIMESTAMPTZ' | 'JSONB' | 'UUID' | 'REAL' | 'DOUBLE PRECISION' | 'NUMERIC' | 'BYTEA' | 'DATE' | 'VARCHAR' | 'ENUM' | 'VECTOR';
 export interface ColumnConfig {
     type: ColumnType;
     isPrimaryKey: boolean;
@@ -55,6 +76,18 @@ export interface ColumnConfig {
     defaultValue: string | null;
     referencesTarget: string | null;
     maxLength: number | null;
+    /** FK `ON DELETE` action, or null for the Postgres default. */
+    onDelete: ReferentialAction | null;
+    /** FK `ON UPDATE` action, or null for the Postgres default. */
+    onUpdate: ReferentialAction | null;
+    /** Enum type name when `type === 'ENUM'`, else null. */
+    enumName: string | null;
+    /** pgvector dimensions when `type === 'VECTOR'`, else null. */
+    vectorDimensions: number | null;
+    /** Whether the column is an array of its base type. */
+    isArray: boolean;
+    /** Column-level `CHECK` expression, or null. */
+    check: string | null;
 }
 /**
  * Explicit many-to-many relation declaration for the code-first schema.
@@ -86,6 +119,13 @@ export interface ManyToManyDef {
      */
     references?: string | readonly string[];
 }
+/** A table-level named (or unnamed) `CHECK` constraint. */
+export interface CheckDef {
+    /** Optional constraint name → `CONSTRAINT "name" CHECK (...)`. */
+    name?: string;
+    /** Raw SQL boolean expression, e.g. `price > cost`. */
+    expression: string;
+}
 export interface TableDef {
     /**
      * DDL-facing table name (snake_case). This is the name used when generating
@@ -117,6 +157,8 @@ export interface TableDef {
      * {@link SchemaMetadata} with `manyToMany` {@link RelationDef}s.
      */
     manyToMany?: readonly ManyToManyDef[];
+    /** Table-level `CHECK` constraints. */
+    checks?: readonly CheckDef[];
 }
 /**
  * User-facing input shape for a single table when using the object format.
@@ -127,8 +169,10 @@ export interface TableInput {
     primaryKey?: readonly string[];
     /** Optional explicit many-to-many relations on this table */
     manyToMany?: readonly ManyToManyDef[];
+    /** Optional table-level CHECK constraints */
+    checks?: readonly CheckDef[];
     /** Column definitions keyed by camelCase field name */
-    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | undefined;
+    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | readonly CheckDef[] | undefined;
 }
 export interface SchemaDef {
     /**
@@ -137,6 +181,22 @@ export interface SchemaDef {
      * name is available as `tables[key].name`.
      */
     tables: Record<string, TableDef>;
+    /**
+     * Schema-level enum declarations (`CREATE TYPE "<name>" AS ENUM (...)`),
+     * keyed by DDL enum type name → ordered labels. Consumed by `schema-sql.ts`
+     * to emit `CREATE TYPE` before the tables that reference them and by
+     * `generate.ts` for string-literal union codegen. Omitted when no enums are
+     * declared (back-compat with `{ tables }`-only consumers).
+     */
+    enums?: Record<string, readonly string[]>;
+}
+/** Options accepted by {@link defineSchema}. */
+export interface DefineSchemaOptions {
+    /**
+     * Schema-level enum declarations, keyed by DDL enum type name → ordered
+     * labels. Columns opt in via `{ type: 'enum', enumName: '<name>' }`.
+     */
+    enums?: Record<string, readonly string[]>;
 }
 /** Input format: table name -> column defs (object format) or TableDef (legacy builder) */
 type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef | TableInput>;
@@ -159,7 +219,7 @@ type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef | TableIn
  * });
  * ```
  */
-export declare function defineSchema(input: SchemaInput): SchemaDef;
+export declare function defineSchema(input: SchemaInput, options?: DefineSchemaOptions): SchemaDef;
 export declare class ColumnBuilder {
     private _config;
     constructor();
@@ -186,7 +246,12 @@ export declare class ColumnBuilder {
     nullable(): this;
     unique(): this;
     default(val: string): this;
-    references(target: string): this;
+    references(target: string, opts?: {
+        onDelete?: ReferentialAction;
+        onUpdate?: ReferentialAction;
+    }): this;
+    check(expression: string): this;
+    array(): this;
     build(): ColumnConfig;
 }
 /** @deprecated Use defineSchema() with plain objects instead */

package/dist/schema-builder.js

@@ -51,12 +51,34 @@ const TYPE_MAP = {
     double: 'DOUBLE PRECISION',
     numeric: 'NUMERIC',
     bytea: 'BYTEA',
+    // Sentinels — the real DDL type is derived from `enumName` / `dimensions`
+    // in schema-sql.ts, never from these placeholders.
+    enum: 'ENUM',
+    vector: 'VECTOR',
 };
 /** Convert a user-facing ColumnDef to the internal ColumnConfig */
 function resolveColumn(def) {
     if (!(def.type in TYPE_MAP)) {
         throw new Error(`Invalid column type "${def.type}". Valid types: ${Object.keys(TYPE_MAP).join(', ')}`);
     }
+    if (def.type === 'enum' && !def.enumName) {
+        throw new Error(`Column of type "enum" requires an "enumName" (the CREATE TYPE name).`);
+    }
+    if (def.type === 'vector' && (def.dimensions == null || def.dimensions <= 0)) {
+        throw new Error(`Column of type "vector" requires a positive "dimensions" count.`);
+    }
+    // `references` is either the "table.column" string or a { target, onDelete, onUpdate } object.
+    let referencesTarget = null;
+    let onDelete = null;
+    let onUpdate = null;
+    if (typeof def.references === 'string') {
+        referencesTarget = def.references;
+    }
+    else if (def.references) {
+        referencesTarget = def.references.target;
+        onDelete = def.references.onDelete ?? null;
+        onUpdate = def.references.onUpdate ?? null;
+    }
     return {
         type: TYPE_MAP[def.type],
         isPrimaryKey: def.primaryKey ?? false,
@@ -64,8 +86,14 @@ function resolveColumn(def) {
         isNullable: def.nullable ?? false,
         isUnique: def.unique ?? false,
         defaultValue: def.default ?? null,
-        referencesTarget: def.references ?? null,
+        referencesTarget,
         maxLength: def.maxLength ?? null,
+        onDelete,
+        onUpdate,
+        enumName: def.enumName ?? null,
+        vectorDimensions: def.dimensions ?? null,
+        isArray: def.array ?? false,
+        check: def.check ?? null,
     };
 }
 /** Check if a value is a TableDef (from legacy table() builder) */
@@ -91,7 +119,7 @@ function isTableDef(v) {
  * });
  * ```
  */
-export function defineSchema(input) {
+export function defineSchema(input, options) {
     const tables = {};
     for (const [accessor, value] of Object.entries(input)) {
         // The user-facing key is the camelCase JS accessor; the DDL-facing
@@ -110,6 +138,7 @@ export function defineSchema(input) {
             const columns = {};
             let pk;
             let m2m;
+            let checks;
             for (const [fieldName, def] of Object.entries(raw)) {
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
@@ -120,6 +149,15 @@ export function defineSchema(input) {
                     }
                     continue;
                 }
+                if (fieldName === 'checks') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "checks" must be an array of { name?, expression } objects`);
+                        }
+                        checks = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'primaryKey') {
                     // Top-level composite primary key declaration
                     if (def !== undefined) {
@@ -160,10 +198,11 @@ export function defineSchema(input) {
                 columns,
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
                 ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
+                ...(checks && checks.length > 0 ? { checks } : {}),
             };
         }
     }
-    return { tables };
+    return { tables, ...(options?.enums ? { enums: options.enums } : {}) };
 }
 /**
  * Local copy of camelToSnake to avoid a circular import dependency at the
@@ -187,6 +226,12 @@ export class ColumnBuilder {
             defaultValue: null,
             referencesTarget: null,
             maxLength: null,
+            onDelete: null,
+            onUpdate: null,
+            enumName: null,
+            vectorDimensions: null,
+            isArray: false,
+            check: null,
         };
     }
     serial() {
@@ -283,8 +328,18 @@ export class ColumnBuilder {
         this._config.defaultValue = val;
         return this;
     }
-    references(target) {
+    references(target, opts) {
         this._config.referencesTarget = target;
+        this._config.onDelete = opts?.onDelete ?? null;
+        this._config.onUpdate = opts?.onUpdate ?? null;
+        return this;
+    }
+    check(expression) {
+        this._config.check = expression;
+        return this;
+    }
+    array() {
+        this._config.isArray = true;
         return this;
     }
     build() {

package/dist/schema-sql.d.ts

@@ -5,11 +5,21 @@
  * Also provides diff and push commands for syncing schema to a live database.
  */
 import { type Dialect } from './dialect.js';
+import { type ReferentialAction } from './schema.js';
 import type { SchemaDef, TableDef } from './schema-builder.js';
 export interface SchemaSqlOptions {
     /** SQL dialect used for DDL generation. Defaults to PostgreSQL. */
     dialect?: Dialect;
+    /**
+     * How to handle the pgvector extension when the schema contains a `vector`
+     * column. `'auto'` (default) prepends `CREATE EXTENSION IF NOT EXISTS vector;`
+     * — appropriate for `push`. `'manual'` emits a leading comment only, so the
+     * generated `.sql` migration doesn't silently require superuser privileges.
+     */
+    extensions?: 'auto' | 'manual';
 }
+/** Map a {@link ReferentialAction} to its SQL keyword form. */
+export declare function referentialActionToSql(action: ReferentialAction): string;
 /**
  * Convert a SchemaDef into an ordered array of SQL DDL statements.
  *
@@ -44,7 +54,64 @@ export interface DiffResult {
     statements: string[];
     /** SQL statements to reverse the diff (DOWN direction, for migrations) */
     reverseStatements: string[];
+    /**
+     * Human-readable warnings for changes the diff detected but refuses to apply
+     * automatically because they are destructive or otherwise unsafe (enum value
+     * removal/reorder, etc.). Never executed — surfaced for the operator.
+     */
+    warnings?: string[];
 }
+/** A FK's current referential actions as read from the DB. */
+export interface DbForeignKey {
+    constraintName: string;
+    column: string;
+    targetTable: string;
+    targetColumn: string;
+    onDelete: ReferentialAction;
+    onUpdate: ReferentialAction;
+}
+/**
+ * Build the `ADD CONSTRAINT ... FOREIGN KEY` statement for a FK with the given
+ * referential actions. Default (`no action`) clauses are omitted, matching how
+ * Postgres normalizes them, so re-diffing is stable.
+ */
+export declare function buildAddForeignKeyStatement(table: string, constraintName: string, column: string, targetTable: string, targetColumn: string, onDelete: ReferentialAction, onUpdate: ReferentialAction, dialect?: Dialect): string;
+/**
+ * Decide whether a FK's referential actions changed. When they differ, returns
+ * the DROP + ADD CONSTRAINT statements (and their reverse) — Postgres has no
+ * `ALTER CONSTRAINT` for referential actions, so drop-and-recreate is the only
+ * path. Returns null when the actions already match.
+ */
+export declare function diffReferentialAction(table: string, db: DbForeignKey, schemaOnDelete: ReferentialAction, schemaOnUpdate: ReferentialAction, dialect?: Dialect): {
+    statements: string[];
+    reverseStatements: string[];
+} | null;
+/**
+ * Compute append-only enum value changes. Returns `ALTER TYPE ... ADD VALUE`
+ * statements for labels present in the schema but not the DB (in order), plus a
+ * destructive warning for any DB label the schema dropped or any reorder —
+ * Postgres cannot remove or reorder enum values without recreating the type.
+ */
+export declare function diffEnumValues(enumName: string, schemaLabels: readonly string[], dbLabels: readonly string[], dialect?: Dialect): {
+    statements: string[];
+    warnings: string[];
+};
+/** A check constraint as declared or read from the DB. */
+export interface CheckSpec {
+    name: string;
+    expression: string;
+}
+/**
+ * Diff a table's CHECK constraints (matched by name). Adds constraints missing
+ * from the DB, drops DB constraints absent from the schema, and drop+adds when a
+ * same-named constraint's expression changed. Expression comparison is a naive
+ * whitespace-insensitive match — semantically-equal-but-different-spelled
+ * expressions may re-emit (documented; harmless drop+add).
+ */
+export declare function diffCheckConstraints(table: string, schemaChecks: readonly CheckSpec[], dbChecks: readonly CheckSpec[], dialect?: Dialect): {
+    statements: string[];
+    reverseStatements: string[];
+};
 /**
  * Compare a SchemaDef against a live Postgres database and return the diff.
  *