@prisma-next/target-postgres 0.14.0-dev.7 → 0.14.0-dev.71

package/src/core/migrations/postgres-migration.ts

@@ -3,9 +3,11 @@ import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control'
 import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
 import { Migration as SqlMigration } from '@prisma-next/family-sql/migration';
 import type { ControlStack } from '@prisma-next/framework-components/control';
+import { MigrationContractViews } from '@prisma-next/migration-tools/migration';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { DdlColumn, DdlTableConstraint } from '@prisma-next/sql-relational-core/ast';
 import { errorPostgresMigrationStackMissing } from '../errors';
+import { PostgresContractView } from '../postgres-contract-view';
 import {
   AddCheckConstraintCall,
   AddColumnCall,
@@ -15,6 +17,7 @@ import {
   AlterColumnTypeCall,
   type AlterColumnTypeOptions,
   CreateIndexCall,
+  CreateNativeEnumTypeCall,
   CreateSchemaCall,
   CreateTableCall,
   DropCheckConstraintCall,
@@ -22,6 +25,7 @@ import {
   DropConstraintCall,
   DropDefaultCall,
   DropIndexCall,
+  DropNativeEnumTypeCall,
   DropNotNullCall,
   DropTableCall,
   SetDefaultCall,
@@ -60,20 +64,31 @@ import type { PostgresPlanTargetDetails } from './planner-target-details';
  * is an antipattern in a migration. (The unbound/unspecified namespace concept
  * remains for SQLite, which has no schemas, and for Mongo's connection `db`.)
  */
-export abstract class PostgresMigration extends SqlMigration<
-  PostgresPlanTargetDetails,
-  'postgres'
-> {
+export abstract class PostgresMigration<
+  Start extends Contract<SqlStorage> = Contract<SqlStorage>,
+  End extends Contract<SqlStorage> = Contract<SqlStorage>,
+> extends SqlMigration<PostgresPlanTargetDetails, 'postgres', Start, End> {
   readonly targetId = 'postgres' as const;
 
   /**
    * Materialized Postgres control adapter, created once per migration
    * instance from the injected stack. `undefined` only when the migration
-   * was instantiated without a stack (test fixtures); `dataTransform`
-   * throws in that case to surface the misuse.
+   * was instantiated without a stack (test fixtures); `controlAdapterFor`
+   * throws a PN-MIG-2007 in that case to surface the misuse.
    */
   protected readonly controlAdapter: SqlControlAdapter<'postgres'> | undefined;
 
+  #endView = new MigrationContractViews<PostgresContractView<End>>(
+    this,
+    'PostgresMigration',
+    (json) => PostgresContractView.fromJson<End>(json),
+  );
+  #startView = new MigrationContractViews<PostgresContractView<Start>>(
+    this,
+    'PostgresMigration',
+    (json) => PostgresContractView.fromJson<Start>(json),
+  );
+
   constructor(stack?: ControlStack<'sql', 'postgres'>) {
     super(stack);
     // The descriptor `create()` is typed as the wider `ControlAdapterInstance`;
@@ -84,6 +99,35 @@ export abstract class PostgresMigration extends SqlMigration<
       : undefined;
   }
 
+  /**
+   * Returns the materialized control adapter, or throws a PN-MIG-2007 naming
+   * `operation` when the migration was constructed without a `ControlStack`.
+   * Single home for the null-check that every DDL/DML method shares.
+   */
+  private controlAdapterFor(operation: string): SqlControlAdapter<'postgres'> {
+    if (!this.controlAdapter) {
+      throw errorPostgresMigrationStackMissing(operation);
+    }
+    return this.controlAdapter;
+  }
+
+  /**
+   * The typed, schema-qualified Postgres view over this migration's end-state
+   * contract — `this.endContract.namespace.<schema>.table.<name>`, etc. Throws
+   * if no `endContractJson` was provided.
+   */
+  get endContract(): PostgresContractView<End> {
+    return this.#endView.endContract;
+  }
+
+  /**
+   * The typed Postgres view over this migration's start-state contract, or
+   * `null` for a baseline migration (no `startContractJson`).
+   */
+  get startContract(): PostgresContractView<Start> | null {
+    return this.#startView.startContract;
+  }
+
   /**
    * Instance-method wrapper around the free `dataTransform` factory that
    * supplies the stored control adapter. Authors call this from inside
@@ -94,10 +138,7 @@ export abstract class PostgresMigration extends SqlMigration<
     name: string,
     options: DataTransformOptions,
   ): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return dataTransform(contract, name, options, this.controlAdapter);
+    return dataTransform(contract, name, options, this.controlAdapterFor('dataTransform'));
   }
 
   /**
@@ -112,15 +153,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly columns: readonly DdlColumn[];
     readonly constraints?: readonly DdlTableConstraint[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new CreateTableCall(
       options.schema,
       options.table,
       options.columns,
       options.constraints,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('createTable'));
   }
 
   /**
@@ -132,10 +170,36 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly schema: string;
     readonly ifNotExists?: boolean;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return new CreateSchemaCall(options.schema).toOp(this.controlAdapter);
+    return new CreateSchemaCall(options.schema).toOp(this.controlAdapterFor('createSchema'));
+  }
+
+  /**
+   * Emit a `CREATE TYPE ... AS ENUM (...)` migration operation for a managed
+   * native enum. Builds a typed DDL node and lowers it through the stored
+   * control adapter (members render in declaration order). Throws if no adapter
+   * is present.
+   */
+  protected createNativeEnumType(options: {
+    readonly schema: string;
+    readonly typeName: string;
+    readonly members: readonly string[];
+  }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
+    return new CreateNativeEnumTypeCall(options.schema, options.typeName, options.members).toOp(
+      this.controlAdapterFor('createNativeEnumType'),
+    );
+  }
+
+  /**
+   * Emit a `DROP TYPE` migration operation for a managed native enum, lowered
+   * through the stored control adapter. Throws if no adapter is present.
+   */
+  protected dropNativeEnumType(options: {
+    readonly schema: string;
+    readonly typeName: string;
+  }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
+    return new DropNativeEnumTypeCall(options.schema, options.typeName).toOp(
+      this.controlAdapterFor('dropNativeEnumType'),
+    );
   }
 
   protected addColumn(options: {
@@ -143,11 +207,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: DdlColumn;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddColumnCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('addColumn'),
     );
   }
 
@@ -157,15 +218,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly constraint: string;
     readonly columns: readonly string[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddPrimaryKeyCall(
       options.schema,
       options.table,
       options.constraint,
       options.columns,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('addPrimaryKey'));
   }
 
   protected addUnique(options: {
@@ -174,15 +232,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly constraint: string;
     readonly columns: readonly string[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddUniqueCall(
       options.schema,
       options.table,
       options.constraint,
       options.columns,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('addUnique'));
   }
 
   protected addForeignKey(options: {
@@ -190,11 +245,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly foreignKey: ForeignKeySpec;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddForeignKeyCall(options.schema, options.table, options.foreignKey).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('addForeignKey'),
     );
   }
 
@@ -205,16 +257,13 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly column: string;
     readonly values: readonly string[];
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AddCheckConstraintCall(
       options.schema,
       options.table,
       options.constraint,
       options.column,
       options.values,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('addCheckConstraint'));
   }
 
   protected dropCheckConstraint(options: {
@@ -222,11 +271,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly constraint: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropCheckConstraintCall(options.schema, options.table, options.constraint).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropCheckConstraint'),
     );
   }
 
@@ -236,25 +282,21 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly constraint: string;
     readonly kind?: 'foreignKey' | 'unique' | 'primaryKey';
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropConstraintCall(
       options.schema,
       options.table,
       options.constraint,
       options.kind ?? 'unique',
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('dropConstraint'));
   }
 
   protected dropTable(options: {
     readonly schema: string;
     readonly table: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return new DropTableCall(options.schema, options.table).toOp(this.controlAdapter);
+    return new DropTableCall(options.schema, options.table).toOp(
+      this.controlAdapterFor('dropTable'),
+    );
   }
 
   protected dropColumn(options: {
@@ -262,11 +304,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropColumnCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropColumn'),
     );
   }
 
@@ -276,15 +315,12 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly column: string;
     readonly options: AlterColumnTypeOptions;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new AlterColumnTypeCall(
       options.schema,
       options.table,
       options.column,
       options.options,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('alterColumnType'));
   }
 
   protected setNotNull(options: {
@@ -292,11 +328,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new SetNotNullCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('setNotNull'),
     );
   }
 
@@ -305,11 +338,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropNotNullCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropNotNull'),
     );
   }
 
@@ -320,16 +350,13 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly defaultSql: string;
     readonly operationClass?: 'additive' | 'widening';
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new SetDefaultCall(
       options.schema,
       options.table,
       options.column,
       options.defaultSql,
       options.operationClass,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('setDefault'));
   }
 
   protected dropDefault(options: {
@@ -337,11 +364,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly column: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropDefaultCall(options.schema, options.table, options.column).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropDefault'),
     );
   }
 
@@ -352,16 +376,13 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly columns: readonly string[];
     readonly extras?: CreateIndexExtras;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new CreateIndexCall(
       options.schema,
       options.table,
       options.index,
       options.columns,
       options.extras,
-    ).toOp(this.controlAdapter);
+    ).toOp(this.controlAdapterFor('createIndex'));
   }
 
   protected dropIndex(options: {
@@ -369,11 +390,8 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly table: string;
     readonly index: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
     return new DropIndexCall(options.schema, options.table, options.index).toOp(
-      this.controlAdapter,
+      this.controlAdapterFor('dropIndex'),
     );
   }
 
@@ -383,9 +401,6 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly id: string;
     readonly label?: string;
   }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
