uql-orm 0.80.0 → 0.82.0

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -9,11 +9,11 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     defaultSchemaExpr = 'DATABASE()';
     triggersQuery() {
         return /*sql*/ `
-      SELECT EVENT_OBJECT_TABLE AS \`table\`, TRIGGER_NAME AS name,
+      SELECT TRIGGER_NAME AS name,
         CONCAT('CREATE TRIGGER \`', TRIGGER_SCHEMA, '\`.\`', TRIGGER_NAME, '\` ', ACTION_TIMING, ' ', EVENT_MANIPULATION,
           ' ON \`', EVENT_OBJECT_SCHEMA, '\`.\`', EVENT_OBJECT_TABLE, '\` FOR EACH ROW ', ACTION_STATEMENT) AS definition
       FROM information_schema.TRIGGERS
-      WHERE TRIGGER_SCHEMA = ${this.schemaExpr}
+      WHERE TRIGGER_SCHEMA = ${this.schemaExpr} AND EVENT_OBJECT_TABLE = ${this.dialect.placeholder(1)}
     `;
     }
     getTableNamesQuery() {
@@ -62,7 +62,8 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       SELECT
         INDEX_NAME as index_name,
         GROUP_CONCAT(COALESCE(COLUMN_NAME, '') ORDER BY SEQ_IN_INDEX) as columns,
-        NOT NON_UNIQUE as is_unique
+        NOT NON_UNIQUE as is_unique,
+        MAX(INDEX_TYPE) as method
       FROM information_schema.STATISTICS
       WHERE TABLE_SCHEMA = ${this.schemaExpr}
         AND TABLE_NAME = ?
@@ -110,7 +111,8 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             isPrimaryKey: row.column_key === 'PRI',
             isAutoIncrement: row.extra.toLowerCase().includes('auto_increment'),
             isUnique: row.column_key === 'UNI',
-            length: this.toNumber(row.character_maximum_length),
+            // A `VECTOR`'s is its bytes, four a dimension, which `column_type` already states as dimensions.
+            length: /^vector/i.test(row.column_type) ? undefined : this.toNumber(row.character_maximum_length),
             precision: this.toNumber(row.numeric_precision),
             scale: this.toNumber(row.numeric_scale),
             comment: row.column_comment || undefined,
@@ -120,6 +122,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     async mapIndexesResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.index_name,
+            ...(row.method === 'VECTOR' && { type: 'vector' }),
             // A functional or multi-valued key part has no `COLUMN_NAME` - the `COALESCE` above keeps its
             // place in the list, and it is reported as the expression it is, which is what stops diffing
             // from comparing an entry list the server cannot state against the entity's own.
@@ -164,6 +167,31 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
  * JSON, got LONGTEXT", flagged as data loss) on a table uql created itself.
  */
 export class MariadbSchemaIntrospector extends MysqlSchemaIntrospector {
+    /** Whether an index is MariaDB's vector index, and the distance it was built for. */
+    indexFacets = new Set(['vector', 'distance']);
+    /**
+     * A vector index's distance is kept only in the table's own definition, ``VECTOR KEY `ix` (`vec`)
+     * `DISTANCE`='cosine'``, and left out there for MariaDB's default, euclidean.
+     */
+    async mapIndexesResult(read, tableName, results) {
+        const indexes = await super.mapIndexesResult(read, tableName, results);
+        if (!indexes.some((index) => index.type === 'vector')) {
+            return indexes;
+        }
+        const qualified = [this.schema, tableName]
+            .filter((name) => name !== undefined)
+            .map((name) => this.dialect.escapeId(name));
+        const [row] = await read(/*sql*/ `SHOW CREATE TABLE ${qualified.join('.')}`);
+        const lines = row['Create Table'].split('\n');
+        return indexes.map((index) => {
+            if (index.type !== 'vector') {
+                return index;
+            }
+            const line = lines.find((it) => it.includes(`VECTOR KEY \`${index.name}\``));
+            const metric = line?.match(/`DISTANCE`='(\w+)'/)?.[1] ?? 'euclidean';
+            return { ...index, distance: this.dialect.indexedDistance(metric) };
+        });
+    }
     async mapColumnsResult(read, tableName, results) {
         const columns = await super.mapColumnsResult(read, tableName, results);
         const checks = await read(

package/dist/migrate/introspection/postgresIntrospector.d.ts

@@ -22,7 +22,11 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
      * 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.
      */
     protected getColumnsQuery(_tableName: string): string;
     /**
@@ -32,24 +36,27 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
      * 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.
      */
     protected getIndexesQuery(_tableName: string): string;
-    /**
-     * 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.
-     */
-    protected readonly constraintIndexTypes: readonly string[];
+    /** Whether an entry sorts nulls first, which Postgres states on every entry. */
+    protected readonly nullsFirstSql: string;
+    /** An index's access method, which is the type it declares. */
+    protected readonly indexMethodSql: string;
+    /** An entry's operator class, where it is not the default for its type. */
+    protected readonly opsClassSql: string;
     /** From `pg_constraint`, whose key arrays keep each column paired with the one it references. */
     protected getForeignKeysQuery(_tableName: string): string;
     protected getPrimaryKeyQuery(_tableName: string): string;
     protected mapColumnsResult(_read: TableRowReader, _tableName: string, results: PostgresColumnRow[]): Promise<ColumnSchema[]>;
+    /**
+     * 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.
+     */
+    private withVectorDistance;
     protected mapIndexesResult(_read: TableRowReader, _tableName: string, results: PostgresIndexRow[]): Promise<IndexSchema[]>;
     protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: PostgresForeignKeyRow[]): Promise<ForeignKeySchema[]>;
     protected normalizeType(dataType: string, udtName: string): string;
@@ -73,18 +80,18 @@ declare const FOREIGN_KEY_ACTION_CODES: {
  * 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 declare class CockroachSchemaIntrospector extends PostgresSchemaIntrospector {
     readonly indexFacets: ReadonlySet<IndexFacet>;
+    /** None: it rejects a stated nulls order, so reading one back gives an index it would refuse to rebuild. */
+    protected readonly 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.
      */
-    protected readonly constraintIndexTypes: readonly string[];
+    protected readonly indexMethodSql = "CASE WHEN pg_get_indexdef(ix.indexrelid) LIKE '% USING cspann %' THEN 'vector' ELSE am.amname END";
+    protected readonly opsClassSql = "CASE WHEN k.n = ix.indnkeyatts THEN substring(pg_get_indexdef(ix.indexrelid) from '(\\w+_ops)\\)') END";
 }
 type PostgresForeignKeyRow = {
     constraint_name: string;
@@ -104,13 +111,14 @@ type PostgresIndexRow = {
     is_expression: boolean;
     entry: string;
     descending: boolean;
-    nulls_first: boolean;
+    nulls_first: boolean | null;
     ops_class: string | null;
 };
 type PostgresColumnRow = {
     column_name: string;
     data_type: string;
     udt_name: string;
+    formatted_type: string | null;
     is_nullable: string;
     column_default: string | null;
     is_primary_key: boolean;

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/migrationTarget.js

@@ -1,4 +1,5 @@
 import { isMongoQuerier, isSqlQuerier, } from '../type/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 import { withMongoQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
 import { MigrationBuilder } from './builder/migrationBuilder.js';
 import { migrationSource } from './codegen/migrationFile.js';
@@ -46,5 +47,5 @@ export async function migrationBuilderFor(querier) {
     if (isMongoQuerier(querier)) {
         return new MigrationBuilder(await mongoSchemaGenerator(), mongoSession(querier).run);
     }
-    throw new TypeError('A migration builder needs a SQL or a MongoDB querier');
+    throw new UqlUsageError('A migration builder needs a SQL or a MongoDB querier');
 }

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

@@ -5,9 +5,11 @@ import { getEntities, getMeta } from '../entity/index.js';
 import { SchemaAST } from '../schema/index.js';
 import { hasTriggers } from '../util/field.util.js';
 import { LoggerWrapper } from '../util/index.js';
+import { UqlUsageError } from '../util/uqlError.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
  */
@@ -95,7 +97,7 @@ export class Migrator {
         if (options.to) {
             const toIndex = selected.findIndex((m) => m.name === options.to);
             if (toIndex === -1) {
-                throw new TypeError(`Migration '${options.to}' not found`);
+                throw new UqlUsageError(`Migration '${options.to}' not found`);
             }
             selected = selected.slice(0, toIndex + 1);
         }
@@ -215,17 +217,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 +234,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 +245,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 +395,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;