metal-orm 1.0.14 → 1.0.15

package/src/core/ddl/introspect/postgres.ts

@@ -1,154 +1,245 @@
-import { SchemaIntrospector, IntrospectOptions } from './types.js';
-import { queryRows, shouldIncludeTable } from './utils.js';
-import { DatabaseSchema, DatabaseTable, DatabaseIndex, DatabaseColumn } from '../schema-types.js';
-import { DbExecutor } from '../../orm/db-executor.js';
-
-export const postgresIntrospector: SchemaIntrospector = {
-  async introspect(executor: DbExecutor, options: IntrospectOptions): Promise<DatabaseSchema> {
-    const schema = options.schema || 'public';
-    const tables: DatabaseTable[] = [];
-
-    const columnRows = await queryRows(
-      executor,
-      `
-      SELECT table_schema, table_name, column_name, data_type, is_nullable, column_default
-      FROM information_schema.columns
-      WHERE table_schema = $1
-      ORDER BY table_name, ordinal_position
-      `,
-      [schema]
-    );
-
-    const pkRows = await queryRows(
-      executor,
-      `
-      SELECT
-        ns.nspname AS table_schema,
-        tbl.relname AS table_name,
-        array_agg(att.attname ORDER BY arr.idx) AS pk_columns
-      FROM pg_index i
-      JOIN pg_class tbl ON tbl.oid = i.indrelid
-      JOIN pg_namespace ns ON ns.oid = tbl.relnamespace
-      JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS arr(attnum, idx) ON TRUE
-      LEFT JOIN pg_attribute att ON att.attrelid = tbl.oid AND att.attnum = arr.attnum
-      WHERE i.indisprimary AND ns.nspname = $1
-      GROUP BY ns.nspname, tbl.relname
-      `,
-      [schema]
-    );
-
-    const pkMap = new Map<string, string[]>();
-    pkRows.forEach(r => {
-      pkMap.set(`${r.table_schema}.${r.table_name}`, r.pk_columns || []);
-    });
-
-    const fkRows = await queryRows(
-      executor,
-      `
-      SELECT
-        tc.table_schema,
-        tc.table_name,
-        kcu.column_name,
-        ccu.table_schema AS foreign_table_schema,
-        ccu.table_name AS foreign_table_name,
-        ccu.column_name AS foreign_column_name,
-        rc.update_rule AS on_update,
-        rc.delete_rule AS on_delete
-      FROM information_schema.table_constraints AS tc
-      JOIN information_schema.key_column_usage AS kcu
-        ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
-      JOIN information_schema.constraint_column_usage AS ccu
-        ON ccu.constraint_name = tc.constraint_name AND ccu.table_schema = tc.table_schema
-      JOIN information_schema.referential_constraints rc
-        ON rc.constraint_name = tc.constraint_name AND rc.constraint_schema = tc.table_schema
-      WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_schema = $1
-      `,
-      [schema]
-    );
-
-    const fkMap = new Map<string, any[]>();
-    fkRows.forEach(r => {
-      const key = `${r.table_schema}.${r.table_name}.${r.column_name}`;
-      fkMap.set(key, [{
-        table: `${r.foreign_table_schema}.${r.foreign_table_name}`,
-        column: r.foreign_column_name,
-        onDelete: r.on_delete?.toUpperCase(),
-        onUpdate: r.on_update?.toUpperCase()
-      }]);
-    });
-
-    const indexRows = await queryRows(
-      executor,
-      `
-      SELECT
-        ns.nspname AS table_schema,
-        tbl.relname AS table_name,
-        idx.relname AS index_name,
-        i.indisunique AS is_unique,
-        pg_get_expr(i.indpred, i.indrelid) AS predicate,
-        array_agg(att.attname ORDER BY arr.idx) AS column_names
-      FROM pg_index i
-      JOIN pg_class tbl ON tbl.oid = i.indrelid
-      JOIN pg_namespace ns ON ns.oid = tbl.relnamespace
-      JOIN pg_class idx ON idx.oid = i.indexrelid
-      JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS arr(attnum, idx) ON TRUE
-      LEFT JOIN pg_attribute att ON att.attrelid = tbl.oid AND att.attnum = arr.attnum
-      WHERE ns.nspname = $1 AND NOT i.indisprimary
-      GROUP BY ns.nspname, tbl.relname, idx.relname, i.indisunique, i.indpred
-      `,
-      [schema]
-    );
-
-    const tablesByKey = new Map<string, DatabaseTable>();
-
-    columnRows.forEach(r => {
-      const key = `${r.table_schema}.${r.table_name}`;
-      if (!shouldIncludeTable(r.table_name, options)) {
-        return;
-      }
-      if (!tablesByKey.has(key)) {
-        tablesByKey.set(key, {
-          name: r.table_name,
-          schema: r.table_schema,
-          columns: [],
-          primaryKey: pkMap.get(key) || [],
-          indexes: []
-        });
-      }
-      const cols = tablesByKey.get(key)!;
-      const fk = fkMap.get(`${r.table_schema}.${r.table_name}.${r.column_name}`)?.[0];
-      const column: DatabaseColumn = {
-        name: r.column_name,
-        type: r.data_type,
-        notNull: r.is_nullable === 'NO',
-        default: r.column_default ?? undefined,
-        references: fk
-          ? {
-              table: fk.table,
-              column: fk.column,
-              onDelete: fk.onDelete,
-              onUpdate: fk.onUpdate
-            }
-          : undefined
-      };
-      cols.columns.push(column);
-    });
-
-    indexRows.forEach(r => {
-      const key = `${r.table_schema}.${r.table_name}`;
-      const table = tablesByKey.get(key);
-      if (!table) return;
-      const idx: DatabaseIndex = {
-        name: r.index_name,
-        columns: (r.column_names || []).map((c: string) => ({ column: c })),
-        unique: !!r.is_unique,
-        where: r.predicate || undefined
-      };
-      table.indexes = table.indexes || [];
-      table.indexes.push(idx);
-    });
-
-    tables.push(...tablesByKey.values());
-    return { tables };
-  }
-};
+import type { SchemaIntrospector, IntrospectOptions } from './types.js';
+import { queryRows, shouldIncludeTable } from './utils.js';
+import { DatabaseSchema, DatabaseTable, DatabaseIndex, DatabaseColumn } from '../schema-types.js';
+import type { DbExecutor } from '../../execution/db-executor.js';
+import type { IntrospectContext } from './context.js';
+import { PgInformationSchemaColumns } from './catalogs/postgres.js';
+import { PgKeyColumnUsage, PgTableConstraints, PgConstraintColumnUsage, PgReferentialConstraints, PgIndex, PgClass, PgNamespace, PgAttribute } from './catalogs/postgres.js';
+import { SelectQueryBuilder } from '../../../query-builder/select.js';
+import { eq, and } from '../../ast/expression-builders.js';
+import type { SelectQueryNode, TableNode } from '../../ast/query.js';
+import type { JoinNode } from '../../ast/join.js';
+import type { ColumnNode, ExpressionNode } from '../../ast/expression-nodes.js';
+import { fnTable } from '../../ast/builders.js';
+import { runSelect, runSelectNode } from './run-select.js';
+
+export const postgresIntrospector: SchemaIntrospector = {
+  async introspect(ctx: IntrospectContext, options: IntrospectOptions): Promise<DatabaseSchema> {
+    const schema = options.schema || 'public';
+    const tables: DatabaseTable[] = [];
+
+    // Columns query
+    const qbColumns = new SelectQueryBuilder(PgInformationSchemaColumns as any)
+      .select({
+        table_schema: PgInformationSchemaColumns.columns.table_schema,
+        table_name: PgInformationSchemaColumns.columns.table_name,
+        column_name: PgInformationSchemaColumns.columns.column_name,
+        data_type: PgInformationSchemaColumns.columns.data_type,
+        is_nullable: PgInformationSchemaColumns.columns.is_nullable,
+        column_default: PgInformationSchemaColumns.columns.column_default,
+        ordinal_position: PgInformationSchemaColumns.columns.ordinal_position
+      })
+      .where(eq(PgInformationSchemaColumns.columns.table_schema, schema))
+      .orderBy(PgInformationSchemaColumns.columns.table_name)
+      .orderBy(PgInformationSchemaColumns.columns.ordinal_position);
+
+    const columnRows = await runSelect(qbColumns, ctx);
+
+    // Primary key columns query
+    const qbPk = new SelectQueryBuilder(PgKeyColumnUsage as any)
+      .select({
+        table_schema: PgKeyColumnUsage.columns.table_schema,
+        table_name: PgKeyColumnUsage.columns.table_name,
+        column_name: PgKeyColumnUsage.columns.column_name,
+        ordinal_position: PgKeyColumnUsage.columns.ordinal_position,
+        constraint_name: PgKeyColumnUsage.columns.constraint_name
+      })
+      .innerJoin(PgTableConstraints as any, eq(PgTableConstraints.columns.constraint_name, PgKeyColumnUsage.columns.constraint_name))
+      .where(eq(PgTableConstraints.columns.constraint_type, 'PRIMARY KEY'))
+      .where(eq(PgKeyColumnUsage.columns.table_schema, schema))
+      .orderBy(PgKeyColumnUsage.columns.table_name)
+      .orderBy(PgKeyColumnUsage.columns.ordinal_position);
+
+    const pkRows = await runSelect(qbPk, ctx);
+
+    // Build primary key map (grouped by table, ordered by ordinal_position)
+    const pkMap = new Map<string, string[]>();
+    const pkGrouped = new Map<string, { pos: number; col: string }[]>();
+    for (const r of pkRows) {
+      const key = `${r.table_schema}.${r.table_name}`;
+      const arr = pkGrouped.get(key) ?? [];
+      arr.push({ pos: r.ordinal_position ?? 0, col: r.column_name });
+      pkGrouped.set(key, arr);
+    }
+    for (const [k, vals] of pkGrouped.entries()) {
+      vals.sort((a, b) => (a.pos || 0) - (b.pos || 0));
+      pkMap.set(k, vals.map(v => v.col));
+    }
+
+    // Foreign key columns query
+    const qbFk = new SelectQueryBuilder(PgKeyColumnUsage as any)
+      .select({
+        table_schema: PgKeyColumnUsage.columns.table_schema,
+        table_name: PgKeyColumnUsage.columns.table_name,
+        column_name: PgKeyColumnUsage.columns.column_name,
+        constraint_name: PgKeyColumnUsage.columns.constraint_name,
+        foreign_table_schema: PgConstraintColumnUsage.columns.table_schema,
+        foreign_table_name: PgConstraintColumnUsage.columns.table_name,
+        foreign_column_name: PgConstraintColumnUsage.columns.column_name
+      })
+      .innerJoin(PgTableConstraints as any, eq(PgTableConstraints.columns.constraint_name, PgKeyColumnUsage.columns.constraint_name))
+      .innerJoin(PgConstraintColumnUsage as any, eq(PgConstraintColumnUsage.columns.constraint_name, PgTableConstraints.columns.constraint_name))
+      .innerJoin(PgReferentialConstraints as any, eq(PgReferentialConstraints.columns.constraint_name, PgTableConstraints.columns.constraint_name))
+      .where(eq(PgTableConstraints.columns.constraint_type, 'FOREIGN KEY'))
+      .where(eq(PgKeyColumnUsage.columns.table_schema, schema));
+
+    const fkRows = await runSelect(qbFk, ctx);
+
+    // Build foreign key map
+    const fkMap = new Map<string, any[]>();
+    for (const r of fkRows) {
+      const key = `${r.table_schema}.${r.table_name}.${r.column_name}`;
+      const existing = fkMap.get(key) ?? [];
+      existing.push({
+        table: `${r.foreign_table_schema}.${r.foreign_table_name}`,
+        column: r.foreign_column_name,
+        onDelete: undefined,
+        onUpdate: undefined
+      });
+      fkMap.set(key, existing);
+    }
+
+    // Index columns query using AST with FunctionTable for unnest
+    const indexQuery: SelectQueryNode = {
+      type: 'SelectQuery',
+      from: { type: 'Table', name: 'pg_index', schema: 'pg_catalog', alias: 'i' } as TableNode,
+      columns: [
+        { type: 'Column', table: 'ns', name: 'nspname', alias: 'table_schema' } as ColumnNode,
+        { type: 'Column', table: 'tbl', name: 'relname', alias: 'table_name' } as ColumnNode,
+        { type: 'Column', table: 'idx', name: 'relname', alias: 'index_name' } as ColumnNode,
+        { type: 'Column', table: 'i', name: 'indisunique', alias: 'is_unique' } as ColumnNode,
+        { type: 'Column', table: 'i', name: 'indpred', alias: 'predicate' } as ColumnNode,
+        { type: 'Column', table: 'att', name: 'attname', alias: 'attname' } as ColumnNode,
+        { type: 'Column', table: 'arr', name: 'idx', alias: 'ord' } as ColumnNode
+      ],
+      joins: [
+        // JOIN pg_class AS tbl ON tbl.oid = i.indrelid
+        {
+          type: 'Join',
+          kind: 'INNER',
+          table: { type: 'Table', name: 'pg_class', schema: 'pg_catalog', alias: 'tbl' } as TableNode,
+          condition: eq({ table: 'tbl', name: 'oid' }, { table: 'i', name: 'indrelid' }) as ExpressionNode
+        } as JoinNode,
+        // JOIN pg_namespace AS ns ON ns.oid = tbl.relnamespace
+        {
+          type: 'Join',
+          kind: 'INNER',
+          table: { type: 'Table', name: 'pg_namespace', schema: 'pg_catalog', alias: 'ns' } as TableNode,
+          condition: eq({ table: 'ns', name: 'oid' }, { table: 'tbl', name: 'relnamespace' }) as ExpressionNode
+        } as JoinNode,
+        // JOIN pg_class AS idx ON idx.oid = i.indexrelid
+        {
+          type: 'Join',
+          kind: 'INNER',
+          table: { type: 'Table', name: 'pg_class', schema: 'pg_catalog', alias: 'idx' } as TableNode,
+          condition: eq({ table: 'idx', name: 'oid' }, { table: 'i', name: 'indexrelid' }) as ExpressionNode
+        } as JoinNode,
+        // LATERAL JOIN UNNEST(i.indkey) WITH ORDINALITY AS arr(attnum, idx)
+        {
+          type: 'Join',
+          kind: 'INNER',
+          table: fnTable('unnest', [{ type: 'Column', table: 'i', name: 'indkey' } as ColumnNode], 'arr', { 
+            lateral: true, 
+            withOrdinality: true, 
+            columnAliases: ['attnum', 'idx'] 
+          }),
+          condition: { type: 'BinaryExpression', left: { type: 'Literal', value: 1 }, operator: '=', right: { type: 'Literal', value: 1 } } as unknown as ExpressionNode
+        } as JoinNode,
+        // LEFT JOIN pg_attribute AS att ON att.attrelid = tbl.oid AND att.attnum = arr.attnum
+        {
+          type: 'Join',
+          kind: 'LEFT',
+          table: { type: 'Table', name: 'pg_attribute', schema: 'pg_catalog', alias: 'att' } as TableNode,
+          condition: and(
+            eq({ table: 'att', name: 'attrelid' }, { table: 'tbl', name: 'oid' }),
+            eq({ table: 'att', name: 'attnum' }, { table: 'arr', name: 'attnum' })
+          ) as ExpressionNode
+        } as JoinNode
+      ],
+      where: and(
+        eq({ table: 'ns', name: 'nspname' }, schema) as ExpressionNode,
+        eq({ table: 'i', name: 'indisprimary' }, { type: 'Literal', value: false } as any) as ExpressionNode
+      ) as ExpressionNode
+    };
+
+    const indexQueryRows = await runSelectNode(indexQuery, ctx);
+    
+    // Aggregate index rows by table/index to build final index list
+    const indexGrouped = new Map<string, { table_schema: string; table_name: string; index_name: string; is_unique: any; predicate: any; cols: { ord: number; att: string | null }[] }>();
+    for (const r of indexQueryRows) {
+      const key = `${r.table_schema}.${r.table_name}.${r.index_name}`;
+      const entry = indexGrouped.get(key) ?? { 
+        table_schema: r.table_schema, 
+        table_name: r.table_name, 
+        index_name: r.index_name, 
+        is_unique: r.is_unique, 
+        predicate: r.predicate, 
+        cols: [] 
+      };
+      entry.cols.push({ ord: r.ord ?? 0, att: r.attname ?? null });
+      indexGrouped.set(key, entry);
+    }
+
+    const indexRows = Array.from(indexGrouped.values()).map(v => ({
+      table_schema: v.table_schema,
+      table_name: v.table_name,
+      index_name: v.index_name,
+      is_unique: v.is_unique,
+      predicate: v.predicate,
+      column_names: v.cols.sort((a, b) => (a.ord || 0) - (b.ord || 0)).map(c => c.att).filter(Boolean)
+    }));
+
+    // Build final schema
+    const tablesByKey = new Map<string, DatabaseTable>();
+
+    columnRows.forEach(r => {
+      const key = `${r.table_schema}.${r.table_name}`;
+      if (!shouldIncludeTable(r.table_name, options)) {
+        return;
+      }
+      if (!tablesByKey.has(key)) {
+        tablesByKey.set(key, {
+          name: r.table_name,
+          schema: r.table_schema,
+          columns: [],
+          primaryKey: pkMap.get(key) || [],
+          indexes: []
+        });
+      }
+      const cols = tablesByKey.get(key)!;
+      const fk = fkMap.get(`${r.table_schema}.${r.table_name}.${r.column_name}`)?.[0];
+      const column: DatabaseColumn = {
+        name: r.column_name,
+        type: r.data_type,
+        notNull: r.is_nullable === 'NO',
+        default: r.column_default ?? undefined,
+        references: fk
+          ? {
+              table: fk.table,
+              column: fk.column,
+              onDelete: fk.onDelete,
+              onUpdate: fk.onUpdate
+            }
+          : undefined
+      };
+      cols.columns.push(column);
+    });
+
+    indexRows.forEach(r => {
+      const key = `${r.table_schema}.${r.table_name}`;
+      const table = tablesByKey.get(key);
+      if (!table) return;
+      const idx: DatabaseIndex = {
+        name: r.index_name,
+        columns: (r.column_names || []).map((c: string) => ({ column: c })),
+        unique: !!r.is_unique,
+        where: r.predicate || undefined
+      };
+      table.indexes = table.indexes || [];
+      table.indexes.push(idx);
+    });
+
+    tables.push(...tablesByKey.values());
+    return { tables };
+  }
+};

