uql-orm 0.86.0 → 0.88.0

package/dist/dialect/abstractSqlDialect.d.ts

@@ -106,7 +106,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     createSchemaSql(schema: string): string;
     readonly isolationLevelStrategy: 'inline' | 'set-before' | 'none';
     readonly alterColumnStrategy: 'separate-clauses' | 'single-statement';
-    readonly alterColumnSyntax: 'ALTER COLUMN' | 'MODIFY COLUMN' | 'none';
+    readonly alterColumnSyntax: 'ALTER COLUMN' | 'MODIFY COLUMN';
     readonly dropForeignKeySyntax: 'DROP CONSTRAINT' | 'DROP FOREIGN KEY';
     /**
      * `DROP CONSTRAINT <name>` where a primary key is a named constraint like any other; MySQL spells

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -19,9 +19,7 @@ export const MYSQL_FEATURES = {
     indexIfNotExists: false,
     schemas: true,
     dropTableCascade: false,
-    foreignKeyAlter: true,
-    primaryKeyAlter: true,
-    generatedColumnAdd: true,
+    rebuildsTables: false,
     commentSyntax: 'inline',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,

package/dist/dialect/pgLikeSqlDialect.js

@@ -21,9 +21,7 @@ export const PG_FEATURES = {
     indexIfNotExists: true,
     schemas: true,
     dropTableCascade: true,
-    foreignKeyAlter: true,
-    primaryKeyAlter: true,
-    generatedColumnAdd: true,
+    rebuildsTables: false,
     commentSyntax: 'statement',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: true,

package/dist/migrate/ddl/tableDdl.d.ts

@@ -15,6 +15,11 @@ export declare class TableDdl {
     /** A `CREATE TABLE` up to its column list, a no-op where `ifNotExists` and the table is already there. */
     createTable(target: string, ifNotExists: boolean): string;
     addColumn(table: string, definition: string): string;
+    /**
+     * `column` added, spelled by `render`. MySQL fills a zero into the rows already there for a required
+     * column with no default, so there it is added nullable and required after, failing on them as elsewhere.
+     */
+    addColumnStatements(table: string, column: ColumnSchema, render: (column: ColumnSchema) => string): string[];
     dropColumn(table: string, column: string): string[];
     /**
      * What changes `column` to what it now declares. `definition` is the whole column, which MySQL's

package/dist/migrate/ddl/tableDdl.js

@@ -1,5 +1,5 @@
-import { UqlUsageError } from '../../util/uqlError.js';
 import { formatDefaultValue, sameDefault } from '../builder/expressions.js';
+import { lacksValue } from '../schemaChange.js';
 /**
  * A column's type with the size it was read back with, unless its spelling already carries one:
  * introspection reports `VARCHAR` and `255` apart, where a type from an entity is already whole.
@@ -30,6 +30,19 @@ export class TableDdl {
     addColumn(table, definition) {
         return `ALTER TABLE ${this.dialect.escapeId(table)} ADD COLUMN ${definition};`;
     }
+    /**
+     * `column` added, spelled by `render`. MySQL fills a zero into the rows already there for a required
+     * column with no default, so there it is added nullable and required after, failing on them as elsewhere.
+     */
+    addColumnStatements(table, column, render) {
+        if (this.dialect.alterColumnSyntax !== 'MODIFY COLUMN' || !lacksValue(column)) {
+            return [this.addColumn(table, render(column))];
+        }
+        return [
+            this.addColumn(table, render({ ...column, nullable: true })),
+            ...this.alterColumn(table, column, render(column)),
+        ];
+    }
     dropColumn(table, column) {
         return [`ALTER TABLE ${this.dialect.escapeId(table)} DROP COLUMN ${this.dialect.escapeId(column)};`];
     }
