@prisma-next/target-postgres 0.4.1 → 0.5.0-dev.2

package/src/core/default-normalizer.ts

@@ -0,0 +1,131 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+
+/**
+ * Pre-compiled regex patterns for performance.
+ * These are compiled once at module load time rather than on each function call.
+ */
+const NEXTVAL_PATTERN = /^nextval\s*\(/i;
+const NOW_FUNCTION_PATTERN = /^(now\s*\(\s*\)|CURRENT_TIMESTAMP)$/i;
+const CLOCK_TIMESTAMP_PATTERN = /^clock_timestamp\s*\(\s*\)$/i;
+const TIMESTAMP_CAST_SUFFIX = /::timestamp(?:tz|\s+(?:with|without)\s+time\s+zone)?$/i;
+const TEXT_CAST_SUFFIX = /::text$/i;
+const NOW_LITERAL_PATTERN = /^'now'$/i;
+const UUID_PATTERN = /^gen_random_uuid\s*\(\s*\)$/i;
+const UUID_OSSP_PATTERN = /^uuid_generate_v4\s*\(\s*\)$/i;
+const NULL_PATTERN = /^NULL(?:::.+)?$/i;
+const TRUE_PATTERN = /^true$/i;
+const FALSE_PATTERN = /^false$/i;
+const NUMERIC_PATTERN = /^-?\d+(\.\d+)?$/;
+const STRING_LITERAL_PATTERN = /^'((?:[^']|'')*)'(?:::(?:"[^"]+"|[\w\s]+)(?:\(\d+\))?)?$/;
+
+/**
+ * Returns the canonical expression for a timestamp default function, or undefined
+ * if the expression is not a recognized timestamp default.
+ *
+ * Keeps now()/CURRENT_TIMESTAMP and clock_timestamp() distinct:
+ * - now(), CURRENT_TIMESTAMP, ('now'::text)::timestamp... → 'now()'
+ * - clock_timestamp(), clock_timestamp()::timestamptz → 'clock_timestamp()'
+ *
+ * These are semantically different in Postgres: now() returns the transaction
+ * start time (constant within a transaction), while clock_timestamp() returns
+ * the actual wall-clock time (can differ across rows in a single INSERT).
+ */
+function canonicalizeTimestampDefault(expr: string): string | undefined {
+  if (NOW_FUNCTION_PATTERN.test(expr)) return 'now()';
+  if (CLOCK_TIMESTAMP_PATTERN.test(expr)) return 'clock_timestamp()';
+
+  if (!TIMESTAMP_CAST_SUFFIX.test(expr)) return undefined;
+
+  let inner = expr.replace(TIMESTAMP_CAST_SUFFIX, '').trim();
+
+  if (inner.startsWith('(') && inner.endsWith(')')) {
+    inner = inner.slice(1, -1).trim();
+  }
+
+  if (NOW_FUNCTION_PATTERN.test(inner)) return 'now()';
+  if (CLOCK_TIMESTAMP_PATTERN.test(inner)) return 'clock_timestamp()';
+
+  inner = inner.replace(TEXT_CAST_SUFFIX, '').trim();
+  if (NOW_LITERAL_PATTERN.test(inner)) return 'now()';
+
+  return undefined;
+}
+
+/**
+ * Parses a raw Postgres column default expression into a normalized ColumnDefault.
+ * This enables semantic comparison between contract defaults and introspected schema defaults.
+ *
+ * Used by the migration diff layer to normalize raw database defaults during comparison,
+ * keeping the introspection layer focused on faithful data capture.
+ *
+ * @param rawDefault - Raw default expression from information_schema.columns.column_default
+ * @param nativeType - Native column type, used for type-aware parsing (bigint tagging, JSON detection)
+ * @returns Normalized ColumnDefault or undefined if the expression cannot be parsed
+ */
+export function parsePostgresDefault(
+  rawDefault: string,
+  nativeType?: string,
+): ColumnDefault | undefined {
+  const trimmed = rawDefault.trim();
+  const normalizedType = nativeType?.toLowerCase();
+  const isBigInt = normalizedType === 'bigint' || normalizedType === 'int8';
+
+  if (NEXTVAL_PATTERN.test(trimmed)) {
+    return { kind: 'function', expression: 'autoincrement()' };
+  }
+
+  const canonicalTimestamp = canonicalizeTimestampDefault(trimmed);
+  if (canonicalTimestamp) {
+    return { kind: 'function', expression: canonicalTimestamp };
+  }
+
+  if (UUID_PATTERN.test(trimmed)) {
+    return { kind: 'function', expression: 'gen_random_uuid()' };
+  }
+
+  if (UUID_OSSP_PATTERN.test(trimmed)) {
+    return { kind: 'function', expression: 'gen_random_uuid()' };
+  }
+
+  if (NULL_PATTERN.test(trimmed)) {
+    return { kind: 'literal', value: null };
+  }
+
+  if (TRUE_PATTERN.test(trimmed)) {
+    return { kind: 'literal', value: true };
+  }
+  if (FALSE_PATTERN.test(trimmed)) {
+    return { kind: 'literal', value: false };
+  }
+
+  if (NUMERIC_PATTERN.test(trimmed)) {
+    const num = Number(trimmed);
+    if (!Number.isFinite(num)) return undefined;
+    if (isBigInt && !Number.isSafeInteger(num)) {
+      return { kind: 'literal', value: trimmed };
+    }
+    return { kind: 'literal', value: num };
+  }
+
+  const stringMatch = trimmed.match(STRING_LITERAL_PATTERN);
+  if (stringMatch?.[1] !== undefined) {
+    const unescaped = stringMatch[1].replace(/''/g, "'");
+    if (normalizedType === 'json' || normalizedType === 'jsonb') {
+      try {
+        return { kind: 'literal', value: JSON.parse(unescaped) };
+      } catch {
+        // Keep legacy behavior for malformed/non-JSON string content.
+      }
+    }
+    if (isBigInt && NUMERIC_PATTERN.test(unescaped)) {
+      const num = Number(unescaped);
+      if (Number.isSafeInteger(num)) {
+        return { kind: 'literal', value: num };
+      }
+      return { kind: 'literal', value: unescaped };
+    }
+    return { kind: 'literal', value: unescaped };
+  }
+
+  return { kind: 'function', expression: trimmed };
+}