package/src/core/ddl/introspect/registry.ts

@@ -0,0 +1,26 @@
+import type { DialectName } from '../schema-generator.js';
+import type { SchemaIntrospector } from './types.js';
+import { postgresIntrospector } from './postgres.js';
+import { mysqlIntrospector } from './mysql.js';
+import { sqliteIntrospector } from './sqlite.js';
+import { mssqlIntrospector } from './mssql.js';
+
+const registry = new Map<DialectName, SchemaIntrospector>();
+
+const registerBuiltInIntrospectors = () => {
+  registry.set('postgres', postgresIntrospector);
+  registry.set('mysql', mysqlIntrospector);
+  registry.set('sqlite', sqliteIntrospector);
+  registry.set('mssql', mssqlIntrospector);
+};
+
+registerBuiltInIntrospectors();
+
+export const registerSchemaIntrospector = (dialect: DialectName, introspector: SchemaIntrospector): void => {
+  registry.set(dialect, introspector);
+};
+
+export const getSchemaIntrospector = (dialect: DialectName): SchemaIntrospector | undefined => {
+  return registry.get(dialect);
+};
+

package/src/core/ddl/introspect/run-select.ts

@@ -0,0 +1,25 @@
+import type { SelectQueryBuilder } from '../../../query-builder/select.js';
+import type { IntrospectContext } from './context.js';
+
+import { toRows } from './utils.js';
+
+export async function runSelect<T = Record<string, any>>(
+  qb: SelectQueryBuilder<any, any>,
+  ctx: IntrospectContext
+): Promise<T[]> {
+  const ast = qb.getAST();
+  const compiled = ctx.dialect.compileSelect(ast);
+  const results = await ctx.executor.executeSql(compiled.sql, compiled.params);
+  // executor returns QueryResult[]; take the first result set and map to rows
+  const [first] = results;
+  return toRows(first) as T[];
+}
+
+export default runSelect;
+
+export async function runSelectNode<T = Record<string, any>>(ast: any, ctx: IntrospectContext): Promise<T[]> {
+  const compiled = ctx.dialect.compileSelect(ast);
+  const results = await ctx.executor.executeSql(compiled.sql, compiled.params);
+  const [first] = results;
+  return toRows(first) as T[];
+}

