uql-orm 0.80.0 → 0.81.0

package/dist/migrate/introspection/postgresIntrospector.js

@@ -1,4 +1,5 @@
 import { INDEX_TYPES } from '../../schema/types.js';
+import { isVectorIndexType } from '../../type/vector.js';
 import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
 /**
  * PostgreSQL schema introspector
@@ -15,15 +16,15 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         'opsClass',
         'accessMethod',
         'include',
+        'distance',
     ]);
     triggersQuery() {
         return /*sql*/ `
-      SELECT c.relname AS "table", t.tgname AS name, pg_get_triggerdef(t.oid) AS definition,
-        pg_get_functiondef(t.tgfoid) AS requires
+      SELECT t.tgname AS name, pg_get_triggerdef(t.oid) AS definition, pg_get_functiondef(t.tgfoid) AS requires
       FROM pg_trigger t
       JOIN pg_class c ON c.oid = t.tgrelid
       JOIN pg_namespace n ON n.oid = c.relnamespace
-      WHERE NOT t.tgisinternal AND n.nspname = ${this.schemaExpr}
+      WHERE NOT t.tgisinternal AND n.nspname = ${this.schemaExpr} AND c.relname = ${this.dialect.placeholder(1)}
     `;
     }
     getTableNamesQuery() {
@@ -54,7 +55,11 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
      * database scans meet that table every time something else is migrating.
      *
      * `attgenerated` rather than `is_generated`, which cannot part a stored generated column from the
-     * virtual one Postgres 18 added and uql never declares. CockroachDB states it too.
+     * virtual one Postgres 18 added and uql never declares. CockroachDB states it too. `format_type` for an
+     * extension type's modifier, which `information_schema` drops: a `vector(256)` read back as `vector`.
+     * CockroachDB names that type `vector` where Postgres says `USER-DEFINED`.
+     *
+     * A column is unique by a unique index over it alone, a constraint's or its own, as every engine reads it.
      */
     getColumnsQuery(_tableName) {
         return /*sql*/ `
@@ -69,11 +74,9 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         c.numeric_scale,
         c.is_identity,
         c.identity_generation,
-        CASE WHEN (
-          SELECT a.attgenerated FROM pg_catalog.pg_attribute a
-          WHERE a.attrelid = to_regclass(quote_ident(c.table_schema) || '.' || quote_ident(c.table_name))
-            AND a.attname = c.column_name
-        ) = 's' THEN c.generation_expression END AS generated_as,
+        CASE WHEN a.attgenerated = 's' THEN c.generation_expression END AS generated_as,
+        CASE WHEN c.data_type IN ('USER-DEFINED', 'vector') AND a.atttypmod > -1
+          THEN format_type(a.atttypid, a.atttypmod) END AS formatted_type,
         EXISTS (
           SELECT 1 FROM information_schema.table_constraints tc
           JOIN information_schema.key_column_usage kcu USING (constraint_schema, constraint_name)
@@ -83,19 +86,19 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             AND kcu.column_name = c.column_name
         ) AS is_primary_key,
         EXISTS (
-          SELECT 1 FROM information_schema.table_constraints tc
-          JOIN information_schema.key_column_usage kcu USING (constraint_schema, constraint_name)
-          WHERE tc.table_schema = c.table_schema
-            AND tc.table_name = c.table_name
-            AND tc.constraint_type = 'UNIQUE'
-          GROUP BY tc.constraint_name
-          HAVING COUNT(*) = 1 AND MIN(kcu.column_name) = c.column_name
+          SELECT 1 FROM pg_catalog.pg_index ix
+          WHERE ix.indrelid = a.attrelid AND ix.indisunique AND NOT ix.indisprimary
+            AND ix.indnkeyatts = 1 AND ix.indkey[0] = a.attnum
+            AND ix.indpred IS NULL AND ix.indexprs IS NULL
         ) AS is_unique,
         pg_catalog.col_description(
           to_regclass(quote_ident(c.table_schema) || '.' || quote_ident(c.table_name)),
           c.ordinal_position
         ) AS column_comment
       FROM information_schema.columns c
+      LEFT JOIN pg_catalog.pg_attribute a
+        ON a.attrelid = to_regclass(quote_ident(c.table_schema) || '.' || quote_ident(c.table_name))
+        AND a.attname = c.column_name
       WHERE c.table_schema = ${this.schemaExpr}
         AND c.table_name = $1
       ORDER BY c.ordinal_position
@@ -108,23 +111,23 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
      * while `pg_get_indexdef` reprints an identifier *quoted*, so a camelCase column came back as
      * `"tenantId"` and matched no column of the table. Prisma and drizzle-kit both split it this way.
      *
-     * Indexes backing a constraint are left out, primary keys among them: `@Field({ unique })` emits a
-     * `UNIQUE` constraint and no index, so reporting the index Postgres builds underneath it told every
-     * project it had an index its entities never asked for.
+     * The key's index and an `EXCLUDE`'s are left out. A `UNIQUE` constraint's index stays, as SQL Server
+     * and the MySQL family report theirs: the diff reads one over a single column as that column's
+     * uniqueness, and one over several as the unique `@Index` it is.
      */
     getIndexesQuery(_tableName) {
         return /*sql*/ `
       SELECT
         i.relname AS index_name,
         ix.indisunique AS is_unique,
-        am.amname AS method,
+        ${this.indexMethodSql} AS method,
         pg_get_expr(ix.indpred, ix.indrelid, true) AS predicate,
         k.n <= ix.indnkeyatts AS is_key,
         k.attnum = 0 AS is_expression,
         COALESCE(a.attname::text, pg_get_indexdef(ix.indexrelid, k.n::int, true)) AS entry,
         (ix.indoption[k.n - 1] & 1) <> 0 AS descending,
-        (ix.indoption[k.n - 1] & 2) <> 0 AS nulls_first,
-        CASE WHEN op.opcdefault THEN NULL ELSE op.opcname END AS ops_class
+        ${this.nullsFirstSql} AS nulls_first,
+        ${this.opsClassSql} AS ops_class
       FROM pg_class t
       JOIN pg_index ix ON t.oid = ix.indrelid
       JOIN pg_class i ON i.oid = ix.indexrelid
@@ -137,22 +140,17 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         AND n.nspname = ${this.schemaExpr}
         AND NOT ix.indisprimary
         AND NOT EXISTS (
-          SELECT 1 FROM pg_constraint con
-          WHERE con.conindid = ix.indexrelid
-            AND con.contype IN (${this.constraintIndexTypes.map((type) => `'${type}'`).join(', ')})
+          SELECT 1 FROM pg_constraint con WHERE con.conindid = ix.indexrelid AND con.contype = 'x'
         )
       ORDER BY i.relname, k.n
     `;
     }
-    /**
-     * Constraint kinds whose backing index is the constraint itself rather than an index anyone asked
-     * for. Postgres builds one for `PRIMARY KEY`, `UNIQUE` and `EXCLUDE`, and only for those: a plain
-     * `CREATE UNIQUE INDEX` has no `pg_constraint` row at all, so it survives.
-     *
-     * Nothing to do with {@link indexFacets}, which says which *attributes* of an index diffing may
-     * compare. This one decides which indexes are reported at all.
-     */
-    constraintIndexTypes = ['p', 'u', 'x'];
+    /** Whether an entry sorts nulls first, which Postgres states on every entry. */
+    nullsFirstSql = '(ix.indoption[k.n - 1] & 2) <> 0';
+    /** An index's access method, which is the type it declares. */
+    indexMethodSql = 'am.amname';
+    /** An entry's operator class, where it is not the default for its type. */
+    opsClassSql = 'CASE WHEN op.opcdefault THEN NULL ELSE op.opcname END';
     /** From `pg_constraint`, whose key arrays keep each column paired with the one it references. */
     getForeignKeysQuery(_tableName) {
         const columnsOf = (keys, table) => /*sql*/ `ARRAY_TO_JSON(ARRAY(
@@ -194,7 +192,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.column_name,
-            type: this.normalizeType(row.data_type, row.udt_name),
+            type: row.formatted_type?.toUpperCase() ?? this.normalizeType(row.data_type, row.udt_name),
             nullable: row.is_nullable === 'YES',
             defaultValue: this.parseDefaultValue(row.column_default),
             isPrimaryKey: row.is_primary_key,
@@ -207,11 +205,25 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             generatedAs: row.generated_as ?? undefined,
         }));
     }
