@prisma-next/target-postgres 0.3.0-dev.12 → 0.3.0-dev.122

package/src/core/migrations/planner.ts

@@ -1,5 +1,13 @@
+import {
+  escapeLiteral,
+  normalizeSchemaNativeType,
+  parsePostgresDefault,
+  quoteIdentifier,
+} from '@prisma-next/adapter-postgres/control';
 import type { SchemaIssue } from '@prisma-next/core-control-plane/types';
 import type {
+  CodecControlHooks,
+  ComponentDatabaseDependency,
   MigrationOperationPolicy,
   SqlMigrationPlanner,
   SqlMigrationPlannerPlanOptions,
@@ -7,21 +15,45 @@ import type {
   SqlPlannerConflict,
 } from '@prisma-next/family-sql/control';
 import {
+  collectInitDependencies,
   createMigrationPlan,
+  extractCodecControlHooks,
   plannerFailure,
   plannerSuccess,
 } from '@prisma-next/family-sql/control';
-import { arraysEqual, verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
-import type {
-  ForeignKey,
-  SqlContract,
-  SqlStorage,
-  StorageColumn,
-  StorageTable,
-} from '@prisma-next/sql-contract/types';
+import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
+import type { ForeignKey, StorageColumn, StorageTable } from '@prisma-next/sql-contract/types';
+import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
-
-type OperationClass = 'extension' | 'table' | 'unique' | 'index' | 'foreignKey';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { resolveIdentityValue } from './planner-identity-values';
+import {
+  buildAddColumnOperationIdentity,
+  buildAddNotNullColumnWithTemporaryDefaultOperation,
+} from './planner-recipes';
+import { buildReconciliationPlan } from './planner-reconciliation';
+import {
+  buildAddColumnSql,
+  buildCreateTableSql,
+  buildForeignKeySql,
+  columnExistsCheck,
+  columnNullabilityCheck,
+  constraintExistsCheck,
+  qualifyTableName,
+  tableIsEmptyCheck,
+  toRegclassLiteral,
+} from './planner-sql';
+import { buildTargetDetails } from './planner-target-details';
+
+export type OperationClass =
+  | 'dependency'
+  | 'type'
+  | 'table'
+  | 'column'
+  | 'primaryKey'
+  | 'unique'
+  | 'index'
+  | 'foreignKey';
 
 type PlannerFrameworkComponents = SqlMigrationPlannerPlanOptions extends {
   readonly frameworkComponents: infer T;
@@ -41,7 +73,6 @@ type PlannerDatabaseDependency = {
   readonly id: string;
   readonly label: string;
   readonly install: readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[];
-  readonly verifyDatabaseDependencyInstalled: (schema: SqlSchemaIR) => readonly SchemaIssue[];
 };
 
 export interface PostgresPlanTargetDetails {
@@ -55,6 +86,12 @@ interface PlannerConfig {
   readonly defaultSchema: string;
 }
 
+export interface PlanningMode {
+  readonly includeExtraObjects: boolean;
+  readonly allowWidening: boolean;
+  readonly allowDestructive: boolean;
+}
+
 const DEFAULT_PLANNER_CONFIG: PlannerConfig = {
   defaultSchema: 'public',
 };
@@ -78,38 +115,64 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
       return policyResult;
     }
 
-    const classification = this.classifySchema(options);
-    if (classification.kind === 'conflict') {
-      return plannerFailure(classification.conflicts);
-    }
+    const planningMode = this.resolvePlanningMode(options.policy);
+    const schemaIssues = this.collectSchemaIssues(options, planningMode.includeExtraObjects);
+
+    // Extract codec control hooks once at entry point for reuse across all operations.
+    // This avoids repeated iteration over frameworkComponents for each method that needs hooks.
+    const codecHooks = extractCodecControlHooks(options.frameworkComponents);
 
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
 
+    const reconciliationPlan = buildReconciliationPlan({
+      contract: options.contract,
+      issues: schemaIssues,
+      schemaName,
+      mode: planningMode,
+      policy: options.policy,
+      codecHooks,
+    });
+    if (reconciliationPlan.conflicts.length > 0) {
+      return plannerFailure(reconciliationPlan.conflicts);
+    }
+
+    const storageTypePlan = this.buildStorageTypeOperations(options, schemaName, codecHooks);
+    if (storageTypePlan.conflicts.length > 0) {
+      return plannerFailure(storageTypePlan.conflicts);
+    }
+
+    // Sort table entries once for reuse across all additive operation builders.
+    const sortedTables = sortedEntries(options.contract.storage.tables);
+
+    // Pre-compute constraint lookups once per schema table for O(1) checks across all builders.
+    const schemaLookups = buildSchemaLookupMap(options.schema);
+
     // Build extension operations from component-owned database dependencies
     operations.push(
       ...this.buildDatabaseDependencyOperations(options),
-      ...this.buildTableOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildColumnOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildPrimaryKeyOperations(
-        options.contract.storage.tables,
-        options.schema,
-        schemaName,
-      ),
-      ...this.buildUniqueOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildIndexOperations(options.contract.storage.tables, options.schema, schemaName),
-      ...this.buildForeignKeyOperations(
-        options.contract.storage.tables,
+      ...storageTypePlan.operations,
+      ...reconciliationPlan.operations,
+      ...this.buildTableOperations(sortedTables, options.schema, schemaName, codecHooks),
+      ...this.buildColumnOperations(
+        sortedTables,
         options.schema,
+        schemaLookups,
         schemaName,
+        codecHooks,
       ),
+      ...this.buildPrimaryKeyOperations(sortedTables, options.schema, schemaName),
+      ...this.buildUniqueOperations(sortedTables, schemaLookups, schemaName),
+      ...this.buildIndexOperations(sortedTables, schemaLookups, schemaName),
+      ...this.buildFkBackingIndexOperations(sortedTables, schemaLookups, schemaName),
+      ...this.buildForeignKeyOperations(sortedTables, schemaLookups, schemaName),
     );
 
     const plan = createMigrationPlan<PostgresPlanTargetDetails>({
       targetId: 'postgres',
       origin: null,
       destination: {
-        coreHash: options.contract.coreHash,
-        ...(options.contract.profileHash ? { profileHash: options.contract.profileHash } : {}),
+        storageHash: options.contract.storageHash,
+        ...ifDefined('profileHash', options.contract.profileHash),
       },
       operations,
     });
@@ -122,8 +185,8 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
       return plannerFailure([
         {
           kind: 'unsupportedOperation',
-          summary: 'Init planner requires additive operations be allowed',
-          why: 'The init planner only emits additive operations. Update the policy to include "additive".',
+          summary: 'Migration planner requires additive operations be allowed',
+          why: 'The planner requires the "additive" operation class to be allowed in the policy.',
         },
       ]);
     }
@@ -142,14 +205,15 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
     const seenDependencyIds = new Set<string>();
     const seenOperationIds = new Set<string>();
 
+    const installedIds = new Set(options.schema.dependencies.map((d) => d.id));
+
     for (const dependency of dependencies) {
       if (seenDependencyIds.has(dependency.id)) {
         continue;
       }
       seenDependencyIds.add(dependency.id);
 
-      const issues = dependency.verifyDatabaseDependencyInstalled(options.schema);
-      if (issues.length === 0) {
+      if (installedIds.has(dependency.id)) {
         continue;
       }
 
@@ -158,41 +222,76 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
           continue;
         }
         seenOperationIds.add(installOp.id);
-        // SQL family components are expected to provide compatible target details. This would be better if
-        // the type system could enforce it but it's not likely to occur in practice.
         operations.push(installOp as SqlMigrationPlanOperation<PostgresPlanTargetDetails>);
       }
     }
 
     return operations;
   }
-  private collectDependencies(
+
+  private buildStorageTypeOperations(
     options: PlannerOptionsWithComponents,
-  ): ReadonlyArray<PlannerDatabaseDependency> {
-    const components = options.frameworkComponents;
-    if (components.length === 0) {
-      return [];
-    }
-    const deps: PlannerDatabaseDependency[] = [];
-    for (const component of components) {
-      if (!isSqlDependencyProvider(component)) {
+    schemaName: string,
+    codecHooks: Map<string, CodecControlHooks>,
+  ): {
+    readonly operations: readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[];
+    readonly conflicts: readonly SqlPlannerConflict[];
+  } {
+    const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
+    const conflicts: SqlPlannerConflict[] = [];
+    const storageTypes = options.contract.storage.types ?? {};
+
+    for (const [typeName, typeInstance] of sortedEntries(storageTypes)) {
+      const hook = codecHooks.get(typeInstance.codecId);
+      const planResult = hook?.planTypeOperations?.({
+        typeName,
+        typeInstance,
+        contract: options.contract,
+        schema: options.schema,
+        schemaName,
+        policy: options.policy,
+      });
+      if (!planResult) {
         continue;
       }
-      const initDeps = component.databaseDependencies?.init;
-      if (initDeps && initDeps.length > 0) {
-        deps.push(...initDeps);
+      for (const operation of planResult.operations) {
+        if (!options.policy.allowedOperationClasses.includes(operation.operationClass)) {
+          conflicts.push({
+            kind: 'missingButNonAdditive',
+            summary: `Storage type "${typeName}" requires "${operation.operationClass}" operation "${operation.id}"`,
+            location: {
+              type: typeName,
+            },
+          });
+          continue;
+        }
+        operations.push({
+          ...operation,
+          target: {
+            id: operation.target.id,
+            details: this.buildTargetDetails('type', typeName, schemaName),
+          },
+        });
       }
     }
-    return sortDependencies(deps);
+
+    return { operations, conflicts };
+  }
+  private collectDependencies(
+    options: PlannerOptionsWithComponents,
+  ): ReadonlyArray<PlannerDatabaseDependency> {
+    const dependencies = collectInitDependencies(options.frameworkComponents);
+    return sortDependencies(dependencies.filter(isPostgresPlannerDependency));
   }
 
   private buildTableOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
+    tables: ReadonlyArray<[string, StorageTable]>,
     schema: SqlSchemaIR,
     schemaName: string,
+    codecHooks: Map<string, CodecControlHooks>,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
+    for (const [tableName, table] of tables) {
       if (schema.tables[tableName]) {
         continue;
       }
@@ -215,7 +314,7 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
         execute: [
           {
             description: `create table "${tableName}"`,
-            sql: buildCreateTableSql(qualified, table),
+            sql: buildCreateTableSql(qualified, table, codecHooks),
           },
         ],
         postcheck: [
@@ -230,91 +329,135 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
   }
 
   private buildColumnOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
+    tables: ReadonlyArray<[string, StorageTable]>,
     schema: SqlSchemaIR,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
+    codecHooks: Map<string, CodecControlHooks>,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
+    for (const [tableName, table] of tables) {
       const schemaTable = schema.tables[tableName];
       if (!schemaTable) {
         continue;
       }
+      const schemaLookup = schemaLookups.get(tableName);
       for (const [columnName, column] of sortedEntries(table.columns)) {
         if (schemaTable.columns[columnName]) {
           continue;
         }
-        operations.push(this.buildAddColumnOperation(schemaName, tableName, columnName, column));
+        operations.push(
+          this.buildAddColumnOperation({
+            schema: schemaName,
+            tableName,
+            table,
+            schemaTable,
+            schemaLookup,
+            columnName,
+            column,
+            codecHooks,
+          }),
+        );
       }
     }
     return operations;
   }
 
-  private buildAddColumnOperation(
-    schema: string,
-    tableName: string,
-    columnName: string,
-    column: StorageColumn,
-  ): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
-    const qualified = qualifyTableName(schema, tableName);
+  private buildAddColumnOperation(options: {
+    readonly schema: string;
+    readonly tableName: string;
+    readonly table: StorageTable;
+    readonly schemaTable: SqlSchemaIR['tables'][string];
+    readonly schemaLookup: SchemaTableLookup | undefined;
+    readonly columnName: string;
+    readonly column: StorageColumn;
+    readonly codecHooks: Map<string, CodecControlHooks>;
+  }): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+    const { schema, tableName, table, schemaTable, schemaLookup, columnName, column, codecHooks } =
+      options;
     const notNull = column.nullable === false;
-    const precheck = [
-      {
-        description: `ensure column "${columnName}" is missing`,
-        sql: columnExistsCheck({ schema, table: tableName, column: columnName, exists: false }),
-      },
-      ...(notNull
-        ? [
-            {
-              description: `ensure table "${tableName}" is empty before adding NOT NULL column`,
-              sql: tableIsEmptyCheck(qualified),
-            },
-          ]
-        : []),
-    ];
-    const execute = [
-      {
-        description: `add column "${columnName}"`,
-        sql: buildAddColumnSql(qualified, columnName, column),
-      },
-    ];
-    const postcheck = [
-      {
-        description: `verify column "${columnName}" exists`,
-        sql: columnExistsCheck({ schema, table: tableName, column: columnName }),
-      },
-      ...(notNull
-        ? [
-            {
-              description: `verify column "${columnName}" is NOT NULL`,
-              sql: columnIsNotNullCheck({ schema, table: tableName, column: columnName }),
-            },
-          ]
-        : []),
-    ];
+    const hasDefault = column.default !== undefined;
+    // Planner logic decides whether this column needs the coordinated multi-step
+    // strategy. The strategy recipe itself is built by a dedicated helper.
+    const needsTemporaryDefault = notNull && !hasDefault;
+    const temporaryDefault = needsTemporaryDefault
+      ? resolveIdentityValue(column, codecHooks)
+      : null;
+    const canUseSharedTemporaryDefault =
+      needsTemporaryDefault &&
+      temporaryDefault !== null &&
+      canUseSharedTemporaryDefaultStrategy({
+        table,
+        schemaTable,
+        schemaLookup,
+        columnName,
+      });
+
+    if (canUseSharedTemporaryDefault) {
+      return buildAddNotNullColumnWithTemporaryDefaultOperation({
+        schema,
+        tableName,
+        columnName,
+        column,
+        codecHooks,
+        temporaryDefault,
+      });
+    }
 
+    const qualified = qualifyTableName(schema, tableName);
+    const requiresEmptyTableCheck = needsTemporaryDefault && !canUseSharedTemporaryDefault;
     return {
-      id: `column.${tableName}.${columnName}`,
-      label: `Add column ${columnName} to ${tableName}`,
-      summary: `Adds column ${columnName} to table ${tableName}`,
+      ...buildAddColumnOperationIdentity(schema, tableName, columnName),
       operationClass: 'additive',
-      target: {
-        id: 'postgres',
-        details: this.buildTargetDetails('table', tableName, schema),
-      },
-      precheck,
-      execute,
-      postcheck,
+      precheck: [
+        {
+          description: `ensure column "${columnName}" is missing`,
+          sql: columnExistsCheck({ schema, table: tableName, column: columnName, exists: false }),
+        },
+        ...(requiresEmptyTableCheck
+          ? [
+              {
+                description: `ensure table "${tableName}" is empty before adding NOT NULL column without default`,
+                sql: tableIsEmptyCheck(qualified),
+              },
+            ]
+          : []),
+      ],
+      execute: [
+        {
+          description: `add column "${columnName}"`,
+          sql: buildAddColumnSql(qualified, columnName, column, codecHooks),
+        },
+      ],
+      postcheck: [
+        {
+          description: `verify column "${columnName}" exists`,
+          sql: columnExistsCheck({ schema, table: tableName, column: columnName }),
+        },
+        ...(notNull
+          ? [
+              {
+                description: `verify column "${columnName}" is NOT NULL`,
+                sql: columnNullabilityCheck({
+                  schema,
+                  table: tableName,
+                  column: columnName,
+                  nullable: false,
+                }),
+              },
+            ]
+          : []),
+      ],
     };
   }
 
   private buildPrimaryKeyOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
+    tables: ReadonlyArray<[string, StorageTable]>,
     schema: SqlSchemaIR,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
+    for (const [tableName, table] of tables) {
       if (!table.primaryKey) {
         continue;
       }
@@ -358,15 +501,15 @@ PRIMARY KEY (${table.primaryKey.columns.map(quoteIdentifier).join(', ')})`,
   }
 
   private buildUniqueOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
-    schema: SqlSchemaIR,
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
-      const schemaTable = schema.tables[tableName];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
       for (const unique of table.uniques) {
-        if (schemaTable && hasUniqueConstraint(schemaTable, unique.columns)) {
+        if (lookup && hasUniqueConstraint(lookup, unique.columns)) {
           continue;
         }
         const constraintName = unique.name ?? `${tableName}_${unique.columns.join('_')}_key`;
@@ -382,7 +525,12 @@ PRIMARY KEY (${table.primaryKey.columns.map(quoteIdentifier).join(', ')})`,
           precheck: [
             {
               description: `ensure unique constraint "${constraintName}" is missing`,
-              sql: constraintExistsCheck({ constraintName, schema: schemaName, exists: false }),
+              sql: constraintExistsCheck({
+                constraintName,
+                schema: schemaName,
+                table: tableName,
+                exists: false,
+              }),
             },
           ],
           execute: [
@@ -396,7 +544,7 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
           postcheck: [
             {
               description: `verify unique constraint "${constraintName}" exists`,
-              sql: constraintExistsCheck({ constraintName, schema: schemaName }),
+              sql: constraintExistsCheck({ constraintName, schema: schemaName, table: tableName }),
             },
           ],
         });
@@ -406,18 +554,18 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
   }
 
   private buildIndexOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
-    schema: SqlSchemaIR,
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
-      const schemaTable = schema.tables[tableName];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
       for (const index of table.indexes) {
-        if (schemaTable && hasIndex(schemaTable, index.columns)) {
+        if (lookup && hasIndex(lookup, index.columns)) {
           continue;
         }
-        const indexName = index.name ?? `${tableName}_${index.columns.join('_')}_idx`;
+        const indexName = index.name ?? defaultIndexName(tableName, index.columns);
         operations.push({
           id: `index.${tableName}.${indexName}`,
           label: `Create index ${indexName} on ${tableName}`,
@@ -454,16 +602,76 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
     return operations;
   }
 
+  /**
+   * Generates FK-backing index operations for FKs with `index: true`,
+   * but only when no matching user-declared index exists in `contractTable.indexes`.
+   */
+  private buildFkBackingIndexOperations(
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
+    schemaName: string,
+  ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
+    const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
+      // Collect column sets of user-declared indexes to avoid duplicates
+      const declaredIndexColumns = new Set(table.indexes.map((idx) => idx.columns.join(',')));
+
+      for (const fk of table.foreignKeys) {
+        if (fk.index === false) continue;
+        // Skip if user already declared an index with these columns
+        if (declaredIndexColumns.has(fk.columns.join(','))) continue;
+        // Skip if the index already exists in the database
+        if (lookup && hasIndex(lookup, fk.columns)) continue;
+
+        const indexName = defaultIndexName(tableName, fk.columns);
+        operations.push({
+          id: `index.${tableName}.${indexName}`,
+          label: `Create FK-backing index ${indexName} on ${tableName}`,
+          summary: `Creates FK-backing index ${indexName} on ${tableName}`,
+          operationClass: 'additive',
+          target: {
+            id: 'postgres',
+            details: this.buildTargetDetails('index', indexName, schemaName, tableName),
+          },
+          precheck: [
+            {
+              description: `ensure index "${indexName}" is missing`,
+              sql: `SELECT to_regclass(${toRegclassLiteral(schemaName, indexName)}) IS NULL`,
+            },
+          ],
+          execute: [
+            {
+              description: `create FK-backing index "${indexName}"`,
+              sql: `CREATE INDEX ${quoteIdentifier(indexName)} ON ${qualifyTableName(
+                schemaName,
+                tableName,
+              )} (${fk.columns.map(quoteIdentifier).join(', ')})`,
+            },
+          ],
+          postcheck: [
+            {
+              description: `verify index "${indexName}" exists`,
+              sql: `SELECT to_regclass(${toRegclassLiteral(schemaName, indexName)}) IS NOT NULL`,
+            },
+          ],
+        });
+      }
+    }
+    return operations;
+  }
+
   private buildForeignKeyOperations(
-    tables: SqlContract<SqlStorage>['storage']['tables'],
-    schema: SqlSchemaIR,
+    tables: ReadonlyArray<[string, StorageTable]>,
+    schemaLookups: ReadonlyMap<string, SchemaTableLookup>,
     schemaName: string,
   ): readonly SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] {
     const operations: SqlMigrationPlanOperation<PostgresPlanTargetDetails>[] = [];
-    for (const [tableName, table] of sortedEntries(tables)) {
-      const schemaTable = schema.tables[tableName];
+    for (const [tableName, table] of tables) {
+      const lookup = schemaLookups.get(tableName);
       for (const foreignKey of table.foreignKeys) {
-        if (schemaTable && hasForeignKey(schemaTable, foreignKey)) {
+        if (foreignKey.constraint === false) continue;
+        if (lookup && hasForeignKey(lookup, foreignKey)) {
           continue;
         }
         const fkName = foreignKey.name ?? `${tableName}_${foreignKey.columns.join('_')}_fkey`;
@@ -482,6 +690,7 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
               sql: constraintExistsCheck({
                 constraintName: fkName,
                 schema: schemaName,
+                table: tableName,
                 exists: false,
               }),
             },
@@ -489,18 +698,17 @@ UNIQUE (${unique.columns.map(quoteIdentifier).join(', ')})`,
           execute: [
             {
               description: `add foreign key "${fkName}"`,
-              sql: `ALTER TABLE ${qualifyTableName(schemaName, tableName)}
-ADD CONSTRAINT ${quoteIdentifier(fkName)}
-FOREIGN KEY (${foreignKey.columns.map(quoteIdentifier).join(', ')})
-REFERENCES ${qualifyTableName(schemaName, foreignKey.references.table)} (${foreignKey.references.columns
-                .map(quoteIdentifier)
-                .join(', ')})`,
+              sql: buildForeignKeySql(schemaName, tableName, fkName, foreignKey),
             },
           ],
           postcheck: [
             {
               description: `verify foreign key "${fkName}" exists`,
-              sql: constraintExistsCheck({ constraintName: fkName, schema: schemaName }),
+              sql: constraintExistsCheck({
+                constraintName: fkName,
+                schema: schemaName,
+                table: tableName,
+              }),
             },
           ],
         });
@@ -515,240 +723,87 @@ REFERENCES ${qualifyTableName(schemaName, foreignKey.references.table)} (${forei
     schema: string,
     table?: string,
   ): PostgresPlanTargetDetails {
-    return {
-      schema,
-      objectType,
-      name,
-      ...(table ? { table } : {}),
-    };
+    return buildTargetDetails(objectType, name, schema, table);
+  }
+
+  private resolvePlanningMode(policy: MigrationOperationPolicy): PlanningMode {
+    const allowWidening = policy.allowedOperationClasses.includes('widening');
+    const allowDestructive = policy.allowedOperationClasses.includes('destructive');
+    // `db init` uses additive-only policy and intentionally ignores extras.
+    // Any reconciliation-capable policy should inspect extras to reconcile strict equality.
+    const includeExtraObjects = allowWidening || allowDestructive;
+    return { includeExtraObjects, allowWidening, allowDestructive };
   }
 
-  private classifySchema(options: PlannerOptionsWithComponents):
-    | { kind: 'ok' }
-    | {
-        kind: 'conflict';
-        conflicts: SqlPlannerConflict[];
-      } {
+  private collectSchemaIssues(
+    options: PlannerOptionsWithComponents,
+    strict: boolean,
+  ): readonly SchemaIssue[] {
     const verifyOptions: VerifySqlSchemaOptionsWithComponents = {
       contract: options.contract,
       schema: options.schema,
-      strict: false,
+      strict,
       typeMetadataRegistry: new Map(),
       frameworkComponents: options.frameworkComponents,
+      normalizeDefault: parsePostgresDefault,
+      normalizeNativeType: normalizeSchemaNativeType,
     };
     const verifyResult = verifySqlSchema(verifyOptions);
-
-    const conflicts = this.extractConflicts(verifyResult.schema.issues);
-    if (conflicts.length > 0) {
-      return { kind: 'conflict', conflicts };
-    }
-    return { kind: 'ok' };
-  }
-
-  private extractConflicts(issues: readonly SchemaIssue[]): SqlPlannerConflict[] {
-    const conflicts: SqlPlannerConflict[] = [];
-    for (const issue of issues) {
-      if (isAdditiveIssue(issue)) {
-        continue;
-      }
-      const conflict = this.convertIssueToConflict(issue);
-      if (conflict) {
-        conflicts.push(conflict);
-      }
-    }
-    return conflicts.sort(conflictComparator);
-  }
-
-  private convertIssueToConflict(issue: SchemaIssue): SqlPlannerConflict | null {
-    switch (issue.kind) {
-      case 'type_mismatch':
-        return this.buildConflict('typeMismatch', issue);
-      case 'nullability_mismatch':
-        return this.buildConflict('nullabilityConflict', issue);
-      case 'primary_key_mismatch':
-        return this.buildConflict('indexIncompatible', issue);
-      case 'unique_constraint_mismatch':
-        return this.buildConflict('indexIncompatible', issue);
-      case 'index_mismatch':
-        return this.buildConflict('indexIncompatible', issue);
-      case 'foreign_key_mismatch':
-        return this.buildConflict('foreignKeyConflict', issue);
-      default:
-        return null;
-    }
-  }
-
-  private buildConflict(kind: SqlPlannerConflict['kind'], issue: SchemaIssue): SqlPlannerConflict {
-    const location = buildConflictLocation(issue);
-    const meta =
-      issue.expected || issue.actual
-        ? Object.freeze({
-            ...(issue.expected ? { expected: issue.expected } : {}),
-            ...(issue.actual ? { actual: issue.actual } : {}),
-          })
-        : undefined;
-
-    return {
-      kind,
-      summary: issue.message,
-      ...(location ? { location } : {}),
-      ...(meta ? { meta } : {}),
-    };
+    return verifyResult.schema.issues;
   }
 }
 
-function isSqlDependencyProvider(component: unknown): component is {
-  readonly databaseDependencies?: {
-    readonly init?: readonly PlannerDatabaseDependency[];
-  };
-} {
-  if (typeof component !== 'object' || component === null) {
+function canUseSharedTemporaryDefaultStrategy(options: {
+  readonly table: StorageTable;
+  readonly schemaTable: SqlSchemaIR['tables'][string];
+  readonly schemaLookup: SchemaTableLookup | undefined;
+  readonly columnName: string;
+}): boolean {
+  const { table, schemaTable, schemaLookup, columnName } = options;
+
+  // Shared placeholders are only safe when later plan steps do not require
+  // row-specific values for this newly added column.
+  if (table.primaryKey?.columns.includes(columnName) && !schemaTable.primaryKey) {
     return false;
   }
-  const record = component as Record<string, unknown>;
 
-  // If present, enforce familyId match to avoid mixing families at runtime.
-  if (Object.hasOwn(record, 'familyId') && record['familyId'] !== 'sql') {
-    return false;
+  for (const unique of table.uniques) {
+    if (!unique.columns.includes(columnName)) {
+      continue;
+    }
+    if (!schemaLookup || !hasUniqueConstraint(schemaLookup, unique.columns)) {
+      return false;
+    }
   }
 
-  if (!Object.hasOwn(record, 'databaseDependencies')) {
-    return false;
+  for (const foreignKey of table.foreignKeys) {
+    if (foreignKey.constraint === false || !foreignKey.columns.includes(columnName)) {
+      continue;
+    }
+    if (!schemaLookup || !hasForeignKey(schemaLookup, foreignKey)) {
+      return false;
+    }
   }
-  const deps = record['databaseDependencies'];
-  return deps === undefined || (typeof deps === 'object' && deps !== null);
+
+  return true;
 }
 
 function sortDependencies(
   dependencies: ReadonlyArray<PlannerDatabaseDependency>,
 ): ReadonlyArray<PlannerDatabaseDependency> {
-  if (dependencies.length <= 1) {
-    return dependencies;
-  }
   return [...dependencies].sort((a, b) => a.id.localeCompare(b.id));
 }
 
-function buildCreateTableSql(qualifiedTableName: string, table: StorageTable): string {
-  const columnDefinitions = Object.entries(table.columns).map(
-    ([columnName, column]: [string, StorageColumn]) => {
-      const parts = [
-        quoteIdentifier(columnName),
-        column.nativeType,
-        column.nullable ? '' : 'NOT NULL',
-      ].filter(Boolean);
-      return parts.join(' ');
-    },
-  );
-
-  const constraintDefinitions: string[] = [];
-  if (table.primaryKey) {
-    constraintDefinitions.push(
-      `PRIMARY KEY (${table.primaryKey.columns.map(quoteIdentifier).join(', ')})`,
-    );
-  }
-
-  const allDefinitions = [...columnDefinitions, ...constraintDefinitions];
-  return `CREATE TABLE ${qualifiedTableName} (\n  ${allDefinitions.join(',\n  ')}\n)`;
-}
-
-function qualifyTableName(schema: string, table: string): string {
-  return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
-}
-
-function toRegclassLiteral(schema: string, name: string): string {
-  const regclass = `${quoteIdentifier(schema)}.${quoteIdentifier(name)}`;
-  return `'${escapeLiteral(regclass)}'`;
-}
-
-/** Escapes and quotes a SQL identifier (table, column, schema name). */
-function quoteIdentifier(identifier: string): string {
-  // TypeScript enforces string type - no runtime check needed for internal callers
-  return `"${identifier.replace(/"/g, '""')}"`;
-}
-
-function escapeLiteral(value: string): string {
-  return value.replace(/'/g, "''");
+function isPostgresPlannerDependency(
+  dependency: ComponentDatabaseDependency<unknown>,
+): dependency is PlannerDatabaseDependency {
+  return dependency.install.every((operation) => operation.target.id === 'postgres');
 }
 
 function sortedEntries<V>(record: Readonly<Record<string, V>>): Array<[string, V]> {
   return Object.entries(record).sort(([a], [b]) => a.localeCompare(b)) as Array<[string, V]>;
 }
 
-function constraintExistsCheck({
-  constraintName,
-  schema,
-  exists = true,
-}: {
-  constraintName: string;
-  schema: string;
-  exists?: boolean;
-}): string {
-  const existsClause = exists ? 'EXISTS' : 'NOT EXISTS';
-  return `SELECT ${existsClause} (
-  SELECT 1 FROM pg_constraint c
-  JOIN pg_namespace n ON c.connamespace = n.oid
-  WHERE c.conname = '${escapeLiteral(constraintName)}'
-  AND n.nspname = '${escapeLiteral(schema)}'
-)`;
-}
-
-function columnExistsCheck({
-  schema,
-  table,
-  column,
-  exists = true,
-}: {
-  schema: string;
-  table: string;
-  column: string;
-  exists?: boolean;
-}): string {
-  const existsClause = exists ? '' : 'NOT ';
-  return `SELECT ${existsClause}EXISTS (
-  SELECT 1
-  FROM information_schema.columns
-  WHERE table_schema = '${escapeLiteral(schema)}'
-    AND table_name = '${escapeLiteral(table)}'
-    AND column_name = '${escapeLiteral(column)}'
-)`;
-}
-
-function columnIsNotNullCheck({
-  schema,
-  table,
-  column,
-}: {
-  schema: string;
-  table: string;
-  column: string;
-}): string {
-  return `SELECT EXISTS (
-  SELECT 1
-  FROM information_schema.columns
-  WHERE table_schema = '${escapeLiteral(schema)}'
-    AND table_name = '${escapeLiteral(table)}'
-    AND column_name = '${escapeLiteral(column)}'
-    AND is_nullable = 'NO'
-)`;
-}
-
-function tableIsEmptyCheck(qualifiedTableName: string): string {
-  return `SELECT NOT EXISTS (SELECT 1 FROM ${qualifiedTableName} LIMIT 1)`;
-}
-
-function buildAddColumnSql(
-  qualifiedTableName: string,
-  columnName: string,
-  column: StorageColumn,
-): string {
-  const parts = [
-    `ALTER TABLE ${qualifiedTableName}`,
-    `ADD COLUMN ${quoteIdentifier(columnName)} ${column.nativeType}`,
-    column.nullable ? '' : 'NOT NULL',
-  ].filter(Boolean);
-  return parts.join(' ');
-}
-
 function tableHasPrimaryKeyCheck(
   schema: string,
   table: string,
@@ -772,91 +827,51 @@ function tableHasPrimaryKeyCheck(
 )`;
 }
 
-function hasUniqueConstraint(
-  table: SqlSchemaIR['tables'][string],
-  columns: readonly string[],
-): boolean {
-  return table.uniques.some((unique) => arraysEqual(unique.columns, columns));
+/**
+ * Pre-computed lookup sets for a schema table's constraints.
+ * Converts O(n*m) linear scans to O(1) Set lookups per constraint check.
+ */
+interface SchemaTableLookup {
+  readonly uniqueKeys: Set<string>;
+  readonly indexKeys: Set<string>;
+  readonly uniqueIndexKeys: Set<string>;
+  readonly fkKeys: Set<string>;
 }
 
-function hasIndex(table: SqlSchemaIR['tables'][string], columns: readonly string[]): boolean {
-  return table.indexes.some((index) => !index.unique && arraysEqual(index.columns, columns));
+function buildSchemaLookupMap(schema: SqlSchemaIR): ReadonlyMap<string, SchemaTableLookup> {
+  const map = new Map<string, SchemaTableLookup>();
+  for (const [tableName, table] of Object.entries(schema.tables)) {
+    map.set(tableName, buildSchemaTableLookup(table));
+  }
+  return map;
 }
 
-function hasForeignKey(table: SqlSchemaIR['tables'][string], fk: ForeignKey): boolean {
-  return table.foreignKeys.some(
-    (candidate) =>
-      arraysEqual(candidate.columns, fk.columns) &&
-      candidate.referencedTable === fk.references.table &&
-      arraysEqual(candidate.referencedColumns, fk.references.columns),
+function buildSchemaTableLookup(table: SqlSchemaIR['tables'][string]): SchemaTableLookup {
+  const uniqueKeys = new Set(table.uniques.map((u) => u.columns.join(',')));
+  const indexKeys = new Set(table.indexes.map((i) => i.columns.join(',')));
+  const uniqueIndexKeys = new Set(
+    table.indexes.filter((i) => i.unique).map((i) => i.columns.join(',')),
   );
+  const fkKeys = new Set(
+    table.foreignKeys.map(
+      (fk) => `${fk.columns.join(',')}|${fk.referencedTable}|${fk.referencedColumns.join(',')}`,
+    ),
+  );
+  return { uniqueKeys, indexKeys, uniqueIndexKeys, fkKeys };
 }
 
-function isAdditiveIssue(issue: SchemaIssue): boolean {
-  switch (issue.kind) {
-    case 'missing_table':
-    case 'missing_column':
-    case 'extension_missing':
-      return true;
-    case 'primary_key_mismatch':
-      return issue.actual === undefined;
-    case 'unique_constraint_mismatch':
-    case 'index_mismatch':
-    case 'foreign_key_mismatch':
-      return issue.indexOrConstraint === undefined;
-    default:
-      return false;
-  }
-}
-
-function buildConflictLocation(issue: SchemaIssue) {
-  const location: {
-    table?: string;
-    column?: string;
-    constraint?: string;
-  } = {};
-  if (issue.table) {
-    location.table = issue.table;
-  }
-  if (issue.column) {
-    location.column = issue.column;
-  }
-  if (issue.indexOrConstraint) {
-    location.constraint = issue.indexOrConstraint;
-  }
-  return Object.keys(location).length > 0 ? location : undefined;
+function hasUniqueConstraint(lookup: SchemaTableLookup, columns: readonly string[]): boolean {
+  const key = columns.join(',');
+  return lookup.uniqueKeys.has(key) || lookup.uniqueIndexKeys.has(key);
 }
 
-function conflictComparator(a: SqlPlannerConflict, b: SqlPlannerConflict): number {
-  if (a.kind !== b.kind) {
-    return a.kind < b.kind ? -1 : 1;
-  }
-  const aLocation = a.location ?? {};
-  const bLocation = b.location ?? {};
-  const tableCompare = compareStrings(aLocation.table, bLocation.table);
-  if (tableCompare !== 0) {
-    return tableCompare;
-  }
-  const columnCompare = compareStrings(aLocation.column, bLocation.column);
-  if (columnCompare !== 0) {
-    return columnCompare;
-  }
-  const constraintCompare = compareStrings(aLocation.constraint, bLocation.constraint);
-  if (constraintCompare !== 0) {
-    return constraintCompare;
-  }
-  return compareStrings(a.summary, b.summary);
+function hasIndex(lookup: SchemaTableLookup, columns: readonly string[]): boolean {
+  const key = columns.join(',');
+  return lookup.indexKeys.has(key) || lookup.uniqueKeys.has(key);
 }
 
-function compareStrings(a?: string, b?: string): number {
-  if (a === b) {
-    return 0;
-  }
-  if (a === undefined) {
-    return -1;
-  }
-  if (b === undefined) {
-    return 1;
-  }
-  return a < b ? -1 : 1;
+function hasForeignKey(lookup: SchemaTableLookup, fk: ForeignKey): boolean {
+  return lookup.fkKeys.has(
+    `${fk.columns.join(',')}|${fk.references.table}|${fk.references.columns.join(',')}`,
+  );
 }