package/src/core/ddl/introspect/sqlite.ts

@@ -1,15 +1,15 @@
 import { SchemaIntrospector, IntrospectOptions } from './types.js';
 import { queryRows, shouldIncludeTable } from './utils.js';
 import { DatabaseSchema, DatabaseTable, DatabaseIndex } from '../schema-types.js';
-import { DbExecutor } from '../../orm/db-executor.js';
+import { DbExecutor } from '../../execution/db-executor.js';
 
 const escapeSingleQuotes = (name: string) => name.replace(/'/g, "''");
 
 export const sqliteIntrospector: SchemaIntrospector = {
-  async introspect(executor: DbExecutor, options: IntrospectOptions): Promise<DatabaseSchema> {
+  async introspect(ctx: { executor: DbExecutor }, options: IntrospectOptions): Promise<DatabaseSchema> {
     const tables: DatabaseTable[] = [];
     const tableRows = await queryRows(
-      executor,
+      ctx.executor,
       `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%';`
     );
 
@@ -18,7 +18,7 @@ export const sqliteIntrospector: SchemaIntrospector = {
       if (!shouldIncludeTable(name, options)) continue;
       const table: DatabaseTable = { name, columns: [], primaryKey: [], indexes: [] };
 
-      const cols = await queryRows(executor, `PRAGMA table_info('${escapeSingleQuotes(name)}');`);
+      const cols = await queryRows(ctx.executor, `PRAGMA table_info('${escapeSingleQuotes(name)}');`);
       cols.forEach(c => {
         table.columns.push({
           name: c.name,
@@ -33,7 +33,7 @@ export const sqliteIntrospector: SchemaIntrospector = {
         }
       });
 
-      const fkRows = await queryRows(executor, `PRAGMA foreign_key_list('${escapeSingleQuotes(name)}');`);
+      const fkRows = await queryRows(ctx.executor, `PRAGMA foreign_key_list('${escapeSingleQuotes(name)}');`);
       fkRows.forEach(fk => {
         const col = table.columns.find(c => c.name === fk.from);
         if (col) {
@@ -46,10 +46,10 @@ export const sqliteIntrospector: SchemaIntrospector = {
         }
       });
 
-      const idxList = await queryRows(executor, `PRAGMA index_list('${escapeSingleQuotes(name)}');`);
+      const idxList = await queryRows(ctx.executor, `PRAGMA index_list('${escapeSingleQuotes(name)}');`);
       for (const idx of idxList) {
         const idxName = idx.name as string;
-        const columnsInfo = await queryRows(executor, `PRAGMA index_info('${escapeSingleQuotes(idxName)}');`);
+        const columnsInfo = await queryRows(ctx.executor, `PRAGMA index_info('${escapeSingleQuotes(idxName)}');`);
         const idxEntry: DatabaseIndex = {
           name: idxName,
           columns: columnsInfo.map(ci => ({ column: ci.name as string })),

package/src/core/ddl/introspect/types.ts

@@ -1,19 +1,23 @@
-import type { DbExecutor } from '../../../orm/db-executor.js';
-import { DatabaseSchema } from '../schema-types.js';
-
-/**
- * Dialect-agnostic options for schema introspection.
- */
-export interface IntrospectOptions {
-  /** Dialect-specific schema/catalog. Postgres: schema; MySQL: database; MSSQL: schema. */
-  schema?: string;
-  includeTables?: string[];
-  excludeTables?: string[];
-}
-
-/**
- * Strategy interface implemented per dialect to introspect an existing database schema.
- */
-export interface SchemaIntrospector {
-  introspect(executor: DbExecutor, options: IntrospectOptions): Promise<DatabaseSchema>;
-}
+import type { DbExecutor } from '../../execution/db-executor.js';
+import { DatabaseSchema } from '../schema-types.js';
+import type { IntrospectContext } from './context.js';
+
+export type { IntrospectContext };
+
+/**
+ * Dialect-agnostic options for schema introspection.
+ */
+export interface IntrospectOptions {
+  /** Dialect-specific schema/catalog. Postgres: schema; MySQL: database; MSSQL: schema. */
+  schema?: string;
+  includeTables?: string[];
+  excludeTables?: string[];
+}
+
+/**
+ * Strategy interface implemented per dialect to introspect an existing database schema.
+ */
+export interface SchemaIntrospector {
+  // Requires IntrospectContext with both dialect and executor
+  introspect(ctx: IntrospectContext, options: IntrospectOptions): Promise<DatabaseSchema>;
+}

package/src/core/ddl/introspect/utils.ts

@@ -1,4 +1,4 @@
-import { DbExecutor, QueryResult } from '../../orm/db-executor.js';
+import { DbExecutor, QueryResult } from '../../execution/db-executor.js';
 import { IntrospectOptions } from './types.js';
 
 export const toRows = (result: QueryResult | undefined): Record<string, any>[] => {

package/src/core/ddl/naming-strategy.ts

@@ -0,0 +1,10 @@
+import type { TableDef, IndexDef } from '../../schema/table.js';
+
+export const deriveIndexName = (table: TableDef, index: IndexDef): string => {
+  const base = (index.columns ?? [])
+    .map(col => (typeof col === 'string' ? col : col.column))
+    .join('_');
+
+  const suffix = index.unique ? 'uniq' : 'idx';
+  return `${table.name}_${base}_${suffix}`;
+};

package/src/core/ddl/schema-dialect.ts

@@ -0,0 +1,41 @@
+import type { TableDef, IndexDef } from '../../schema/table.js';
+import type { ColumnDef, ForeignKeyReference } from '../../schema/column.js';
+import type { DatabaseTable, DatabaseColumn, ColumnDiff } from './schema-types.js';
+
+export type DialectName =
+  | 'postgres'
+  | 'mysql'
+  | 'sqlite'
+  | 'mssql'
+  | (string & {});
+
+export interface SchemaDialect {
+  readonly name: DialectName;
+
+  // Minimal quoting surface; reusable for helpers
+  quoteIdentifier(id: string): string;
+
+  // Table naming
+  formatTableName(table: TableDef | DatabaseTable): string;
+
+  // Column rendering
+  renderColumnType(column: ColumnDef): string;
+  renderDefault(value: unknown, column: ColumnDef): string;
+  renderAutoIncrement(column: ColumnDef, table: TableDef): string | undefined;
+
+  // Constraints & indexes
+  renderReference(ref: ForeignKeyReference, table: TableDef): string;
+  renderIndex(table: TableDef, index: IndexDef): string;
+  renderTableOptions(table: TableDef): string | undefined;
+
+  // Capability flags
+  supportsPartialIndexes(): boolean;
+
+  // DDL operations
+  dropColumnSql?(table: DatabaseTable, column: string): string[];
+  dropIndexSql?(table: DatabaseTable, index: string): string[];
+  dropTableSql?(table: DatabaseTable): string[];
+  warnDropColumn?(table: DatabaseTable, column: string): string | undefined;
+  alterColumnSql?(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string[];
+  warnAlterColumn?(table: TableDef, column: ColumnDef, actualColumn: DatabaseColumn, diff: ColumnDiff): string | undefined;
+}