package/src/core/descriptor-meta.ts

@@ -1,5 +1,5 @@
-import type { CodecTypes } from '@prisma-next/adapter-postgres/codec-types';
 import { postgresAuthoringFieldPresets, postgresAuthoringTypes } from './authoring';
+import type { CodecTypes } from './codecs';
 
 const postgresTargetDescriptorMetaBase = {
   kind: 'target',

package/src/core/errors.ts

@@ -0,0 +1,33 @@
+import { CliStructuredError } from '@prisma-next/errors/control';
+
+/**
+ * A `PostgresMigration` instance method that needs the materialized control
+ * adapter (currently only `this.dataTransform(...)`) was invoked, but the
+ * migration was constructed without a `ControlStack`. Concrete authoring
+ * usage always goes through the migration CLI entrypoint, which assembles
+ * a stack from the loaded `prisma-next.config.ts`; reaching this error
+ * means a test fixture or ad-hoc consumer instantiated `PostgresMigration`
+ * with the no-arg form (legal for `operations` / `describe` introspection
+ * only).
+ *
+ * Distinct from `PN-MIG-2001` (placeholder not filled) and `PN-MIG-2005`
+ * (data-transform query plan against wrong contract) because the missing
+ * input is the stack itself, not the per-operation contract.
+ *
+ * Lives in `@prisma-next/target-postgres/errors` rather than the shared
+ * framework migration errors module because the failure is target-specific:
+ * the contract it talks about (`PostgresMigration`, the Postgres control
+ * adapter, the Postgres-target stack) only exists in this package.
+ */
+export function errorPostgresMigrationStackMissing(): CliStructuredError {
+  return new CliStructuredError(
+    '2007',
+    'PostgresMigration.dataTransform requires a control adapter',
+    {
+      domain: 'MIG',
+      why: 'PostgresMigration.dataTransform was invoked on an instance constructed without a ControlStack. The stored controlAdapter is undefined, so dataTransform cannot lower its query plan.',
+      fix: 'Construct the migration via the migration CLI entrypoint (which assembles a ControlStack from the loaded prisma-next.config.ts), or pass a ControlStack containing a Postgres adapter to the migration constructor in test fixtures.',
+      meta: {},
+    },
+  );
+}

package/src/core/json-schema-type-expression.ts

@@ -0,0 +1,131 @@
+type JsonSchemaRecord = Record<string, unknown>;
+
+const MAX_DEPTH = 32;
+
+function isRecord(value: unknown): value is JsonSchemaRecord {
+  return typeof value === 'object' && value !== null;
+}
+
+function escapeStringLiteral(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r');
+}
+
+function quotePropertyKey(key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : `'${escapeStringLiteral(key)}'`;
+}
+
+function renderLiteral(value: unknown): string {
+  if (typeof value === 'string') {
+    return `'${escapeStringLiteral(value)}'`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (value === null) {
+    return 'null';
+  }
+  return 'unknown';
+}
+
+function renderUnion(items: readonly unknown[], depth: number): string {
+  const rendered = items.map((item) => render(item, depth));
+  return rendered.join(' | ');
+}
+
+function renderObjectType(schema: JsonSchemaRecord, depth: number): string {
+  const properties = isRecord(schema['properties']) ? schema['properties'] : {};
+  const required = Array.isArray(schema['required'])
+    ? new Set(schema['required'].filter((key): key is string => typeof key === 'string'))
+    : new Set<string>();
+  const keys = Object.keys(properties).sort((left, right) => left.localeCompare(right));
+
+  if (keys.length === 0) {
+    const additionalProperties = schema['additionalProperties'];
+    if (additionalProperties === true || additionalProperties === undefined) {
+      return 'Record<string, unknown>';
+    }
+    return `Record<string, ${render(additionalProperties, depth)}>`;
+  }
+
+  const renderedProperties = keys.map((key) => {
+    const valueSchema = (properties as JsonSchemaRecord)[key];
+    const optionalMarker = required.has(key) ? '' : '?';
+    return `${quotePropertyKey(key)}${optionalMarker}: ${render(valueSchema, depth)}`;
+  });
+
+  return `{ ${renderedProperties.join('; ')} }`;
+}
+
+function renderArrayType(schema: JsonSchemaRecord, depth: number): string {
+  if (Array.isArray(schema['items'])) {
+    return `readonly [${schema['items'].map((item) => render(item, depth)).join(', ')}]`;
+  }
+
+  if (schema['items'] !== undefined) {
+    const itemType = render(schema['items'], depth);
+    const needsParens = itemType.includes(' | ') || itemType.includes(' & ');
+    return needsParens ? `(${itemType})[]` : `${itemType}[]`;
+  }
+
+  return 'unknown[]';
+}
+
+function render(schema: unknown, depth: number): string {
+  if (depth > MAX_DEPTH || !isRecord(schema)) {
+    return 'JsonValue';
+  }
+
+  const nextDepth = depth + 1;
+
+  if ('const' in schema) {
+    return renderLiteral(schema['const']);
+  }
+
+  if (Array.isArray(schema['enum'])) {
+    return schema['enum'].map((value) => renderLiteral(value)).join(' | ');
+  }
+
+  if (Array.isArray(schema['oneOf'])) {
+    return renderUnion(schema['oneOf'], nextDepth);
+  }
+
+  if (Array.isArray(schema['anyOf'])) {
+    return renderUnion(schema['anyOf'], nextDepth);
+  }
+
+  if (Array.isArray(schema['allOf'])) {
+    return schema['allOf'].map((item) => render(item, nextDepth)).join(' & ');
+  }
+
+  if (Array.isArray(schema['type'])) {
+    return schema['type'].map((item) => render({ ...schema, type: item }, nextDepth)).join(' | ');
+  }
+
+  switch (schema['type']) {
+    case 'string':
+      return 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'null':
+      return 'null';
+    case 'array':
+      return renderArrayType(schema, nextDepth);
+    case 'object':
+      return renderObjectType(schema, nextDepth);
+    default:
+      break;
+  }
+
+  return 'JsonValue';
+}
+
+export function renderTypeScriptTypeFromJsonSchema(schema: unknown): string {
+  return render(schema, 0);
+}

package/src/core/migrations/op-factory-call.ts

@@ -793,7 +793,7 @@ export class DataTransformCall extends PostgresOpFactoryCallNode {
 
   renderTypeScript(): string {
     return [
-      `dataTransform(endContract, ${jsonToTsSource(this.label)}, {`,
+      `this.dataTransform(endContract, ${jsonToTsSource(this.label)}, {`,
       `  check: () => placeholder(${jsonToTsSource(this.checkSlot)}),`,
       `  run: () => placeholder(${jsonToTsSource(this.runSlot)}),`,
       '})',
@@ -802,10 +802,6 @@ export class DataTransformCall extends PostgresOpFactoryCallNode {
 
   override importRequirements(): readonly ImportRequirement[] {
     return [
-      { moduleSpecifier: TARGET_MIGRATION_MODULE, symbol: this.factoryName },
-      // `placeholder` is re-exported from `@prisma-next/target-postgres/migration`
-      // so the user's migration.ts only depends on a single migration-authoring
-      // entrypoint.
       { moduleSpecifier: TARGET_MIGRATION_MODULE, symbol: 'placeholder' },
       {
         moduleSpecifier: './end-contract.json',

package/src/core/migrations/operations/columns.ts

@@ -1,4 +1,4 @@
-import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import { quoteIdentifier } from '../../sql-utils';
 import {
   columnDefaultExistsCheck,
   columnExistsCheck,

package/src/core/migrations/operations/constraints.ts

@@ -1,5 +1,5 @@
-import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
 import type { ReferentialAction } from '@prisma-next/sql-contract/types';
+import { quoteIdentifier } from '../../sql-utils';
 import { constraintExistsCheck, qualifyTableName } from '../planner-sql-checks';
 import { type ForeignKeySpec, type Op, step, targetDetails } from './shared';
 

package/src/core/migrations/operations/data-transform.ts

@@ -1,34 +1,42 @@
 /**
  * User-facing `dataTransform` factory for the Postgres migration authoring
- * surface. Invoked directly inside a `migration.ts` file:
+ * surface. Invoked directly inside a `migration.ts` file via the
+ * `PostgresMigration` instance method (`this.dataTransform(...)`), which
+ * supplies the control adapter from the migration's injected stack:
  *
  * ```ts
  * import endContract from './end-contract.json' with { type: 'json' };
- * import { dataTransform } from '@prisma-next/target-postgres/migration';
  *
- * dataTransform(endContract, 'backfill emails', {
- *   check: () => db.users.count().where(({ email }) => email.isNull()),
- *   run:   () => db.users.update({ email: '' }).where(({ email }) => email.isNull()),
- * });
+ * class M extends Migration {
+ *   override get operations() {
+ *     return [
+ *       this.dataTransform(endContract, 'backfill emails', {
+ *         check: () => db.users.count().where(({ email }) => email.isNull()),
+ *         run:   () => db.users.update({ email: '' }).where(({ email }) => email.isNull()),
+ *       }),
+ *     ];
+ *   }
+ * }
  * ```
  *
  * The factory accepts lazy closures (`() => SqlQueryPlan | Buildable`),
  * invokes each one, asserts that its `meta.storageHash` matches the
  * `contract` it was handed (→ `PN-MIG-2005` on mismatch), and lowers the
- * plan via the Postgres adapter to a serialized `{sql, params}` payload
- * for `ops.json`.
+ * plan via the supplied control adapter to a serialized `{sql, params}`
+ * payload for `ops.json`. The free factory remains usable standalone
+ * (tests, ad-hoc tooling, non-class contexts) by passing the adapter
+ * explicitly as the fourth argument.
  */
 
-import { createPostgresAdapter } from '@prisma-next/adapter-postgres/adapter';
 import type { Contract } from '@prisma-next/contract/types';
 import { errorDataTransformContractMismatch } from '@prisma-next/errors/migration';
+import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
 import type {
   DataTransformOperation,
   SerializedQueryPlan,
 } from '@prisma-next/framework-components/control';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
-import { lowerSqlPlan } from '@prisma-next/sql-runtime';
 
 interface Buildable<R = unknown> {
   build(): SqlQueryPlan<R>;
@@ -47,21 +55,19 @@ export interface DataTransformOptions {
   readonly run: DataTransformClosure | readonly DataTransformClosure[];
 }
 
-/** Single shared adapter for apply/CLI; sufficient for single-threaded migration execution. */
-let adapterSingleton: ReturnType<typeof createPostgresAdapter> | null = null;
-function getAdapter(): ReturnType<typeof createPostgresAdapter> {
-  if (adapterSingleton === null) {
-    adapterSingleton = createPostgresAdapter();
-  }
-  return adapterSingleton;
-}
+/**
+ * Concrete Postgres flavor of `DataTransformOperation`, re-exported so the
+ * `PostgresMigration.dataTransform` instance method can name it without
+ * leaking the framework-components symbol into call sites.
+ */
+export type PostgresDataTransformOperation = DataTransformOperation;
 
 export function dataTransform<TContract extends Contract<SqlStorage>>(
   contract: TContract,
   name: string,
   options: DataTransformOptions,
+  adapter: SqlControlAdapter<'postgres'>,
 ): DataTransformOperation {
-  const adapter = getAdapter();
   const runClosures: readonly DataTransformClosure[] = Array.isArray(options.run)
     ? options.run
     : [options.run as DataTransformClosure];
@@ -79,13 +85,13 @@ export function dataTransform<TContract extends Contract<SqlStorage>>(
 function invokeAndLower(
   closure: DataTransformClosure,
   contract: Contract<SqlStorage>,
-  adapter: ReturnType<typeof createPostgresAdapter>,
+  adapter: SqlControlAdapter<'postgres'>,
   name: string,
 ): SerializedQueryPlan {
   const result = closure();
   const plan = isBuildable(result) ? result.build() : result;
   assertContractMatches(plan, contract, name);
-  const lowered = lowerSqlPlan(adapter, contract, plan);
+  const lowered = adapter.lower(plan.ast, { contract });
   return { sql: lowered.sql, params: lowered.params };
 }
 

package/src/core/migrations/operations/dependencies.ts

@@ -1,4 +1,4 @@
-import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import { quoteIdentifier } from '../../sql-utils';
 import { type Op, step } from './shared';
 
 export function createExtension(extensionName: string): Op {

package/src/core/migrations/operations/enums.ts

@@ -1,4 +1,4 @@
-import { escapeLiteral, qualifyName, quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import { escapeLiteral, qualifyName, quoteIdentifier } from '../../sql-utils';
 import { type Op, step, targetDetails } from './shared';
 
 function enumTypeExistsCheck(schemaName: string, nativeType: string, exists = true): string {

package/src/core/migrations/operations/indexes.ts

@@ -1,4 +1,4 @@
-import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import { quoteIdentifier } from '../../sql-utils';
 import { qualifyTableName, toRegclassLiteral } from '../planner-sql-checks';
 import { type Op, step, targetDetails } from './shared';
 

package/src/core/migrations/operations/shared.ts

@@ -1,7 +1,7 @@
-import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
 import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
 import type { ReferentialAction } from '@prisma-next/sql-contract/types';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { quoteIdentifier } from '../../sql-utils';
 import type { OperationClass, PostgresPlanTargetDetails } from '../planner-target-details';
 
 export type Op = SqlMigrationPlanOperation<PostgresPlanTargetDetails>;

package/src/core/migrations/operations/tables.ts

@@ -1,4 +1,4 @@
-import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import { quoteIdentifier } from '../../sql-utils';
 import { qualifyTableName, toRegclassLiteral } from '../planner-sql-checks';
 import { type ColumnSpec, type Op, renderColumnDefinition, step, targetDetails } from './shared';
 

package/src/core/migrations/planner-ddl-builders.ts

@@ -1,4 +1,3 @@
-import { escapeLiteral, quoteIdentifier } from '@prisma-next/adapter-postgres/control';
 import type { CodecControlHooks } from '@prisma-next/family-sql/control';
 import type {
   ForeignKey,
@@ -7,6 +6,7 @@ import type {
   StorageTable,
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
+import { escapeLiteral, quoteIdentifier } from '../sql-utils';
 import type { PostgresColumnDefault } from '../types';
 import { qualifyTableName } from './planner-sql-checks';
 import { resolveColumnTypeMetadata } from './planner-type-resolution';

package/src/core/migrations/planner-recipes.ts

@@ -1,6 +1,6 @@
-import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
 import type { CodecControlHooks, SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
 import type { StorageColumn, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import { quoteIdentifier } from '../sql-utils';
 import { buildAddColumnSql } from './planner-ddl-builders';
 import {
   columnExistsCheck,

package/src/core/migrations/planner-sql-checks.ts

@@ -1,6 +1,6 @@
-import { escapeLiteral, quoteIdentifier } from '@prisma-next/adapter-postgres/control';
 import type { CodecControlHooks } from '@prisma-next/family-sql/control';
 import type { StorageColumn, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import { escapeLiteral, quoteIdentifier } from '../sql-utils';
 import { resolveColumnTypeMetadata } from './planner-type-resolution';
 
 export function qualifyTableName(schema: string, table: string): string {

package/src/core/migrations/planner.ts

@@ -1,7 +1,3 @@
-import {
-  normalizeSchemaNativeType,
-  parsePostgresDefault,
-} from '@prisma-next/adapter-postgres/control';
 import type {
   MigrationOperationPolicy,
   SqlMigrationPlannerPlanOptions,
@@ -16,6 +12,8 @@ import type {
   MigrationScaffoldContext,
   SchemaIssue,
 } from '@prisma-next/framework-components/control';
+import { parsePostgresDefault } from '../default-normalizer';
+import { normalizeSchemaNativeType } from '../native-type-normalizer';
 import { planIssues } from './issue-planner';
 import { TypeScriptRenderablePostgresMigration } from './planner-produced-postgres-migration';
 import { postgresPlannerStrategies } from './planner-strategies';

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

@@ -1,4 +1,14 @@
+import type { Contract } from '@prisma-next/contract/types';
+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 type { SqlStorage } from '@prisma-next/sql-contract/types';
+import { errorPostgresMigrationStackMissing } from '../errors';
+import {
+  type DataTransformOptions,
+  dataTransform,
+  type PostgresDataTransformOperation,
+} from './operations/data-transform';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
 /**
@@ -14,7 +24,50 @@ import type { PostgresPlanTargetDetails } from './planner-target-details';
  * emits `extends Migration` against a target-specific re-export of this
  * class from `@prisma-next/target-postgres/migration`, keeping the
  * authoring surface target-scoped rather than family-scoped.
+ *
+ * The constructor materializes a single Postgres `SqlControlAdapter` from
+ * `stack.adapter.create(stack)` and stores it; the protected `dataTransform`
+ * instance method forwards to the free `dataTransform` factory with that
+ * stored adapter, so user migrations can write `this.dataTransform(...)`
+ * without threading the adapter through every call.
  */
-export abstract class PostgresMigration extends SqlMigration<PostgresPlanTargetDetails> {
+export abstract class PostgresMigration extends SqlMigration<
+  PostgresPlanTargetDetails,
+  'postgres'
+> {
   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.
+   */
+  protected readonly controlAdapter: SqlControlAdapter<'postgres'> | undefined;
+
+  constructor(stack?: ControlStack<'sql', 'postgres'>) {
+    super(stack);
+    // The descriptor `create()` is typed as the wider `ControlAdapterInstance`;
+    // the Postgres descriptor concretely returns a `SqlControlAdapter<'postgres'>`,
+    // so the cast holds for any Postgres-target stack assembled at runtime.
+    this.controlAdapter = stack?.adapter
+      ? (stack.adapter.create(stack) as SqlControlAdapter<'postgres'>)
+      : undefined;
+  }
+
+  /**
+   * Instance-method wrapper around the free `dataTransform` factory that
+   * supplies the stored control adapter. Authors call this from inside
+   * `get operations()`; the adapter argument is hidden from the call site.
+   */
+  protected dataTransform<TContract extends Contract<SqlStorage>>(
+    contract: TContract,
+    name: string,
+    options: DataTransformOptions,
+  ): PostgresDataTransformOperation {
+    if (!this.controlAdapter) {
+      throw errorPostgresMigrationStackMissing();
+    }
+    return dataTransform(contract, name, options, this.controlAdapter);
+  }
 }

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

@@ -21,17 +21,27 @@ export interface RenderMigrationMeta {
 }
 
 /**
- * Always-present base import — the rendered scaffold always extends the
- * target-owned `Migration` (i.e. `PostgresMigration`) re-exported from
- * `@prisma-next/target-postgres/migration`. That re-export fixes the
- * `SqlMigration` generic to `PostgresPlanTargetDetails` and the abstract
- * `targetId` to `'postgres'`, so user-authored migrations don't need to
- * thread target-details or redeclare `targetId`.
+ * Always-present base imports for the rendered scaffold. Both come from
+ * `@prisma-next/target-postgres/migration` so an authored Postgres
+ * `migration.ts` only needs a single dependency for its base class and
+ * its CLI entrypoint:
+ *
+ * - `Migration` — the target-owned re-export fixes the `SqlMigration`
+ *   generic to `PostgresPlanTargetDetails` and the abstract `targetId`
+ *   to `'postgres'`, so user-authored migrations don't need to thread
+ *   target-details or redeclare `targetId`.
+ * - `MigrationCLI` — the migration-file CLI entrypoint, re-exported from
+ *   `@prisma-next/cli/migration-cli`. Loads `prisma-next.config.ts`,
+ *   assembles a `ControlStack`, and instantiates the migration class.
+ *   The migration file owns this dependency directly: pulling CLI
+ *   machinery in at script run time is acceptable because the script's
+ *   whole purpose is to be invoked from the project that owns the
+ *   config.
  */
-const BASE_IMPORT: ImportRequirement = {
-  moduleSpecifier: '@prisma-next/target-postgres/migration',
-  symbol: 'Migration',
-};
+const BASE_IMPORTS: readonly ImportRequirement[] = [
+  { moduleSpecifier: '@prisma-next/target-postgres/migration', symbol: 'Migration' },
+  { moduleSpecifier: '@prisma-next/target-postgres/migration', symbol: 'MigrationCLI' },
+];
 
 export function renderCallsToTypeScript(
   calls: ReadonlyArray<PostgresOpFactoryCall>,
@@ -53,13 +63,13 @@ export function renderCallsToTypeScript(
     '  }',
     '}',
     '',
-    'Migration.run(import.meta.url, M);',
+    'MigrationCLI.run(import.meta.url, M);',
     '',
   ].join('\n');
 }
 
 function buildImports(calls: ReadonlyArray<PostgresOpFactoryCall>): string {
-  const requirements: ImportRequirement[] = [BASE_IMPORT];
+  const requirements: ImportRequirement[] = [...BASE_IMPORTS];
   for (const call of calls) {
     for (const req of call.importRequirements()) {
       requirements.push(req);