@prisma-next/target-postgres 0.3.0-dev.6 → 0.3.0-dev.63

package/src/core/migrations/planner.ts

@@ -1,5 +1,14 @@
+import {
+  escapeLiteral,
+  expandParameterizedNativeType,
+  normalizeSchemaNativeType,
+  parsePostgresDefault,
+  quoteIdentifier,
+} from '@prisma-next/adapter-postgres/control';
+import { isTaggedBigInt } from '@prisma-next/contract/types';
 import type { SchemaIssue } from '@prisma-next/core-control-plane/types';
 import type {
+  CodecControlHooks,
   MigrationOperationPolicy,
   SqlMigrationPlanner,
   SqlMigrationPlannerPlanOptions,
@@ -8,20 +17,31 @@ import type {
 } from '@prisma-next/family-sql/control';
 import {
   createMigrationPlan,
+  extractCodecControlHooks,
   plannerFailure,
   plannerSuccess,
 } from '@prisma-next/family-sql/control';
-import { arraysEqual, verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
+import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
 import type {
   ForeignKey,
-  SqlContract,
-  SqlStorage,
+  ReferentialAction,
   StorageColumn,
   StorageTable,
 } from '@prisma-next/sql-contract/types';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { PostgresColumnDefault } from '../types';
+import { buildReconciliationPlan } from './planner-reconciliation';
 
-type OperationClass = 'extension' | 'table' | 'unique' | 'index' | 'foreignKey';
+export type OperationClass =
+  | 'extension'
+  | 'type'
+  | 'table'
+  | 'column'
+  | 'primaryKey'
+  | 'unique'
+  | 'index'
+  | 'foreignKey';
 
 type PlannerFrameworkComponents = SqlMigrationPlannerPlanOptions extends {
   readonly frameworkComponents: infer T;
@@ -55,6 +75,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 +104,57 @@ 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,
+    });
+    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,
-        options.schema,
-        schemaName,
-      ),
+      ...storageTypePlan.operations,
+      ...reconciliationPlan.operations,
+      ...this.buildTableOperations(sortedTables, options.schema, schemaName),
+      ...this.buildColumnOperations(sortedTables, options.schema, schemaName),
+      ...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 +167,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.',
         },
       ]);
     }
@@ -166,6 +211,55 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
 
     return operations;
   }
