uql-orm 0.45.0 → 0.46.0

package/dist/migrate/generator/definitionToNode.js

@@ -1,4 +1,15 @@
-import { derivedForeignKeyName } from '../../util/sql.util.js';
+import { derivedForeignKeyName, derivedIndexName } from '../../util/sql.util.js';
+/**
+ * A table the builder names but has not seen.
+ *
+ * A `RelationshipNode` points at a whole `TableNode` because the AST wires `incomingRelations` through
+ * it; a builder creating one table has no node for the table its foreign key targets, and the
+ * generator reads only the name. Stated once, so the three casts it replaces cannot be mistaken for a
+ * node that was resolved and lost.
+ */
+function unresolvedTable(name) {
+    return { name };
+}
 /**
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
  * `createTable` and an entity reach `generateCreateTableFromNode` in the same shape. Free functions and
@@ -40,7 +51,7 @@ export function tableDefinitionToNode(def) {
                 columns: fkDef.columns.map((name) => columns.get(name)).filter((c) => c !== undefined),
             },
             to: {
-                table: { name: fkDef.references.table },
+                table: unresolvedTable(fkDef.references.table),
                 columns: fkDef.references.columns.map((name) => ({ name })),
             },
             onDelete: fkDef.onDelete,
@@ -50,30 +61,41 @@ export function tableDefinitionToNode(def) {
     }
     return table;
 }
+/**
+ * A builder's column as the AST node the generators render from.
+ *
+ * The shared half is spread, not copied field by field: `ColumnDefinition` *is* a `ColumnNode` minus
+ * the graph links, so spreading it and adding those back is a node by construction. Listed one by one,
+ * the copy silently dropped whatever the node gained next - `enum` first, and the type had no way to
+ * say so. The two builder-only keys are destructured off: `index` and `foreignKey` are lifted onto the
+ * table by `columnIndex`/`columnForeignKey`, which is the path that renders them.
+ *
+ * No `references` node either: `SchemaAST.addRelationship` sets that one.
+ */
 export function fullColumnDefinitionToNode(col, tableName) {
+    const { index: _index, foreignKey: _foreignKey, ...column } = col;
+    return { ...column, table: unresolvedTable(tableName), referencedBy: [] };
+}
+/**
+ * The index a column-level `index` declares, or nothing.
+ *
+ * Shared with `TableBuilder.build`, which lifts these into the table it is creating: written twice,
+ * `addColumn` had no lift at all and silently emitted a column with no index.
+ */
+export function columnIndex(tableName, col) {
+    if (!col.index) {
+        return undefined;
+    }
     return {
-        name: col.name,
-        type: col.type,
-        nullable: col.nullable,
-        defaultValue: col.defaultValue,
-        isPrimaryKey: col.primaryKey,
-        isAutoIncrement: col.autoIncrement,
-        isUnique: col.unique,
-        comment: col.comment,
-        table: { name: tableName },
-        referencedBy: [],
-        references: col.foreignKey
-            ? {
-                name: derivedForeignKeyName(tableName, [col.name]),
-                type: 'ManyToOne',
-                from: { table: { name: tableName }, columns: [] },
-                to: {
-                    table: { name: col.foreignKey.table },
-                    columns: col.foreignKey.columns.map((name) => ({ name })),
-                },
-                onDelete: col.foreignKey.onDelete,
-                onUpdate: col.foreignKey.onUpdate,
-            }
-            : undefined,
+        name: typeof col.index === 'string' ? col.index : derivedIndexName(tableName, [col.name]),
+        entries: [{ column: col.name }],
+        unique: col.isUnique,
     };
 }
