@minnowdb/core 0.4.0 → 0.5.0

package/dist/engine/database.js

@@ -2,23 +2,23 @@ import { toColumnarBatch, } from "./batch.js";
 import { ArtifactCache } from "./artifact-cache.js";
 import { BufferedTableWriter } from "./buffered-writer.js";
 export { attachLifecycleFlush, BufferedTableWriter, MAX_BUFFERED_WRITER_PENDING_ADDS, } from "./buffered-writer.js";
-import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UniqueConstraintError, VisibleSegmentCursorStaleError, } from "./errors.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError, } from "./errors.js";
 import { BLOCK_HEADER_LENGTH, buildPhysicalColumnFromRanges, decodeBlock, decodePhysicalBlock, encodeBlock, encodePhysicalBlock, getCompressionMemoryBound, inspectBlock, maximumPhysicalBlockByteLength, MAX_BLOCK_METADATA_BYTE_LENGTH, MAX_BLOCK_ROW_COUNT, MAX_PHYSICAL_COLUMN_BYTE_LENGTH, MAX_STORED_BLOCK_BYTE_LENGTH, measurePhysicalColumnRanges, physicalColumnByteLength, slicePhysicalColumn, StoredBlockPayloadTooLargeError, wellFormedUtf8ByteLength, } from "../block-format/index.js";
 import { dateIsoString, dateMilliseconds } from "../date-value.js";
 import { estimateCompactionRowsPerOutput, planAlignedWriteBlockRanges as writeBlockRanges, } from "./write-block-planner.js";
-import { MAX_CACHEABLE_TEXT_CHARACTERS } from "./cache-limits.js";
+import { MAX_CACHEABLE_TEXT_CHARACTERS, MAX_SQL_PARAMETERS } from "./cache-limits.js";
 import { fillColumnDefaults, patchAutoIncrementValues, } from "./defaults.js";
 import { cachedQueryTerms, FTS_TOKENIZER_VERSION, renderDocumentValue, tokenize as ftsTokenize, } from "./fts.js";
 import { boundedMaintenanceBatchItems, simpleDataTypes, floorWholeNumberProduct, BlockReadBatchTooLargeError, validateColumnDefault, validateEnumValues, secondaryIndexColumnIds, secondaryIndexDirections, secondaryUniqueKeyNamespace, CompactionJobConflictError, CompactionBacklogError, GarbageCollectionJobConflictError, MAX_LEVEL_ZERO_SEGMENTS, MAX_FTS_CANDIDATE_ROW_IDS, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_INDEXED_STRING_CHARACTERS, MAX_CATALOG_NAME_CHARACTERS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_MAINTENANCE_BATCH_ITEMS, MAX_STORAGE_BULK_READ_ITEMS, MAX_TRANSACTION_STAGE_BLOCKS, MAX_TRANSACTION_STAGE_BYTES, MAX_SNAPSHOT_SESSION_TTL_MS, MAX_POSTING_BUILD_TTL_MS, MAX_TEMP_OWNER_TTL_MS, MAX_SNAPSHOT_FRAME_BATCH_BYTES, MAX_SNAPSHOT_FRAME_BATCH_ITEMS, MAX_SNAPSHOT_METADATA_BATCH_BYTES, SNAPSHOT_FRAME_KINDS, validateStorageId, SnapshotManifestMissingError, SchemaConflictError, TableInUseError, TableRecordConflictError, TransactionRecordConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, } from "../storage/types.js";
 import { decodeSnapshotFrameStream, encodeSnapshotFrameStreamFooter, encodeSnapshotFrameStreamHeader, extendSnapshotFrameStreamChecksum, snapshotFrameEnvelopeParts, snapshotFrameStreamHeaderIdentity, } from "../storage/snapshot.js";
 import { Snapshot, TransactionManager, } from "../transactions/index.js";
-import { applyWindowFunctions, bindPlanParameters, bindStatementParameters, DUAL_TABLE, dualTableRows, blockHasSubqueries, combineUnionResults, compileCheckExpression, compileQuery, hasAggregate, createRecursiveCteState, compileStatement, createPreparedColumnarQuery, evaluateJoinedRowExpression, evaluateRowExpression, externalizeQueryResult, expressionColumnNames, inferBlockSchema, isDefaultInsertValue, referencedColumns, childExpressions, expandFtsColumns, expandNaturalJoins, expandSourceColumnAliases, expandViewSources, forEachBlockExpression, planContainsFts, planHasNaturalJoins, planHasSourceColumnAliases, planReadsTable, planReadsViews, planReadsBeyondSingleScan, projectResultColumns, queryResultNeedsExternalization, resolveStatementDatetimes, subqueryResolutionSteps, topLevelFtsMatchConjuncts, transparentProjectionSource, validateDefaultExpression, windowOutputDomain, windowOutputType, } from "./query.js";
+import { applyWindowFunctions, bindPlanParameters, bindStatementParameters, DUAL_TABLE, dualTableRows, blockHasSubqueries, combineUnionResults, compileCheckExpression, compileQuery, hasAggregate, createRecursiveCteState, compileStatement, comparisonHolds, createPreparedColumnarQuery, evaluateJoinedRowExpression, evaluateRowExpression, externalizeQueryResult, expressionColumnNames, inferBlockSchema, inferResultColumnDomains, isDefaultInsertValue, referencedColumns, childExpressions, expandFtsColumns, expandNaturalJoins, expandSourceColumnAliases, expandViewSources, forEachBlockExpression, planContainsFts, planHasNaturalJoins, planHasSourceColumnAliases, planReadsTable, planReadsViews, planReadsBeyondSingleScan, projectResultColumns, queryResultNeedsExternalization, resolveStatementDatetimes, subqueryResolutionSteps, topLevelFtsMatchConjuncts, transparentProjectionSource, unknownColumnDomains, validateDefaultExpression, windowOutputDomain, windowOutputType, } from "./query.js";
 import { copyQueryResult, planMemoKey, queryResultMemoKey, queryResultRetainedBytes, RESULT_MEMO_MAX_BYTES, } from "./query-cache.js";
 import { QueryMemoryBudgetError, QueryMemoryContext, DEFAULT_QUERY_MEMORY_BUDGET_BYTES, } from "./memory.js";
 import { LiveQueryLimitError, LiveQuerySet, MAX_LIVE_QUERY_SETS_PER_DATABASE, } from "./live.js";
 import { chooseJoinOrder, renderPlan } from "./optimizer.js";
 import { encodeSqlEqualityValue } from "./sql-semantics.js";
