turbine-orm 0.27.0 → 0.28.0

package/dist/schema-sql.js

@@ -6,7 +6,28 @@
  */
 import pg from 'pg';
 import { postgresDialect } from './dialect.js';
+import { UnsupportedFeatureError } from './errors.js';
+import { pgConfActionToReferential, stripCheckWrapper } from './introspect.js';
 import { camelToSnake } from './schema.js';
+/** Map a {@link ReferentialAction} to its SQL keyword form. */
+export function referentialActionToSql(action) {
+    switch (action) {
+        case 'cascade':
+            return 'CASCADE';
+        case 'restrict':
+            return 'RESTRICT';
+        case 'set null':
+            return 'SET NULL';
+        case 'set default':
+            return 'SET DEFAULT';
+        case 'no action':
+            return 'NO ACTION';
+    }
+}
+/** Single-quote-escape an enum label for a `CREATE TYPE ... AS ENUM` literal. */
+function quoteEnumLabel(label) {
+    return `'${label.replace(/'/g, "''")}'`;
+}
 /**
  * Whether a resolved column type is an auto-increment pseudo-type (SERIAL /
  * BIGSERIAL). These carry an implicit sequence default and NOT NULL, and their
@@ -16,6 +37,38 @@ import { camelToSnake } from './schema.js';
 function isSerialType(type) {
     return type === 'SERIAL' || type === 'BIGSERIAL';
 }
+/** Whether any column in the schema is a pgvector column. */
+function schemaHasVectorColumn(schema) {
+    for (const table of Object.values(schema.tables)) {
+        for (const col of Object.values(table.columns)) {
+            if (col.vectorDimensions != null)
+                return true;
+        }
+    }
+    return false;
+}
+/** Build a `CREATE TYPE "<name>" AS ENUM ('a', 'b')` statement. */
+function generateCreateEnumType(enumName, labels, dialect) {
+    const values = labels.map(quoteEnumLabel).join(', ');
+    return `CREATE TYPE ${dialect.quoteIdentifier(enumName)} AS ENUM (${values});`;
+}
+/**
+ * Resolve the DDL type token for a column: an enum type name, a `vector(n)`
+ * literal, or the dialect's scalar type — with a trailing `[]` for arrays.
+ */
+function resolveDdlType(config, dialect) {
+    let base;
+    if (config.enumName) {
+        base = dialect.quoteIdentifier(config.enumName);
+    }
+    else if (config.vectorDimensions != null) {
+        base = `vector(${config.vectorDimensions})`;
+    }
+    else {
+        base = dialect.buildColumnType({ type: config.type, maxLength: config.maxLength });
+    }
+    return config.isArray ? `${base}[]` : base;
+}
 // ---------------------------------------------------------------------------
 // SQL Generation — SchemaDef → CREATE TABLE statements
 // ---------------------------------------------------------------------------
