uql-orm 0.34.0 → 0.35.0

package/dist/migrate/migrator.js

@@ -2,7 +2,7 @@ import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getEntities, getMeta } from '../entity/index.js';
-import { introspectSchema } from '../schema/index.js';
+import { introspectSchema, SchemaAST } from '../schema/index.js';
 import { isKnownMigratorDialect, isSqlQuerier } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 import { withQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
@@ -71,19 +71,20 @@ export class Migrator {
     setSchemaGenerator(generator) {
         this.schemaGenerator = generator;
     }
-    createIntrospector() {
+    /** `schema` reads one namespace instead of the connection's own; see {@link BaseSqlIntrospector.schema}. */
+    createIntrospector(schema) {
         const d = this.dialectName;
         if (!isKnownMigratorDialect(d)) {
             return undefined;
         }
         switch (d) {
             case 'postgres':
-                return new PostgresSchemaIntrospector(this.pool);
+                return new PostgresSchemaIntrospector(this.pool, schema);
             case 'cockroachdb':
-                return new CockroachSchemaIntrospector(this.pool);
+                return new CockroachSchemaIntrospector(this.pool, schema);
             case 'mysql':
             case 'mariadb':
-                return new MysqlSchemaIntrospector(this.pool);
+                return new MysqlSchemaIntrospector(this.pool, schema);
             case 'sqlite':
                 return new SqliteSchemaIntrospector(this.pool);
             case 'mongodb':
@@ -279,7 +280,7 @@ export class Migrator {
         if (!this.schemaGenerator || !this.schemaIntrospector) {
             throw new TypeError('Schema generator and introspector must be set');
         }
-        const ast = await introspectSchema(this.schemaIntrospector);
+        const ast = await this.introspectClaimedSchemas();
         const diffs = [];
         for (const entity of this.entities) {
             const meta = getMeta(entity);
@@ -292,6 +293,27 @@ export class Migrator {
         }
         return diffs;
     }
+    /**
+     * One AST spanning every schema the entities claim, each table stamped with the schema it was read
+     * from. Read per schema rather than all at once, so a table comes back keyed exactly as the entity
+     * that wants it spells the key: `undefined` on both sides for the connection's default, a name on
+     * both sides otherwise. Ordinarily that is one schema and one pass, as before, and that pass keeps
+     * {@link schemaIntrospector} so a caller that replaced it still wins.
+     */
+    async introspectClaimedSchemas() {
+        const claimed = new Set(this.entities.map((entity) => this.pool.dialect.resolveSchema(getMeta(entity))));
+        const merged = new SchemaAST();
+        for (const schema of claimed) {
+            const introspector = schema === undefined ? this.schemaIntrospector : this.createIntrospector(schema);
+            if (!introspector) {
+                continue;
+            }
+            for (const table of (await introspectSchema(introspector)).getTables()) {
+                merged.addTable(table);
+            }
+        }
+        return merged;
+    }
     async findEntityForTable(tableName) {
         await this.ensureSchemaGenerator();
         if (!this.schemaGenerator) {
@@ -549,10 +571,10 @@ export function defineMigration(migration) {
  * ```ts
  * export default defineBuilderMigration({
  *   async up(m) {
- *     await m.createTable('users', (table) => {
- *       table.id();
- *       table.string('email', 255).unique();
- *       table.timestamps();
+ *     await m.createTable('users', (t) => {
+ *       t.id();
+ *       t.string('email', { length: 255 }).unique();
+ *       t.timestamps();
  *     });
  *   },
  *   async down(m) {

package/dist/migrate/schemaGenerator.d.ts

@@ -14,10 +14,10 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     get namingStrategy(): NamingStrategy | undefined;
     get features(): DialectFeatures;
     resolveTableName<E>(meta: EntityMeta<E>): string;
+    resolveTableAlias<E>(meta: EntityMeta<E>): string;
+    resolveSchema<E>(meta: EntityMeta<E>): string | undefined;
     resolveColumnName(key: string, field: FieldOptions): string;
-    /**
-     * Escape an identifier (table name, column name, etc.)
-     */
+    /** Escape an identifier (table name, column name, etc.) */
     protected escapeId(identifier: string): string;
     /**
      * Primary key type for auto-increment integer IDs
@@ -39,9 +39,9 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      */
     generateCreateSchema(entities: readonly Type<unknown>[], options?: CreateSchemaOptions): string[];
     /**
-     * One statement per distinct schema the entities name, in first-seen order. `resolveSchema` is
-     * already `undefined` on an engine without schemas, so this is empty there, and empty in the
-     * ordinary case where nothing named one.
+     * One statement per distinct schema the tables being created live in, in first-seen order. Only
+     * the tables actually being created, so a narrowed `only` does not declare namespaces it is not
+     * about to fill. Empty on an engine without schemas, whose tables are never qualified.
      */
     private generateCreateSchemas;
     generateDropSchema(entities: readonly Type<unknown>[], options?: DropSchemaOptions): string[];
@@ -57,7 +57,11 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {
         ifNotExists?: boolean;
     }): string;
-    generateDropIndex(tableName: string, indexName: string): string;
+    /**
+     * `schema` is the table's, because that is where its indexes live. MySQL takes it from the table
+     * operand instead, which is already qualified.
+     */
+    generateDropIndex(tableName: string, indexName: string, schema?: string): string;
     /**
      * Generate a column definition from a {@link ColumnSchema}, whose type is the engine's own spelling
      * and may already carry its precision (or even `PRIMARY KEY`, for a serial).
@@ -162,7 +166,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
  * other way and the table is created under one name and compared under another, which reports every
  * table of a project using a naming strategy as both missing and unexpected.
  */
-export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableName' | 'resolveColumnName'>, entities: readonly Type<unknown>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;
+export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName'>, entities: readonly Type<unknown>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;
 /**
  * Synchronous factory for SQL schema generators only.
  * For MongoDB, use `createSchemaGeneratorAsync` from `./schemaGeneratorAsync.js` so the optional `mongodb` peer is not loaded at import time.

package/dist/migrate/schemaGenerator.js

@@ -2,7 +2,8 @@ import { AbstractSqlDialect } from '../dialect/index.js';
 import { getMeta } from '../entity/index.js';
 import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
-import { escapeSqlId, getKeys, isAutoIncrement } from '../util/index.js';
+import { getKeys, isAutoIncrement, qualifyName } from '../util/index.js';
+import { derivedForeignKeyName } from '../util/sql.util.js';
 import { formatDefaultValue } from './builder/expressions.js';
 import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
@@ -26,14 +27,18 @@ export class SqlSchemaGenerator {
     resolveTableName(meta) {
         return this.dialect.resolveTableName(meta);
     }
+    resolveTableAlias(meta) {
+        return this.dialect.resolveTableAlias(meta);
+    }
+    resolveSchema(meta) {
+        return this.dialect.resolveSchema(meta);
+    }
     resolveColumnName(key, field) {
         return this.dialect.resolveColumnName(key, field);
     }
-    /**
-     * Escape an identifier (table name, column name, etc.)
-     */
+    /** Escape an identifier (table name, column name, etc.) */
     escapeId(identifier) {
-        return escapeSqlId(identifier, this.dialect.escapeIdChar);
+        return this.dialect.escapeId(identifier);
     }
     /**
      * Primary key type for auto-increment integer IDs
@@ -67,15 +72,15 @@ export class SqlSchemaGenerator {
         const inline = withForeignKeys && !this.features.foreignKeyAlter;
         // Namespaces first: a qualified `CREATE TABLE` fails against a schema nobody created, and the
         // schema is the one part of the layout a migration cannot infer from the table it is making.
-        const statements = this.generateCreateSchemas(entities);
+        const statements = this.generateCreateSchemas(tables);
         statements.push(...tables.flatMap((table) => this.generateCreateTableFromNode(inline ? table : { ...table, outgoingRelations: [] }, options)));
         if (withForeignKeys && !inline) {
             for (const table of tables) {
                 for (const rel of table.outgoingRelations) {
-                    statements.push(this.generateAddForeignKeySql(table.name, {
+                    statements.push(this.generateAddForeignKeySql(qualifyName(table.name, table.schema), {
                         name: rel.name,
                         columns: rel.from.columns.map((c) => c.name),
-                        referencesTable: rel.to.table.name,
+                        referencesTable: qualifyName(rel.to.table.name, rel.to.table.schema),
                         referencesColumns: rel.to.columns.map((c) => c.name),
                         onDelete: rel.onDelete ?? this.defaultForeignKeyAction,
                         onUpdate: rel.onUpdate ?? this.defaultForeignKeyAction,
@@ -86,18 +91,16 @@ export class SqlSchemaGenerator {
         return statements;
     }
     /**
-     * One statement per distinct schema the entities name, in first-seen order. `resolveSchema` is
-     * already `undefined` on an engine without schemas, so this is empty there, and empty in the
-     * ordinary case where nothing named one.
+     * One statement per distinct schema the tables being created live in, in first-seen order. Only
+     * the tables actually being created, so a narrowed `only` does not declare namespaces it is not
+     * about to fill. Empty on an engine without schemas, whose tables are never qualified.
      */
-    generateCreateSchemas(entities) {
-        const named = entities
-            .map((entity) => this.dialect.resolveSchema(getMeta(entity)))
-            .filter((it) => it !== undefined);
+    generateCreateSchemas(tables) {
+        const named = tables.map((table) => table.schema).filter((it) => it !== undefined);
         return [...new Set(named)].map((schema) => this.dialect.createSchemaSql(schema));
     }
     generateDropSchema(entities, options = {}) {
-        return this.orderedTables(entities, 'drop').map((table) => this.generateDropTable(table.name, options));
+        return this.orderedTables(entities, 'drop').map((table) => this.generateDropTable(qualifyName(table.name, table.schema), options));
     }
     /**
      * The tables of `entities` in dependency order, optionally narrowed to `only`. The AST always spans
@@ -111,7 +114,7 @@ export class SqlSchemaGenerator {
             return tables;
         }
         const wanted = new Set(only);
-        return tables.filter((table) => wanted.has(table.name));
+        return tables.filter((table) => wanted.has(qualifyName(table.name, table.schema)));
     }
     generateDropTable(tableName, options = {}) {
         const ifExists = options.ifExists ? 'IF EXISTS ' : '';
@@ -151,7 +154,7 @@ export class SqlSchemaGenerator {
         // Drop indexes
         if (diff.indexesToDrop?.length) {
             for (const indexName of diff.indexesToDrop) {
-                statements.push(this.generateDropIndex(diff.tableName, indexName));
+                statements.push(this.generateDropIndex(diff.tableName, indexName, diff.schema));
             }
         }
         return statements;
@@ -176,7 +179,7 @@ export class SqlSchemaGenerator {
         // Reverse index additions by dropping them
         if (diff.indexesToAdd?.length) {
             for (const index of diff.indexesToAdd) {
-                statements.push(this.generateDropIndex(diff.tableName, index.name));
+                statements.push(this.generateDropIndex(diff.tableName, index.name, diff.schema));
             }
         }
         if (diff.columnsToDrop?.length || diff.indexesToDrop?.length) {
@@ -187,11 +190,15 @@ export class SqlSchemaGenerator {
     generateCreateIndex(tableName, index, options = {}) {
         return this.dialect.getCreateIndexStatement(tableName, index, options);
     }
-    generateDropIndex(tableName, indexName) {
+    /**
+     * `schema` is the table's, because that is where its indexes live. MySQL takes it from the table
+     * operand instead, which is already qualified.
+     */
+    generateDropIndex(tableName, indexName, schema) {
         if (this.dialect.dropIndexSyntax === 'on-table') {
             return `DROP INDEX ${this.escapeId(indexName)} ON ${this.escapeId(tableName)};`;
         }
-        return `DROP INDEX IF EXISTS ${this.escapeId(indexName)};`;
+        return `DROP INDEX IF EXISTS ${this.dialect.escapeQualifiedId(indexName, schema)};`;
     }
     /**
      * Generate a column definition from a {@link ColumnSchema}, whose type is the engine's own spelling
@@ -316,7 +323,8 @@ export class SqlSchemaGenerator {
         const meta = getMeta(entity);
         if (!currentTable) {
             return {
-                tableName: this.dialect.resolveTableName(meta),
+                tableName: this.resolveTableName(meta),
+                schema: this.resolveSchema(meta),
                 type: 'create',
             };
         }
@@ -354,7 +362,8 @@ export class SqlSchemaGenerator {
             return undefined;
         }
         return {
-            tableName: this.dialect.resolveTableName(meta),
+            tableName: this.resolveTableName(meta),
+            schema: this.resolveSchema(meta),
             type: 'alter',
             columnsToAdd: columnsToAdd.length > 0 ? columnsToAdd : undefined,
             columnsToAlter: columnsToAlter.length > 0 ? columnsToAlter : undefined,
@@ -371,7 +380,9 @@ export class SqlSchemaGenerator {
      * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
      */
     missingIndexes(entity, currentTable) {
-        const desired = buildEntityAST(this, [entity]).getTable(currentTable.name)?.indexes ?? [];
+        // Keyed by the qualified name, so a table in a schema finds itself rather than reporting that
+        // the entity declares no indexes at all.
+        const desired = buildEntityAST(this, [entity]).getTable(qualifyName(currentTable.name, currentTable.schema))?.indexes ?? [];
         const present = new Set(currentTable.indexes.map((index) => index.name));
         return desired
             .filter((index) => !present.has(index.name) && !this.isInlineVectorIndex(index))
@@ -491,12 +502,12 @@ export class SqlSchemaGenerator {
                 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.escapeId(rel.to.table.name)} (${toCols})` +
+                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 ifNotExists = options.ifNotExists && this.features.ifNotExists ? 'IF NOT EXISTS ' : '';
-        let createSql = `CREATE TABLE ${ifNotExists}${this.escapeId(table.name)} (\n`;
+        let createSql = `CREATE TABLE ${ifNotExists}${this.dialect.escapeQualifiedId(table.name, table.schema)} (\n`;
         createSql += columns.map((col) => `  ${col}`).join(',\n');
         if (constraints.length > 0) {
             createSql += ',\n';
@@ -542,7 +553,8 @@ export class SqlSchemaGenerator {
      * Delegates to `generateCreateIndex` for unified SQL assembly.
      */
     generateCreateIndexFromNode(index, options = { ifNotExists: false }) {
-        return this.generateCreateIndex(index.table.name, indexNodeToSchema(index), options);
+        // The index's own name stays unqualified: it is created in the schema of the table it is on.
+        return this.generateCreateIndex(qualifyName(index.table.name, index.table.schema), indexNodeToSchema(index), options);
     }
     generateCreateTableFromDefinition(table, options = {}) {
         const tableNode = tableDefinitionToNode(table);
@@ -573,7 +585,7 @@ export class SqlSchemaGenerator {
         const refCols = foreignKey.referencesColumns.map((c) => this.escapeId(c)).join(', ');
         const constraintName = foreignKey.name
             ? this.escapeId(foreignKey.name)
-            : this.escapeId(`fk_${tableName}_${foreignKey.columns.join('_')}`);
+            : this.escapeId(derivedForeignKeyName(tableName, foreignKey.columns));
         if (!this.features.foreignKeyAlter) {
             throw new TypeError(`Dialect ${this.dialect} does not support adding foreign keys to existing tables`);
         }
@@ -595,7 +607,10 @@ export class SqlSchemaGenerator {
  */
 export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
     return buildSchemaAST(entities, {
-        resolveTableName: (meta) => generator.resolveTableName(meta),
+        // The alias, not `resolveTableName`: a node holds its schema separately, so that a name derived
+        // from it stays a single identifier.
+        resolveTableName: (meta) => generator.resolveTableAlias(meta),
+        resolveSchema: (meta) => generator.resolveSchema(meta),
         resolveColumnName: (key, field) => generator.resolveColumnName(key, field),
         defaultForeignKeyAction,
     });

package/dist/schema/schemaAST.d.ts

@@ -5,6 +5,12 @@
  * Provides graph operations like navigation, validation, and topological sorting.
  */
 import type { ColumnNode, IndexNode, SchemaAST as ISchemaAST, RelationshipNode, RelationshipType, TableNode, ValidationError } from './types.js';
+/**
+ * A table node with its collections empty, ready to be filled. Six places build one, and the fields
+ * that are pure boilerplate are exactly the ones a new field gets forgotten in: {@link TableNode.schema}
+ * was added and `SchemaAST.clone` kept rebuilding nodes without it.
+ */
+export declare function createTableNode(name: string, schema?: string, comment?: string): TableNode;
 /**
  * Schema AST - A graph representation of a database schema.
  *
@@ -20,7 +26,8 @@ export declare class SchemaAST implements ISchemaAST {
     readonly relationships: RelationshipNode[];
     readonly indexes: IndexNode[];
     /**
-     * Get a table by name.
+     * Get a table by the name it is keyed under: schema-qualified where it has one, so two tables of
+     * the same name in different schemas stay distinct. Build the key with `qualifyName`.
      */
     getTable(name: string): TableNode | undefined;
     /**

package/dist/schema/schemaAST.js

@@ -4,6 +4,24 @@
  * The main class for working with schema graphs.
  * Provides graph operations like navigation, validation, and topological sorting.
  */
+import { qualifyName } from '../util/sql.util.js';
+/**
+ * A table node with its collections empty, ready to be filled. Six places build one, and the fields
+ * that are pure boilerplate are exactly the ones a new field gets forgotten in: {@link TableNode.schema}
+ * was added and `SchemaAST.clone` kept rebuilding nodes without it.
+ */
+export function createTableNode(name, schema, comment) {
+    return {
+        name,
+        schema,
+        comment,
+        columns: new Map(),
+        primaryKey: [],
+        indexes: [],
+        incomingRelations: [],
+        outgoingRelations: [],
+    };
+}
 /**
  * Schema AST - A graph representation of a database schema.
  *
@@ -19,7 +37,8 @@ export class SchemaAST {
     relationships = [];
     indexes = [];
     /**
-     * Get a table by name.
+     * Get a table by the name it is keyed under: schema-qualified where it has one, so two tables of
+     * the same name in different schemas stay distinct. Build the key with `qualifyName`.
      */
     getTable(name) {
         return this.tables.get(name);
@@ -28,8 +47,7 @@ export class SchemaAST {
      * Add a table to the schema.
      */
     addTable(table) {
-        table.schema = this;
-        this.tables.set(table.name, table);
+        this.tables.set(qualifyName(table.name, table.schema), table);
     }
     /**
      * Remove a table from the schema.
@@ -353,16 +371,7 @@ export class SchemaAST {
         // back to it on creation - `columns` and `primaryKey` are readonly properties holding mutable
         // containers, so they are filled in afterwards without reassigning anything.
         for (const [name, table] of this.tables) {
-            const clonedTable = {
-                name,
-                columns: new Map(),
-                primaryKey: [],
-                indexes: [],
-                comment: table.comment,
-                schema: clone,
-                incomingRelations: [],
-                outgoingRelations: [],
-            };
+            const clonedTable = createTableNode(table.name, table.schema, table.comment);
             for (const [colName, col] of table.columns) {
                 clonedTable.columns.set(colName, { ...col, table: clonedTable, referencedBy: [], references: undefined });
             }

package/dist/schema/schemaASTBuilder.d.ts

@@ -8,13 +8,15 @@
 import type { EntityMeta, FieldOptions, Type } from '../type/index.js';
 import type { NamingStrategy } from '../type/namingStrategy.js';
 import { SchemaAST } from './schemaAST.js';
-import type { ForeignKeyAction } from './types.js';
+import { type ForeignKeyAction } from './types.js';
 /**
  * Options for building SchemaAST from entities.
  */
 export interface BuildSchemaASTOptions {
-    /** Custom table name resolver */
+    /** Custom resolver for a table's own name, unqualified. */
     resolveTableName?: (meta: EntityMeta<unknown>) => string;
+    /** Custom resolver for the schema a table lives in; `undefined` leaves it unqualified. */
+    resolveSchema?: (meta: EntityMeta<unknown>) => string | undefined;
     /** Custom column name resolver */
     resolveColumnName?: (key: string, field: FieldOptions) => string;
     /** Naming strategy to use */

package/dist/schema/schemaASTBuilder.js

@@ -6,9 +6,10 @@
  * - Database introspection results (TableSchema[])
  */
 import { getMeta } from '../entity/metadata/definition.js';
+import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
 import { fieldOptionsToCanonical } from './canonicalType.js';
-import { SchemaAST } from './schemaAST.js';
-import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
+import { createTableNode, SchemaAST } from './schemaAST.js';
+import { DEFAULT_FOREIGN_KEY_ACTION, } from './types.js';
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).
  *
@@ -21,6 +22,7 @@ export function buildSchemaAST(entities, options = {}) {
         ast: new SchemaAST(),
         resolveTableName: options.resolveTableName ??
             ((m) => namingStrategy?.tableName(m.name ?? m.entity.name) ?? m.name ?? m.entity.name),
+        resolveSchema: options.resolveSchema ?? ((m) => m.schema),
         resolveColumnName: options.resolveColumnName ?? ((k, f) => namingStrategy?.columnName(f.name ?? k) ?? f.name ?? k),
         defaultForeignKeyAction: options.defaultForeignKeyAction ?? DEFAULT_FOREIGN_KEY_ACTION,
     };
@@ -67,18 +69,8 @@ function resolveColumnCanonicalType(field, seen = new Set()) {
  */
 function addTableFromEntity(ctx, meta) {
     const tableName = ctx.resolveTableName(meta);
-    const columns = new Map();
-    const primaryKey = [];
-    // Create placeholder table (will be fully initialized below)
-    const table = {
-        name: tableName,
-        columns,
-        primaryKey,
-        indexes: [],
-        schema: ctx.ast,
-        incomingRelations: [],
-        outgoingRelations: [],
-    };
+    const table = createTableNode(tableName, ctx.resolveSchema(meta));
+    const { columns, primaryKey } = table;
     // Add columns from fields
     const fields = meta.fields;
     for (const key of Object.keys(fields)) {
@@ -113,12 +105,15 @@ function addTableFromEntity(ctx, meta) {
     }
     ctx.ast.addTable(table);
 }
+/** The node an entity maps to, found under the key {@link SchemaAST} stores it by. */
+function tableOf(ctx, meta) {
+    return ctx.ast.getTable(qualifyName(ctx.resolveTableName(meta), ctx.resolveSchema(meta)));
+}
 /**
  * Add relationships from entity relation decorators.
  */
 function addRelationshipsFromEntity(ctx, meta) {
-    const tableName = ctx.resolveTableName(meta);
-    const table = ctx.ast.getTable(tableName);
+    const table = tableOf(ctx, meta);
     if (!table)
         return;
     const relations = meta.relations;
@@ -126,10 +121,8 @@ function addRelationshipsFromEntity(ctx, meta) {
         const relation = relations[key];
         if (!relation)
             continue;
-        const relatedEntity = relation.entity();
-        const relatedMeta = getMeta(relatedEntity);
-        const relatedTableName = ctx.resolveTableName(relatedMeta);
-        const relatedTable = ctx.ast.getTable(relatedTableName);
+        const relatedMeta = getMeta(relation.entity());
+        const relatedTable = tableOf(ctx, relatedMeta);
         if (!relatedTable)
             continue;
         // Only the owning side gets the FK. `mappedBy` marks the inverse side of a one-to-one, whose
@@ -152,7 +145,7 @@ function addRelationshipsFromEntity(ctx, meta) {
             const foreignColumn = relatedTable.columns.get(foreignColName);
             if (localColumn && foreignColumn) {
                 const relNode = {
-                    name: `fk_${tableName}_${localColName}`,
+                    name: derivedForeignKeyName(table.name, [localColName]),
                     type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
                     from: { table, columns: [localColumn] },
                     to: { table: relatedTable, columns: [foreignColumn] },
@@ -173,8 +166,7 @@ function addRelationshipsFromEntity(ctx, meta) {
  * in common beyond their target table.
  */
 function addIndexesFromEntity(ctx, meta) {
-    const tableName = ctx.resolveTableName(meta);
-    const table = ctx.ast.getTable(tableName);
+    const table = tableOf(ctx, meta);
     if (!table)
         return;
     for (const key of Object.keys(meta.fields)) {
@@ -185,7 +177,7 @@ function addIndexesFromEntity(ctx, meta) {
         if (!column)
             continue;
         ctx.ast.addIndex({
-            name: typeof field.index === 'string' ? field.index : `idx_${tableName}_${column.name}`,
+            name: typeof field.index === 'string' ? field.index : derivedIndexName(table.name, [column.name]),
             table,
             entries: [{ column: column.name }],
             unique: field.unique ?? false,
@@ -224,7 +216,7 @@ function addCompositeIndex(ctx, table, meta, idxMeta) {
     // An index over expressions alone has no column names to build a default name from.
     const named = entries.map((entry, at) => (entry.expression ? `expr${at}` : entry.column));
     ctx.ast.addIndex({
-        name: idxMeta.name ?? `idx_${table.name}_${named.join('_')}`,
+        name: idxMeta.name ?? derivedIndexName(table.name, named),
         table,
         entries,
         include: idxMeta.include?.map((column) => resolveIncludeColumn(ctx, meta, column)),

package/dist/schema/types.d.ts

@@ -98,8 +98,17 @@ export interface ColumnNode {
  * Represents a database table with all its columns, indexes, and relationships.
  */
 export interface TableNode {
-    /** Table name in the database */
+    /**
+     * The table's own name, never qualified. Everything derived from a table reads this: an index or
+     * constraint name is a single identifier, and `idx_sales.Order_total` is a syntax error.
+     */
     readonly name: string;
+    /**
+     * The namespace the table lives in, absent where nothing named one and it resolves through the
+     * connection's own default. Joined onto {@link name} by `qualifyName`, which is the key a
+     * `SchemaAST` stores the table under and the operand a statement names it by.
+     */
+    readonly schema?: string;
     /** Map of column name to column node */
     readonly columns: Map<string, ColumnNode>;
     /** Primary key columns (supports composite keys) */
@@ -108,8 +117,6 @@ export interface TableNode {
     readonly indexes: IndexNode[];
     /** Optional table comment */
     readonly comment?: string;
-    /** Reference to the parent schema */
-    schema: SchemaAST;
     /** Relationships pointing TO this table (other tables referencing this one) */
     incomingRelations: RelationshipNode[];
     /** Relationships pointing FROM this table (this table referencing others) */

package/dist/type/migration.d.ts

@@ -168,7 +168,13 @@ export interface ForeignKeySchema {
  * Represents a difference between current and desired schema
  */
 export interface SchemaDiff {
+    /** Qualified where the table has a schema, since it is also the key the table is found under. */
     readonly tableName: string;
+    /**
+     * The schema {@link tableName} is in, carried separately for the identifiers that live in it
+     * rather than name it: a Postgres index is dropped as `schema.index`, never `schema.table`.
+     */
+    readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
     readonly columnsToAdd?: ColumnSchema[];
     readonly columnsToAlter?: {
@@ -243,9 +249,17 @@ export interface SchemaGenerator {
      */
     diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
     /**
-     * Resolve table name using entity and naming strategy
+     * The table's key: {@link resolveTableAlias} behind {@link resolveSchema}, which is how a
+     * `SchemaAST` stores it and how a diff finds it again.
      */
     resolveTableName<E>(meta: EntityMeta<E>): string;
+    /**
+     * The table's own name, unqualified. What a derived index or constraint name is built from, since
+     * those are single identifiers.
+     */
+    resolveTableAlias<E>(meta: EntityMeta<E>): string;
+    /** The schema the table lives in, `undefined` where nothing named one. */
+    resolveSchema<E>(meta: EntityMeta<E>): string | undefined;
     /**
      * Resolve column name using field options and naming strategy
      */

package/dist/util/sql.util.d.ts

@@ -9,6 +9,23 @@ export declare function unflatObject<T extends object>(row: RawRow, attrsPaths:
 export declare function obtainAttrsPaths<T extends object>(row: T): {
     [k: string]: string[];
 };
+/**
+ * A name behind its namespace, or bare where there is none: the one place the two are joined, so a
+ * table's key, its statement operand and its escaped form cannot spell it differently. Never the
+ * seed for a derived identifier - an index or constraint name is a single identifier, and
+ * `idx_sales.Order_total` is a syntax error.
+ */
+export declare function qualifyName(name: string, schema?: string): string;
+/**
+ * The name a derived index or constraint gets when nothing named it: `idx_Order_total`.
+ *
+ * One owner, because it is a rule two layers apply and a third has to match: the entity AST derives
+ * it, the DDL generator falls back to it, and a diff compares what the database reports against it.
+ * `table` is the table's own name, never qualified - the result is a single identifier.
+ */
+export declare function derivedIndexName(table: string, columns: readonly string[]): string;
+/** The constraint name a foreign key gets when nothing named it: `fk_Order_customerId`. */
+export declare function derivedForeignKeyName(table: string, columns: readonly string[]): string;
 /**
  * Escape a SQL identifier (table name, column name, etc.)
  * @param val the identifier to escape