@@ -39,17 +52,15 @@ export class TableDdl {
      * column was (`from`), only the clauses that changed.
      */
     alterColumn(table, column, definition, from) {
-        if (this.dialect.alterColumnSyntax === 'none') {
-            throw new UqlUsageError(`${this.dialect}: Cannot alter column "${column.name}" - you must recreate the table. ` +
-                `This database does not support ALTER COLUMN.`);
-        }
         const target = this.dialect.escapeId(table);
         if (this.dialect.alterColumnStrategy !== 'separate-clauses') {
             return [`ALTER TABLE ${target} ${this.dialect.alterColumnSyntax} ${definition};`];
         }
-        const alter = `ALTER TABLE ${target} ALTER COLUMN ${this.dialect.escapeId(column.name)}`;
+        const name = this.dialect.escapeId(column.name);
+        const alter = `ALTER TABLE ${target} ALTER COLUMN ${name}`;
         return [
-            (!from || from.type !== column.type) && `${alter} TYPE ${column.type};`,
+            // Cast, since the engine converts only between types it deems compatible: text to integer needs saying.
+            (!from || from.type !== column.type) && `${alter} TYPE ${column.type} USING ${name}::${column.type};`,
             (!from || from.nullable !== column.nullable) && `${alter} ${column.nullable ? 'DROP NOT NULL' : 'SET NOT NULL'};`,
             (!from || !sameDefault(column.defaultValue, from.defaultValue, this.dialect)) &&
                 (column.defaultValue === undefined ? `${alter} DROP DEFAULT;` : `${alter} SET${this.defaultClause(column)};`),

package/dist/migrate/ddl/tableRebuild.d.ts

@@ -0,0 +1,17 @@
+import type { AbstractSqlDialect } from '../../dialect/index.js';
+import type { RebuiltTable, Rename } from '../../type/index.js';
+/** What the copy reads besides the columns both sides share: renamed ones, and a default filling a column's nulls. */
+export type RebuildCopy = {
+    readonly renames: readonly Rename[];
+    readonly fills: ReadonlyMap<string, string>;
+};
+/**
+ * SQLite's documented rebuild of `table`: a new table in the shape `to` gives, the rows copied into it,
+ * the old one dropped and the new one renamed into its place, then its indexes and triggers. A foreign
+ * key pointing at the table would delete or null its rows with the drop, so the guard fails the whole
+ * rebuild first unless foreign keys are off, as the migrator turns them off on a SQLite connection.
+ */
+export declare function rebuildTable(dialect: AbstractSqlDialect, table: string, { from, to }: {
+    readonly from: RebuiltTable;
+    readonly to: RebuiltTable;
+}, copy: RebuildCopy): string[];

package/dist/migrate/ddl/tableRebuild.js

@@ -0,0 +1,56 @@
+import { OWNED_PREFIX } from '../../dialect/aliases.js';
+/** The table a rebuild copies into, under a name no entity's table takes. */
+const NEW_TABLE_PREFIX = `${OWNED_PREFIX}_new_`;
+/** The table the guard inserts into, refused while foreign keys would take rows down with the rebuilt one. */
+const GUARD_TABLE = `${OWNED_PREFIX}_rebuild_guard`;
+/**
+ * SQLite's documented rebuild of `table`: a new table in the shape `to` gives, the rows copied into it,
+ * the old one dropped and the new one renamed into its place, then its indexes and triggers. A foreign
+ * key pointing at the table would delete or null its rows with the drop, so the guard fails the whole
+ * rebuild first unless foreign keys are off, as the migrator turns them off on a SQLite connection.
+ */
+export function rebuildTable(dialect, table, { from, to }, copy) {
+    const id = (name) => dialect.escapeId(name);
+    const target = id(`${NEW_TABLE_PREFIX}${table}`);
+    const [create, ...rest] = to.statements;
+    const copied = to.columns.flatMap((column) => {
+        const source = copy.renames.find((rename) => rename.to === column)?.from ?? column;
+        if (!from.columns.includes(source)) {
+            return [];
+        }
+        const fill = copy.fills.get(column);
+        return [{ column: id(column), value: fill === undefined ? id(source) : `coalesce(${id(source)}, ${fill})` }];
+    });
+    return [
+        ...guard(dialect, table),
+        renameCreatedTable(create, target),
+        ...(copied.length
+            ? [
+                `INSERT INTO ${target} (${copied.map((it) => it.column).join(', ')}) ` +
+                    `SELECT ${copied.map((it) => it.value).join(', ')} FROM ${id(table)};`,
+            ]
+            : []),
+        `DROP TABLE ${id(table)};`,
+        `ALTER TABLE ${target} RENAME TO ${id(table)};`,
+        ...rest,
+    ];
+}
+/** Fails, naming the way out, where foreign keys are on and any table references `table`. */
+function guard(dialect, table) {
+    const id = (name) => dialect.escapeId(name);
+    const guardTable = id(GUARD_TABLE);
+    const referencing = id('referencing');
+    const refusal = id(`turn foreign keys off to rebuild ${table}: the rows referencing it would be lost`);
+    return [
+        `CREATE TABLE IF NOT EXISTS ${guardTable} (${referencing} INTEGER CONSTRAINT ${refusal} CHECK (${referencing} = 0));`,
+        `INSERT INTO ${guardTable} SELECT count(*) FROM pragma_foreign_keys AS k, sqlite_master AS m, ` +
+            `pragma_foreign_key_list(m.name) AS f WHERE k.foreign_keys AND m.type = 'table' ` +
+            `AND f.${id('table')} = ${dialect.escape(table)} COLLATE NOCASE;`,
+        `DROP TABLE ${guardTable};`,
+    ];
+}
+const CREATE_TABLE_NAME = /^(\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?)(?:"(?:[^"]|"")*"|`(?:[^`]|``)*`|\[[^\]]*\]|[^\s(]+)/i;
+/** A `CREATE TABLE` as the engine or the generator spelled it, creating `name` instead. */
+function renameCreatedTable(sql, name) {
+    return sql.replace(CREATE_TABLE_NAME, `$1${name}`);
+}

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

@@ -1,5 +1,5 @@
 import { type ForeignKeyAction } from '../../schema/types.js';
-import type { ColumnSchema, InstalledTriggers, ForeignKeySchema, IndexSchema, PrimaryKeySchema, QuerierPool, RawRow, SchemaIntrospector, SqlQuerier, TableSchema } from '../../type/index.js';
+import type { ColumnSchema, InstalledTriggers, ForeignKeySchema, IndexSchema, PrimaryKeySchema, QuerierPool, RawRow, SchemaIntrospector, SqlQuerier, StoredDefinition, TableSchema } from '../../type/index.js';
 import { BaseSqlIntrospector } from './baseSqlIntrospector.js';
 /**
  * Reads the rows of one statement while introspecting a table.
@@ -37,6 +37,8 @@ export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntro
      */
     protected readonly defaultSchemaExpr: string;
     getTableSchema(tableName: string): Promise<TableSchema | undefined>;
+    /** See {@link TableSchema.definition}: none, but where the engine keeps the statements themselves. */
+    protected getDefinition(_read: TableRowReader, _tableName: string): Promise<StoredDefinition[] | undefined>;
     getTableNames(): Promise<string[]>;
     /**
      * Every trigger uql installed in this schema, by table and then by name, with the statements recreating

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js

@@ -30,11 +30,12 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
             if (!exists) {
                 return undefined;
             }
-            const [columns, indexes, foreignKeys, primaryKey] = await Promise.all([
+            const [columns, indexes, foreignKeys, primaryKey, definition] = await Promise.all([
                 this.getColumns(read, tableName),
                 this.getIndexes(read, tableName),
                 this.getForeignKeys(read, tableName),
                 this.getPrimaryKey(read, tableName),
+                this.getDefinition(read, tableName),
             ]);
             return {
                 name: tableName,
@@ -42,9 +43,14 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
                 primaryKey,
                 indexes,
                 foreignKeys,
+                definition,
             };
         });
     }
+    /** See {@link TableSchema.definition}: none, but where the engine keeps the statements themselves. */
+    async getDefinition(_read, _tableName) {
+        return undefined;
+    }
     async getTableNames() {
         return this.withSqlQuerier(async (querier) => {
             const results = await querier.all(this.getTableNamesQuery());

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

@@ -1,7 +1,7 @@
 import type { AbstractSqlDialect } from '../../dialect/index.js';
 import type { IndexFacet } from '../../schema/indexDifferences.js';
 import { SchemaAST } from '../../schema/schemaAST.js';
-import type { TableSchema } from '../../type/migration.js';
+import type { ColumnRenames, TableSchema } from '../../type/migration.js';
 /**
  * Base class for SQL introspectors with shared AST building logic.
  */
@@ -22,7 +22,9 @@ export declare abstract class BaseSqlIntrospector {
      * rather than raised: the point of naming them is to read a database other things are still
      * changing, where scanning every table is both wasted work and a relation that can vanish mid-scan.
      */
-    introspect(tables?: readonly string[]): Promise<SchemaAST>;
+    introspect(tables?: readonly string[], renames?: ColumnRenames): Promise<SchemaAST>;
+    /** `table` with each column `renames` names under its new name, wherever the table names it. */
+    private renamed;
     abstract getTableNames(): Promise<string[]>;
     abstract getTableSchema(tableName: string): Promise<TableSchema | undefined>;
     /**

package/dist/migrate/introspection/baseSqlIntrospector.js

@@ -1,7 +1,7 @@
 import { canonicalColumnType } from '../../schema/canonicalType.js';
 import { createTableNode, keyOfColumns, SchemaAST } from '../../schema/schemaAST.js';
 import { escapeSqlId } from '../../util/index.js';
-import { derivedForeignKeyName } from '../../util/sql.util.js';
+import { derivedForeignKeyName, qualifyName } from '../../util/sql.util.js';
 /**
  * Base class for SQL introspectors with shared AST building logic.
  */
@@ -27,17 +27,39 @@ export class BaseSqlIntrospector {
      * rather than raised: the point of naming them is to read a database other things are still
      * changing, where scanning every table is both wasted work and a relation that can vanish mid-scan.
      */
-    async introspect(tables) {
+    async introspect(tables, renames) {
         const tableNames = tables ?? (await this.getTableNames());
         const tableSchemas = [];
         for (const tableName of tableNames) {
             const schema = await this.getTableSchema(tableName);
             if (schema) {
-                tableSchemas.push(schema);
+                tableSchemas.push(renames ? this.renamed(schema, renames) : schema);
             }
         }
         return this.buildAST(tableSchemas);
     }
+    /** `table` with each column `renames` names under its new name, wherever the table names it. */
+    renamed(table, renames) {
+        const nameIn = (tableName) => (column) => renames.get(qualifyName(tableName, this.schema))?.find((rename) => rename.from === column)?.to ?? column;
+        const own = nameIn(table.name);
+        return {
+            ...table,
+            columns: table.columns.map((column) => ({ ...column, name: own(column.name) })),
+            primaryKey: table.primaryKey && { ...table.primaryKey, columns: table.primaryKey.columns.map(own) },
+            indexes: table.indexes?.map((index) => ({
+                ...index,
+                entries: index.entries.map((entry) => (entry.expression ? entry : { ...entry, column: own(entry.column) })),
+            })),
+            foreignKeys: table.foreignKeys?.map((foreignKey) => ({
+                ...foreignKey,
+                columns: foreignKey.columns.map(own),
+                references: {
+                    ...foreignKey.references,
+                    columns: foreignKey.references.columns.map(nameIn(foreignKey.references.table)),
+                },
+            })),
+        };
+    }
     /**
      * Build SchemaAST from table schemas.
      */
@@ -75,13 +97,16 @@ export class BaseSqlIntrospector {
         // key from `(b, a)`, and a flag says only that a column is *in* the key. Falls back to the flags
         // for an introspector that reports no key of its own.
         table.primaryKey = schema.primaryKey ?? keyOfColumns(schema.columns);
+        table.definition = schema.definition;
         return table;
     }
     buildRelationships(ast, tableNodes, schema, fromTable) {
         for (const fk of schema.foreignKeys ?? []) {
             const toTable = tableNodes.get(fk.references.table);
-            if (!toTable)
+            if (!toTable) {
+                fromTable.externalForeignKeys.push(fk);
                 continue;
+            }
             const fromColumns = fk.columns.flatMap((name) => fromTable.columns.get(name) ?? []);
             const toColumns = fk.references.columns.flatMap((name) => toTable.columns.get(name) ?? []);
             if (fromColumns.length > 0 && toColumns.length > 0) {

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

@@ -1,5 +1,5 @@
 import type { IndexFacet } from '../../schema/indexDifferences.js';
-import type { ColumnSchema, ForeignKeySchema, IndexSchema } from '../../type/index.js';
+import type { ColumnSchema, ForeignKeySchema, IndexSchema, StoredDefinition } from '../../type/index.js';
 import { AbstractSqlSchemaIntrospector, type TableRowReader } from './abstractSqlSchemaIntrospector.js';
 /**
  * SQLite schema introspector
@@ -32,12 +32,12 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
     protected mapColumnsResult(read: TableRowReader, tableName: string, results: SqliteColumnRow[]): Promise<ColumnSchema[]>;
     protected mapIndexesResult(read: TableRowReader, _tableName: string, results: SqliteIndexRow[]): Promise<IndexSchema[]>;
     protected mapForeignKeysResult(_read: TableRowReader, tableName: string, results: SqliteForeignKeyRow[]): Promise<ForeignKeySchema[]>;
+    /** Every statement `sqlite_master` keeps for the table, its `CREATE TABLE` first. An automatic index has none. */
+    protected getDefinition(read: TableRowReader, tableName: string): Promise<StoredDefinition[]>;
     protected mapPrimaryKeyResult(results: SqliteColumnRow[]): string[] | undefined;
     private getUniqueColumns;
     /** libSQL's `libsql_vector_idx(col, 'metric=...')`, read back from the statement that created it. */
     private getVectorIndex;
-    /** The statement that created the table, which is where SQLite keeps every expression it was given. */
-    private getTableDdl;
     private getIndexColumns;
     protected normalizeType(type: string): string;
     protected extractLength(type: string): number | undefined;

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -69,7 +69,10 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         const uniqueColumns = await this.getUniqueColumns(read, tableName);
         // Only a sole `INTEGER PRIMARY KEY` is the rowid, which is what numbers itself.
         const soleKey = results.filter((row) => row.pk > 0).length === 1;
-        const ddl = results.some((row) => row.hidden === STORED_GENERATED) ? await this.getTableDdl(read, tableName) : '';
+        const [table] = results.some((row) => row.hidden === STORED_GENERATED)
+            ? await this.getDefinition(read, tableName)
+            : [];
+        const ddl = table?.sql ?? '';
         return results.map((row) => ({
             name: row.name,
             type: this.normalizeType(row.type),
@@ -136,6 +139,11 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             };
         });
     }
+    /** Every statement `sqlite_master` keeps for the table, its `CREATE TABLE` first. An automatic index has none. */
+    getDefinition(read, tableName) {
+        return read(
+        /*sql*/ `SELECT type AS kind, name, sql FROM sqlite_master WHERE tbl_name = ? AND sql IS NOT NULL ORDER BY type <> 'table'`, [tableName]);
+    }
     mapPrimaryKeyResult(results) {
         const pkColumns = results.filter((r) => r.pk > 0).sort((a, b) => a.pk - b.pk);
         if (pkColumns.length === 0) {
@@ -176,12 +184,6 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             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) {
-        const [row] = await read(
-        /*sql*/ `SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?`, [tableName]);
-        return row.sql;
-    }
     getIndexColumns(read, indexName) {
         return read(/*sql*/ `PRAGMA index_info(${this.escapeId(indexName)})`);
     }

package/dist/migrate/migrationTarget.js

@@ -10,8 +10,34 @@ import { MongoMigrationStorage } from './storage/mongoStorage.js';
 const sqlSession = (querier) => ({
     querier,
     run: (statement) => querier.run(statement),
-    transaction: (work) => querier.transaction(work),
+    transaction: (work) => querier.dialect.features.rebuildsTables ? withForeignKeysOff(querier, work) : querier.transaction(work),
 });
+/**
+ * SQLite's own procedure for a schema change: foreign keys off before the transaction, where the switch
+ * takes effect, and every reference checked before it commits. Otherwise dropping a table to rebuild it
+ * deletes the rows pointing at it. A connection whose transaction runs elsewhere keeps them on, which the
+ * rebuild's guard refuses.
+ */
+async function withForeignKeysOff(querier, work) {
+    const [{ foreign_keys: enforced }] = await querier.all('PRAGMA foreign_keys');
+    if (!enforced) {
+        return querier.transaction(work);
+    }
+    await querier.run('PRAGMA foreign_keys = OFF');
+    try {
+        await querier.transaction(async () => {
+            await work();
+            const violations = await querier.all('PRAGMA foreign_key_check');
+            if (violations.length) {
+                const [{ table, parent }] = violations;
+                throw new UqlUsageError(`The migration leaves ${violations.length} row(s) referencing a missing one, the first in "${table}" pointing at "${parent}".`);
+            }
+        });
+    }
+    finally {
+        await querier.run('PRAGMA foreign_keys = ON');
+    }
+}
 const mongoSession = (querier) => ({
     querier,
     run: (statement) => runMongoCommand(querier.db, statement),

package/dist/migrate/migrator.d.ts

@@ -86,14 +86,30 @@ export declare class Migrator {
      * it. Read off the catalogue rather than recorded by uql, and exactly right for restoring one.
      */
     private revertedTriggers;
+    /**
+     * What a generated migration does that its reader must not miss: each column it drops or retypes, which
+     * can lose data, and each table it creates empty while the database holds one no entity names with the
+     * same columns, which may be the table renamed. That one is never renamed here: it may be another's.
+     */
+    private noteChanges;
+    /**
+     * Refuses, before anything runs, each column the changes require with no default while rows would hold
+     * none: every engine fails on one but MySQL, which fills in a zero. Counted, since an empty table is fine.
+     */
+    private assertFillable;
+    /** The tables the database holds that no entity names, each paired with a new one it is identical to. */
+    private renamedTables;
     /** The entities whose tables are among `created`. */
     private createdEntities;
     /** The table `entity` maps to, as a diff names it. */
     private tableOf;
     /**
-     * Get all schema differences between entities and database
+     * The differences between the entities and the database. With `renames`, a column identical to one the
+     * entity no longer names is renamed in place rather than dropped and added, as a generated migration wants.
      */
-    getDiffs(): Promise<SchemaDiff[]>;
+    getDiffs(options?: {
+        renames?: boolean;
+    }): Promise<SchemaDiff[]>;
     /**
      * The tables `entities` name, read a schema at a time so each is keyed as its entity spells it. Those
      * alone: nothing else is diffed, and another table can be dropped mid-scan by whatever else is running.
@@ -131,7 +147,8 @@ export declare class Migrator {
     /**
      * 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.
+     * Without `drop`, a column's drop is held too. A rebuilt table applies its diff whole, so holding any
+     * part of it holds the rebuild, and only what an `ALTER` adds goes ahead: a plain column, an index.
      */
     protected filterDiff(diff: SchemaDiff, options: {
         safe?: boolean;