uql-orm 0.45.1 → 0.47.0

package/dist/migrate/builder/types.d.ts

@@ -4,7 +4,7 @@
  * Type definitions for the fluent migration builder API.
  * Enables type-safe migrations without raw SQL.
  */
-import type { CanonicalType, ForeignKeyAction } from '../../schema/types.js';
+import type { ColumnNode, EnumValues, ForeignKeyAction } from '../../schema/types.js';
 import type { IndexColumnInput, IndexOptions, IndexSchema } from '../../type/index.js';
 import type { ForeignKeySchema } from '../../type/migration.js';
 /**
@@ -68,41 +68,20 @@ export interface VectorColumnOptions extends BaseColumnOptions {
     dimensions?: number;
 }
 /**
- * Base options for a column definition.
+ * A column as the builder describes one: {@link ColumnNode} without the graph links a DTO cannot carry.
+ *
+ * Derived rather than restated, so the two cannot drift. A column gained `enum` and this shape was
+ * simply missing it, which is why a hand-written `createTable` could never constrain one. A field
+ * added to the node now reaches here, and failing to render it is a compile error rather than a
+ * column that quietly loses half its declaration.
  */
-export interface ColumnDefinition {
-    /** Column name */
-    name: string;
-    /** Canonical type */
-    type: CanonicalType;
-    /** Whether the column is nullable */
-    nullable: boolean;
-    /** Default value or expression */
-    defaultValue?: unknown;
-    /** Whether this is a primary key */
-    primaryKey: boolean;
-    /** Whether this column auto-increments */
-    autoIncrement: boolean;
-    /** Whether this column has a unique constraint */
-    unique: boolean;
-    /** Column comment */
-    comment?: string;
-}
+export type ColumnDefinition = Omit<ColumnNode, 'table' | 'referencedBy' | 'references'>;
 /**
- * Foreign key definition for a column.
+ * The foreign key a single column declares: {@link ForeignKeySchema} without the local columns, which
+ * are the column itself. Derived for the reason {@link ColumnDefinition} is - restated, the two spelled
+ * their target differently and every hand-off between them had to translate.
  */
-export interface ForeignKeyDefinition {
-    /** Constraint name */
-    name?: string;
-    /** Referenced table */
-    table: string;
-    /** Referenced column(s) */
-    columns: string[];
-    /** Action on delete */
-    onDelete: ForeignKeyAction;
-    /** Action on update */
-    onUpdate: ForeignKeyAction;
-}
+export type ForeignKeyDefinition = Omit<ForeignKeySchema, 'columns'>;
 /**
  * Full column definition including foreign key.
  */
@@ -259,6 +238,10 @@ export interface IColumnBuilder {
     autoIncrement(): this;
     /** Add unique constraint */
     unique(): this;
+    /** Constrain the column to these values, as a `CHECK (col IN (...))`. */
+    enum(values: EnumValues): this;
+    /** Make the column one the database computes, as `GENERATED ALWAYS AS (<sql>) STORED`. */
+    computed(sql: string): this;
     /** Add comment */
     comment(text: string): this;
     /** Add index */

package/dist/migrate/codegen/entityCodeGenerator.js

@@ -12,7 +12,7 @@
 import { canonicalToTypeScript } from '../../schema/canonicalType.js';
 import { DEFAULT_FOREIGN_KEY_ACTION, } from '../../schema/types.js';
 import { camelCase, pascalCase, singularize } from '../../util/string.util.js';
-import { buildFieldOptionsSource } from './fieldOptionsSource.js';
+import { buildFieldOptionsSource, fieldNeedsRaw } from './fieldOptionsSource.js';
 import { buildIndexDecoratorSource, indexNeedsRaw, isPlainFieldIndex } from './indexDecoratorSource.js';
 /**
  * Generates TypeScript entity code from SchemaAST.
@@ -75,11 +75,13 @@ export class EntityCodeGenerator {
     buildImports(table) {
         const uqlImports = new Set(['Entity', 'Field']);
         const relatedImports = [];
-        // Check for Id decorator
         for (const col of table.columns.values()) {
             if (col.isPrimaryKey) {
                 uqlImports.add('Id');
             }
+            if (fieldNeedsRaw(col)) {
+                uqlImports.add('raw');
+            }
         }
         // Check for relation decorators
         if (this.options.includeRelations) {
@@ -145,9 +147,6 @@ export class EntityCodeGenerator {
             lines.push('  /**');
             lines.push(`   * @sync-added ${new Date().toISOString().split('T')[0]}`);
             lines.push(`   * Column: ${col.name} (${this.formatTypeDescription(col.type)})`);
-            if (col.comment) {
-                lines.push(`   * ${col.comment}`);
-            }
             lines.push('   */');
         }
         // Decorator