+    /**
+     * A vector index keeps its distance as its vector column's operator class, `{type}_{metric}_ops`, which
+     * is how `PgIndexDdl` writes the entity's `distance`; read back as that `distance`, so the two compare.
+     * No class named is the engine's default, L2.
+     */
+    withVectorDistance(index) {
+        if (!isVectorIndexType(index.type)) {
+            return index;
+        }
+        const opsClass = index.entries.find((entry) => entry.opsClass)?.opsClass;
+        const distance = this.dialect.indexedDistance(opsClass ? /_([a-z0-9]+)_ops$/.exec(opsClass)?.[1] : 'l2');
+        const entries = index.entries.map(({ opsClass: _opsClass, ...entry }) => entry);
+        return distance ? { ...index, distance, entries } : index;
+    }
     async mapIndexesResult(_read, _tableName, results) {
         // One row per index entry, ordered by position, so the rows of an index are its entries in order.
         return [...Map.groupBy(results, (row) => row.index_name)].map(([name, rows]) => {
             const include = rows.filter((row) => !row.is_key).map((row) => row.entry);
-            return {
+            return this.withVectorDistance({
                 name,
                 entries: rows.filter((row) => row.is_key).map(mapIndexEntry),
                 unique: rows[0].is_unique,
@@ -219,7 +231,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
                 where: rows[0].predicate ?? undefined,
                 include: include.length > 0 ? include : undefined,
                 ...fulltextIndex(rows),
-            };
+            });
         });
     }
     async mapForeignKeysResult(_read, _tableName, results) {
@@ -315,7 +327,7 @@ function mapIndexEntry(row) {
         column: row.entry,
         ...(row.is_expression && { expression: true }),
         order: row.descending ? 'desc' : 'asc',
-        nulls: row.nulls_first ? 'first' : 'last',
+        ...(row.nulls_first !== null && { nulls: row.nulls_first ? 'first' : 'last' }),
         ...(row.ops_class && { opsClass: row.ops_class }),
     };
 }