+/** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
+export function columnForeignKey(col) {
+    if (!col.foreignKey) {
+        return undefined;
+    }
+    return { ...col.foreignKey, columns: [col.name] };
+}

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

@@ -18,9 +18,11 @@ export declare abstract class BaseSqlIntrospector {
     constructor(dialect: AbstractSqlDialect, schema?: string | undefined);
     protected escapeId(identifier: string): string;
     /**
-     * Introspect entire database schema and return SchemaAST.
+     * The database as a {@link SchemaAST}, or just the tables named. A name nothing matches is left out
+     * 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(): Promise<SchemaAST>;
+    introspect(tables?: readonly string[]): Promise<SchemaAST>;
     abstract getTableNames(): Promise<string[]>;
     abstract getTableSchema(tableName: string): Promise<TableSchema | undefined>;
     /**

package/dist/migrate/introspection/baseSqlIntrospector.js

@@ -23,10 +23,12 @@ export class BaseSqlIntrospector {
         return escapeSqlId(identifier, this.dialect.escapeIdChar);
     }
     /**
-     * Introspect entire database schema and return SchemaAST.
+     * The database as a {@link SchemaAST}, or just the tables named. A name nothing matches is left out
+     * 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() {
-        const tableNames = await this.getTableNames();
+    async introspect(tables) {
+        const tableNames = tables ?? (await this.getTableNames());
         const tableSchemas = [];
         for (const tableName of tableNames) {
             const schema = await this.getTableSchema(tableName);
@@ -52,15 +54,13 @@ export class BaseSqlIntrospector {
             const table = createTableNode(schema.name, this.schema);
             const { columns } = table;
             for (const col of schema.columns) {
+                // Spread, not field by field: a `ColumnSchema` is a `ColumnNode` minus the graph links, so
+                // everything but the type crosses unchanged and a field either shape gains cannot be dropped
+                // here. Listed by hand this had already lost `enum` and `generatedAs`.
+                const { type, length: _length, precision: _precision, scale: _scale, ...rest } = col;
                 const column = {
-                    name: col.name,
-                    type: canonicalColumnType(col.type, col),
-                    nullable: col.nullable,
-                    defaultValue: col.defaultValue,
-                    isPrimaryKey: col.isPrimaryKey,
-                    isAutoIncrement: col.isAutoIncrement,
-                    isUnique: col.isUnique,
-                    comment: col.comment,
+                    ...rest,
+                    type: canonicalColumnType(type, col),
                     table,
                     referencedBy: [],
                 };

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

@@ -10,7 +10,7 @@ export declare class MongoSchemaIntrospector implements SchemaIntrospector {
     /** `listIndexes` reports keys and uniqueness; a `partialFilterExpression` is no SQL predicate. */
     readonly indexFacets: ReadonlySet<IndexFacet>;
     constructor(pool: QuerierPool);
-    introspect(): Promise<SchemaAST>;
+    introspect(tables?: readonly string[]): Promise<SchemaAST>;
     getTableSchema(tableName: string): Promise<TableSchema | undefined>;
     getTableNames(): Promise<string[]>;
     tableExists(tableName: string): Promise<boolean>;

package/dist/migrate/introspection/mongoIntrospector.js