package/dist/migrate/codegen/fieldOptionsSource.d.ts

@@ -8,3 +8,5 @@ import type { ColumnNode } from '../../schema/types.js';
  * file from scratch.
  */
 export declare function buildFieldOptionsSource(col: ColumnNode, propertyName: string, indexName?: string): string;
+/** Whether the field's decorator needs `raw` imported, the way {@link indexNeedsRaw} does for an index. */
+export declare function fieldNeedsRaw(col: ColumnNode): boolean;

package/dist/migrate/codegen/fieldOptionsSource.js

@@ -1,4 +1,41 @@
 import { canonicalToColumnType } from '../../schema/canonicalType.js';
+import { quoted, rawTag } from './sourceLiteral.js';
+/**
+ * What each field of a {@link ColumnNode} contributes to `@Field({ ... })`, in emit order, and `null`
+ * where nothing does.
+ *
+ * The `satisfies` is the point: a field the node gains cannot reach here without someone answering
+ * whether an entity generated from a database keeps it. Written as a hand-rolled `if` chain, this had
+ * already dropped `comment` - introspection reads one on Postgres and MySQL, and regenerating an
+ * entity threw it away.
+ */
+const OPTION_SOURCE = {
+    // Without this the entity maps to a column named after the property, which for anything the
+    // transformer rewrote - every `user_id` - is a column the database does not have.
+    name: (col, { propertyName }) => (propertyName === col.name ? [] : [`name: ${quoted(col.name)}`]),
+    type: (col) => {
+        const columnType = canonicalToColumnType(col.type);
+        return [
+            ...(columnType ? [`columnType: ${quoted(columnType)}`] : []),
+            ...(col.type.length && col.type.category === 'string' ? [`length: ${col.type.length}`] : []),
+            ...(col.type.precision === undefined ? [] : [`precision: ${col.type.precision}`]),
+            ...(col.type.precision !== undefined && col.type.scale !== undefined ? [`scale: ${col.type.scale}`] : []),
+        ];
+    },
+    nullable: (col) => (col.nullable ? ['nullable: true'] : []),
+    isUnique: (col) => (col.isUnique ? ['unique: true'] : []),
+    enum: (col) => col.enum ? [`enum: [${col.enum.map((it) => (typeof it === 'number' ? it : quoted(it))).join(', ')}]`] : [],
+    defaultValue: (col) => col.defaultValue === undefined ? [] : [`defaultValue: ${defaultValueSource(col.defaultValue)}`],
+    generatedAs: (col) => (col.generatedAs ? [`computed: ${rawTag(col.generatedAs)}`, 'stored: true'] : []),
+    comment: (col) => (col.comment ? [`comment: ${quoted(col.comment)}`] : []),
+    // A key is `@Id`, and a numeric one generates by that alone. Neither is an option to write out.
+    isPrimaryKey: null,
+    isAutoIncrement: null,
+    // Graph links. A foreign key becomes a relation decorator, emitted beside the field rather than in it.
+    table: null,
+    references: null,
+    referencedBy: null,
+};
 /**
  * A column's `@Field({ ... })` options as source, or `''` when it needs none.
  *
@@ -8,47 +45,26 @@ import { canonicalToColumnType } from '../../schema/canonicalType.js';
  * file from scratch.
  */
 export function buildFieldOptionsSource(col, propertyName, indexName) {
-    const options = [];
-    // Without this the entity maps to a column named after the property, which for anything the
-    // transformer rewrote - every `user_id` - is a column the database does not have.
-    if (propertyName !== col.name) {
-        options.push(`name: '${col.name}'`);
-    }
-    const columnType = canonicalToColumnType(col.type);
-    if (columnType) {
-        options.push(`columnType: '${columnType}'`);
-    }
-    if (col.type.length && col.type.category === 'string') {
-        options.push(`length: ${col.type.length}`);
-    }
-    if (col.type.precision !== undefined) {
-        options.push(`precision: ${col.type.precision}`);
-        if (col.type.scale !== undefined) {
-            options.push(`scale: ${col.type.scale}`);
-        }
-    }
-    if (col.nullable) {
-        options.push('nullable: true');
-    }
-    if (col.isUnique) {
-        options.push('unique: true');
-    }
-    if (col.defaultValue !== undefined) {
-        options.push(`defaultValue: ${formatDefaultValueSource(col.defaultValue)}`);
-    }
-    if (indexName) {
-        options.push(`index: '${indexName}'`);
-    }
+    const context = { propertyName, indexName };
+    const options = [
+        ...Object.values(OPTION_SOURCE).flatMap((source) => source?.(col, context) ?? []),
+        // Not a column field: the index is a table-level object the field only borrows.
+        ...(indexName ? [`index: ${quoted(indexName)}`] : []),
+    ];
     return options.length > 0 ? `{ ${options.join(', ')} }` : '';
 }