-import { externalSqlDomainValue, externalSqlTextValue, isSqlDomainValue, normalizeSqlDomainValue, protectedSqlTextValue, } from "./sql-domains.js";
+import { externalSqlDomainValue, externalSqlTextValue, isDateDomainValue, isSqlDomainValue, normalizeSqlDomainValue, protectedSqlTextValue, } from "./sql-domains.js";
 import { toCatalog } from "./catalog.js";
 import { applyColumnSteps, assertColumnDroppable, declaredForeignKeys, isDestructiveStep, planMigration, } from "./schema.js";
 import { columnarTableFromRows, createColumnarTable, vectorValue, } from "./vector.js";
@@ -272,7 +272,7 @@ function migrationResult(steps) {
     };
 }
 export const MAX_GARBAGE_COLLECTION_RETAIN_RECENT_VERSIONS = 1_024;
-export { CompactionBacklogError, CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, TableInUseError, UniqueConstraintError, VisibleSegmentCursorStaleError, };
+export { CompactionBacklogError, CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, TableInUseError, UniqueConstraintError, VisibleSegmentCursorStaleError, };
 /**
  * How deep a delete's referential actions may cascade. A chain of CASCADE keys can reach further
  * tables; the bound stops a cycle from recursing, the same way the trigger chain is bounded.
@@ -297,7 +297,11 @@ function externalizeExecuteResult(result) {
     const columns = [...new Set(result.returnedRows.flatMap((row) => Object.keys(row)))];
     return {
         ...result,
-        returnedRows: externalizeQueryResult({ columns, rows: result.returnedRows }).rows,
+        returnedRows: externalizeQueryResult({
+            columns,
+            columnDomains: unknownColumnDomains(columns),
+            rows: result.returnedRows,
+        }).rows,
     };
 }
 /** Rejects an INSERT value that is still an unbound `?`/`$n` slot. */