@@ -10,8 +10,8 @@ export class MongoSchemaIntrospector {
     constructor(pool) {
         this.pool = pool;
     }
-    async introspect() {
-        const tableNames = await this.getTableNames();
+    async introspect(tables) {
+        const tableNames = tables ?? (await this.getTableNames());
         const ast = new SchemaAST();
         for (const name of tableNames) {
             const schema = await this.getTableSchema(name);

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

@@ -7,6 +7,11 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
     protected getTableNamesQuery(): string;
     protected tableExistsQuery(): string;
     protected parseTableExistsResult(results: SqliteCountRow[]): boolean;
+    /**
+     * `table_xinfo`, not `table_info`: the latter omits generated columns entirely, so a table carrying
+     * one read back without it and every sync offered to add a column that was already there - which
+     * SQLite cannot do to an existing table anyway. PRAGMA takes no bound parameters, hence the splice.
+     */
     protected getColumnsQuery(tableName: string): string;
     protected getIndexesQuery(tableName: string): string;
     protected getForeignKeysQuery(tableName: string): string;

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -28,9 +28,13 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }
         return false;
     }
-    // SQLite uses PRAGMA which doesn't use parameterized queries in the same way
+    /**
+     * `table_xinfo`, not `table_info`: the latter omits generated columns entirely, so a table carrying
+     * one read back without it and every sync offered to add a column that was already there - which
+     * SQLite cannot do to an existing table anyway. PRAGMA takes no bound parameters, hence the splice.
+     */
     getColumnsQuery(tableName) {
-        return /*sql*/ `PRAGMA table_info(${this.escapeId(tableName)})`;
+        return /*sql*/ `PRAGMA table_xinfo(${this.escapeId(tableName)})`;
     }
     getIndexesQuery(tableName) {
         return /*sql*/ `PRAGMA index_list(${this.escapeId(tableName)})`;

package/dist/migrate/schemaGenerator.d.ts

@@ -36,6 +36,15 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * pointing at it emitted `INT`, and every engine refuses that constraint.
      */
     protected serialType(type: CanonicalType): string;
+    /**
+     * The SQL type a column is spelled with: the engine's generated-key form for an auto-increment key,
+     * the canonical type otherwise.
+     *
+     * One method because both paths that spell a column need the same answer - written twice, with a
+     * comment asking the two to stay in sync, is how the generated key and the column referencing it
+     * came to disagree in the first place.
+     */
+    protected columnSqlType(col: ColumnNode): string;
     protected canonicalTypeToSql(type: CanonicalType): string;
     /** The entity side as an AST, carrying this generator's default referential action. */
     buildAST(entities: readonly Type<unknown>[]): SchemaAST;
@@ -101,10 +110,26 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * Generate ALTER COLUMN statements (database-specific)
      */
     generateAlterColumnStatements(tableName: string, column: ColumnSchema, newDefinition: string): string[];
+    /** The inline ` COMMENT '...'` a column declaration carries, where the engine takes one there. */
+    generateColumnComment(comment: string): string;
+    /**
+     * The `COMMENT ON` statements a table and its columns need, on an engine that carries a comment
+     * that way. Empty on the others: MySQL writes them inline, SQLite has no comments at all.
+     *
+     * Emitted after the `CREATE TABLE` rather than folded into it, which is what `COMMENT ON` requires -
+     * and what makes a comment reach Postgres, where it was previously read as unsupported and dropped.
+     */
+    protected generateCommentStatements(table: TableNode): string[];
     /**
-     * Generate column comment clause (if supported)
+     * The `COMMENT ON COLUMN` one column needs, on an engine that carries a comment that way.
+     *
+     * Shared by `CREATE TABLE` and every path that adds a column: written only for the former, a column
+     * added later reached the database undocumented, the way its enum `CHECK` used to.
      */
-    generateColumnComment(columnName: string, comment: string): string;
+    protected generateColumnCommentStatement(tableName: string, column: {
+        name: string;
+        comment?: string;
+    }, schema?: string): string[];
     /**
      * Compare an entity with a database table node and return the differences.
      */
@@ -131,6 +156,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      */
     private missingIndexes;
     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
@@ -155,10 +181,25 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
         ifNotExists?: boolean;
     }): string[];
     generateRenameTableSql(oldName: string, newName: string): string;
+    /**
+     * `ADD COLUMN`, plus the constraint and index the column declares.
+     *
+     * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
+     * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
+     * dropped both without a word. Several statements in one string is what `generateAlterColumnSql`
+     * already returns, and `execute` splits them.
+     */
     generateAddColumnSql(tableName: string, column: FullColumnDefinition): string;
     generateAlterColumnSql(tableName: string, columnName: string, column: FullColumnDefinition): string;
     generateDropColumnSql(tableName: string, columnName: string): string;
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
+    /**
+     * `CONSTRAINT <name> FOREIGN KEY (...) REFERENCES ... ON DELETE ... ON UPDATE ...`.
+     *
+     * One spelling for the two places that need it - inline in a `CREATE TABLE`, and after `ADD` in an
+     * `ALTER`. Written twice, the two drifted over which end they qualified with a schema.
+     */
+    protected foreignKeyConstraint(tableName: string, foreignKey: ForeignKeySchema, refTableSql: string): string;
     generateAddForeignKeySql(tableName: string, foreignKey: ForeignKeySchema): string;
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
     /**
@@ -176,6 +217,11 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * no name at all - a table's key is always `PRIMARY` there.
      */
     generateDropPrimaryKeySql(tableName: string, constraintName?: string): string;
+    /**
+     * A column an `ALTER` can carry. Only a generated one is ever refused, and only where the engine
+     * takes it in a `CREATE TABLE` but not afterwards.
+     */
+    private assertColumnAddable;
     private assertPrimaryKeyAlterable;
 }
 /**

package/dist/migrate/schemaGenerator.js

@@ -8,7 +8,7 @@ import { getKeys, isAutoIncrement, isSoleIdField, qualifyName } from '../util/in
 import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
 import { indexDdlFor } from './ddl/index.js';
-import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
+import { columnForeignKey, columnIndex, fullColumnDefinitionToNode, tableDefinitionToNode, } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 /**
  * Unified SQL schema generator.
@@ -61,6 +61,17 @@ export class SqlSchemaGenerator {
     serialType(type) {
         return `${this.canonicalTypeToSql(type)} ${this.dialect.autoIncrementSuffix}`;
     }
+    /**
+     * The SQL type a column is spelled with: the engine's generated-key form for an auto-increment key,
+     * the canonical type otherwise.
+     *
+     * One method because both paths that spell a column need the same answer - written twice, with a
+     * comment asking the two to stay in sync, is how the generated key and the column referencing it
+     * came to disagree in the first place.
+     */
+    columnSqlType(col) {
+        return col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type);
+    }
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
     }