+
+  private buildStorageTypeOperations(
+    options: PlannerOptionsWithComponents,
+    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;
+      }
+      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 { operations, conflicts };
+  }
   private collectDependencies(
     options: PlannerOptionsWithComponents,
   ): ReadonlyArray<PlannerDatabaseDependency> {
@@ -187,12 +281,12 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
   }
 
   private buildTableOperations(
-    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 (schema.tables[tableName]) {
         continue;
       }
@@ -230,12 +324,12 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
   }
 
   private buildColumnOperations(
-    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) {
       const schemaTable = schema.tables[tableName];
       if (!schemaTable) {
         continue;
@@ -258,15 +352,20 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
   ): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
     const qualified = qualifyTableName(schema, tableName);
     const notNull = column.nullable === false;
+    const hasDefault = column.default !== undefined;
+    // Only require empty table for NOT NULL columns WITHOUT defaults.
+    // PostgreSQL allows adding NOT NULL columns with defaults to non-empty tables
+    // because the default value is applied to existing rows.
+    const requiresEmptyTable = notNull && !hasDefault;
     const precheck = [
       {
         description: `ensure column "${columnName}" is missing`,
         sql: columnExistsCheck({ schema, table: tableName, column: columnName, exists: false }),
       },
-      ...(notNull
+      ...(requiresEmptyTable
         ? [
             {
-              description: `ensure table "${tableName}" is empty before adding NOT NULL column`,
+              description: `ensure table "${tableName}" is empty before adding NOT NULL column without default`,
               sql: tableIsEmptyCheck(qualified),
             },
           ]
@@ -287,7 +386,12 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
         ? [
             {
               description: `verify column "${columnName}" is NOT NULL`,
-              sql: columnIsNotNullCheck({ schema, table: tableName, column: columnName }),
+              sql: columnNullabilityCheck({
+                schema,
+                table: tableName,
+                column: columnName,
+                nullable: false,
+              }),
             },
           ]
         : []),
@@ -309,12 +413,12 @@ class PostgresMigrationPlanner implements SqlMigrationPlanner<PostgresPlanTarget
   }
 
   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 +462,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`;
@@ -406,15 +510,15 @@ 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`;
@@ -454,16 +558,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 = `${tableName}_${fk.columns.join('_')}_idx`;
+        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`;
@@ -489,12 +653,7 @@ 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: [
@@ -515,85 +674,33 @@ 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;
   }
 }
 
@@ -633,7 +740,8 @@ function buildCreateTableSql(qualifiedTableName: string, table: StorageTable): s
     ([columnName, column]: [string, StorageColumn]) => {
       const parts = [
         quoteIdentifier(columnName),
-        column.nativeType,
+        buildColumnTypeSql(column),
+        buildColumnDefaultSql(column.default, column),
         column.nullable ? '' : 'NOT NULL',
       ].filter(Boolean);
       return parts.join(' ');
@@ -651,30 +759,178 @@ function buildCreateTableSql(qualifiedTableName: string, table: StorageTable): s
   return `CREATE TABLE ${qualifiedTableName} (\n  ${allDefinitions.join(',\n  ')}\n)`;
 }
 
-function qualifyTableName(schema: string, table: string): string {
-  return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+/**
+ * Pattern for safe PostgreSQL type names.
+ * Allows letters, digits, underscores, spaces (for "double precision", "character varying"),
+ * and trailing [] for array types.
+ */
+const SAFE_NATIVE_TYPE_PATTERN = /^[a-zA-Z][a-zA-Z0-9_ ]*(\[\])?$/;
+
+function assertSafeNativeType(nativeType: string): void {
+  if (!SAFE_NATIVE_TYPE_PATTERN.test(nativeType)) {
+    throw new Error(
+      `Unsafe native type name in contract: "${nativeType}". ` +
+        'Native type names must match /^[a-zA-Z][a-zA-Z0-9_ ]*(\\[\\])?$/',
+    );
+  }
 }
 
-function toRegclassLiteral(schema: string, name: string): string {
-  const regclass = `${quoteIdentifier(schema)}.${quoteIdentifier(name)}`;
-  return `'${escapeLiteral(regclass)}'`;
+/**
+ * Sanity check against accidental SQL injection from malformed contract files.
+ * Rejects semicolons, SQL comment tokens, and dollar-quoting.
+ * Not a comprehensive security boundary — the contract is developer-authored.
+ */
+function assertSafeDefaultExpression(expression: string): void {
+  if (expression.includes(';') || /--|\/\*|\$\$|\bSELECT\b/i.test(expression)) {
+    throw new Error(
+      `Unsafe default expression in contract: "${expression}". ` +
+        'Default expressions must not contain semicolons, SQL comment tokens, dollar-quoting, or subqueries.',
+    );
+  }
+}
+
+/**
+ * Builds the column type SQL, handling autoincrement as a special case.
+ * For autoincrement on int4/int8, we use SERIAL/BIGSERIAL types.
+ */
+export function buildColumnTypeSql(column: StorageColumn): string {
+  const columnDefault = column.default;
+
+  // For autoincrement, use SERIAL/BIGSERIAL types instead of int4/int8
+  if (columnDefault?.kind === 'function' && columnDefault.expression === 'autoincrement()') {
+    if (column.nativeType === 'int4' || column.nativeType === 'integer') {
+      return 'SERIAL';
+    }
+    if (column.nativeType === 'int8' || column.nativeType === 'bigint') {
+      return 'BIGSERIAL';
+    }
+    if (column.nativeType === 'int2' || column.nativeType === 'smallint') {
+      return 'SMALLSERIAL';
+    }
+  }
+
+  if (column.typeRef) {
+    return quoteIdentifier(column.nativeType);
+  }
+
+  // Validate nativeType before using it unquoted in DDL
+  assertSafeNativeType(column.nativeType);
+  return renderParameterizedTypeSql(column) ?? column.nativeType;
+}
+
+/**
+ * Renders parameterized type SQL for a column, returning null if no expansion is needed.
+ *
+ * Uses the shared expandParameterizedNativeType utility from the postgres adapter.
+ * Returns null when the column has no typeParams, allowing the caller to fall back
+ * to the base nativeType.
+ */
+function renderParameterizedTypeSql(column: StorageColumn): string | null {
+  if (!column.typeParams) {
+    return null;
+  }
+
+  const expanded = expandParameterizedNativeType({
+    nativeType: column.nativeType,
+    codecId: column.codecId,
+    typeParams: column.typeParams,
+  });
+
+  // If no expansion happened (returned the same base type), return null
+  // so caller can decide whether to use nativeType directly
+  return expanded !== column.nativeType ? expanded : null;
+}
+
+/**
+ * Builds the DEFAULT clause for a column definition.
+ * Returns empty string if no default is defined.
+ *
+ * Note: autoincrement is handled specially via SERIAL types, so we skip it here.
+ */
+function buildColumnDefaultSql(
+  columnDefault: PostgresColumnDefault | undefined,
+  column?: StorageColumn,
+): string {
+  if (!columnDefault) {
+    return '';
+  }
+
+  switch (columnDefault.kind) {
+    case 'literal':
+      return `DEFAULT ${renderDefaultLiteral(columnDefault.value, column)}`;
+    case 'function': {
+      // autoincrement is handled by SERIAL type, no explicit DEFAULT needed
+      if (columnDefault.expression === 'autoincrement()') {
+        return '';
+      }
+      assertSafeDefaultExpression(columnDefault.expression);
+      return `DEFAULT (${columnDefault.expression})`;
+    }
+    case 'sequence':
+      // Sequence names use quoteIdentifier for safe identifier handling
+      return `DEFAULT nextval(${quoteIdentifier(columnDefault.name)}::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 renderDefaultLiteral(value: unknown, column?: StorageColumn): string {
+  const isJsonColumn = column?.nativeType === 'json' || column?.nativeType === 'jsonb';
+
+  if (value instanceof Date) {
+    return `'${escapeLiteral(value.toISOString())}'`;
+  }
+  if (!isJsonColumn && isTaggedBigInt(value)) {
+    if (!/^-?\d+$/.test(value.value)) {
+      throw new Error(`Invalid tagged bigint value: "${value.value}" is not a valid integer`);
+    }
+    return value.value;
+  }
+  if (typeof value === 'bigint') {
+    return value.toString();
+  }
+  if (typeof value === 'string') {
+    return `'${escapeLiteral(value)}'`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (value === null) {
+    return 'NULL';
+  }
+  const json = JSON.stringify(value);
+  if (isJsonColumn) {
+    return `'${escapeLiteral(json)}'::${column.nativeType}`;
+  }
+  return `'${escapeLiteral(json)}'`;
+}
+
+export function buildTargetDetails(
+  objectType: OperationClass,
+  name: string,
+  schema: string,
+  table?: string,
+): PostgresPlanTargetDetails {
+  return {
+    schema,
+    objectType,
+    name,
+    ...ifDefined('table', table),
+  };
 }
 
-function escapeLiteral(value: string): string {
-  return value.replace(/'/g, "''");
+export function qualifyTableName(schema: string, table: string): string {
+  return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+}
+
+export function toRegclassLiteral(schema: string, name: string): string {
+  const regclass = `${quoteIdentifier(schema)}.${quoteIdentifier(name)}`;
+  return `'${escapeLiteral(regclass)}'`;
 }
 
 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({
+export function constraintExistsCheck({
   constraintName,
   schema,
   exists = true,
@@ -692,7 +948,7 @@ function constraintExistsCheck({
 )`;
 }
 
-function columnExistsCheck({
+export function columnExistsCheck({
   schema,
   table,
   column,
@@ -713,22 +969,25 @@ function columnExistsCheck({
 )`;
 }
 
-function columnIsNotNullCheck({
+export function columnNullabilityCheck({
   schema,
   table,
   column,
+  nullable,
 }: {
   schema: string;
   table: string;
   column: string;
+  nullable: boolean;
 }): string {
+  const expected = nullable ? 'YES' : 'NO';
   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'
+    AND is_nullable = '${expected}'
 )`;
 }
 
@@ -741,9 +1000,12 @@ function buildAddColumnSql(
   columnName: string,
   column: StorageColumn,
 ): string {
+  const typeSql = buildColumnTypeSql(column);
+  const defaultSql = buildColumnDefaultSql(column.default, column);
   const parts = [
     `ALTER TABLE ${qualifiedTableName}`,
-    `ADD COLUMN ${quoteIdentifier(columnName)} ${column.nativeType}`,
+    `ADD COLUMN ${quoteIdentifier(columnName)} ${typeSql}`,
+    defaultSql,
     column.nullable ? '' : 'NOT NULL',
   ].filter(Boolean);
   return parts.join(' ');
@@ -772,91 +1034,90 @@ 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 hasUniqueConstraint(lookup: SchemaTableLookup, columns: readonly string[]): boolean {
+  const key = columns.join(',');
+  return lookup.uniqueKeys.has(key) || lookup.uniqueIndexKeys.has(key);
 }
 
-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 hasIndex(lookup: SchemaTableLookup, columns: readonly string[]): boolean {
+  const key = columns.join(',');
+  return lookup.indexKeys.has(key) || lookup.uniqueKeys.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 hasForeignKey(lookup: SchemaTableLookup, fk: ForeignKey): boolean {
+  return lookup.fkKeys.has(
+    `${fk.columns.join(',')}|${fk.references.table}|${fk.references.columns.join(',')}`,
+  );
 }
 
-function compareStrings(a?: string, b?: string): number {
-  if (a === b) {
-    return 0;
-  }
-  if (a === undefined) {
-    return -1;
+const REFERENTIAL_ACTION_SQL: Record<ReferentialAction, string> = {
+  noAction: 'NO ACTION',
+  restrict: 'RESTRICT',
+  cascade: 'CASCADE',
+  setNull: 'SET NULL',
+  setDefault: 'SET DEFAULT',
+};
+
+function buildForeignKeySql(
+  schemaName: string,
+  tableName: string,
+  fkName: string,
+  foreignKey: ForeignKey,
+): string {
+  let 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(', ')})`;
+
+  if (foreignKey.onDelete !== undefined) {
+    const action = REFERENTIAL_ACTION_SQL[foreignKey.onDelete];
+    if (!action) {
+      throw new Error(`Unknown referential action for onDelete: ${String(foreignKey.onDelete)}`);
+    }
+    sql += `\nON DELETE ${action}`;
   }
-  if (b === undefined) {
-    return 1;
+  if (foreignKey.onUpdate !== undefined) {
+    const action = REFERENTIAL_ACTION_SQL[foreignKey.onUpdate];
+    if (!action) {
+      throw new Error(`Unknown referential action for onUpdate: ${String(foreignKey.onUpdate)}`);
+    }
+    sql += `\nON UPDATE ${action}`;
   }
-  return a < b ? -1 : 1;
+
+  return sql;
 }