-    if (!this.controlAdapter) {
-      throw errorPostgresMigrationStackMissing();
-    }
-    return installExtension(options, this.controlAdapter);
+    return installExtension(options, this.controlAdapterFor('installExtension'));
   }
 }

package/src/core/migrations/render-typescript.ts

@@ -45,15 +45,19 @@ export function renderCallsToTypeScript(
   calls: ReadonlyArray<OpFactoryCall>,
   meta: RenderMigrationMeta,
 ): string {
-  const imports = buildImports(calls);
+  const imports = buildImports(calls, meta);
   const operationsBody = calls.map((c) => renderCall(c)).join(',\n');
+  const hasStart = meta.from !== null;
+  const startField = hasStart ? ['  override readonly startContractJson = startContract;'] : [];
 
   return [
     shebangLineFor(detectScaffoldRuntime()),
     imports,
     '',
-    'export default class M extends Migration {',
-    buildDescribeMethod(meta),
+    `export default class M extends Migration<${hasStart ? 'Start' : 'never'}, End> {`,
+    ...startField,
+    '  override readonly endContractJson = endContract;',
+    '',
     '  override get operations() {',
     '    return [',
     indent(operationsBody, 6),
@@ -70,8 +74,8 @@ function renderCall(call: OpFactoryCall): string {
   return call.renderTypeScript();
 }
 
-function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
-  const requirements: ImportRequirement[] = [...BASE_IMPORTS];
+function buildImports(calls: ReadonlyArray<OpFactoryCall>, meta: RenderMigrationMeta): string {
+  const requirements: ImportRequirement[] = [...BASE_IMPORTS, ...contractImports(meta)];
   for (const call of calls) {
     for (const req of call.importRequirements()) {
       requirements.push(req);
@@ -80,16 +84,39 @@ function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
   return renderImports(requirements);
 }
 
-function buildDescribeMethod(meta: RenderMigrationMeta): string {
-  const lines: string[] = [];
-  lines.push('  override describe() {');
-  lines.push('    return {');
-  lines.push(`      from: ${JSON.stringify(meta.from)},`);
-  lines.push(`      to: ${JSON.stringify(meta.to)},`);
-  lines.push('    };');
-  lines.push('  }');
-  lines.push('');
-  return lines.join('\n');
+/**
+ * The committed contract-JSON imports the scaffold reads its from/to identity
+ * from. `end-contract.json` is always present; `start-contract.json` is added
+ * only for a non-baseline migration (`meta.from !== null`). The matching
+ * `Contract` type imports (aliased `Start`/`End`) feed the
+ * `Migration<Start, End>` generics. Baseline emits `Migration<never, End>` with
+ * no start imports — `never` is the honest "no prior contract" Start.
+ */
+function contractImports(meta: RenderMigrationMeta): readonly ImportRequirement[] {
+  const reqs: ImportRequirement[] = [
+    {
+      moduleSpecifier: './end-contract.json',
+      symbol: 'endContract',
+      kind: 'default',
+      attributes: { type: 'json' },
+    },
+    { moduleSpecifier: './end-contract', symbol: 'Contract', alias: 'End', typeOnly: true },
+  ];
+  if (meta.from !== null) {
+    reqs.push({
+      moduleSpecifier: './start-contract.json',
+      symbol: 'startContract',
+      kind: 'default',
+      attributes: { type: 'json' },
+    });
+    reqs.push({
+      moduleSpecifier: './start-contract',
+      symbol: 'Contract',
+      alias: 'Start',
+      typeOnly: true,
+    });
+  }
+  return reqs;
 }
 
 function indent(text: string, spaces: number): string {

package/src/core/migrations/resolve-ddl-schema.ts

@@ -0,0 +1,26 @@
+import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { DEFAULT_NAMESPACE_ID } from '../namespace-ids';
+import { isPostgresSchema } from '../postgres-schema';
+
+/**
+ * Given the contract's storage and a namespace id, returns the live Postgres
+ * DDL schema name that namespace maps to. A named Postgres namespace dispatches
+ * to its `ddlSchemaName(storage)`; the unbound sentinel resolves to
+ * `DEFAULT_NAMESPACE_ID` (the search-path default for offline planning); a
+ * bare object payload (used by some tests) falls back to the namespace id
+ * itself.
+ */
+export function resolveDdlSchemaForNamespaceStorage(
+  storage: SqlStorage,
+  namespaceId: string,
+): string {
+  if (namespaceId === UNBOUND_NAMESPACE_ID) {
+    return DEFAULT_NAMESPACE_ID;
+  }
+  const namespace = storage.namespaces[namespaceId];
+  if (namespace && isPostgresSchema(namespace)) {
+    return namespace.ddlSchemaName(storage);
+  }
+  return namespaceId;
+}

package/src/core/migrations/runner.ts

@@ -12,7 +12,6 @@ import type {
   SqlMigrationRunnerSuccessValue,
 } from '@prisma-next/family-sql/control';
 import { runnerFailure, runnerSuccess } from '@prisma-next/family-sql/control';
-import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
 import type { MigrationRunnerResult } from '@prisma-next/framework-components/control';
 import { APP_SPACE_ID } from '@prisma-next/framework-components/control';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
@@ -23,8 +22,6 @@ import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Result } from '@prisma-next/utils/result';
 import { notOk, ok, okVoid } from '@prisma-next/utils/result';
-import { parsePostgresDefault } from '../default-normalizer';
-import { normalizeSchemaNativeType } from '../native-type-normalizer';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
 interface ApplyPlanSuccessValue {
@@ -124,30 +121,27 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
       applyValue = applyResult.value;
     }
 
-    // Schema verification on app-space only — extension spaces don't
-    // own user-facing tables in the live schema, and `verifySqlSchema`
-    // matches the destination contract against the database, which
-    // would flag every app-space table as "extra" when called against
-    // an extension contract.
+    // Verify the schema on app-space only: extension spaces don't own
+    // user-facing tables, so verifying the destination contract against the
+    // database would flag every app-space table as "extra". Delegates to the
+    // family `verifySchema` — the same comparison the CLI verify runs.
     if (space === APP_SPACE_ID) {
-      const schemaIR = await this.family.introspect({
+      const schemaNode = await this.family.introspect({
         driver,
         contract: options.destinationContract,
       });
-      const schemaVerifyResult = verifySqlSchema({
+      const schemaVerifyResult = this.family.verifySchema({
         contract: options.destinationContract,
-        schema: schemaIR,
+        schema: schemaNode,
         strict: options.strictVerification ?? true,
-        context: options.context ?? {},
-        typeMetadataRegistry: this.family.typeMetadataRegistry,
         frameworkComponents: options.frameworkComponents,
-        normalizeDefault: parsePostgresDefault,
-        normalizeNativeType: normalizeSchemaNativeType,
       });
       if (!schemaVerifyResult.ok) {
         return runnerFailure('SCHEMA_VERIFY_FAILED', schemaVerifyResult.summary, {
           why: 'The resulting database schema does not satisfy the destination contract.',
-          meta: { issues: schemaVerifyResult.schema.issues },
+          meta: {
+            issues: schemaVerifyResult.schema.issues,
+          },
         });
       }
     }
@@ -666,6 +660,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
           migrationName: edge.dirName,
           migrationHash: edge.migrationHash,
           operations: edgeOps,
+          ...ifDefined('destinationContractJson', edge.destinationContractJson),
         },
       });
     }