@@ -894,6 +898,9 @@ export class MinnowDatabase {
         const checkNames = (input.checks ?? []).map((check) => claimConstraintName(check.name));
         const uniqueConstraintNames = (input.uniqueConstraints ?? []).map((constraint) => claimConstraintName(constraint.name));
         const foreignKeys = await Promise.all((input.foreignKeys ?? []).map(async (key, keyIndex) => {
+            if (key.enforced === false && key.onDelete !== "restrict") {
+                throw new TypeError(`Informational FOREIGN KEY ${key.name} cannot declare ON DELETE actions`);
+            }
             const childNames = key.columns ?? [key.column];
             const children = childNames.map((columnName) => {
                 const column = columns.find((candidate) => candidate.name === columnName);
@@ -959,6 +966,7 @@ export class MinnowDatabase {
                 parentTable: key.parentTable,
                 parentColumns: parentNames,
                 onDelete: key.onDelete,
+                ...(key.enforced === false ? { enforced: false } : {}),
             };
         }));
         const checks = (input.checks ?? []).map((check, checkIndex) => {
@@ -1383,7 +1391,7 @@ export class MinnowDatabase {
                     throw new TypeError(`${tableName} is a view, not a table`);
                 if (options.ifExists === true)
                     return false;
-                throw new Error(`Table not found: ${tableName}`);
+                throw new UnknownTableError(tableName);
             }
             pinnedTableId ??= table.id;
             if (table.id !== pinnedTableId) {
@@ -1513,7 +1521,7 @@ export class MinnowDatabase {
                 }
                 if (options.ifExists === true)
                     return false;
-                throw new Error(`Table not found: ${tableName}`);
+                throw new UnknownTableError(tableName);
             }
             pinnedTableId ??= table.id;
             if (table.id !== pinnedTableId) {
@@ -1596,12 +1604,14 @@ export class MinnowDatabase {
                 : undefined;
             const current = await this.store.getTable(table.id);
             if (current === undefined)
-                throw new TypeError(`Unknown table: ${tableName}`);
+                throw new UnknownTableError(tableName);
             const result = await this.#writeBatch(current, batch, "insert", keys, autoIncrement);
             return { result, batch, generated, autoIncrement, rowCount };
         });
         const { result, batch, generated, autoIncrement, rowCount } = completed;
         collectAutoIncrementGenerated(batch, generated, autoIncrement);
+        if (result.segmentId === null)
+            throw new Error("An insert did not create a segment");
         return {
             tableName: result.tableName,
             segmentId: result.segmentId,
@@ -1655,35 +1665,49 @@ export class MinnowDatabase {
     async insert(tableName, row) {
         return this.insertBatch(tableName, [row]);
     }
-    upsertBatch(tableName, input) {
-        return this.#withWriteReservation(() => this.#upsertBatchReserved(tableName, input));
+    upsertBatch(tableName, input, options = {}) {
+        return this.#withWriteReservation(() => this.#upsertBatchReserved(tableName, input, options));
     }
-    async #upsertBatchReserved(tableName, input) {
+    async #upsertBatchReserved(tableName, input, options) {
         const completed = await this.#runWrite(async () => {
             const table = await this.#findTable(tableName);
             const keyColumn = getUniqueKeyColumn(table);
             if (keyColumn === undefined) {
                 throw new TypeError(`Table needs a unique key before it can be upserted: ${table.name}`);
             }
-            const { batch, generated, autoIncrement, rowCount } = await this.#fillDefaults(table, input);
+            const { batch, generated, autoIncrement } = await this.#fillDefaults(table, input);
             const deferred = autoIncrement !== undefined && autoIncrement.missingIndexes.length > 0;
             const keys = deferred ? undefined : batchKeys(table, batch);
             const current = await this.store.getTable(table.id);
             if (current === undefined)
-                throw new TypeError(`Unknown table: ${tableName}`);
-            const result = await this.#writeBatch(current, batch, "upsert", keys, autoIncrement);
-            return { result, batch, generated, autoIncrement, rowCount };
+                throw new UnknownTableError(tableName);
+            const result = await this.#writeBatch(current, batch, "upsert", keys, autoIncrement, options.conflictWhere);
+            return { result, batch, generated, autoIncrement };
         });
-        const { result, batch, generated, autoIncrement, rowCount } = completed;
+        const { result, batch, generated, autoIncrement } = completed;
         collectAutoIncrementGenerated(batch, generated, autoIncrement);
+        if (result.acceptedRowIndexes.length !== result.requestedRowCount) {
+            for (const [name, values] of generated) {
+                generated.set(name, result.acceptedRowIndexes.map((index) => values[index] ?? null));
+            }
+        }
         return {
-            ...result,
-            rowCount,
+            tableName: result.tableName,
+            segmentId: result.segmentId,
+            requestedRowCount: result.requestedRowCount,
+            rowCount: result.rowCount,
+            insertedRowCount: result.insertedRowCount,
+            updatedRowCount: result.updatedRowCount,
+            skippedRowCount: result.skippedRowCount,
+            blockCount: result.blockCount,
+            storedBytes: result.storedBytes,
+            version: result.version,
+            metrics: result.metrics,
             ...(generated.size === 0 ? {} : { generatedColumns: Object.fromEntries(generated) }),
         };
     }
-    async upsert(tableName, row) {
-        return this.upsertBatch(tableName, [row]);
+    async upsert(tableName, row, options = {}) {
+        return this.upsertBatch(tableName, [row], options);
     }
     updateBatch(tableName, input) {
         return this.#withWriteReservation(() => this.#updateBatchReserved(tableName, input));
@@ -1699,7 +1723,7 @@ export class MinnowDatabase {
             const keys = validateUpdateBatch(table, keyColumn, normalizedInput);
             const current = await this.store.getTable(table.id);
             if (current === undefined)
-                throw new TypeError(`Unknown table: ${tableName}`);
+                throw new UnknownTableError(tableName);
             const currentKey = getUniqueKeyColumn(current);
             if (currentKey?.id !== keyColumn.id) {
                 throw new TypeError(`Table unique key changed during update: ${tableName}`);
@@ -1999,7 +2023,8 @@ export class MinnowDatabase {
                 columnBlockIds[column.id] = blockIds;
             }
             const checks = table.checks ?? [];
-            const changedForeignKey = (table.foreignKeys ?? []).some((key) => foreignKeyColumns(key).some((column) => input.changes[column] !== undefined));
+            const changedForeignKey = (table.foreignKeys ?? []).some((key) => key.enforced !== false &&
+                foreignKeyColumns(key).some((column) => input.changes[column] !== undefined));
             const preImages = await this.#triggerPreImages(table, keyColumn, input.keys.filter((key) => key !== null), "update", (sql, params) => this.#sessionQuery(transaction, sql, { params }), checks.length > 0 ||
                 changedForeignKey ||
                 secondaryIndexUpdateNeedsPreImages(table, input) ||
@@ -2117,12 +2142,13 @@ export class MinnowDatabase {
         }
         throw new Error(`Unique-key lookup returned an inconsistent result: ${table.name}`);
     }
-    async #writeBatch(table, input, kind, keys, autoIncrement) {
+    async #writeBatch(table, input, kind, keys, autoIncrement, conflictWhere) {
         await this.#assertCompactionCapacity(table);
         const started = performance.now();
-        const rowCount = input.columns[table.columns[0]?.name ?? ""]?.length ?? 0;
-        const logicalBytes = estimateBatchBytes(input);
-        const { transaction, rowIds: reservedRowIds, autoIncrementValues, } = await this.#transactions.beginWithReservation({ tableId: table.id, count: rowCount }, autoIncrement === undefined
+        const requestedRowCount = input.columns[table.columns[0]?.name ?? ""]?.length ?? 0;
+        let rowCount = requestedRowCount;
+        let logicalBytes = estimateBatchBytes(input);
+        const { transaction, rowIds: reservedRowIds, autoIncrementValues, } = await this.#transactions.beginWithReservation({ tableId: table.id, count: requestedRowCount }, autoIncrement === undefined
             ? undefined
             : {
                 tableId: table.id,
@@ -2133,11 +2159,14 @@ export class MinnowDatabase {
         transaction.limitLevelZeroSegments(table.id, MAX_LEVEL_ZERO_SEGMENTS);
         const blockStager = new BoundedWriteBlockStager(transaction);
         let resolvedKeys = keys;
-        const segmentId = this.#createId();
+        let segmentId = null;
         const columnBlockIds = {};
         let storedBytes = 0;
         let blockCount = 0;
         let counts;
+        let skippedRowCount = 0;
+        let acceptedRowIndexes = Array.from({ length: requestedRowCount }, (_, index) => index);
+        let upsertFirings;
         let encodeMs = 0;
         let stageMs = 0;
         let commitMs = 0;
@@ -2157,6 +2186,65 @@ export class MinnowDatabase {
                 }
                 resolvedKeys = batchKeys(table, input);
             }
+            const normalizedConflictWhere = kind === "upsert" && conflictWhere !== undefined
+                ? normalizeUpsertConflictWhere(table, conflictWhere)
+                : undefined;
+            const upsertKeyColumn = kind === "upsert" ? getUniqueKeyColumn(table) : undefined;
+            if (upsertKeyColumn !== undefined) {
+                upsertFirings = await this.#upsertTriggerFirings(table, upsertKeyColumn, input, rowCount, (sql, params) => this.#sessionQuery(transaction, sql, { params }), normalizedConflictWhere, normalizedConflictWhere !== undefined);
+            }
+            if (normalizedConflictWhere !== undefined) {
+                if (upsertFirings === undefined) {
+                    throw new Error("Upsert conflict classification is missing");
+                }
+                const classifiedFirings = upsertFirings;
+                acceptedRowIndexes = [...classifiedFirings.inserts, ...classifiedFirings.updates].sort((left, right) => left - right);
+                skippedRowCount = classifiedFirings.skipped.length;
+                input = selectBatchRows(input, acceptedRowIndexes);
+                rowCount = acceptedRowIndexes.length;
+                logicalBytes = estimateBatchBytes(input);
+                resolvedKeys = batchKeys(table, input);
+                counts = {
+                    inserted: classifiedFirings.inserts.length,
+                    updated: classifiedFirings.updates.length,
+                };
+                const acceptedPosition = new Map(acceptedRowIndexes.map((original, position) => [original, position]));
+                upsertFirings = {
+                    inserts: classifiedFirings.inserts.map((index) => acceptedPosition.get(index) ?? -1),
+                    updates: classifiedFirings.updates.map((index) => acceptedPosition.get(index) ?? -1),
+                    skipped: [],
+                    oldImages: acceptedRowIndexes.map((index) => classifiedFirings.oldImages[index]),
+                };
+                if (rowCount === 0) {
+                    await transaction.abort();
+                    const version = transaction.snapshotVersion;
+                    if (version === null)
+                        throw new Error("An existing table has no catalog version");
+                    return {
+                        tableName: table.name,
+                        segmentId: null,
+                        requestedRowCount,
+                        rowCount: 0,
+                        insertedRowCount: 0,
+                        updatedRowCount: 0,
+                        skippedRowCount,
+                        acceptedRowIndexes,
+                        blockCount: 0,
+                        storedBytes: 0,
+                        version,
+                        metrics: createWriteMetrics({
+                            logicalBytes: 0,
+                            storedBytes: 0,
+                            encodeMs: 0,
+                            stageMs: 0,
+                            commitMs: 0,
+                            totalMs: performance.now() - started,
+                            retries: 0,
+                            rows: 0,
+                        }),
+                    };
+                }
+            }
             if (resolvedKeys !== undefined) {
                 transaction.setUniqueKeyChanges({
                     tableId: table.id,
@@ -2169,11 +2257,20 @@ export class MinnowDatabase {
             // generated values are patched also covers an auto-incremented referencing column, and
             // registering this batch's key membership first permits valid self-references.
             await assertForeignKeys();
-            counts =
-                kind === "insert" && resolvedKeys !== undefined
-                    ? { inserted: resolvedKeys.size, updated: 0 }
-                    : await this.#classifyKeys(table, transaction.snapshotVersion, kind, resolvedKeys);
-            const rowIds = reservedRowIds ?? (await this.store.reserveRowIds(table.id, rowCount));
+            if (normalizedConflictWhere === undefined) {
+                counts =
+                    kind === "insert" && resolvedKeys !== undefined
+                        ? { inserted: resolvedKeys.size, updated: 0 }
+                        : await this.#classifyKeys(table, transaction.snapshotVersion, kind, resolvedKeys);
+            }
+            if (counts === undefined)
+                throw new Error("Write classification is missing");
+            const reserved = reservedRowIds ?? (await this.store.reserveRowIds(table.id, rowCount));
+            const rowIds = {
+                start: reserved.start,
+                endExclusive: reserved.start + BigInt(rowCount),
+            };
+            segmentId = this.#createId();
             // Insert batches maintain any active full-text index by tokenizing their own rows into a
             // commit delta. Other mutation kinds emit nothing on purpose: the store's stale-writer
             // rule then flips the index to "invalid" (keyed histories are unindexable) and the scan
@@ -2267,10 +2364,6 @@ export class MinnowDatabase {
             const insertValueAt = (source, column, rowIndex) => (source === "new" ? (input.columns[column]?.[rowIndex] ?? null) : null);
             // Upserts fire per-row: INSERT triggers for fresh keys, UPDATE triggers (with the
             // replaced row as OLD) for conflicting ones — ON CONFLICT DO UPDATE semantics.
-            const upsertKeyColumn = kind === "upsert" ? getUniqueKeyColumn(table) : undefined;
-            const upsertFirings = upsertKeyColumn === undefined
-                ? undefined
-                : await this.#upsertTriggerFirings(table, upsertKeyColumn, input, rowCount);
             stageSecondaryUniqueInsertChanges(transaction, table, input, kind === "upsert" ? upsertFirings?.oldImages : undefined);
             if (kind === "insert") {
                 await this.#stageTriggerDerivedInserts(transaction, table, "insert", rowCount, insertValueAt, "before");
@@ -2304,12 +2397,15 @@ export class MinnowDatabase {
                     return {
                         tableName: table.name,
                         segmentId,
+                        requestedRowCount,
                         rowCount,
                         blockCount,
                         storedBytes,
                         version: manifest.version,
                         insertedRowCount: counts.inserted,
                         updatedRowCount: counts.updated,
+                        skippedRowCount,
+                        acceptedRowIndexes,
                         metrics: createWriteMetrics({
                             logicalBytes,
                             storedBytes,
@@ -2329,7 +2425,7 @@ export class MinnowDatabase {
                     }
                     const stagedDerivations = kind === "insert"
                         ? (table.triggers ?? []).some((trigger) => trigger.event === "insert")
-                        : upsertFirings !== undefined;
+                        : upsertFirings !== undefined || conflictWhere !== undefined;
                     if (stagedDerivations)
                         throw new StaleTriggerDerivationsError(error);
                     retries += 1;
@@ -2383,6 +2479,7 @@ export class MinnowDatabase {
         });
         return externalizeQueryResult({
             columns: columns.map(({ name }) => name),
+            columnDomains: columns.map(({ sqlDomain }) => sqlDomain ?? null),
             rows,
         }).rows;
     }
@@ -2481,6 +2578,7 @@ export class MinnowDatabase {
             let resolvedPlan = plan;
             let ftsStats;
             let outputNeedsExternalization = true;
+            let outputColumnDomains = [];
             const prepareAtSnapshot = async (snapshot, realTables, visibility) => {
                 const typedSchemas = new Map([...realTables.values()].map((table) => [
                     table.name,
@@ -2508,6 +2606,7 @@ export class MinnowDatabase {
                 // columnar forms of derived and windowed sources too, not just the result memo.
                 options.memoize !== false, options.spillToStorage !== false, options.spillToStorage === true, options.spillPageRows);
                 outputNeedsExternalization = queryResultNeedsExternalization(resolvedPlan, typedSchemas);
+                outputColumnDomains = inferResultColumnDomains(resolvedPlan, typedSchemas);
             };
             if (options.version !== undefined) {
                 // Explicit time travel keeps the per-call lease and version-anchored reads.
@@ -2523,6 +2622,7 @@ export class MinnowDatabase {
             return createPreparedColumnarQuery(chooseJoinOrder(resolvedPlan, columnarTables), columnarTables, memory, {
                 ...(ftsStats === undefined ? {} : { ftsStats }),
                 outputNeedsExternalization,
+                outputColumnDomains,
             });
         }
         catch (error) {
@@ -2550,7 +2650,7 @@ export class MinnowDatabase {
                 names.forEach((name, index) => {
                     const table = state.tables[index];
                     if (table === undefined)
-                        throw new Error(`Table not found: ${name}`);
+                        throw new UnknownTableError(name);
                     realTables.set(table.name, table);
                 });
                 const segmentsByTable = new Map();
@@ -2825,7 +2925,11 @@ export class MinnowDatabase {
                     // and the final columnar table hold memory across the fixpoint loop.
                     const iterationMemory = memory.createChild();
                     try {
-                        const frontierTable = derivedColumnarTable(reference, { columns: [...state.columns], rows: state.frontier }, schema);
+                        const frontierTable = derivedColumnarTable(reference, {
+                            columns: [...state.columns],
+                            columnDomains: schema.map(({ sqlDomain }) => sqlDomain ?? null),
+                            rows: state.frontier,
+                        }, schema);
                         state.absorb(await this.#executeBlock(step, snapshot, visibility, iterationMemory, realTables, typedSchemas, new Map([[reference, frontierTable]]), cacheResults, allowSpill, forceSpill, spillPageRows));
                     }
                     finally {
@@ -2833,7 +2937,11 @@ export class MinnowDatabase {
                     }
                 }
                 typedSchemas.set(source.table, schema);
-                inputs.set(source.table, derivedColumnarTable(source.table, { columns: [...state.columns], rows: state.rows }, schema));
+                inputs.set(source.table, derivedColumnarTable(source.table, {
+                    columns: [...state.columns],
+                    columnDomains: schema.map(({ sqlDomain }) => sqlDomain ?? null),
+                    rows: state.rows,
+                }, schema));
                 continue;
             }
             if (source.union !== undefined) {
@@ -2939,7 +3047,7 @@ export class MinnowDatabase {
             }
             const table = realTables.get(source.table);
             if (table === undefined)
-                throw new TypeError(`Unknown table: ${source.table}`);
+                throw new UnknownTableError(source.table);
             const requestedColumns = columns.get(table.name) ?? [];
             inputs.set(table.name, await this.#materializeColumnarTableAtSnapshot(table, snapshot, requestedColumns.length === 0 ? [] : resolveReadColumns(table, requestedColumns), visibility, onlyRealSource));
         }
@@ -3076,6 +3184,7 @@ export class MinnowDatabase {
             cursor.signal.throwIfAborted();
             await cursor.consume({
                 columns: [...result.columns],
+                columnDomains: [...result.columnDomains],
                 rows: result.rows.slice(start, start + cursor.batchRows),
             });
         }
@@ -4013,7 +4122,7 @@ export class MinnowDatabase {
             const tables = proof.records;
             const table = tables.find((record) => record.name === tableName);
             if (table === undefined)
-                throw new TypeError(`Table not found: ${tableName}`);
+                throw new UnknownTableError(tableName);
             if (table.view !== undefined)
                 throw new TypeError(`Cannot create a trigger on view ${tableName}`);
             pinnedTableId ??= table.id;
@@ -4046,7 +4155,7 @@ export class MinnowDatabase {
                 }
                 const target = tables.find((record) => record.name === compiled.table);
                 if (target === undefined)
-                    throw new TypeError(`Table not found: ${compiled.table}`);
+                    throw new UnknownTableError(compiled.table);
                 if (target.view !== undefined) {
                     throw new TypeError(`Trigger bodies cannot write to views: ${compiled.table}`);
                 }
@@ -4124,19 +4233,32 @@ export class MinnowDatabase {
      * in-batch duplicate key fires as an UPDATE of the earlier occurrence. Returns undefined
      * when the table has no insert or update triggers.
      */
-    async #upsertTriggerFirings(table, keyColumn, batch, rowCount, readRows) {
+    async #upsertTriggerFirings(table, keyColumn, batch, rowCount, readRows, conflictWhere, force = false) {
         const fires = (table.triggers ?? []).some((trigger) => trigger.event === "insert" || trigger.event === "update");
-        if (!fires || rowCount === 0)
+        if ((!fires && !force) || rowCount === 0)
             return undefined;
         const quote = (name) => `"${name.replaceAll('"', '""')}"`;
         const keyValues = batch.columns[keyColumn.name] ?? [];
-        const params = keyValues.filter((value) => value !== null);
-        const placeholders = params.map(() => "?").join(", ");
-        const sql = `SELECT * FROM ${quote(table.name)} WHERE ${quote(keyColumn.name)} IN (${placeholders})`;
-        const result = readRows === undefined
-            ? await this.query(sql, { params, memoize: false })
-            : await readRows(sql, params);
-        const byToken = new Map(result.rows.map((row) => {
+        const distinct = new Map();
+        for (const value of keyValues) {
+            if (value !== null)
+                distinct.set(keyToken(keyColumn.type, value), value);
+        }
+        const params = [...distinct.values()];
+        const rows = [];
+        // Each value also contributes a comma token, so the parser's token cap is reached before
+        // its parameter cap. A fixed 1,024-key window stays comfortably inside both limits.
+        const keyWindowSize = Math.min(MAX_SQL_PARAMETERS, 1_024);
+        for (let start = 0; start < params.length; start += keyWindowSize) {
+            const window = params.slice(start, start + keyWindowSize);
+            const placeholders = window.map(() => "?").join(", ");
+            const sql = `SELECT * FROM ${quote(table.name)} WHERE ${quote(keyColumn.name)} IN (${placeholders})`;
+            const result = readRows === undefined
+                ? await this.query(sql, { params: window, memoize: false })
+                : await readRows(sql, window);
+            rows.push(...result.rows);
+        }
+        const byToken = new Map(rows.map((row) => {
             const key = row[keyColumn.name];
             return [
                 key === null || key === undefined ? "" : keyToken(keyColumn.type, key),
@@ -4145,29 +4267,36 @@ export class MinnowDatabase {
         }));
         const inserts = [];
         const updates = [];
+        const skipped = [];
         const oldImages = [];
-        const seenInBatch = new Map();
+        const currentByToken = new Map(byToken);
         for (let rowIndex = 0; rowIndex < rowCount; rowIndex += 1) {
             const key = keyValues[rowIndex] ?? null;
             const token = key === null ? "" : keyToken(keyColumn.type, key);
-            const earlier = seenInBatch.get(token);
-            const old = earlier === undefined
-                ? byToken.get(token)
-                : Object.fromEntries(table.columns.map((column) => [
-                    column.name,
-                    batch.columns[column.name]?.[earlier] ?? null,
-                ]));
+            const old = currentByToken.get(token);
             if (old === undefined) {
                 inserts.push(rowIndex);
                 oldImages.push(undefined);
             }
             else {
-                updates.push(rowIndex);
                 oldImages.push(old);
+                const rawLeft = conflictWhere === undefined ? null : (old[conflictWhere.column.name] ?? null);
+                const left = conflictWhere?.column.sqlDomain === undefined
+                    ? rawLeft
+                    : normalizeSqlDomainValue(conflictWhere.column.sqlDomain, rawLeft);
+                if (conflictWhere !== undefined &&
+                    !comparisonHolds(conflictWhere.operator, left, conflictWhere.value)) {
+                    skipped.push(rowIndex);
+                    continue;
+                }
+                updates.push(rowIndex);
             }
-            seenInBatch.set(token, rowIndex);
+            currentByToken.set(token, Object.fromEntries(table.columns.map((column) => [
+                column.name,
+                batch.columns[column.name]?.[rowIndex] ?? null,
+            ])));
         }
-        return { inserts, updates, oldImages };
+        return { inserts, updates, skipped, oldImages };
     }
     /** Fires INSERT and UPDATE triggers for one upsert batch at one timing, per the plan. */
     async #stageUpsertTriggerFirings(transaction, table, batch, firings, timing, cascadeBudget = 1) {
@@ -4826,7 +4955,8 @@ export class MinnowDatabase {
             await this.#assertKeysExist(table, keyColumn, transaction.snapshotVersion, committedKeys);
         }
         const sessionChecks = table.checks ?? [];
-        const changedForeignKey = (table.foreignKeys ?? []).some((key) => foreignKeyColumns(key).some((column) => input.changes[column] !== undefined));
+        const changedForeignKey = (table.foreignKeys ?? []).some((key) => key.enforced !== false &&
+            foreignKeyColumns(key).some((column) => input.changes[column] !== undefined));
         const preImages = await this.#triggerPreImages(table, keyColumn, input.keys.filter((key) => key !== null), "update", (preImageSql, params) => this.#sessionQuery(transaction, preImageSql, { params }), sessionChecks.length > 0 ||
             changedForeignKey ||
             secondaryIndexUpdateNeedsPreImages(table, input) ||
@@ -5389,7 +5519,12 @@ export class MinnowDatabase {
             // The remaining metadata-only steps share one catalog/manifest CAS. Physical drops ran
             // above because segment rewriting and payload retirement have a stronger atomic boundary.
             const columns = applyColumnSteps(record, steps, this.#createId);
-            if (JSON.stringify(columns) === JSON.stringify(record.columns)) {
+            const foreignKeyStep = steps.find((step) => step.kind === "alter-foreign-keys");
+            const foreignKeys = foreignKeyStep?.kind === "alter-foreign-keys"
+                ? foreignKeyStep.foreignKeys.map((key) => ({ ...key }))
+                : record.foreignKeys;
+            if (JSON.stringify(columns) === JSON.stringify(record.columns) &&
+                JSON.stringify(foreignKeys ?? []) === JSON.stringify(record.foreignKeys ?? [])) {
                 if (changed)
                     alteredTables.push(tableName);
                 continue;
@@ -5400,6 +5535,7 @@ export class MinnowDatabase {
             assertDependentViewsKeepSchema(proof.records, record, candidateSchemas);
             const updated = await this.store.updateTable(record.id, record.revision, {
                 columns,
+                ...(foreignKeyStep === undefined ? {} : { foreignKeys }),
                 ...(autoIncrementSeed === undefined ? {} : { autoIncrementSeed }),
                 expectedManifestVersion: { value: proof.manifestVersion },
                 expectedCatalogEpoch: proof.catalogEpoch,
@@ -5533,6 +5669,8 @@ export class MinnowDatabase {
      */
     async #assertForeignKeysPresent(table, rowsByColumn, read, transaction) {
         for (const key of table.foreignKeys ?? []) {
+            if (key.enforced === false)
+                continue;
             const childNames = foreignKeyColumns(key);
             const parentNames = foreignKeyParentColumns(key);
             if (childNames.length > 1) {
@@ -5671,7 +5809,7 @@ export class MinnowDatabase {
     async #applyReferentialActions(parent, keys, session, cascadeBudget) {
         if (keys.length === 0)
             return;
-        const children = await this.#childForeignKeys(parent.name);
+        const children = (await this.#childForeignKeys(parent.name)).filter(({ key }) => key.enforced !== false);
         if (children.length === 0)
             return;
         if (cascadeBudget < 0) {
@@ -6055,7 +6193,12 @@ export class MinnowDatabase {
                     return value;
                 });
                 const selected = await transaction.query(`SELECT * FROM ${quoteSqlIdentifier(table.name)} WHERE ${quoteSqlIdentifier(keyColumn.name)} IN (${keys.map(() => "?").join(", ")})`, { params: keys });
-                const currentByKey = new Map(selected.rows.map((row) => [keyToken(row[keyColumn.name] ?? null), row]));
+                const currentByKey = new Map(selected.rows.map((row) => {
+                    const value = keyColumn.hidden
+                        ? compositeKeyValue(primaryKeyColumns(table), primaryKeyColumns(table).map(({ name }) => row[name] ?? null))
+                        : (row[keyColumn.name] ?? null);
+                    return [keyToken(value), row];
+                }));
                 const updateKeys = [];
                 const changes = Object.fromEntries(assignments.map(({ column }) => [column, []]));
                 for (const [position, rowIndex] of conflictingRows.entries()) {
@@ -6457,7 +6600,11 @@ export class MinnowDatabase {
                     const stageRows = async (rows) => {
                         if (rows.length === 0)
                             return;
-                        const batchResult = { columns: tableColumns.map(({ name }) => name), rows: [...rows] };
+                        const batchResult = {
+                            columns: tableColumns.map(({ name }) => name),
+                            columnDomains: tableColumns.map(({ sqlDomain }) => sqlDomain ?? null),
+                            rows: [...rows],
+                        };
                         if (queryResultRetainedBytes(batchResult) > executionMemoryBudgetBytes) {
                             throw new QueryMemoryBudgetError("CREATE TABLE AS result batch", queryResultRetainedBytes(batchResult), 0, executionMemoryBudgetBytes);
                         }
@@ -6592,7 +6739,7 @@ export class MinnowDatabase {
                     }
                     const record = proof.records.find((candidate) => candidate.name === addColumnStatement.table);
                     if (record === undefined)
-                        throw new TypeError(`Unknown table: ${addColumnStatement.table}`);
+                        throw new UnknownTableError(addColumnStatement.table);
                     if (record.view !== undefined)
                         throw new TypeError(`${addColumnStatement.table} is a view, not a table`);
                     pinnedTableId ??= record.id;
@@ -7092,7 +7239,7 @@ export class MinnowDatabase {
             plan = chooseJoinOrder(plan, rowCounts);
         const baseTable = tables.find((table) => table.name === plan.base.table);
         if (baseTable === undefined)
-            throw new TypeError(`Unknown table: ${plan.base.table}`);
+            throw new UnknownTableError(plan.base.table);
         const requestedBaseColumns = columns.get(baseTable.name) ?? [];
         const projectedBaseColumns = requestedBaseColumns.length === 0 ? [] : resolveReadColumns(baseTable, requestedBaseColumns);
         if (secondaryIndexOrderForPlan(plan, baseTable, projectedBaseColumns, false) !== undefined) {
@@ -7165,6 +7312,7 @@ export class MinnowDatabase {
                     prepared = createPreparedColumnarQuery(plan, inputTables, memory, {
                         ...(ftsStats === undefined ? {} : { ftsStats }),
                         outputNeedsExternalization: queryResultNeedsExternalization(plan, typedSchemas),
+                        outputColumnDomains: inferResultColumnDomains(plan, typedSchemas),
                     });
                     if (cursor !== undefined) {
                         const emission = { happened: false };
@@ -7177,10 +7325,18 @@ export class MinnowDatabase {
                             await cursor.consume(externalizeQueryResult(batch));
                         });
                         if (!emission.happened) {
-                            await cursor.consume({ columns: [...columns], rows: [] });
+                            await cursor.consume({
+                                columns: [...columns],
+                                columnDomains: inferResultColumnDomains(plan, typedSchemas),
+                                rows: [],
+                            });
                         }
                         options.onStats?.({ peakMemoryBytes: memory.usage.peakBytes });
-                        return { columns: [...columns], rows: [] };
+                        return {
+                            columns: [...columns],
+                            columnDomains: inferResultColumnDomains(plan, typedSchemas),
+                            rows: [],
+                        };
                     }
                     if (!attempt.spill) {
                         try {
@@ -7534,7 +7690,8 @@ export class MinnowDatabase {
             const rows = startRow > 0 || limit !== undefined
                 ? combined.slice(startRow, limit === undefined ? undefined : startRow + limit)
                 : combined;
-            return { columns: plan.select.map((item) => item.alias), rows };
+            const columns = plan.select.map((item) => item.alias);
+            return { columns, columnDomains: unknownColumnDomains(columns), rows };
         }
         finally {
             root.close();
@@ -8395,6 +8552,7 @@ export class MinnowDatabase {
         let writtenBytes = 0;
         let batchBytes = 0;
         let metadataBatchBytes = 0;
+        let batchBlockCount = 0;
         const batch = [];
         const flush = async () => {
             if (batch.length === 0 || identity === undefined)
@@ -8410,6 +8568,7 @@ export class MinnowDatabase {
             });
             batchBytes = 0;
             metadataBatchBytes = 0;
+            batchBlockCount = 0;
             writtenBytes = session.stagedBytes;
             options.onProgress?.({ phase: "blocks", writtenBytes, totalBytes });
         };
@@ -8439,6 +8598,7 @@ export class MinnowDatabase {
                     if (batch.length > 0 &&
                         (batch.length >= MAX_SNAPSHOT_FRAME_BATCH_ITEMS ||
                             batchBytes + entry.frame.payload.byteLength > MAX_SNAPSHOT_FRAME_BATCH_BYTES ||
+                            (entry.frame.kind === "block" && batchBlockCount > 0) ||
                             (entry.frame.kind !== "block" &&
                                 metadataBatchBytes + entry.frame.payload.byteLength >
                                     MAX_SNAPSHOT_METADATA_BATCH_BYTES))) {
@@ -8449,6 +8609,9 @@ export class MinnowDatabase {
                     if (entry.frame.kind !== "block") {
                         metadataBatchBytes = safeWholeNumberSum([metadataBatchBytes, entry.frame.payload.byteLength], "Snapshot import metadata batch bytes");
                     }
+                    else {
+                        batchBlockCount += 1;
+                    }
                     continue;
                 }
                 if (identity === undefined)
@@ -11525,7 +11688,7 @@ export class MinnowDatabase {
         }
         const table = tables.find((candidate) => candidate.name === tableName);
         if (table === undefined || table.view !== undefined) {
-            throw new TypeError(`Unknown table: ${tableName}`);
+            throw new UnknownTableError(tableName);
         }
         if (indexColumns.length === 0)
             throw new TypeError("An index needs at least one column");
@@ -13733,7 +13896,7 @@ export class MinnowDatabase {
         validateName(name, "Table");
         const table = await this.store.getTableByName(name);
         if (table === undefined)
-            throw new Error(`Table not found: ${name}`);
+            throw new UnknownTableError(name);
         // Reads resolve a view into its query before reaching here, so a view arriving at this
         // point is a write, a DDL statement, or a path that forgot to rewrite: all of them errors.
         if (table.view !== undefined)
@@ -14989,32 +15152,72 @@ function compositeKeyValue(columns, values) {
 /** Canonicalizes logical PostgreSQL domains before validation and primitive block encoding. */
 function normalizeDomainBatch(table, input) {
     for (const column of table.columns) {
-        const domain = column.sqlDomain;
-        if (domain === undefined)
-            continue;
         const values = input.columns[column.name];
         if (values === undefined)
             continue;
-        input.columns[column.name] = values.map((value) => normalizeSqlDomainValue(domain, value));
+        if (column.sqlDomain !== undefined || column.type === "datetime") {
+            input.columns[column.name] = values.map((value) => normalizeColumnLogicalValue(column, value));
+        }
+    }
+}
+function normalizeColumnLogicalValue(column, value) {
+    if (column.sqlDomain !== undefined)
+        return normalizeSqlDomainValue(column.sqlDomain, value);
+    if (column.type === "datetime" && isDateDomainValue(value)) {
+        const external = externalSqlDomainValue(value);
+        if (typeof external !== "string")
+            throw new TypeError("Invalid DATE value");
+        return new Date(`${external}T00:00:00.000Z`);
     }
+    return value;
+}
+function selectBatchRows(input, indexes) {
+    return {
+        columns: Object.fromEntries(Object.entries(input.columns).map(([name, values]) => [
+            name,
+            indexes.map((index) => values[index] ?? null),
+        ])),
+        ...(input.omitted === undefined
+            ? {}
+            : {
+                omitted: Object.fromEntries(Object.entries(input.omitted).map(([name, values]) => [
+                    name,
+                    indexes.map((index) => values[index] ?? false),
+                ])),
+            }),
+        rowCount: indexes.length,
+    };
+}
+function normalizeUpsertConflictWhere(table, predicate) {
+    const operators = ["=", "!=", "<>", ">", ">=", "<", "<="];
+    if (!operators.includes(predicate.operator)) {
+        throw new TypeError(`Unsupported upsert conflict operator: ${predicate.operator}`);
+    }
+    const column = visibleTableColumns(table).find(({ name }) => name === predicate.column);
+    if (column === undefined) {
+        throw new TypeError(`Unknown upsert conflict column: ${table.name}.${predicate.column}`);
+    }
+    const value = normalizeColumnLogicalValue(column, predicate.value);
+    if (value !== null)
+        validateValue({ ...column, nullable: true }, value, 0);
+    return { column, operator: predicate.operator, value };
 }
 function normalizeDomainUpdate(table, input) {
-    if (!table.columns.some((column) => column.sqlDomain !== undefined))
+    if (!table.columns.some((column) => column.sqlDomain !== undefined || column.type === "datetime"))
         return input;
     let changed = false;
     const changes = { ...input.changes };
     for (const [name, values] of Object.entries(input.changes)) {
-        const domain = table.columns.find((column) => column.name === name)?.sqlDomain;
-        if (domain === undefined)
+        const column = table.columns.find((candidate) => candidate.name === name);
+        if (column === undefined || (column.sqlDomain === undefined && column.type !== "datetime"))
             continue;
         changed = true;
-        changes[name] = values.map((value) => normalizeSqlDomainValue(domain, value));
+        changes[name] = values.map((value) => normalizeColumnLogicalValue(column, value));
     }
     const key = getUniqueKeyColumn(table);
-    const keyDomain = key?.sqlDomain;
-    const keys = keyDomain === undefined
+    const keys = key === undefined || (key.sqlDomain === undefined && key.type !== "datetime")
         ? input.keys
-        : input.keys.map((value) => normalizeSqlDomainValue(keyDomain, value));
+        : input.keys.map((value) => normalizeColumnLogicalValue(key, value));
     return changed || keys !== input.keys ? { keys, changes } : input;
 }
 /** Coerces literals and bound parameters opposite a domain column before planning/index probes. */
@@ -16227,6 +16430,17 @@ function columnVectorKeyToken(type, vector, row) {
     }
     throw new Error("Column vector type mismatch");
 }
+function normalizedDatetimeLiteral(value) {
+    if (value instanceof Date)
+        return Number.isFinite(dateMilliseconds(value)) ? value : undefined;
+    if (!isDateDomainValue(value))
+        return undefined;
+    const external = externalSqlDomainValue(value);
+    if (typeof external !== "string")
+        return undefined;
+    const date = new Date(`${external}T00:00:00.000Z`);
+    return Number.isFinite(dateMilliseconds(date)) ? date : undefined;
+}
 function zonePredicates(plan, table) {
     if (plan.joins.length > 0 || plan.base.table !== table.name)
         return [];
@@ -16245,10 +16459,11 @@ function zonePredicates(plan, table) {
     const literalValue = (column, expression) => {
         if (expression.kind !== "literal")
             return undefined;
+        const datetime = column.type === "datetime" ? normalizedDatetimeLiteral(expression.value) : undefined;
         const value = column.type === "datetime"
-            ? expression.value instanceof Date
-                ? dateMilliseconds(expression.value)
-                : undefined
+            ? datetime === undefined
+                ? undefined
+                : dateMilliseconds(datetime)
             : typeof expression.value === "number"
                 ? expression.value
                 : undefined;
@@ -16291,10 +16506,11 @@ function zonePredicates(plan, table) {
         const column = leftColumn ?? rightColumn;
         if (column === undefined || literal.kind !== "literal")
             continue;
+        const datetime = column.type === "datetime" ? normalizedDatetimeLiteral(literal.value) : undefined;
         const value = column.type === "datetime"
-            ? literal.value instanceof Date
-                ? dateMilliseconds(literal.value)
-                : undefined
+            ? datetime === undefined
+                ? undefined
+                : dateMilliseconds(datetime)
             : typeof literal.value === "number"
                 ? literal.value
                 : undefined;
@@ -16324,9 +16540,16 @@ function secondaryIndexPredicates(plan, table) {
     const literalValue = (column, expression) => {
         if (expression.kind !== "literal" || expression.value === null)
             return undefined;
+        let value = expression.value;
+        if (column.type === "datetime" && isDateDomainValue(value)) {
+            const datetime = normalizedDatetimeLiteral(value);
+            if (datetime === undefined)
+                return undefined;
+            value = datetime;
+        }
         try {
-            secondaryIndexTerm(column.type, expression.value);
-            return expression.value;
+            secondaryIndexTerm(column.type, value);
+            return value;
         }
         catch {
             return undefined;