@@ -27,10 +80,25 @@ function isSerialType(type) {
  */
 export function schemaToSQL(schema, options) {
     const dialect = options?.dialect ?? postgresDialect;
+    const extensions = options?.extensions ?? 'auto';
     const statements = [];
     // Topologically sort tables by their foreign key references
     const sorted = topologicalSort(schema);
     const resolveRef = makeRefResolver(schema);
+    // pgvector extension line — only when a vector column exists. Postgres-only:
+    // a dialect that can't do pgvector must not silently emit broken DDL.
+    if (schemaHasVectorColumn(schema)) {
+        if (!dialect.supportsVector) {
+            throw new UnsupportedFeatureError('vector columns', dialect.name, 'pgvector is a PostgreSQL-only feature.');
+        }
+        statements.push(extensions === 'manual'
+            ? '-- Requires the pgvector extension: run `CREATE EXTENSION IF NOT EXISTS vector;` before applying.'
+            : 'CREATE EXTENSION IF NOT EXISTS vector;');
+    }
+    // CREATE TYPE for every schema-level enum, before the tables that use them.
+    for (const [enumName, labels] of Object.entries(schema.enums ?? {})) {
+        statements.push(generateCreateEnumType(enumName, labels, dialect));
+    }
     // Generate CREATE TABLE statements
     for (const tableName of sorted) {
         const table = schema.tables[tableName];
@@ -147,6 +215,12 @@ function generateCreateTable(table, resolveRef, dialect = postgresDialect) {
         const cols = compositePk.map((c) => dialect.quoteIdentifier(camelToSnake(c)));
         columnDefs.push(dialect.buildPrimaryKeyConstraint(cols));
     }
+    // Table-level CHECK constraints (named → CONSTRAINT "name" CHECK (...)).
+    for (const chk of table.checks ?? []) {
+        columnDefs.push(chk.name
+            ? `CONSTRAINT ${dialect.quoteIdentifier(chk.name)} CHECK (${chk.expression})`
+            : `CHECK (${chk.expression})`);
+    }
     return dialect.buildCreateTableStatement({
         table: dialect.quoteIdentifier(tableName),
         definitions: columnDefs,
@@ -185,16 +259,33 @@ function generateColumnDef(fieldName, config, resolveRef, dialect = postgresDial
             };
         }
     }
-    return dialect.buildColumnDefinition({
+    // Resolve the DDL type (enum name / vector(n) / scalar, plus [] for arrays).
+    // Passed as a fully-formed `type` token with no maxLength so the dialect
+    // doesn't re-apply VARCHAR(n) on top of it.
+    const ddlType = resolveDdlType(config, dialect);
+    let def = dialect.buildColumnDefinition({
         name: dialect.quoteIdentifier(snakeName),
-        type: config.type,
-        maxLength: config.maxLength,
+        type: ddlType,
+        maxLength: null,
         primaryKey: config.isPrimaryKey,
         unique: config.isUnique,
         notNull,
         defaultValue,
         references,
     });
+    // Referential actions follow the REFERENCES clause (which buildColumnDefinition
+    // emits last). Postgres omits ON DELETE/UPDATE for the default NO ACTION.
+    if (references) {
+        if (config.onDelete)
+            def += ` ON DELETE ${referentialActionToSql(config.onDelete)}`;
+        if (config.onUpdate)
+            def += ` ON UPDATE ${referentialActionToSql(config.onUpdate)}`;
+    }
+    // Column-level CHECK constraint (raw SQL expression, user-authored).
+    if (config.check) {
+        def += ` CHECK (${config.check})`;
+    }
+    return def;
 }
 /**
  * Normalize a default value from the user's schema definition to valid SQL.
@@ -249,6 +340,94 @@ function generateForeignKeyIndexes(table, dialect = postgresDialect) {
     }
     return indexes;
 }
+/**
+ * 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 function buildAddForeignKeyStatement(table, constraintName, column, targetTable, targetColumn, onDelete, onUpdate, dialect = postgresDialect) {
+    const q = (s) => dialect.quoteIdentifier(s);
+    let sql = `ALTER TABLE ${q(table)} ADD CONSTRAINT ${q(constraintName)} FOREIGN KEY (${q(column)}) REFERENCES ${q(targetTable)}(${q(targetColumn)})`;
+    if (onDelete !== 'no action')
+        sql += ` ON DELETE ${referentialActionToSql(onDelete)}`;
+    if (onUpdate !== 'no action')
+        sql += ` ON UPDATE ${referentialActionToSql(onUpdate)}`;
+    return `${sql};`;
+}
+/**
+ * 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 function diffReferentialAction(table, db, schemaOnDelete, schemaOnUpdate, dialect = postgresDialect) {
+    if (db.onDelete === schemaOnDelete && db.onUpdate === schemaOnUpdate)
+        return null;
+    const q = (s) => dialect.quoteIdentifier(s);
+    const drop = `ALTER TABLE ${q(table)} DROP CONSTRAINT ${q(db.constraintName)};`;
+    const add = buildAddForeignKeyStatement(table, db.constraintName, db.column, db.targetTable, db.targetColumn, schemaOnDelete, schemaOnUpdate, dialect);
+    const reverseAdd = buildAddForeignKeyStatement(table, db.constraintName, db.column, db.targetTable, db.targetColumn, db.onDelete, db.onUpdate, dialect);
+    return { statements: [drop, add], reverseStatements: [drop, reverseAdd] };
+}
+/**
+ * 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 function diffEnumValues(enumName, schemaLabels, dbLabels, dialect = postgresDialect) {
+    const statements = [];
+    const warnings = [];
+    const dbSet = new Set(dbLabels);
+    for (const label of schemaLabels) {
+        if (!dbSet.has(label)) {
+            statements.push(`ALTER TYPE ${dialect.quoteIdentifier(enumName)} ADD VALUE ${quoteEnumLabel(label)};`);
+        }
+    }
+    const schemaSet = new Set(schemaLabels);
+    const removed = dbLabels.filter((l) => !schemaSet.has(l));
+    if (removed.length > 0) {
+        warnings.push(`Enum "${enumName}": labels [${removed.join(', ')}] exist in the database but not the schema. ` +
+            `Postgres cannot remove enum values in place — recreate the type manually if intended.`);
+    }
+    return { statements, warnings };
+}
+/**
+ * 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 function diffCheckConstraints(table, schemaChecks, dbChecks, dialect = postgresDialect) {
+    const q = (s) => dialect.quoteIdentifier(s);
+    const statements = [];
+    const reverseStatements = [];
+    const dbByName = new Map(dbChecks.map((c) => [c.name, c]));
+    const schemaByName = new Map(schemaChecks.map((c) => [c.name, c]));
+    const norm = (e) => e.replace(/\s+/g, ' ').trim();
+    const addStmt = (c) => `ALTER TABLE ${q(table)} ADD CONSTRAINT ${q(c.name)} CHECK (${c.expression});`;
+    const dropStmt = (name) => `ALTER TABLE ${q(table)} DROP CONSTRAINT ${q(name)};`;
+    for (const sc of schemaChecks) {
+        const existing = dbByName.get(sc.name);
+        if (!existing) {
+            statements.push(addStmt(sc));
+            reverseStatements.push(dropStmt(sc.name));
+        }
+        else if (norm(existing.expression) !== norm(sc.expression)) {
+            // Expression changed → drop + add.
+            statements.push(dropStmt(sc.name), addStmt(sc));
+            reverseStatements.push(dropStmt(sc.name), addStmt(existing));
+        }
+    }
+    for (const dc of dbChecks) {
+        if (!schemaByName.has(dc.name)) {
+            statements.push(dropStmt(dc.name));
+            reverseStatements.push(addStmt(dc));
+        }
+    }
+    return { statements, reverseStatements };
+}
 /**
  * Compare a SchemaDef against a live Postgres database and return the diff.
  *
@@ -303,12 +482,78 @@ export async function schemaDiff(schema, connectionString) {
                 dbUniques[row.table_name] = {};
             dbUniques[row.table_name][row.column_name] = row.constraint_name;
         }
+        // Existing enums (typname → ordered labels) for CREATE TYPE / ADD VALUE diff.
+        const enumResult = await client.query(`SELECT t.typname, e.enumlabel
+       FROM pg_type t
+       JOIN pg_enum e ON t.oid = e.enumtypid
+       JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+       WHERE n.nspname = 'public'
+       ORDER BY t.typname, e.enumsortorder`);
+        const dbEnums = {};
+        for (const row of enumResult.rows) {
+            if (!dbEnums[row.typname])
+                dbEnums[row.typname] = [];
+            dbEnums[row.typname].push(row.enumlabel);
+        }
+        // Existing single-column FK referential actions, keyed by table → column.
+        const fkResult = await client.query(`SELECT rel.relname AS table_name, con.conname AS constraint_name,
+              att.attname AS column, tgt.relname AS target_table,
+              tatt.attname AS target_column, con.confdeltype, con.confupdtype
+       FROM pg_constraint con
+       JOIN pg_catalog.pg_namespace n ON n.oid = con.connamespace
+       JOIN pg_catalog.pg_class rel ON rel.oid = con.conrelid
+       JOIN pg_catalog.pg_class tgt ON tgt.oid = con.confrelid
+       JOIN pg_catalog.pg_attribute att ON att.attrelid = con.conrelid AND att.attnum = con.conkey[1]
+       JOIN pg_catalog.pg_attribute tatt ON tatt.attrelid = con.confrelid AND tatt.attnum = con.confkey[1]
+       WHERE con.contype = 'f' AND n.nspname = 'public'
+         AND array_length(con.conkey, 1) = 1`);
+        const dbForeignKeys = {};
+        for (const row of fkResult.rows) {
+            if (!dbForeignKeys[row.table_name])
+                dbForeignKeys[row.table_name] = {};
+            dbForeignKeys[row.table_name][row.column] = {
+                constraintName: row.constraint_name,
+                column: row.column,
+                targetTable: row.target_table,
+                targetColumn: row.target_column,
+                onDelete: pgConfActionToReferential(row.confdeltype),
+                onUpdate: pgConfActionToReferential(row.confupdtype),
+            };
+        }
+        // Existing CHECK constraints (contype='c'), keyed by table.
+        const checkResult = await client.query(`SELECT rel.relname AS table_name, con.conname, pg_get_constraintdef(con.oid) AS definition
+       FROM pg_constraint con
+       JOIN pg_catalog.pg_class rel ON rel.oid = con.conrelid
+       JOIN pg_catalog.pg_namespace n ON n.oid = con.connamespace
+       WHERE con.contype = 'c' AND n.nspname = 'public'`);
+        const dbChecks = {};
+        for (const row of checkResult.rows) {
+            if (!dbChecks[row.table_name])
+                dbChecks[row.table_name] = [];
+            dbChecks[row.table_name].push({ name: row.conname, expression: stripCheckWrapper(row.definition) });
+        }
         // Build a set of DDL-facing snake_case table names that the schema defines.
         const schemaDdlNames = new Set();
         for (const def of Object.values(schema.tables))
             schemaDdlNames.add(def.name);
-        const result = { create: [], alter: [], drop: [], statements: [], reverseStatements: [] };
+        const result = { create: [], alter: [], drop: [], statements: [], reverseStatements: [], warnings: [] };
         const resolveRef = makeRefResolver(schema);
+        // --- Enums: CREATE TYPE for new enums (before tables), ADD VALUE for grown
+        //     ones, and a warning for any destructive removal/reorder. New CREATE
+        //     TYPEs go first so tables that reference them create cleanly. ---
+        for (const [enumName, labels] of Object.entries(schema.enums ?? {})) {
+            const existing = dbEnums[enumName];
+            if (!existing) {
+                result.statements.push(generateCreateEnumType(enumName, labels, dialect));
+                result.reverseStatements.unshift(`DROP TYPE IF EXISTS ${dialect.quoteIdentifier(enumName)};`);
+            }
+            else {
+                const { statements, warnings } = diffEnumValues(enumName, labels, existing, dialect);
+                result.statements.push(...statements);
+                result.warnings.push(...warnings);
+                // ADD VALUE cannot be reversed (Postgres can't drop enum values).
+            }
+        }
         // Tables to create (in schema but not in DB)
         const sorted = topologicalSort(schema);
         for (const tableKey of sorted) {
@@ -359,7 +604,9 @@ export async function schemaDiff(schema, connectionString) {
                 // BIGSERIAL (int8) before 0.24.0 — `push` won't try to shrink them.
                 const expectedUdt = schemaTypeToUdt(config);
                 if (expectedUdt && !isSerialType(config.type) && dbCol.udtName !== expectedUdt) {
-                    const sqlType = config.type === 'VARCHAR' && config.maxLength ? `VARCHAR(${config.maxLength})` : config.type;
+                    // resolveDdlType handles enum names, vector(n), arrays, and VARCHAR(n) —
+                    // config.type alone would emit the internal ENUM/VECTOR sentinels here.
+                    const sqlType = resolveDdlType(config, dialect);
                     const oldSqlType = udtToSqlType(dbCol.udtName, dbCol.maxLength);
                     const sql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} TYPE ${sqlType} USING ${dialect.quoteIdentifier(snakeName)}::${sqlType};`;
                     const reverseSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} TYPE ${oldSqlType} USING ${dialect.quoteIdentifier(snakeName)}::${oldSqlType};`;
@@ -452,6 +699,54 @@ export async function schemaDiff(schema, connectionString) {
             if (alterDef.columns.length > 0) {
                 result.alter.push(alterDef);
             }
+            // --- Referential action changes on existing single-column FKs ---
+            // Postgres has no ALTER CONSTRAINT for actions → DROP + ADD CONSTRAINT.
+            const tableFks = dbForeignKeys[tableName] ?? {};
+            for (const [fieldName, config] of Object.entries(tableDef.columns)) {
+                if (!config.referencesTarget)
+                    continue;
+                const snakeName = camelToSnake(fieldName);
+                const dbFk = tableFks[snakeName];
+                if (!dbFk)
+                    continue; // FK not present in DB yet (or composite) — skip
+                const change = diffReferentialAction(tableName, dbFk, config.onDelete ?? 'no action', config.onUpdate ?? 'no action', dialect);
+                if (change) {
+                    result.statements.push(...change.statements);
+                    for (const rev of change.reverseStatements.slice().reverse())
+                        result.reverseStatements.unshift(rev);
+                }
+            }
+            // --- Named table-level CHECK constraints ---
+            // Presence-only diffing: ADD checks whose NAME is missing from the DB.
+            // We do NOT auto-drop DB checks absent from the schema (column-level /
+            // inline checks carry auto-generated names the code-first schema never
+            // sees), and we do NOT drop+add on expression mismatch: pg_get_constraintdef
+            // canonicalizes expressions (casts, ANY(ARRAY[...]) rewrites), so authored
+            // text almost never string-matches the stored form — comparing would emit a
+            // spurious full-table-revalidating drop+add on every diff. An apparent
+            // mismatch surfaces as a warning instead; rename the constraint to
+            // intentionally replace its expression. Unnamed schema checks are skipped
+            // (no stable identity to diff on).
+            const namedSchemaChecks = (tableDef.checks ?? [])
+                .filter((c) => typeof c.name === 'string' && c.name.length > 0)
+                .map((c) => ({ name: c.name, expression: c.expression }));
+            const tableDbChecks = dbChecks[tableName] ?? [];
+            const dbCheckByName = new Map(tableDbChecks.map((c) => [c.name, c]));
+            const normExpr = (e) => e.replace(/\s+/g, ' ').trim();
+            for (const sc of namedSchemaChecks) {
+                const existing = dbCheckByName.get(sc.name);
+                const addSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ADD CONSTRAINT ${dialect.quoteIdentifier(sc.name)} CHECK (${sc.expression});`;
+                const dropSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} DROP CONSTRAINT ${dialect.quoteIdentifier(sc.name)};`;
+                if (!existing) {
+                    result.statements.push(addSql);
+                    result.reverseStatements.unshift(dropSql);
+                }
+                else if (normExpr(existing.expression) !== normExpr(sc.expression)) {
+                    result.warnings.push(`check constraint "${sc.name}" on "${tableName}": stored expression differs from the schema text ` +
+                        `(Postgres canonicalizes CHECK expressions, so this is usually cosmetic). ` +
+                        `To intentionally replace it, rename the constraint or drop/re-add it in a manual migration.`);
+                }
+            }
         }
         return result;
     }
@@ -463,6 +758,11 @@ export async function schemaDiff(schema, connectionString) {
  * Map a schema column type to its expected PostgreSQL UDT name.
  */
 function schemaTypeToUdt(config) {
+    // Enum columns: udt is the enum type name. Vector columns: udt is `vector`.
+    if (config.enumName)
+        return config.enumName;
+    if (config.vectorDimensions != null)
+        return 'vector';
     const map = {
         SERIAL: 'int4',
         BIGSERIAL: 'int8',
@@ -481,7 +781,11 @@ function schemaTypeToUdt(config) {
         NUMERIC: 'numeric',
         BYTEA: 'bytea',
     };
-    return map[config.type] ?? null;
+    const base = map[config.type] ?? null;
+    // Postgres names an array type `_<element>` (e.g. `_text` for text[]).
+    if (base && config.isArray)
+        return `_${base}`;
+    return base;
 }
 /**
  * Reverse map: PostgreSQL UDT name → SQL type (for generating reverse ALTER TYPE).

package/dist/schema.d.ts

@@ -35,6 +35,28 @@ export interface TableMetadata {
     relations: Record<string, RelationDef>;
     /** Indexes on this table */
     indexes: IndexMetadata[];
+    /**
+     * Named `CHECK` constraints on this table (introspected from
+     * `pg_constraint` where `contype = 'c'`, excluding NOT NULL artifacts).
+     * Optional / defaults to `[]` for back-compat.
+     */
+    checks?: readonly CheckMetadata[];
+    /**
+     * True when this metadata entry describes a database **view** or
+     * **materialized view** rather than a base table (introspected with the
+     * `includeViews` option). Views are read-only: every write builder
+     * (`create`/`update`/`upsert`/`delete` + their `*Many` forms) throws a
+     * `ValidationError` (E003). A view without a primary key is additionally
+     * excluded from the `findUnique`-family generated accessor types.
+     * Optional / defaults to `false` for back-compat.
+     */
+    isView?: boolean;
+}
+export interface CheckMetadata {
+    /** Constraint name (system-generated or user-supplied). */
+    name: string;
+    /** The check expression source (`pg_get_constraintdef` inner text). */
+    expression: string;
 }
 export interface ColumnMetadata {
     /** snake_case column name */
@@ -61,6 +83,23 @@ export interface ColumnMetadata {
      * emits the `auto` modifier. Optional / defaults to `false` for back-compat.
      */
     isGenerated?: boolean;
+    /**
+     * True when this is a Postgres **`GENERATED ALWAYS AS (expr) STORED`** column
+     * (`information_schema.columns.is_generated = 'ALWAYS'`). Distinct from
+     * {@link isGenerated} — which flags a server-*assigned* identity/serial value
+     * that a client MAY still override — a STORED generated column's value is
+     * *computed from other columns* and can NEVER be supplied on insert/update
+     * (Postgres rejects it). Codegen therefore omits it from `*Create`/`*Update`
+     * input types, and the write builders reject any `data` containing it with a
+     * {@link ValidationError} (E003). Optional / defaults to `false`.
+     */
+    isGeneratedStored?: boolean;
+    /**
+     * The generation expression for a {@link isGeneratedStored} column
+     * (`information_schema.columns.generation_expression`), e.g. `price * qty`.
+     * Present only when `isGeneratedStored` is true and the catalog exposed it.
+     */
+    generationExpression?: string;
     /** Whether this is an array column */
     isArray: boolean;
     /** Dialect-specific array/bulk-insert type token when needed. */
@@ -70,8 +109,22 @@ export interface ColumnMetadata {
     /** Max character length (for varchar) */
     maxLength?: number;
 }
+/**
+ * PostgreSQL referential action for a foreign key's `ON DELETE` / `ON UPDATE`
+ * clause. `'no action'` is the implicit default (matches Postgres) and is
+ * omitted from emitted DDL.
+ */
+export type ReferentialAction = 'cascade' | 'restrict' | 'set null' | 'set default' | 'no action';
 export interface RelationDef {
     type: 'hasMany' | 'hasOne' | 'belongsTo' | 'manyToMany';
+    /**
+     * FK `ON DELETE` action (introspected from `pg_constraint.confdeltype`).
+     * Present on `belongsTo`/`hasMany` relations derived from a real FK; omitted
+     * when unknown (e.g. `defineSchema`-only metadata) or `'no action'`.
+     */
+    onDelete?: ReferentialAction;
+    /** FK `ON UPDATE` action (introspected from `pg_constraint.confupdtype`). */
+    onUpdate?: ReferentialAction;
     /** Relation name (camelCase, used as the field name) */
     name: string;
     /** Source table */

package/dist/seed.d.ts

@@ -0,0 +1,4 @@
+import { TurbineClient } from './client.js';
+export type SeedFunction = (db: TurbineClient) => Promise<void> | void;
+export type DefinedSeed = () => Promise<void>;
+export declare function defineSeed(fn: SeedFunction): DefinedSeed;

package/dist/seed.js

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { TurbineClient } from './client.js';
+import { ConnectionError } from './errors.js';
+const emptySchema = { tables: {}, enums: {} };
+function entryUrl() {
+    const entry = process.argv[1];
+    if (!entry)
+        return null;
+    try {
+        return pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return pathToFileURL(resolve(entry)).href;
+    }
+}
+function callerUrl() {
+    const stack = new Error().stack;
+    if (!stack)
+        return null;
+    for (const line of stack.split('\n').slice(2)) {
+        const fileUrl = line.match(/(file:\/\/\/[^):]+):\d+:\d+/)?.[1];
+        if (fileUrl && !fileUrl.endsWith('/seed.ts') && !fileUrl.endsWith('/seed.js'))
+            return fileUrl;
+        const filePath = line.match(/\(?((?:\/|[A-Za-z]:\\)[^):]+):\d+:\d+\)?/)?.[1];
+        if (filePath && !filePath.endsWith('/src/seed.ts') && !filePath.endsWith('\\src\\seed.ts')) {
+            return pathToFileURL(resolve(filePath)).href;
+        }
+    }
+    return null;
+}
+function isDirectSeedModule() {
+    const entry = entryUrl();
+    const caller = callerUrl();
+    return process.env.NODE_TEST_CONTEXT === undefined && !!entry && !!caller && entry === caller;
+}
+async function runSeed(fn) {
+    const connectionString = process.env.DATABASE_URL;
+    if (!connectionString) {
+        throw new ConnectionError('[turbine] DATABASE_URL is required to run this seed.');
+    }
+    const db = new TurbineClient({ connectionString }, emptySchema);
+    try {
+        await fn(db);
+    }
+    finally {
+        await db.disconnect();
+    }
+}
+export function defineSeed(fn) {
+    const run = () => runSeed(fn);
+    if (isDirectSeedModule()) {
+        queueMicrotask(() => {
+            run().catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(message);
+                process.exitCode = 1;
+            });
+        });
+    }
+    return run;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {
@@ -67,7 +67,6 @@
     "typecheck": "tsc --noEmit --project tsconfig.test.json",
     "generate": "tsx src/cli/index.ts generate",
     "status": "tsx src/cli/index.ts status",
-    "examples": "tsx examples/examples.ts",
     "dogfood": "tsx examples/dogfood.ts",
     "test": "tsx --test --test-concurrency=1 src/test/*.test.ts",
     "test:unit": "DATABASE_URL= tsx --test src/test/*.test.ts",
@@ -117,7 +116,7 @@
   "peerDependencies": {
     "@zvndev/powdb-client": "^0.7.1 || ^0.8.0",
     "@zvndev/powdb-embedded": "^0.7.1 || ^0.8.0",
-    "mssql": "^10.0.0 || ^11.0.0",
+    "mssql": "^10.0.0 || ^11.0.0 || ^12.0.0",
     "mysql2": "^3.0.0"
   },
   "peerDependenciesMeta": {