@minnowdb/core 0.2.1 → 0.4.0

package/dist/engine/schema.js

@@ -1,5 +1,7 @@
-import { validateColumnDefault, validateEnumValues, } from "../storage/index.js";
-import { compileCheckExpression, expressionColumns } from "./query.js";
+import { copyDate, dateMilliseconds } from "../date-value.js";
+import { validateColumnDefault, validateEnumValues, validateSqlDomain, } from "../storage/types.js";
+import { compileCheckExpression, expressionColumns, validateDefaultExpression, } from "./query.js";
+import { externalSqlDomainValue, normalizeSqlDomainValue } from "./sql-domains.js";
 /**
  * The constraint name `migrate()` gives a declared relation. It matches the name the SQL parser
  * derives for an unnamed inline REFERENCES, so a table built either way has the same catalog.
@@ -7,12 +9,20 @@ import { compileCheckExpression, expressionColumns } from "./query.js";
 export function foreignKeyName(tableName, columnName) {
     return `${tableName}_${columnName}_fkey`;
 }
-function defaultSpecFromArg(type, value) {
+function defaultSpecFromArg(type, value, sqlDomain) {
+    if (sqlDomain?.kind === "numeric") {
+        if ((typeof value !== "number" || !Number.isFinite(value)) && typeof value !== "string") {
+            throw new TypeError("NUMERIC default must be a finite number or decimal string");
+        }
+        normalizeSqlDomainValue(sqlDomain, value);
+        return { kind: "literal", value };
+    }
     switch (type) {
         case "datetime":
-            if (value !== "now")
-                throw new TypeError('Datetime columns default with "now"');
-            return { kind: "now" };
+            if (!(value instanceof Date) || !Number.isFinite(dateMilliseconds(value))) {
+                throw new TypeError("Default literal must be a valid Date");
+            }
+            return { kind: "literal", value: copyDate(value) };
         case "string":
             if (typeof value !== "string")
                 throw new TypeError("Default literal must be a string");
@@ -34,70 +44,135 @@ function createColumn(type, state = {}) {
         type,
         isNullable: (state.isNullable ?? false),
         isUnique: (state.isUnique ?? false),
-        hasDefault: (state.defaultSpec !== undefined || state.defaultFn !== undefined),
+        hasDefault: (state.defaultSpec !== undefined),
+        integer: state.integer ?? false,
+        ...(state.sqlDomain === undefined ? {} : { sqlDomain: state.sqlDomain }),
         ...(state.defaultSpec === undefined ? {} : { defaultSpec: state.defaultSpec }),
-        ...(state.defaultFn === undefined
-            ? {}
-            : { defaultFn: state.defaultFn }),
         ...(state.renamedFromName === undefined ? {} : { renamedFromName: state.renamedFromName }),
         ...(state.reference === undefined ? {} : { reference: state.reference }),
         ...(state.enumValues === undefined ? {} : { enumValues: state.enumValues }),
-        ...(state.backfillValue === undefined
-            ? {}
-            : { backfillValue: state.backfillValue }),
+        ...(state.backfillValue === undefined ? {} : { backfillValue: state.backfillValue }),
     };
     return {
         ...base,
-        nullable: () => createColumn(type, { ...state, isNullable: true }),
-        unique: () => createColumn(type, { ...state, isUnique: true }),
-        renamedFrom: (name) => createColumn(type, { ...state, renamedFromName: name }),
-        backfill: (value) => createColumn(type, { ...state, backfillValue: value }),
-        references: (table, referencedColumn, options = {}) => createColumn(type, {
+        nullable: () => createColumn(type, {
             ...state,
-            reference: {
-                table,
-                column: referencedColumn,
-                onDelete: options.onDelete ?? "restrict",
-            },
+            isNullable: true,
+        }),
+        unique: () => createColumn(type, {
+            ...state,
+            isUnique: true,
         }),
+        renamedFrom: (name) => {
+            validateSchemaName(name, "Rename source");
+            return createColumn(type, { ...state, renamedFromName: name });
+        },
+        backfill: (value) => createColumn(type, { ...state, backfillValue: value }),
+        references: (table, referencedColumn, options = {}) => {
+            validateSchemaName(table, "Referenced table");
+            validateSchemaName(referencedColumn, "Referenced column");
+            return createColumn(type, {
+                ...state,
+                reference: {
+                    table,
+                    column: referencedColumn,
+                    onDelete: options.onDelete ?? "restrict",
+                },
+            });
+        },
         default: ((value) => {
-            // A declared default is one thing: a function replaces any spec and vice versa.
-            const cleared = { ...state };
-            delete cleared.defaultSpec;
-            delete cleared.defaultFn;
-            return typeof value === "function"
-                ? createColumn(type, { ...cleared, defaultFn: value })
-                : createColumn(type, { ...cleared, defaultSpec: defaultSpecFromArg(type, value) });
+            return createColumn(type, {
+                ...state,
+                defaultSpec: defaultSpecFromArg(type, value, state.sqlDomain),
+            });
+        }),
+        defaultSql: ((sql) => {
+            const expression = sql.trim();
+            if (expression.length === 0 || expression !== sql) {
+                throw new TypeError("Default SQL must be a trimmed non-empty expression");
+            }
+            return createColumn(type, {
+                ...state,
+                defaultSpec: { kind: "expression", sql: expression },
+            });
         }),
         autoIncrement: (() => {
             if (type !== "number") {
                 throw new TypeError("Auto-increment requires a number column");
             }
-            const cleared = { ...state };
-            delete cleared.defaultFn;
-            return createColumn(type, { ...cleared, defaultSpec: { kind: "autoincrement" } });
+            return createColumn(type, {
+                ...state,
+                defaultSpec: { kind: "autoincrement" },
+            });
         }),
     };
 }
+function validateSchemaName(name, kind) {
+    if (name.length === 0)
+        throw new TypeError(`${kind} name cannot be empty`);
+    if (name.trim() !== name) {
+        throw new TypeError(`${kind} name cannot start or end with whitespace: ${JSON.stringify(name)}`);
+    }
+}
 /**
  * Rebuilds a column carrying an exact default spec — the wire layer's escape hatch, since the
- * public `.default()` interprets "now" on datetime columns and cannot express auto-increment.
+ * public `.default()` accepts literals and cannot express auto-increment catalog metadata.
  */
 export function columnWithDefaultSpec(base, spec) {
-    return createColumn(base.type, {
+    return columnFromState({
+        type: base.type,
         isNullable: base.isNullable,
         isUnique: base.isUnique,
+        integer: base.integer ?? false,
+        ...(base.sqlDomain === undefined ? {} : { sqlDomain: base.sqlDomain }),
         ...(base.renamedFromName === undefined ? {} : { renamedFromName: base.renamedFromName }),
         ...(base.reference === undefined ? {} : { reference: base.reference }),
         ...(base.enumValues === undefined ? {} : { enumValues: base.enumValues }),
         defaultSpec: spec,
     });
 }
+/** Rebuilds a fluent column from structured-clone-safe metadata. */
+export function columnFromState(state) {
+    return createColumn(state.type, {
+        isNullable: state.isNullable,
+        isUnique: state.isUnique,
+        integer: state.integer ?? false,
+        ...(state.sqlDomain === undefined ? {} : { sqlDomain: state.sqlDomain }),
+        ...(state.renamedFromName === undefined ? {} : { renamedFromName: state.renamedFromName }),
+        ...(state.reference === undefined ? {} : { reference: state.reference }),
+        ...(state.defaultSpec === undefined ? {} : { defaultSpec: state.defaultSpec }),
+        ...(state.enumValues === undefined ? {} : { enumValues: state.enumValues }),
+        ...(state.backfillValue === undefined ? {} : { backfillValue: state.backfillValue }),
+    });
+}
 export const column = {
     boolean: () => createColumn("boolean"),
     number: () => createColumn("number"),
+    /** Exact safe-integer semantics, matching SQL INTEGER/SMALLINT/BIGINT. */
+    integer: () => createColumn("number", { integer: true }),
     string: () => createColumn("string"),
     datetime: () => createColumn("datetime"),
+    /** Exact decimal SQL NUMERIC. Selects return strings; writes accept strings or numbers. */
+    numeric: (options = {}) => {
+        const sqlDomain = validateSqlDomain({ kind: "numeric", ...options }, "numeric column");
+        return createColumn("string", { sqlDomain });
+    },
+    json: () => createColumn("string", { sqlDomain: { kind: "json" } }),
+    jsonb: () => createColumn("string", { sqlDomain: { kind: "jsonb" } }),
+    uuid: () => createColumn("string", { sqlDomain: { kind: "uuid" } }),
+    time: () => createColumn("string", { sqlDomain: { kind: "time" } }),
+    interval: () => createColumn("string", { sqlDomain: { kind: "interval" } }),
+    /** JSON array text at the JavaScript boundary, with the SQL element type retained in metadata. */
+    array: (element) => createColumn("string", {
+        sqlDomain: validateSqlDomain({ kind: "array", element }, "array column"),
+    }),
+    /** A named SQL enum domain, distinct from the lightweight `column.enum()` restriction. */
+    sqlEnum: (name, values) => {
+        validateSchemaName(name, "Enum type");
+        return createColumn("string", {
+            sqlDomain: validateSqlDomain({ kind: "enum", name, values: validateEnumValues(values, name) }, name),
+        });
+    },
     /**
      * A string column restricted to a closed set of values, typed as their literal union:
      *
@@ -112,7 +187,35 @@ export const column = {
      */
     enum: (values) => createColumn("string", { enumValues: validateEnumValues(values, "enum column") }),
 };
+function validateDeclaredColumnValue(definition, value, context, label) {
+    if (definition.sqlDomain !== undefined) {
+        try {
+            normalizeSqlDomainValue(definition.sqlDomain, value);
+        }
+        catch (error) {
+            throw new TypeError(`${label} does not fit ${context}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return;
+    }
+    const matches = definition.type === "datetime"
+        ? value instanceof Date && Number.isFinite(dateMilliseconds(value))
+        : definition.type === "number"
+            ? typeof value === "number" &&
+                Number.isFinite(value) &&
+                (!definition.integer || Number.isSafeInteger(value))
+            : typeof value === definition.type;
+    if (!matches) {
+        const expected = definition.integer ? "safe integer" : definition.type;
+        throw new TypeError(`${label} value must be a ${expected}: ${context}`);
+    }
+    if (definition.enumValues !== undefined &&
+        typeof value === "string" &&
+        !definition.enumValues.includes(value)) {
+        throw new TypeError(`${label} value must be one of: ${definition.enumValues.join(", ")} (${context})`);
+    }
+}
 export function table(name, columns, options = {}) {
+    validateSchemaName(name, "Table");
     const entries = Object.entries(columns);
     if (entries.length === 0)
         throw new TypeError(`Table ${name} needs at least one column`);
@@ -121,26 +224,48 @@ export function table(name, columns, options = {}) {
         throw new TypeError(`Table ${name} may name at most one unique column`);
     }
     const uniqueEntry = uniqueColumns[0];
+    const primaryKey = options.primaryKey ?? [];
+    if (uniqueEntry !== undefined && primaryKey.length > 0) {
+        throw new TypeError(`Table ${name} cannot declare both .unique() and a table primary key`);
+    }
+    if (primaryKey.length === 0 && options.primaryKey !== undefined) {
+        throw new TypeError(`Table ${name} primary key needs at least one column`);
+    }
+    if (new Set(primaryKey).size !== primaryKey.length) {
+        throw new TypeError(`Table ${name} primary key columns must be distinct`);
+    }
+    for (const columnName of primaryKey) {
+        const definition = columns[columnName];
+        if (definition === undefined) {
+            throw new TypeError(`PRIMARY KEY column not found: ${name}.${columnName}`);
+        }
+        if (definition.isNullable) {
+            throw new TypeError(`PRIMARY KEY cannot be nullable: ${name}.${columnName}`);
+        }
+    }
     if (uniqueEntry?.[1].isNullable === true) {
         throw new TypeError(`Table ${name} unique column must not be nullable: ${uniqueEntry[0]}`);
     }
     for (const [columnName, definition] of entries) {
-        if (definition.defaultFn !== undefined && definition.isNullable) {
-            throw new TypeError(`Defaults require a non-nullable column: ${columnName}`);
+        validateSchemaName(columnName, "Column");
+        if (definition.integer && definition.type !== "number") {
+            throw new TypeError(`Integer domain requires a number column: ${name}.${columnName}`);
+        }
+        if (definition.sqlDomain !== undefined) {
+            if (definition.type !== "string") {
+                throw new TypeError(`SQL domains require string storage: ${name}.${columnName}`);
+            }
+            validateSqlDomain(definition.sqlDomain, `${name}.${columnName}`);
+        }
+        if (definition.integer && definition.sqlDomain !== undefined) {
+            throw new TypeError(`A column cannot be both integer and a SQL domain: ${name}.${columnName}`);
+        }
+        if (definition.enumValues !== undefined && definition.sqlDomain !== undefined) {
+            throw new TypeError(`A column cannot have both enum restrictions and a SQL domain: ${name}.${columnName}`);
         }
         const backfill = definition.backfillValue;
         if (backfill !== undefined && typeof backfill !== "function") {
-            const matches = definition.type === "datetime"
-                ? backfill instanceof Date
-                : typeof backfill === definition.type;
-            if (!matches) {
-                throw new TypeError(`Backfill value must be a ${definition.type}: ${name}.${columnName}`);
-            }
-            if (definition.enumValues !== undefined &&
-                typeof backfill === "string" &&
-                !definition.enumValues.includes(backfill)) {
-                throw new TypeError(`Backfill value must be one of: ${definition.enumValues.join(", ")} (${name}.${columnName})`);
-            }
+            validateDeclaredColumnValue(definition, backfill, `${name}.${columnName}`, "Backfill");
         }
         if (backfill !== undefined && definition.isNullable) {
             throw new TypeError(`A nullable column needs no backfill: ${name}.${columnName}. Rows without it already read NULL.`);
@@ -154,28 +279,91 @@ export function table(name, columns, options = {}) {
         validateColumnDefault({
             name: columnName,
             type: definition.type,
+            ...(definition.integer ? { integer: true } : {}),
+            ...(definition.sqlDomain === undefined ? {} : { sqlDomain: definition.sqlDomain }),
             nullable: definition.isNullable,
-            isUniqueKey: definition.isUnique,
+            isUniqueKey: definition.isUnique || (primaryKey.length === 1 && primaryKey[0] === columnName),
             ...(definition.enumValues === undefined ? {} : { enumValues: definition.enumValues }),
         }, spec);
+        if (spec.kind === "expression") {
+            validateDefaultExpression(spec.sql, {
+                name: `${name}.${columnName}`,
+                type: definition.type,
+                ...(definition.sqlDomain === undefined ? {} : { sqlDomain: definition.sqlDomain }),
+            });
+        }
+        if (spec.kind === "literal" && definition.sqlDomain !== undefined) {
+            normalizeSqlDomainValue(definition.sqlDomain, spec.value);
+        }
+    }
+    const foreignKeys = options.foreignKeys ?? [];
+    const constraintNames = new Set();
+    const foreignKeyNames = new Set();
+    for (const key of foreignKeys) {
+        validateSchemaName(key.name, "FOREIGN KEY");
+        if (foreignKeyNames.has(key.name)) {
+            throw new TypeError(`Duplicate FOREIGN KEY in table ${name}: ${key.name}`);
+        }
+        foreignKeyNames.add(key.name);
+        if (constraintNames.has(key.name)) {
+            throw new TypeError(`Duplicate constraint in table ${name}: ${key.name}`);
+        }
+        constraintNames.add(key.name);
+        if (key.columns.length === 0 || new Set(key.columns).size !== key.columns.length) {
+            throw new TypeError(`FOREIGN KEY ${key.name} needs distinct child columns`);
+        }
+        if (key.references.columns.length === 0 ||
+            new Set(key.references.columns).size !== key.references.columns.length) {
+            throw new TypeError(`FOREIGN KEY ${key.name} needs distinct parent columns`);
+        }
+        if (key.columns.length !== key.references.columns.length) {
+            throw new TypeError(`FOREIGN KEY ${key.name} has different child and parent arity`);
+        }
+        validateSchemaName(key.references.table, "Referenced table");
+        key.references.columns.forEach((columnName) => validateSchemaName(columnName, "Referenced column"));
+        for (const columnName of key.columns) {
+            const definition = columns[columnName];
+            if (definition === undefined) {
+                throw new TypeError(`FOREIGN KEY ${key.name} names an unknown column: ${name}.${columnName}`);
+            }
+            if ((key.onDelete ?? "restrict") === "set null" && !definition.isNullable) {
+                throw new TypeError(`FOREIGN KEY ${key.name} cannot SET NULL a NOT NULL column`);
+            }
+        }
     }
     const checks = options.checks ?? [];
     const checkNames = new Set();
     for (const check of checks) {
-        if (check.name.length === 0)
-            throw new TypeError(`Table ${name} has an unnamed CHECK`);
+        validateSchemaName(check.name, "CHECK");
         if (checkNames.has(check.name)) {
             throw new TypeError(`Duplicate CHECK in table ${name}: ${check.name}`);
         }
         checkNames.add(check.name);
+        if (constraintNames.has(check.name)) {
+            throw new TypeError(`Duplicate constraint in table ${name}: ${check.name}`);
+        }
+        constraintNames.add(check.name);
         if (check.sql.trim().length === 0) {
             throw new TypeError(`CHECK ${check.name} in table ${name} has no expression`);
         }
+        for (const reference of expressionColumns(compileCheckExpression(check.sql, check.name))) {
+            const pieces = reference.split(".");
+            const columnName = pieces.at(-1) ?? reference;
+            const qualifier = pieces.length > 1 ? pieces.slice(0, -1).join(".") : undefined;
+            if (qualifier !== undefined && qualifier !== name) {
+                throw new TypeError(`CHECK ${check.name} references another table: ${reference}`);
+            }
+            if (columns[columnName] === undefined) {
+                throw new TypeError(`CHECK ${check.name} names an unknown column: ${columnName}`);
+            }
+        }
     }
     return {
         kind: "table",
         name,
         columns,
+        primaryKey,
+        foreignKeys,
         checks,
         "~standard": {
             version: 1,
@@ -188,27 +376,31 @@ export function table(name, columns, options = {}) {
                 const issues = [];
                 for (const [columnName, definition] of entries) {
                     const columnValue = row[columnName];
-                    if (columnValue === undefined || columnValue === null) {
-                        // A default-bearing column may be omitted — the engine (or the facade, for
-                        // function defaults) fills it at insert time.
-                        if (!definition.isNullable &&
-                            definition.defaultSpec === undefined &&
-                            definition.defaultFn === undefined) {
+                    if (columnValue === undefined) {
+                        if (!definition.isNullable && definition.defaultSpec === undefined) {
                             issues.push({ message: `Missing non-nullable column`, path: [columnName] });
                         }
                         continue;
                     }
-                    const matches = definition.type === "datetime"
-                        ? columnValue instanceof Date
-                        : typeof columnValue === definition.type;
-                    if (!matches) {
-                        issues.push({ message: `Expected ${definition.type}`, path: [columnName] });
+                    if (columnValue === null) {
+                        if (!definition.isNullable) {
+                            issues.push({ message: `Expected non-null value`, path: [columnName] });
+                        }
+                        continue;
+                    }
+                    try {
+                        validateDeclaredColumnValue(definition, columnValue, `${name}.${columnName}`, "Value");
                     }
-                    else if (definition.enumValues !== undefined &&
-                        typeof columnValue === "string" &&
-                        !definition.enumValues.includes(columnValue)) {
+                    catch (error) {
+                        const message = definition.enumValues !== undefined && typeof columnValue === "string"
+                            ? `Expected one of: ${definition.enumValues.join(", ")}`
+                            : definition.sqlDomain === undefined
+                                ? `Expected ${definition.integer ? "safe integer" : definition.type}`
+                                : error instanceof Error
+                                    ? error.message
+                                    : `Invalid value`;
                         issues.push({
-                            message: `Expected one of: ${definition.enumValues.join(", ")}`,
+                            message,
                             path: [columnName],
                         });
                     }
@@ -235,12 +427,23 @@ export function declaredForeignKeys(definition) {
             continue;
         keys.push({
             name: foreignKeyName(definition.name, columnName),
-            column: columnName,
+            columns: [columnName],
             parentTable: reference.table,
-            parentColumn: reference.column,
+            parentColumns: [reference.column],
             onDelete: reference.onDelete,
         });
     }
+    for (const key of definition.foreignKeys) {
+        const childColumns = [...key.columns];
+        const parentColumns = [...key.references.columns];
+        keys.push({
+            name: key.name,
+            columns: childColumns,
+            parentTable: key.references.table,
+            parentColumns,
+            onDelete: key.onDelete ?? "restrict",
+        });
+    }
     return keys;
 }
 /**
@@ -255,16 +458,18 @@ export function declaredForeignKeys(definition) {
  * ```
  */
 export function view(name, definition) {
+    validateSchemaName(name, "View");
     const entries = Object.entries(definition.columns);
     if (entries.length === 0)
         throw new TypeError(`View ${name} needs at least one column`);
     if (definition.sql.trim().length === 0)
         throw new TypeError(`View ${name} has no query`);
     for (const [columnName, columnDefinition] of entries) {
+        validateSchemaName(columnName, "Column");
         if (columnDefinition.isUnique) {
             throw new TypeError(`A view column cannot be a unique key: ${name}.${columnName}`);
         }
-        if (columnDefinition.defaultSpec !== undefined || columnDefinition.defaultFn !== undefined) {
+        if (columnDefinition.defaultSpec !== undefined) {
             throw new TypeError(`A view column cannot have a default: ${name}.${columnName}`);
         }
     }
@@ -286,14 +491,38 @@ export function schema(tables, options = {}) {
         names.add(definition.name);
     }
     for (const definition of tables) {
-        for (const [columnName, columnDefinition] of Object.entries(definition.columns)) {
-            const reference = columnDefinition.reference;
-            if (reference === undefined)
-                continue;
-            const target = tables.find(({ name }) => name === reference.table);
-            if (target === undefined || !(reference.column in target.columns)) {
-                throw new TypeError(`Relation target does not exist: ${definition.name}.${columnName} -> ${reference.table}.${reference.column}`);
+        const declaredNames = new Set();
+        for (const key of declaredForeignKeys(definition)) {
+            if (declaredNames.has(key.name)) {
+                throw new TypeError(`Duplicate FOREIGN KEY in table ${definition.name}: ${key.name}`);
+            }
+            declaredNames.add(key.name);
+            const childNames = key.columns;
+            const parentNames = key.parentColumns;
+            const target = tables.find(({ name }) => name === key.parentTable);
+            if (target === undefined ||
+                childNames.some((columnName) => !(columnName in definition.columns)) ||
+                parentNames.some((columnName) => !(columnName in target.columns))) {
+                throw new TypeError(`Relation target does not exist: ${definition.name}.${childNames.join(",")} -> ${key.parentTable}.${parentNames.join(",")}`);
             }
+            const targetPrimary = target.primaryKey.length > 0
+                ? [...target.primaryKey]
+                : Object.entries(target.columns).flatMap(([name, columnDefinition]) => columnDefinition.isUnique ? [name] : []);
+            if (parentNames.length !== targetPrimary.length ||
+                parentNames.some((columnName, index) => columnName !== targetPrimary[index])) {
+                throw new TypeError(`Relation target must be the unique key: ${definition.name}.${childNames.join(",")} -> ${key.parentTable}(${targetPrimary.join(", ")})`);
+            }
+            childNames.forEach((childName, index) => {
+                const child = definition.columns[childName];
+                const parentName = parentNames[index];
+                const parent = parentName === undefined ? undefined : target.columns[parentName];
+                if (child === undefined ||
+                    child.type !== parent?.type ||
+                    child.integer !== parent.integer ||
+                    JSON.stringify(child.sqlDomain ?? null) !== JSON.stringify(parent.sqlDomain ?? null)) {
+                    throw new TypeError(`Relation types must match: ${definition.name}.${childName} and ${key.parentTable}.${String(parentName)}`);
+                }
+            });
         }
     }
     return { kind: "schema", tables, views };
@@ -367,16 +596,22 @@ export function isDestructiveStep(step) {
  * the catalog still points at it. Each of these would leave a constraint or key referring to a
  * column no longer there, so the drop is refused rather than silently invalidating them.
  */
-function assertColumnDroppable(record, column) {
+export function assertColumnDroppable(record, column) {
     const where = `${record.name}.${column.name}`;
-    if (record.uniqueKeyColumnId === column.id) {
+    if (record.uniqueKeyColumnId === column.id ||
+        (record.primaryKeyColumnIds ?? []).includes(column.id)) {
         throw new TypeError(`The unique key cannot be dropped: ${where}. Unique-key changes need the table recreated.`);
     }
     for (const key of record.foreignKeys) {
-        if (key.column === column.name) {
+        if (key.columns.includes(column.name)) {
             throw new TypeError(`FOREIGN KEY ${key.name} still uses this column: ${where}`);
         }
     }
+    for (const index of record.indexes ?? []) {
+        if (index.columns.some(({ name }) => name === column.name)) {
+            throw new TypeError(`Index ${index.name} still uses this column: ${where}`);
+        }
+    }
     for (const check of record.checks) {
         let referenced;
         try {
@@ -391,6 +626,24 @@ function assertColumnDroppable(record, column) {
         }
     }
 }
+function assertColumnRenamable(catalog, record, column) {
+    const where = `${record.name}.${column.name}`;
+    for (const owner of catalog.tables) {
+        for (const key of owner.foreignKeys) {
+            const usesChild = owner.name === record.name && key.columns.includes(column.name);
+            const usesParent = key.parentTable === record.name && key.parentColumns.includes(column.name);
+            if (usesChild || usesParent) {
+                throw new TypeError(`FOREIGN KEY ${key.name} prevents renaming ${where}`);
+            }
+        }
+    }
+    for (const check of record.checks) {
+        const referenced = expressionColumns(compileCheckExpression(check.sql, check.name));
+        if (referenced.includes(column.name)) {
+            throw new TypeError(`CHECK ${check.name} prevents renaming ${where}`);
+        }
+    }
+}
 /**
  * Freezes a column's backfill. A generator runs exactly once — here, while the migration is being
  * planned — so the catalog stores a value rather than a function and no two readers can disagree.
@@ -399,7 +652,27 @@ function resolveBackfill(definition) {
     const declared = definition.backfillValue;
     if (declared === undefined)
         return undefined;
-    return typeof declared === "function" ? declared() : declared;
+    const value = typeof declared === "function" ? declared() : declared;
+    validateDeclaredColumnValue(definition, value, "added column", "Backfill");
+    return value;
+}
+function storedBackfill(definition, value) {
+    if (definition.sqlDomain === undefined)
+        return value;
+    const normalized = normalizeSqlDomainValue(definition.sqlDomain, value);
+    if (normalized === null)
+        throw new TypeError("A backfill cannot be NULL");
+    return normalized;
+}
+function backfillsEqual(left, right) {
+    const externalLeft = externalSqlDomainValue(left);
+    const externalRight = externalSqlDomainValue(right);
+    if (externalLeft instanceof Date || externalRight instanceof Date) {
+        return (externalLeft instanceof Date &&
+            externalRight instanceof Date &&
+            dateMilliseconds(externalLeft) === dateMilliseconds(externalRight));
+    }
+    return externalLeft === externalRight;
 }
 /**
  * Constraints on an existing table cannot change through a metadata-only step. Attaching a
@@ -409,17 +682,18 @@ function resolveBackfill(definition) {
  * discipline every other unprovable change gets: an explicit error naming the fix.
  */
 function assertConstraintsUnchanged(record, definition) {
-    const describeKey = (key) => `${key.column} -> ${key.parentTable}.${key.parentColumn} ON DELETE ${key.onDelete}`;
+    const describeKey = (key) => `${key.columns.join(",")} -> ${key.parentTable}.` +
+        `${key.parentColumns.join(",")} ON DELETE ${key.onDelete}`;
     const existingKeys = new Map(record.foreignKeys.map((key) => [key.name, key]));
     const declaredKeys = new Map(declaredForeignKeys(definition).map((key) => [key.name, key]));
     for (const [name, declared] of declaredKeys) {
         const existing = existingKeys.get(name);
         if (existing === undefined) {
-            throw new TypeError(`FOREIGN KEY cannot be added after creation: ${definition.name}.${declared.column}. ` +
+            throw new TypeError(`FOREIGN KEY cannot be added after creation: ${definition.name}.${declared.columns.join(",")}. ` +
                 `Existing rows are not known to satisfy it; recreate the table to add a relation.`);
         }
         if (describeKey(existing) !== describeKey(declared)) {
-            throw new TypeError(`FOREIGN KEY cannot change: ${definition.name}.${declared.column} is ` +
+            throw new TypeError(`FOREIGN KEY cannot change: ${definition.name}.${declared.columns.join(",")} is ` +
                 `${describeKey(existing)}, schema says ${describeKey(declared)}`);
         }
     }
@@ -466,9 +740,13 @@ export function planMigration(catalog, definition, options = {}) {
             if (existing === undefined && from !== undefined) {
                 const source = recordColumnsByName.get(from);
                 if (source !== undefined) {
+                    if (renameSources.has(from)) {
+                        throw new TypeError(`Rename source is used more than once: ${tableDefinition.name}.${from}`);
+                    }
                     if (definedNames.has(from)) {
                         throw new TypeError(`Rename source is still defined: ${tableDefinition.name}.${from}`);
                     }
+                    assertColumnRenamable(catalog, record, source);
                     steps.push({
                         kind: "rename-column",
                         tableName: tableDefinition.name,
@@ -484,7 +762,7 @@ export function planMigration(catalog, definition, options = {}) {
                 if (!columnDefinition.isNullable && backfill === undefined) {
                     throw new TypeError(`Added columns must be nullable, or carry a backfill: ${tableDefinition.name}.${columnName}`);
                 }
-                if (columnDefinition.isUnique) {
+                if (columnDefinition.isUnique || tableDefinition.primaryKey.includes(columnName)) {
                     throw new TypeError(`Unique keys cannot be added after creation: ${tableDefinition.name}.${columnName}`);
                 }
                 steps.push({
@@ -499,6 +777,23 @@ export function planMigration(catalog, definition, options = {}) {
             if (existing.type !== columnDefinition.type) {
                 throw new TypeError(`Column types cannot change: ${tableDefinition.name}.${columnName} is ${existing.type}, schema says ${columnDefinition.type}`);
             }
+            if ((existing.integer === true) !== columnDefinition.integer ||
+                JSON.stringify(existing.sqlDomain ?? null) !==
+                    JSON.stringify(columnDefinition.sqlDomain ?? null)) {
+                throw new TypeError(`Column domains cannot change: ${tableDefinition.name}.${columnName}`);
+            }
+            if (existing.backfill === undefined && columnDefinition.backfillValue !== undefined) {
+                throw new TypeError(`Backfills cannot be added after a column exists: ${tableDefinition.name}.${columnName}`);
+            }
+            if (existing.backfill !== undefined && columnDefinition.backfillValue === undefined) {
+                throw new TypeError(`Backfills cannot be removed: ${tableDefinition.name}.${columnName}`);
+            }
+            if (existing.backfill !== undefined &&
+                columnDefinition.backfillValue !== undefined &&
+                typeof columnDefinition.backfillValue !== "function" &&
+                !backfillsEqual(existing.backfill, columnDefinition.backfillValue)) {
+                throw new TypeError(`Backfills cannot change: ${tableDefinition.name}.${columnName}`);
+            }
             const existingEnum = existing.enumValues;
             const definedEnum = columnDefinition.enumValues;
             if (definedEnum !== undefined && existingEnum === undefined) {
@@ -528,8 +823,10 @@ export function planMigration(catalog, definition, options = {}) {
                     }
                 }
             }
-            const existingIsKey = record.uniqueKeyColumnId === existing.id;
-            if (existingIsKey !== columnDefinition.isUnique) {
+            const existingIsKey = record.uniqueKeyColumnId === existing.id ||
+                (record.primaryKeyColumnIds ?? []).includes(existing.id);
+            const definedIsKey = columnDefinition.isUnique || tableDefinition.primaryKey.includes(columnName);
+            if (existingIsKey !== definedIsKey) {
                 throw new TypeError(`Unique keys cannot change: ${tableDefinition.name}.${columnName}`);
             }
             if (existing.nullable && !columnDefinition.isNullable) {
@@ -578,6 +875,20 @@ export function planMigration(catalog, definition, options = {}) {
                 columnName: columnRecord.name,
             });
         }
+        const existingKeyIds = record.primaryKeyColumnIds ??
+            (record.uniqueKeyColumnId === undefined ? [] : [record.uniqueKeyColumnId]);
+        const desiredKeyNames = tableDefinition.primaryKey.length > 0
+            ? tableDefinition.primaryKey
+            : Object.entries(tableDefinition.columns).flatMap(([name, definition]) => definition.isUnique ? [name] : []);
+        const desiredKeyIds = desiredKeyNames.map((name) => {
+            const definition = tableDefinition.columns[name];
+            const currentName = definition?.renamedFromName ?? name;
+            return recordColumnsByName.get(name)?.id ?? recordColumnsByName.get(currentName)?.id;
+        });
+        if (desiredKeyIds.length !== existingKeyIds.length ||
+            desiredKeyIds.some((id, index) => id !== existingKeyIds[index])) {
+            throw new TypeError(`Primary key order cannot change: ${tableDefinition.name}`);
+        }
         assertConstraintsUnchanged(record, tableDefinition);
     }
     if (options.schemaOwnsDatabase === true) {
@@ -591,32 +902,164 @@ export function planMigration(catalog, definition, options = {}) {
         }
     }
     planViewSteps(catalog, definition, steps);
-    return { steps };
+    // A managed view can depend on a managed table the same authoritative schema removes. Drop
+    // dependents first; the SQL engine correctly refuses the reverse order. Replacements stay
+    // after table-creation steps so a newly declared body can resolve its sources.
+    const droppedViews = steps.filter((step) => step.kind === "drop-view");
+    const droppedTables = steps.filter((step) => step.kind === "drop-table");
+    return {
+        steps: [
+            ...steps.filter((step) => step.kind !== "drop-view" && step.kind !== "drop-table"),
+            ...droppedViews,
+            ...droppedTables,
+        ],
+    };
 }
 /**
- * A thin, fully typed handle over the existing batch APIs: inserts require every non-nullable
- * column, updates exclude the unique key, and reads return the complete inferred row shape.
+ * A thin, fully typed SQL handle: inserts require every non-nullable column, updates exclude the
+ * unique key, and reads return the complete inferred row shape. Every operation is rendered as
+ * parameterized SQL and goes through the parser/planner/executor; this helper has no private
+ * batch or table-read semantics that can drift from SQL.
  */
 export function typedTable(database, definition) {
     const columnNames = Object.keys(definition.columns);
-    // Pads every schema column, so omitting a nullable one is an explicit null rather than a
-    // "Missing column" error from the engine; function defaults fill their omitted slots here,
-    // before the batch reaches the engine.
-    const pad = (rows) => rows.map((row) => Object.fromEntries(columnNames.map((name) => {
-        const value = row[name] ?? null;
-        const fill = definition.columns[name]?.defaultFn;
-        return [name, value === null && fill !== undefined ? fill() : value];
-    })));
+    const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+    const scalarUniqueKey = Object.entries(definition.columns).find(([, columnDefinition]) => columnDefinition.isUnique)?.[0];
+    const keyColumns = definition.primaryKey.length > 0
+        ? [...definition.primaryKey]
+        : scalarUniqueKey === undefined
+            ? []
+            : [scalarUniqueKey];
+    const normalizedRows = (rows) => {
+        if (rows.length === 0)
+            throw new TypeError("A batch needs at least one row");
+        // Keep extra runtime keys in the SQL column list. TypeScript normally excludes them, but a
+        // cast or JavaScript caller must still get the engine's "column does not exist" error rather
+        // than having data silently discarded by this facade.
+        const names = new Set(columnNames);
+        for (const row of rows)
+            for (const name of Object.keys(row))
+                names.add(name);
+        const ordered = [...names];
+        return { names: ordered, rows };
+    };
+    const insert = (rows, replace) => {
+        const normalized = normalizedRows(rows);
+        const params = [];
+        const values = normalized.rows
+            .map((row) => {
+            const placeholders = normalized.names.map((name) => {
+                const value = row[name];
+                if (!Object.hasOwn(row, name) || value === undefined)
+                    return "DEFAULT";
+                params.push(value);
+                return `$${String(params.length)}`;
+            });
+            return `(${placeholders.join(", ")})`;
+        })
+            .join(", ");
+        let sql = `INSERT INTO ${quote(definition.name)} (${normalized.names.map(quote).join(", ")}) VALUES ${values}`;
+        if (replace) {
+            if (keyColumns.length === 0) {
+                throw new TypeError(`Upsert requires a unique key: ${definition.name}`);
+            }
+            sql += ` ON CONFLICT (${keyColumns.map(quote).join(", ")}) DO REPLACE`;
+        }
+        return database.execute(sql, params);
+    };
+    const requireUniqueKey = (operation) => {
+        if (keyColumns.length === 0) {
+            throw new TypeError(`${operation} requires a table with a unique key: ${definition.name}`);
+        }
+        return keyColumns;
+    };
+    const keyParts = (key) => {
+        if (keyColumns.length === 1)
+            return [key];
+        if (typeof key !== "object" || key === null) {
+            throw new TypeError(`Composite key for ${definition.name} must be an object`);
+        }
+        return keyColumns.map((name) => key[name]);
+    };
+    const keyToken = (value) => {
+        const parts = keyParts(value);
+        return JSON.stringify(parts.map((part) => part instanceof Date ? ["date", dateMilliseconds(part)] : [typeof part, String(part)]));
+    };
+    const assertKeys = (keys, operation) => {
+        if (keys.length === 0)
+            throw new TypeError(`A ${operation} batch needs at least one key`);
+        const seen = new Set();
+        for (const key of keys) {
+            if (keyParts(key).some((part) => part === undefined || part === null)) {
+                throw new TypeError(`Missing ${operation} key value for ${definition.name}`);
+            }
+            const token = keyToken(key);
+            if (seen.has(token))
+                throw new TypeError(`Duplicate key in ${operation} batch: ${String(key)}`);
+            seen.add(token);
+        }
+    };
     return {
         definition,
-        insert: (rows) => database.insertBatch(definition.name, pad(rows)),
-        upsert: (rows) => database.upsertBatch(definition.name, pad(rows)),
-        update: (input) => database.updateBatch(definition.name, {
-            keys: input.keys,
-            changes: input.changes,
-        }),
-        delete: (input) => database.deleteBatch(definition.name, { keys: input.keys }),
-        rows: async () => (await database.readTable(definition.name)),
+        insert: (rows) => insert(rows, false),
+        upsert: (rows) => insert(rows, true),
+        update: (input) => {
+            const keys = requireUniqueKey("UPDATE");
+            assertKeys(input.keys, "update");
+            const assignments = [];
+            const params = [];
+            for (const [name, rawValues] of Object.entries(input.changes)) {
+                if (!(name in definition.columns)) {
+                    // Render it anyway so SQL owns the public validation error.
+                }
+                const values = rawValues;
+                if (values.length !== input.keys.length) {
+                    throw new TypeError(`Update column ${name} has ${String(values.length)} values for ${String(input.keys.length)} keys`);
+                }
+                const branches = [];
+                values.forEach((value, index) => {
+                    if (value === undefined)
+                        return;
+                    const keyValue = input.keys[index];
+                    if (keyValue === undefined) {
+                        throw new TypeError(`Missing update key at position ${String(index)}`);
+                    }
+                    const conditions = keyParts(keyValue).map((part, keyIndex) => {
+                        params.push(part);
+                        return `${quote(keys[keyIndex] ?? "")} = $${String(params.length)}`;
+                    });
+                    params.push(value);
+                    branches.push(`WHEN ${conditions.join(" AND ")} THEN $${String(params.length)}`);
+                });
+                if (branches.length > 0) {
+                    assignments.push(`${quote(name)} = CASE ${branches.join(" ")} ELSE ${quote(name)} END`);
+                }
+            }
+            if (assignments.length === 0)
+                throw new TypeError("An update batch needs at least one change");
+            const predicates = input.keys.map((keyValue) => {
+                const conditions = keyParts(keyValue).map((part, keyIndex) => {
+                    params.push(part);
+                    return `${quote(keys[keyIndex] ?? "")} = $${String(params.length)}`;
+                });
+                return `(${conditions.join(" AND ")})`;
+            });
+            return database.execute(`UPDATE ${quote(definition.name)} SET ${assignments.join(", ")} WHERE ${predicates.join(" OR ")}`, params);
+        },
+        delete: (input) => {
+            const keys = requireUniqueKey("DELETE");
+            assertKeys(input.keys, "delete");
+            const params = [];
+            const predicates = input.keys.map((keyValue) => {
+                const conditions = keyParts(keyValue).map((part, keyIndex) => {
+                    params.push(part);
+                    return `${quote(keys[keyIndex] ?? "")} = $${String(params.length)}`;
+                });
+                return `(${conditions.join(" AND ")})`;
+            });
+            return database.execute(`DELETE FROM ${quote(definition.name)} WHERE ${predicates.join(" OR ")}`, params);
+        },
+        rows: async () => (await database.query(`SELECT ${columnNames.map(quote).join(", ")} FROM ${quote(definition.name)}`)).rows,
     };
 }
 /** Applies one table's alteration steps onto its current column records. */
@@ -635,10 +1078,21 @@ export function applyColumnSteps(record, steps, createId) {
                     id: createId(),
                     name: step.columnName,
                     type: step.definition.type,
+                    ...(step.definition.integer ? { integer: true } : {}),
+                    ...(step.definition.sqlDomain === undefined
+                        ? {}
+                        : { sqlDomain: structuredClone(step.definition.sqlDomain) }),
                     // A backfill is what lets the column be non-nullable: every row has a value, either
                     // written or substituted at read time.
                     nullable: step.backfill === undefined ? true : step.definition.isNullable,
-                    ...(step.backfill === undefined ? {} : { backfill: step.backfill }),
+                    ...(step.backfill === undefined
+                        ? {}
+                        : {
+                            backfill: storedBackfill(step.definition, step.backfill),
+                        }),
+                    ...(step.definition.defaultSpec === undefined
+                        ? {}
+                        : { defaultValue: step.definition.defaultSpec }),
                     ...(step.definition.enumValues === undefined
                         ? {}
                         : { enumValues: [...step.definition.enumValues] }),
@@ -704,6 +1158,14 @@ function columnDefaultsEqual(left, right) {
         return left === right;
     if (left.kind !== right.kind)
         return false;
-    return left.kind !== "literal" || right.kind !== "literal" || left.value === right.value;
+    if (left.kind === "expression" && right.kind === "expression")
+        return left.sql === right.sql;
+    if (left.kind !== "literal" || right.kind !== "literal")
+        return true;
+    if (left.value instanceof Date || right.value instanceof Date) {
+        return (left.value instanceof Date &&
+            right.value instanceof Date &&
+            dateMilliseconds(left.value) === dateMilliseconds(right.value));
+    }
+    return left.value === right.value;
 }
-//# sourceMappingURL=schema.js.map