+/** Whether the field's decorator needs `raw` imported, the way {@link indexNeedsRaw} does for an index. */
+export function fieldNeedsRaw(col) {
+    return col.generatedAs !== undefined;
+}
 /**
  * A default value as source. Strings stay single-quoted, expressions included: `defaultValue: 'now()'`
  * is what reaches the DDL. The generator used to branch on `CURRENT_TIMESTAMP`/`NEXTVAL`/`(` first, but
  * both branches emitted a quoted string and only the fallthrough escaped embedded quotes.
  */
-function formatDefaultValueSource(value) {
+function defaultValueSource(value) {
     if (typeof value === 'string') {
-        return `'${value.replace(/'/g, "\\'")}'`;
+        return quoted(value);
     }
     if (typeof value === 'boolean' || typeof value === 'number') {
         return value.toString();

package/dist/migrate/codegen/indexDecoratorSource.js

@@ -1,3 +1,4 @@
+import { rawTag } from './sourceLiteral.js';
 /**
  * A vector index carries its metric in the operator class pgvector names after it
  * (`vector_cosine_ops`), which is the only place introspection can recover it from. `@Index` requires
@@ -94,12 +95,3 @@ function indexEntrySource(entry, propertyName) {
     }
     return `{ column: '${propertyName(entry.column)}', ${modifiers.join(', ')} }`;
 }
-/**
- * SQL as a `raw` tagged template. A database reprints an expression as arbitrary text, and exactly
- * three sequences can end or interpolate a template literal, so escaping those is the whole job.
- * Newlines need none, which keeps a multi-line expression readable in the generated entity.
- */
-function rawTag(sql) {
-    const escaped = sql.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
-    return `raw\`${escaped}\``;
-}

package/dist/migrate/codegen/sourceLiteral.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A string as single-quoted source. Introspected text is arbitrary - a comment or a default
+ * expression can hold a quote or a backslash - and only escaping both keeps the generated file
+ * parsing.
+ */
+export declare function quoted(text: string): string;
+/**
+ * SQL as a `raw` tagged template. A database reprints an expression as arbitrary text, and exactly
+ * three sequences can end or interpolate a template literal, so escaping those is the whole job.
+ * Newlines need none, which keeps a multi-line expression readable in the generated entity.
+ */
+export declare function rawTag(sql: string): string;

package/dist/migrate/codegen/sourceLiteral.js

@@ -0,0 +1,17 @@
+/**
+ * A string as single-quoted source. Introspected text is arbitrary - a comment or a default
+ * expression can hold a quote or a backslash - and only escaping both keeps the generated file
+ * parsing.
+ */
+export function quoted(text) {
+    return `'${text.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/**
+ * SQL as a `raw` tagged template. A database reprints an expression as arbitrary text, and exactly
+ * three sequences can end or interpolate a template literal, so escaping those is the whole job.
+ * Newlines need none, which keeps a multi-line expression readable in the generated entity.
+ */
+export function rawTag(sql) {
+    const escaped = sql.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+    return `raw\`${escaped}\``;
+}

package/dist/migrate/generator/definitionToNode.d.ts

@@ -1,4 +1,5 @@
 import type { ColumnNode, TableNode } from '../../schema/types.js';
+import type { ForeignKeySchema, IndexSchema } from '../../type/migration.js';
 import type { FullColumnDefinition, TableDefinition } from '../builder/types.js';
 /**
  * A migration builder's table definition as the AST nodes the generators render from, so a hand-written
@@ -6,4 +7,24 @@ import type { FullColumnDefinition, TableDefinition } from '../builder/types.js'
  * not generator methods: nothing here consults the dialect.
  */
 export declare function tableDefinitionToNode(def: TableDefinition): TableNode;
+/**
+ * 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 declare function fullColumnDefinitionToNode(col: FullColumnDefinition, tableName: string): ColumnNode;
+/**
+ * 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 declare function columnIndex(tableName: string, col: FullColumnDefinition): IndexSchema | undefined;
+/** The foreign key a column-level `references` declares, or nothing. Shared for the same reason. */
+export declare function columnForeignKey(col: FullColumnDefinition): ForeignKeySchema | undefined;

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;
 }
 /**