@@ -323,16 +335,21 @@ function mapIndexEntry(row) {
  * CockroachDB answers the same catalogue queries and differs only in what it can express: v26.2.5
  * still rejects `NULLS FIRST/LAST` and operator classes as "unimplemented", and it sorts nulls first
  * on an ASC column where Postgres sorts them last. Reading a nulls order back would therefore report
- * every ascending index as drifted, against an entity that could not have asked for one. Its access
- * method, `prefix`, needs nothing: a method that is not a known index type is reported as no type.
+ * every ascending index as drifted, against an entity that could not have asked for one.
  */
 export class CockroachSchemaIntrospector extends PostgresSchemaIntrospector {
-    indexFacets = new Set(['order', 'include']);
+    indexFacets = new Set([
+        'order',
+        'include',
+        'vector',
+        'distance',
+    ]);
+    /** None: it rejects a stated nulls order, so reading one back gives an index it would refuse to rebuild. */
+    nullsFirstSql = 'NULL::BOOL';
     /**
-     * `'u'` is missing on purpose. CockroachDB registers a `UNIQUE` constraint for a plain `CREATE
-     * UNIQUE INDEX` too, naming it after the index, so filtering on it would hide every unique index a
-     * user asked for and report it missing forever. It leaves no way to tell the two apart, so the
-     * index a `@Field({ unique })` builds underneath itself stays visible there.
+     * Every index reports the access method `prefix` and no operator class, so a vector index is read off
+     * its definition, `USING cspann (vec vector_cosine_ops)`: its type, and its last key's class.
      */
-    constraintIndexTypes = ['p', 'x'];
+    indexMethodSql = `CASE WHEN pg_get_indexdef(ix.indexrelid) LIKE '% USING cspann %' THEN 'vector' ELSE am.amname END`;
+    opsClassSql = `CASE WHEN k.n = ix.indnkeyatts THEN substring(pg_get_indexdef(ix.indexrelid) from '(\\w+_ops)\\)') END`;
 }

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -5,10 +5,10 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  */
 export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     /** Whether an index is libSQL's vector index, where the engine has one; elsewhere a declared one is built plain. */
-    indexFacets = new Set(this.dialect.hasVectorIndex() ? ['vector'] : []);
+    indexFacets = new Set(this.dialect.hasVectorIndex() ? ['vector', 'distance'] : []);
     /** Not SQLite's own tables, nor the ones libSQL keeps a vector index in: its metadata and `<index>_shadow`. */
     triggersQuery() {
-        return /*sql*/ `SELECT tbl_name AS \`table\`, name, sql AS definition FROM sqlite_master WHERE type = 'trigger'`;
+        return /*sql*/ `SELECT name, sql AS definition FROM sqlite_master WHERE type = 'trigger' AND tbl_name = ?`;
     }
     getTableNamesQuery() {
         return /*sql*/ `
@@ -89,15 +89,12 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         const indexSchemas = [];
         for (const index of results) {
             const columns = await this.getIndexColumns(read, index.name);
-            // Include user-created indexes ('c') and multi-column unique constraints ('u')
-            // Skip primary key indexes ('pk') and single-column unique constraints
-            const isUserCreated = index.origin === 'c';
-            const isCompositeUnique = index.origin === 'u' && columns.length > 1;
+            // A unique constraint's index ('u') is reported as every engine reports it, and only the key's ('pk') left out.
             // `PRAGMA index_info` names an expression entry `null` (its `cid` is -2), and the expression text
             // lives only in `sqlite_master.sql`. Reporting `{ column: null }` put a column literally named
             // `null` into the diff, so an index UQL cannot describe is left out, libSQL's vector index aside.
             const named = columns.filter((column) => column.name !== null);
-            if (!isUserCreated && !isCompositeUnique) {
+            if (index.origin === 'pk') {
                 continue;
             }
             if (named.length === columns.length) {
@@ -171,8 +168,13 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             return undefined;
         }
         const metric = row.sql?.match(/'metric=(\w+)'/i)?.[1]?.toLowerCase();
-        const distances = new Map([...this.dialect.vectorMetrics].map(([distance, { index }]) => [index, distance]));
-        return { name: indexName, entries: [{ column }], unique: false, type: 'vector', distance: distances.get(metric) };
+        return {
+            name: indexName,
+            entries: [{ column }],
+            unique: false,
+            type: 'vector',
+            distance: this.dialect.indexedDistance(metric),
+        };
     }
     /** The statement that created the table, which is where SQLite keeps every expression it was given. */
     async getTableDdl(read, tableName) {

package/dist/migrate/migrator.d.ts

@@ -128,6 +128,11 @@ export declare class Migrator {
      * never asks for the rollback, which on SQLite cannot even be expressed (no `ALTER COLUMN`).
      */
     private pendingChanges;
+    /**
+     * Safe mode only adds: a change with a `from` drops or rebuilds what the table holds, so it is held,
+     * and so is a key whole, which rebuilds an index over every row and fails where a column holds a null.
+     * Without `drop`, a column's drop is held too.
+     */
     protected filterDiff(diff: SchemaDiff, options: {
         safe?: boolean;
         drop?: boolean;

package/dist/migrate/migrator.js

@@ -8,6 +8,7 @@ import { LoggerWrapper } from '../util/index.js';
 import { buildMigrationModule } from './codegen/migrationFile.js';
 import { introspectorFor } from './introspection/registry.js';
 import { migrationBuilderFor, migrationTargetFor } from './migrationTarget.js';
+import { dropped, nonEmpty, reverseDiff, sides } from './schemaChange.js';
 /**
  * Main class for managing database migrations
  */
@@ -215,17 +216,10 @@ export class Migrator {
         // Tables this plan creates are left out: their `CREATE` carries their triggers, and asking the
         // catalogue about a table that is not there yet fails outright on some engines.
         const wanted = entities.filter((entity) => !fresh.has(this.tableOf(entity)));
-        const bySchema = new Map();
         const state = [];
         for (const entity of wanted) {
             const meta = getMeta(entity);
-            const schema = dialect.resolveSchema(meta);
-            let owned = bySchema.get(schema);
-            if (!owned) {
-                owned = await this.schemaIntrospectorFor(schema).ownedTriggers();
-                bySchema.set(schema, owned);
-            }
-            const installed = owned.get(dialect.resolveTableAlias(meta)) ?? new Map();
+            const installed = await this.schemaIntrospectorFor(dialect.resolveSchema(meta)).ownedTriggers(dialect.resolveTableAlias(meta));
             // An installed trigger alone keeps it: an entity that stopped declaring one has it to drop.
             if (installed.size || hasTriggers(meta)) {
                 state.push({ entity, installed });
@@ -239,7 +233,7 @@ export class Migrator {
      * its entity declares goes back on after. `down` is lazy: SQLite cannot express every alter's inverse.
      */
     alterPlan(generator, altered, state) {
-        const changing = new Set(altered.filter((diff) => diff.columnsToAlter?.length || diff.columnsToDrop?.length).map((diff) => diff.tableName));
+        const changing = new Set(altered.filter((diff) => sides(diff.columns, 'from').length).map((diff) => diff.tableName));
         const cleared = state.filter(({ entity }) => changing.has(this.tableOf(entity)));
         const after = state.map((it) => (cleared.includes(it) ? { entity: it.entity, installed: new Map() } : it));
         return {
@@ -250,7 +244,7 @@ export class Migrator {
             ],
             down: () => [
                 ...this.revertedTriggers(generator, after),
-                ...altered.toReversed().flatMap((diff) => generator.generateAlterTableDown(diff)),
+                ...altered.toReversed().flatMap((diff) => generator.generateAlterTable(reverseDiff(diff))),
                 ...cleared.flatMap(({ installed }) => [...installed.values()].flat().map((sql) => `${sql};`)),
             ],
         };
@@ -400,45 +394,40 @@ export class Migrator {
             altered: diffs.filter((diff) => diff.type === 'alter'),
         };
     }
+    /**
+     * Safe mode only adds: a change with a `from` drops or rebuilds what the table holds, so it is held,
+     * and so is a key whole, which rebuilds an index over every row and fails where a column holds a null.
+     * Without `drop`, a column's drop is held too.
+     */
     filterDiff(diff, options) {
-        const filteredDiff = { ...diff };
-        if (options.safe !== false) {
-            // In safe mode, we only allow additions (creating tables/columns)
-            // We block drops and alterations to prevent accidental data loss
-            if (filteredDiff.columnsToDrop?.length) {
-                this.logger.logSkippedMigration(`[AutoSync] Skipped dropping ${filteredDiff.columnsToDrop.length} columns in table '${diff.tableName}': ${filteredDiff.columnsToDrop.join(', ')} (safe mode active)`);
-                delete filteredDiff.columnsToDrop;
-            }
-            if (filteredDiff.columnsToAlter?.length) {
-                this.logger.logSkippedMigration(`[AutoSync] Skipped altering ${filteredDiff.columnsToAlter.length} columns in table '${diff.tableName}': ${filteredDiff.columnsToAlter.map((c) => c.to.name).join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
-                delete filteredDiff.columnsToAlter;
-            }
-            if (filteredDiff.primaryKey) {
-                // Rewriting a key drops a constraint and rebuilds an index over the whole table, and fails
-                // outright where the new columns are null on rows that already exist. Firmly not additive.
-                this.logger.logSkippedMigration(`[AutoSync] Skipped changing the primary key of '${diff.tableName}' from (${filteredDiff.primaryKey.from.join(', ')}) to (${filteredDiff.primaryKey.to.join(', ')}) (safe mode active). Use a migration or { safe: false } to apply.`);
-                delete filteredDiff.primaryKey;
+        const safe = options.safe !== false;
+        const skip = (what, names, fix) => {
+            if (names.length) {
+                this.logger.logSkippedMigration(`[AutoSync] Skipped ${names.length} ${what} in table '${diff.tableName}': ${names.join(', ')} (${fix}).`);
             }
-            if (filteredDiff.foreignKeysToAlter?.length) {
-                // Altering one is dropping it and adding it back, so letting the add through while the drop
-                // is held would emit `ADD CONSTRAINT` for a constraint the table still has.
-                this.logger.logSkippedMigration(`[AutoSync] Skipped altering ${filteredDiff.foreignKeysToAlter.length} foreign keys in table '${diff.tableName}': ${filteredDiff.foreignKeysToAlter.map((fk) => fk.to.name).join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
-                delete filteredDiff.foreignKeysToAlter;
-            }
-            if (filteredDiff.indexesToDrop?.length) {
-                // An index recreated under its old name is a drop and an add, held back together.
-                const dropped = new Set(filteredDiff.indexesToDrop.map((index) => index.name));
-                this.logger.logSkippedMigration(`[AutoSync] Skipped dropping ${dropped.size} indexes in table '${diff.tableName}': ${[...dropped].join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
-                filteredDiff.indexesToAdd = filteredDiff.indexesToAdd?.filter((index) => !dropped.has(index.name));
-                delete filteredDiff.indexesToDrop;
+        };
+        const safeFix = 'safe mode active. Use a migration or { safe: false } to apply';
+        const additive = (what, changes, nameOf) => {
+            if (!safe) {
+                return changes;
             }
-            delete filteredDiff.foreignKeysToDrop;
+            skip(`${what} changes`, sides(changes, 'from').map(nameOf), safeFix);
+            return nonEmpty((changes ?? []).filter((change) => change.from === undefined));
+        };
+        const columns = additive('column', diff.columns, (column) => column.name);
+        if (safe && diff.primaryKey) {
+            skip('primary key changes', [diff.tableName], safeFix);
         }
-        if (!options.drop && filteredDiff.columnsToDrop?.length) {
-            this.logger.logSkippedMigration(`[AutoSync] Skipped dropping ${filteredDiff.columnsToDrop.length} columns in table '${diff.tableName}' (drop: false). Use { drop: true } to apply.`);
-            delete filteredDiff.columnsToDrop;
+        if (!options.drop) {
+            skip('column drops', dropped(columns).map((column) => column.name), 'drop: false. Use { drop: true } to apply');
         }
-        return filteredDiff;
+        return {
+            ...diff,
+            primaryKey: safe ? undefined : diff.primaryKey,
+            columns: options.drop ? columns : nonEmpty((columns ?? []).filter((change) => change.to !== undefined)),
+            indexes: additive('index', diff.indexes, (index) => index.name),
+            foreignKeys: additive('foreign key', diff.foreignKeys, (foreignKey) => foreignKey.name ?? foreignKey.columns.join(', ')),
+        };
     }
     /** Runs the statements a generator wrote, in one transaction where the engine takes DDL in one. */
     async executeSyncStatements(statements, options) {

package/dist/migrate/schemaChange.d.ts

@@ -0,0 +1,18 @@
+import type { Change, SchemaDiff } from '../type/index.js';
+/** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
+export declare function sides<T>(changes: readonly Change<T>[] | undefined, side: 'from' | 'to'): T[];
+/** What the changes add: each `to` with no `from`. */
+export declare function added<T>(changes?: readonly Change<T>[]): T[];
+/** What the changes drop: each `from` with no `to`. */
+export declare function dropped<T>(changes?: readonly Change<T>[]): T[];
+/** The changes that alter an object in place, which only a column can. */
+export declare function alterations<T>(changes?: readonly Change<T>[]): {
+    readonly from: T;
+    readonly to: T;
+}[];
+/** `items`, or nothing where it has none, so an empty change list is left off a diff. */
+export declare function nonEmpty<T>(items: readonly T[]): readonly T[] | undefined;
+/** `change` undone: an add becomes a drop, a drop an add, and an alter runs the other way. */
+export declare function swap<T>({ from, to }: Change<T>): Change<T>;
+/** `diff` undone: every change swapped, which is what a migration's `down` runs. */
+export declare function reverseDiff(diff: SchemaDiff): SchemaDiff;

package/dist/migrate/schemaChange.js

@@ -0,0 +1,37 @@
+/** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
+export function sides(changes, side) {
+    return (changes ?? []).flatMap((change) => {
+        const end = change[side];
+        return end === undefined ? [] : [end];
+    });
+}
+/** What the changes add: each `to` with no `from`. */
+export function added(changes = []) {
+    return changes.flatMap(({ from, to }) => (from === undefined && to !== undefined ? [to] : []));
+}
+/** What the changes drop: each `from` with no `to`. */
+export function dropped(changes = []) {
+    return changes.flatMap(({ from, to }) => (to === undefined && from !== undefined ? [from] : []));
+}
+/** The changes that alter an object in place, which only a column can. */
+export function alterations(changes = []) {
+    return changes.flatMap(({ from, to }) => (from === undefined || to === undefined ? [] : [{ from, to }]));
+}
+/** `items`, or nothing where it has none, so an empty change list is left off a diff. */
+export function nonEmpty(items) {
+    return items.length ? items : undefined;
+}
+/** `change` undone: an add becomes a drop, a drop an add, and an alter runs the other way. */
+export function swap({ from, to }) {
+    return { from: to, to: from };
+}
+/** `diff` undone: every change swapped, which is what a migration's `down` runs. */
+export function reverseDiff(diff) {
+    return {
+        ...diff,
+        primaryKey: diff.primaryKey && swap(diff.primaryKey),
+        columns: diff.columns?.map(swap),
+        indexes: diff.indexes?.map(swap),
+        foreignKeys: diff.foreignKeys?.map(swap),
+    };
+}

package/dist/migrate/schemaGenerator.d.ts

@@ -68,18 +68,19 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      */
     private orderedTables;
     generateDropTable(tableName: string, options?: DropSchemaOptions): string;
+    /**
+     * The statements taking a table through `diff`, in the one order both directions need: whatever holds
+     * something down goes before it and comes back after it. A foreign key holds its columns and the key it
+     * points at, so it goes first and comes back last; the key holds its columns; and some engines drop an
+     * index along with its column, which would leave nothing to name. An alter is its drop, then its add.
+     */
     generateAlterTable(diff: SchemaDiff): string[];
     /** `ADD CONSTRAINT` for each of `foreignKeys`. */
     private addForeignKeyStatements;
-    /** `DROP CONSTRAINT` for each of `constraintNames`, the mirror of {@link addForeignKeyStatements}. */
-    private dropForeignKeyStatements;
-    /** The `ALTER COLUMN` restating each of `columns`. */
-    private alterColumnStatements;
     /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
     private addIndexStatements;
-    /** `DROP INDEX` for each of `indexes`, the mirror of {@link addIndexStatements}. */
-    private dropIndexStatements;
-    generateAlterTableDown(diff: SchemaDiff): string[];
+    /** A column added to a table that exists, and its comment where the engine keeps one apart. */
+    private addColumnStatements;
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {
         ifNotExists?: boolean;
     }): string;
@@ -96,8 +97,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     /**
      * The one place a column definition is spelled, so the `ColumnSchema` and `ColumnNode` paths cannot
      * drift. A key column states `NOT NULL` rather than leave it to the key: SQLite lets a key column hold
-     * NULL otherwise, and SQL Server adds no key over a nullable column. `UNIQUE` is left to the key. An
-     * enum's `CHECK` comes last, the only place MariaDB takes it.
+     * NULL otherwise, and SQL Server adds no key over a nullable column. Never `UNIQUE`: a unique column is
+     * a unique index, which the table creates beside it. An enum's `CHECK` comes last, the only place MariaDB takes it.
      */
     private renderColumn;
     /**
@@ -124,10 +125,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     protected diffOptions(): DiffOptions;
     /** Spread, not copied field by field, so a field the node gains cannot go missing here. */
     private columnNodeToSchema;
-    /**
-     * Compare two default values for equality
-     */
-    protected isDefaultValueEqual(current: unknown, desired: unknown): boolean;
+    /** Whether a column's stored default is the one the entity declares, as this engine reprints it. */
+    readonly defaultsEqual: (desired: unknown, current: unknown) => boolean;
     generateCreateTableFromNode(table: TableNode, options?: {
         ifNotExists?: boolean;
     }): string[];
@@ -186,4 +185,4 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
-export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], options?: Pick<BuildSchemaASTOptions, 'defaultForeignKeyAction' | 'textScoreIndexes'>): SchemaAST;
+export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], options?: Pick<BuildSchemaASTOptions, 'defaultForeignKeyAction' | 'textScoreIndexes' | 'vectorIndexRequiresNotNull'>): SchemaAST;