@@ -142,8 +153,9 @@ export class SqlSchemaGenerator {
         // Add new columns
         if (diff.columnsToAdd?.length) {
             for (const column of diff.columnsToAdd) {
-                const colDef = this.generateColumnDefinitionFromSchema(column);
-                statements.push(`ALTER TABLE ${tableName} ADD COLUMN ${colDef};`);
+                this.assertColumnAddable(diff.tableName, column);
+                statements.push(`ALTER TABLE ${tableName} ADD COLUMN ${this.generateColumnDefinitionFromSchema(column)};`);
+                statements.push(...this.generateColumnCommentStatement(diff.tableName, column, diff.schema));
             }
         }
         // Alter existing columns
@@ -279,6 +291,12 @@ export class SqlSchemaGenerator {
      */
     renderColumn(column) {
         let def = `${this.escapeId(column.name)} ${column.type}`;
+        // Before the constraints, which every engine here accepts and is where each documents it. The
+        // clause takes the place of a `DEFAULT`, which is mutually exclusive with it; everything else -
+        // `NOT NULL`, `UNIQUE`, an enum `CHECK`, a comment - a generated column carries like any other.
+        if (column.generatedAs) {
+            def += ` GENERATED ALWAYS AS (${column.generatedAs}) STORED`;
+        }
         if (!column.nullable && !column.isPrimaryKey) {
             def += ' NOT NULL';
         }
@@ -291,7 +309,7 @@ export class SqlSchemaGenerator {
         }
         def += this.defaultClause(column);
         if (column.comment) {
-            def += this.generateColumnComment(column.name, column.comment);
+            def += this.generateColumnComment(column.comment);
         }
         return def;
     }
@@ -350,15 +368,40 @@ export class SqlSchemaGenerator {
         }
         return [`ALTER TABLE ${table} ${this.dialect.alterColumnSyntax} ${newDefinition};`];
     }
+    /** The inline ` COMMENT '...'` a column declaration carries, where the engine takes one there. */
+    generateColumnComment(comment) {
+        return this.features.commentSyntax === 'inline' ? ` COMMENT ${this.dialect.escape(comment)}` : '';
+    }
+    /**
+     * The `COMMENT ON` statements a table and its columns need, on an engine that carries a comment
+     * that way. Empty on the others: MySQL writes them inline, SQLite has no comments at all.
+     *
+     * Emitted after the `CREATE TABLE` rather than folded into it, which is what `COMMENT ON` requires -
+     * and what makes a comment reach Postgres, where it was previously read as unsupported and dropped.
+     */
+    generateCommentStatements(table) {
+        if (this.features.commentSyntax !== 'statement') {
+            return [];
+        }
+        const tableRef = this.dialect.escapeQualifiedId(table.name, table.schema);
+        const statements = table.comment ? [`COMMENT ON TABLE ${tableRef} IS ${this.dialect.escape(table.comment)};`] : [];
+        for (const col of table.columns.values()) {
+            statements.push(...this.generateColumnCommentStatement(table.name, col, table.schema));
+        }
+        return statements;
+    }
     /**
-     * Generate column comment clause (if supported)
+     * The `COMMENT ON COLUMN` one column needs, on an engine that carries a comment that way.
+     *
+     * Shared by `CREATE TABLE` and every path that adds a column: written only for the former, a column
+     * added later reached the database undocumented, the way its enum `CHECK` used to.
      */
-    generateColumnComment(columnName, comment) {
-        if (this.features.columnComment) {
-            const escapedComment = comment.replace(/'/g, "''");
-            return ` COMMENT '${escapedComment}'`;
+    generateColumnCommentStatement(tableName, column, schema) {
+        if (!column.comment || this.features.commentSyntax !== 'statement') {
+            return [];
         }
-        return '';
+        const tableRef = this.dialect.escapeQualifiedId(tableName, schema);
+        return [`COMMENT ON COLUMN ${tableRef}.${this.escapeId(column.name)} IS ${this.dialect.escape(column.comment)};`];
     }
     /**
      * Compare an entity with a database table node and return the differences.
@@ -392,8 +435,17 @@ export class SqlSchemaGenerator {
         const columnDiffs = tableDiff?.columnDiffs ?? [];
         const columnsToAdd = columnDiffs.flatMap((it) => (it.type === 'add' ? [this.columnNodeToSchema(it.expected)] : []));
         const columnsToDrop = columnDiffs.flatMap((it) => (it.type === 'drop' ? [it.column] : []));
+        // Without its values: an alter restates the whole column, and MySQL answers a restated `CHECK` by
+        // adding a *second* constraint rather than replacing the first, so the column would accumulate one
+        // per alter. An enum's values reach the database with the column and are never restated - which is
+        // also why changing them is a hand-written migration. See architecture/roadmap.md.
         const columnsToAlter = columnDiffs.flatMap((it) => it.type === 'alter'
-            ? [{ from: this.columnNodeToSchema(it.actual), to: this.columnNodeToSchema(it.expected) }]
+            ? [
+                {
+                    from: this.columnNodeToSchema(it.actual),
+                    to: { ...this.columnNodeToSchema(it.expected), enum: undefined },
+                },
+            ]
             : []);
         const primaryKey = tableDiff?.primaryKeyDiff && {
             from: tableDiff.primaryKeyDiff.actual,
@@ -460,19 +512,10 @@ export class SqlSchemaGenerator {
             defaultsEqual: (expected, actual) => this.isDefaultValueEqual(actual, expected),
         };
     }
+    /** Spread, not copied field by field, so a field the node gains cannot go missing here. */
     columnNodeToSchema(col) {
-        return {
-            name: col.name,
-            // The same rule `generateColumnFromNode` renders by, so a column added to an existing table
-            // gets the type it would have had if the table were created from scratch.
-            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type),
-            nullable: col.nullable,
-            defaultValue: col.defaultValue,
-            isPrimaryKey: col.isPrimaryKey,
-            isAutoIncrement: col.isAutoIncrement,
-            isUnique: col.isUnique,
-            comment: col.comment,
-        };
+        const { table: _table, referencedBy: _referencedBy, references: _references, ...column } = col;
+        return { ...column, type: this.columnSqlType(col) };
     }
     /**
      * Compare two default values for equality
@@ -531,11 +574,8 @@ export class SqlSchemaGenerator {
         });
         for (const rel of table.outgoingRelations) {
             if (rel.from.columns.length > 0) {
-                const fromCols = rel.from.columns.map((c) => this.escapeId(c.name)).join(', ');
-                const toCols = rel.to.columns.map((c) => this.escapeId(c.name)).join(', ');
-                const constraintName = rel.name ? `CONSTRAINT ${this.escapeId(rel.name)} ` : '';
-                constraints.push(`${constraintName}FOREIGN KEY (${fromCols}) REFERENCES ${this.dialect.escapeQualifiedId(rel.to.table.name, rel.to.table.schema)} (${toCols})` +
-                    ` ON DELETE ${rel.onDelete ?? this.defaultForeignKeyAction} ON UPDATE ${rel.onUpdate ?? this.defaultForeignKeyAction}`);
+                const refTable = this.dialect.escapeQualifiedId(rel.to.table.name, rel.to.table.schema);
+                constraints.push(this.foreignKeyConstraint(table.name, foreignKeyOf(rel), refTable));
             }
         }
         const ifNotExists = options.ifNotExists && this.features.ifNotExists ? 'IF NOT EXISTS ' : '';
@@ -549,6 +589,9 @@ export class SqlSchemaGenerator {
         if (this.dialect.tableOptions) {
             createSql += ` ${this.dialect.tableOptions}`;
         }
+        if (table.comment && this.features.commentSyntax === 'inline') {
+            createSql += ` COMMENT=${this.dialect.escape(table.comment)}`;
+        }
         createSql += ';';
         const statements = [];
         if (this.dialect.vectorExtension) {
@@ -558,6 +601,7 @@ export class SqlSchemaGenerator {
             }
         }
         statements.push(createSql);
+        statements.push(...this.generateCommentStatements(table));
         for (const idx of table.indexes) {
             statements.push(this.generateCreateIndexFromNode(idx));
         }
@@ -568,10 +612,7 @@ export class SqlSchemaGenerator {
      * so only a lone primary key column carries `PRIMARY KEY` inline.
      */
     generateColumnFromNode(col) {
-        return this.renderColumn({
-            ...col,
-            type: col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type),
-        });
+        return this.renderColumn({ ...col, type: this.columnSqlType(col) });
     }
     /**
      * Generate CREATE INDEX SQL from an IndexNode.
@@ -591,9 +632,28 @@ export class SqlSchemaGenerator {
         }
         return `ALTER TABLE ${this.escapeId(oldName)} RENAME TO ${this.escapeId(newName)};`;
     }
+    /**
+     * `ADD COLUMN`, plus the constraint and index the column declares.
+     *
+     * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
+     * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
+     * dropped both without a word. Several statements in one string is what `generateAlterColumnSql`
+     * already returns, and `execute` splits them.
+     */
     generateAddColumnSql(tableName, column) {
+        this.assertColumnAddable(tableName, column);
         const colSql = this.generateColumnFromNode(fullColumnDefinitionToNode(column, tableName));
-        return `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql};`;
+        const statements = [`ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql};`];
+        const foreignKey = columnForeignKey(column);
+        if (foreignKey) {
+            statements.push(...this.addForeignKeyStatements(tableName, [foreignKey]));
+        }
+        const index = columnIndex(tableName, column);
+        if (index) {
+            statements.push(this.generateCreateIndex(tableName, index));
+        }
+        statements.push(...this.generateColumnCommentStatement(tableName, column));
+        return statements.join('\n');
     }
     generateAlterColumnSql(tableName, columnName, column) {
         const node = fullColumnDefinitionToNode(column, tableName);
@@ -605,16 +665,26 @@ export class SqlSchemaGenerator {
     generateRenameColumnSql(tableName, oldName, newName) {
         return `ALTER TABLE ${this.escapeId(tableName)} RENAME COLUMN ${this.escapeId(oldName)} TO ${this.escapeId(newName)};`;
     }
-    generateAddForeignKeySql(tableName, foreignKey) {
+    /**
+     * `CONSTRAINT <name> FOREIGN KEY (...) REFERENCES ... ON DELETE ... ON UPDATE ...`.
+     *
+     * One spelling for the two places that need it - inline in a `CREATE TABLE`, and after `ADD` in an
+     * `ALTER`. Written twice, the two drifted over which end they qualified with a schema.
+     */
+    foreignKeyConstraint(tableName, foreignKey, refTableSql) {
         const fkCols = foreignKey.columns.map((c) => this.escapeId(c)).join(', ');
         const refCols = foreignKey.references.columns.map((c) => this.escapeId(c)).join(', ');
-        const constraintName = this.escapeId(constraintNameOf(tableName, foreignKey));
+        return (`CONSTRAINT ${this.escapeId(constraintNameOf(tableName, foreignKey))} ` +
+            `FOREIGN KEY (${fkCols}) REFERENCES ${refTableSql} (${refCols}) ` +
+            `ON DELETE ${foreignKey.onDelete ?? this.defaultForeignKeyAction} ` +
+            `ON UPDATE ${foreignKey.onUpdate ?? this.defaultForeignKeyAction}`);
+    }
+    generateAddForeignKeySql(tableName, foreignKey) {
         if (!this.features.foreignKeyAlter) {
             throw new TypeError(`Dialect ${this.dialect} does not support adding foreign keys to existing tables`);
         }
-        return (`ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} ` +
-            `FOREIGN KEY (${fkCols}) REFERENCES ${this.escapeId(foreignKey.references.table)} (${refCols}) ` +
-            `ON DELETE ${foreignKey.onDelete ?? this.defaultForeignKeyAction} ON UPDATE ${foreignKey.onUpdate ?? this.defaultForeignKeyAction};`);
+        const constraint = this.foreignKeyConstraint(tableName, foreignKey, this.escapeId(foreignKey.references.table));
+        return `ALTER TABLE ${this.escapeId(tableName)} ADD ${constraint};`;
     }
     generateDropForeignKeySql(tableName, constraintName) {
         return `ALTER TABLE ${this.escapeId(tableName)} ${this.dialect.dropForeignKeySyntax} ${this.escapeId(constraintName)};`;
@@ -650,6 +720,18 @@ export class SqlSchemaGenerator {
         }
         return `ALTER TABLE ${table} DROP CONSTRAINT ${this.escapeId(constraintName)};`;
     }
+    /**
+     * A column an `ALTER` can carry. Only a generated one is ever refused, and only where the engine
+     * takes it in a `CREATE TABLE` but not afterwards.
+     */
+    assertColumnAddable(tableName, column) {
+        if (!column.generatedAs || this.features.generatedColumnAdd) {
+            return;
+        }
+        throw new TypeError(`${this.dialect}: Cannot add the computed column "${column.name}" to the existing table ` +
+            `"${tableName}" - this database only accepts one in a CREATE TABLE. Drop \`stored\` to have the ` +
+            'expression spliced into each statement instead, or recreate the table in a written migration.');
+    }
     assertPrimaryKeyAlterable(tableName) {
         if (this.features.primaryKeyAlter) {
             return;

package/dist/mongo/mongoDialect.js

@@ -17,7 +17,8 @@ export const mongoDialectFeatures = {
     renameColumn: false,
     foreignKeyAlter: false,
     primaryKeyAlter: false,
-    columnComment: false,
+    generatedColumnAdd: false,
+    commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,
     supportsTimestamptz: false,

package/dist/schema/schemaAST.d.ts

@@ -150,7 +150,38 @@ export declare class SchemaAST implements ISchemaAST {
         indexCount: number;
     };
     /**
-     * Convert schema to a plain object for serialization/debugging.
-     */
-    toJSON(): object;
+     * The schema as a plain object, for serialization and debugging. The graph links are what is left
+     * out - they are cycles, and nothing else is: listing the fields to keep instead dropped every
+     * option a column had gained since, `defaultValue` and `enum` included.
+     */
+    toJSON(): {
+        tables: {
+            name: string;
+            columns: {
+                name: string;
+                type: import("./types.js").CanonicalType;
+                nullable: boolean;
+                defaultValue?: unknown;
+                isPrimaryKey: boolean;
+                isAutoIncrement: boolean;
+                isUnique: boolean;
+                enum?: import("./types.js").EnumValues;
+                generatedAs?: string;
+                comment?: string;
+            }[];
+            indexes: {
+                name: string;
+                columns: string[];
+                unique: boolean;
+            }[];
+        }[];
+        relationships: {
+            name: string;
+            type: RelationshipType;
+            from: string;
+            to: string;
+            onDelete: import("./types.js").ForeignKeyAction | undefined;
+            onUpdate: import("./types.js").ForeignKeyAction | undefined;
+        }[];
+    };
 }

package/dist/schema/schemaAST.js

@@ -385,20 +385,15 @@ export class SchemaAST {
         };
     }
     /**
-     * Convert schema to a plain object for serialization/debugging.
+     * The schema as a plain object, for serialization and debugging. The graph links are what is left
+     * out - they are cycles, and nothing else is: listing the fields to keep instead dropped every
+     * option a column had gained since, `defaultValue` and `enum` included.
      */
     toJSON() {
         return {
             tables: Array.from(this.tables.values()).map((t) => ({
                 name: t.name,
-                columns: Array.from(t.columns.values()).map((c) => ({
-                    name: c.name,
-                    type: c.type,
-                    nullable: c.nullable,
-                    isPrimaryKey: c.isPrimaryKey,
-                    isAutoIncrement: c.isAutoIncrement,
-                    isUnique: c.isUnique,
-                })),
+                columns: Array.from(t.columns.values()).map(({ table: _table, referencedBy: _referencedBy, references: _references, ...column }) => column),
                 indexes: t.indexes.map((i) => ({
                     name: i.name,
                     columns: i.entries.map((entry) => entry.column),