@prisma-next/target-postgres 0.13.0-dev.2 → 0.13.0-dev.20

package/src/core/codec-type-map.ts

@@ -38,6 +38,7 @@ import {
   pgTimestampDescriptor,
   pgTimestamptzDescriptor,
   pgTimetzDescriptor,
+  pgUuidDescriptor,
   pgVarbitDescriptor,
   pgVarcharDescriptor,
 } from './codecs';
@@ -68,6 +69,7 @@ export const codecDescriptorMap = {
   bit: pgBitDescriptor,
   'bit varying': pgVarbitDescriptor,
   bytea: pgByteaDescriptor,
+  uuid: pgUuidDescriptor,
   interval: pgIntervalDescriptor,
   enum: pgEnumDescriptor,
   json: pgJsonDescriptor,

package/src/core/codecs.ts

@@ -36,6 +36,7 @@ import {
   sqlTimestampDescriptor,
   sqlVarcharDescriptor,
 } from '@prisma-next/sql-relational-core/ast';
+import { blindCast } from '@prisma-next/utils/casts';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { type as arktype } from 'arktype';
 import {
@@ -77,6 +78,7 @@ import {
   PG_TIMESTAMP_CODEC_ID,
   PG_TIMESTAMPTZ_CODEC_ID,
   PG_TIMETZ_CODEC_ID,
+  PG_UUID_CODEC_ID,
   PG_VARBIT_CODEC_ID,
   PG_VARCHAR_CODEC_ID,
 } from './codec-ids';
@@ -789,6 +791,47 @@ export const pgByteaColumn = () =>
 pgByteaColumn satisfies ColumnHelperFor<PgByteaDescriptor>;
 pgByteaColumn satisfies ColumnHelperForStrict<PgByteaDescriptor>;
 
+const PG_UUID_META = { db: { sql: { postgres: { nativeType: 'uuid' } } } } as const;
+
+export class PgUuidCodec extends CodecImpl<
+  typeof PG_UUID_CODEC_ID,
+  readonly ['equality', 'order'],
+  string,
+  string
+> {
+  async encode(value: string, _ctx: CodecCallContext): Promise<string> {
+    return value;
+  }
+  async decode(wire: string, _ctx: CodecCallContext): Promise<string> {
+    return wire;
+  }
+  encodeJson(value: string): JsonValue {
+    return value;
+  }
+  decodeJson(json: JsonValue): string {
+    return blindCast<string, 'uuid columns serialize to JSON as their wire string form'>(json);
+  }
+}
+
+export class PgUuidDescriptor extends CodecDescriptorImpl<void> {
+  override readonly codecId = PG_UUID_CODEC_ID;
+  override readonly traits = ['equality', 'order'] as const;
+  override readonly targetTypes = ['uuid'] as const;
+  override readonly meta = PG_UUID_META;
+  override readonly paramsSchema: StandardSchemaV1<void> = voidParamsSchema;
+  override factory(): (ctx: CodecInstanceContext) => PgUuidCodec {
+    return () => new PgUuidCodec(this);
+  }
+}
+
+export const pgUuidDescriptor = new PgUuidDescriptor();
+
+export const pgUuidColumn = () =>
+  column(pgUuidDescriptor.factory(), pgUuidDescriptor.codecId, undefined, 'uuid');
+
+pgUuidColumn satisfies ColumnHelperFor<PgUuidDescriptor>;
+pgUuidColumn satisfies ColumnHelperForStrict<PgUuidDescriptor>;
+
 export class PgIntervalCodec extends CodecImpl<
   typeof PG_INTERVAL_CODEC_ID,
   readonly ['equality', 'order'],
@@ -1075,6 +1118,7 @@ export const codecDescriptors: readonly AnyCodecDescriptor[] = [
   pgBitDescriptor,
   pgVarbitDescriptor,
   pgByteaDescriptor,
+  pgUuidDescriptor,
   pgIntervalDescriptor,
   pgEnumDescriptor,
   pgJsonDescriptor,

package/src/core/migrations/enum-planning.ts

@@ -14,17 +14,25 @@ import { isPostgresSchema } from '../postgres-schema';
 
 /**
  * Codec-typed enum entry shape stored under
- * `schema.annotations.pg.storageTypes[(schemaName, nativeType)]`.
+ * `schema.annotations.pg.enumTypes[schemaName][nativeType]`.
  */
 interface PgStorageTypeEntry {
   readonly codecId?: string;
   readonly typeParams?: { readonly values?: unknown };
 }
 
+/**
+ * Live enum types keyed by `(schemaName, nativeType)` as a nested map, so two
+ * schemas sharing a native enum name stay distinct without packing the pair
+ * into a string. This is the same `(namespace, entityName)` coordinate the
+ * contract side addresses entities by.
+ */
+type PgEnumTypesMap = Readonly<Record<string, Readonly<Record<string, PgStorageTypeEntry>>>>;
+
 /** Postgres-specific subtree on family `SqlSchemaIR.annotations`. */
 export interface PostgresSchemaIrAnnotations {
   readonly schema?: string;
-  readonly storageTypes?: Readonly<Record<string, PgStorageTypeEntry>>;
+  readonly enumTypes?: PgEnumTypesMap;
 }
 
 function readOptionalString(value: unknown): string | undefined {
@@ -50,20 +58,27 @@ function readPgStorageTypeEntry(value: unknown): PgStorageTypeEntry | undefined
   };
 }
 
-function readPgStorageTypesMap(
-  value: unknown,
-): Readonly<Record<string, PgStorageTypeEntry>> | undefined {
+function readPgEnumTypesMap(value: unknown): PgEnumTypesMap | undefined {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return undefined;
   }
-  const entries: Record<string, PgStorageTypeEntry> = {};
-  for (const [key, entryValue] of Object.entries(value)) {
-    const entry = readPgStorageTypeEntry(entryValue);
-    if (entry !== undefined) {
-      entries[key] = entry;
+  const bySchema: Record<string, Record<string, PgStorageTypeEntry>> = {};
+  for (const [schemaName, byTypeRaw] of Object.entries(value)) {
+    if (byTypeRaw === null || typeof byTypeRaw !== 'object' || Array.isArray(byTypeRaw)) {
+      continue;
+    }
+    const byType: Record<string, PgStorageTypeEntry> = {};
+    for (const [nativeType, entryValue] of Object.entries(byTypeRaw)) {
+      const entry = readPgStorageTypeEntry(entryValue);
+      if (entry !== undefined) {
+        byType[nativeType] = entry;
+      }
+    }
+    if (Object.keys(byType).length > 0) {
+      bySchema[schemaName] = byType;
     }
   }
-  return Object.keys(entries).length > 0 ? entries : undefined;
+  return Object.keys(bySchema).length > 0 ? bySchema : undefined;
 }
 
 /**
@@ -78,25 +93,13 @@ export function readPostgresSchemaIrAnnotations(schema: SqlSchemaIR): PostgresSc
     return {};
   }
   const schemaField = readOptionalString(Reflect.get(raw, 'schema'));
-  const storageTypes = readPgStorageTypesMap(Reflect.get(raw, 'storageTypes'));
+  const enumTypes = readPgEnumTypesMap(Reflect.get(raw, 'enumTypes'));
   return {
     ...(schemaField !== undefined ? { schema: schemaField } : {}),
-    ...(storageTypes !== undefined ? { storageTypes } : {}),
+    ...(enumTypes !== undefined ? { enumTypes } : {}),
   };
 }
 
-/**
- * Separator for `(schemaName, nativeType)` keys in introspected
- * `schema.annotations.pg.storageTypes`. NUL cannot appear in Postgres
- * identifiers, so the pair is unambiguous.
- */
-export const ENUM_STORAGE_KEY_SEP = '\u0000';
-
-/** Builds the schema-qualified storageTypes map key for a live Postgres enum. */
-export function enumStorageCompoundKey(schemaName: string, nativeType: string): string {
-  return `${schemaName}${ENUM_STORAGE_KEY_SEP}${nativeType}`;
-}
-
 /**
  * Resolves the live-schema name a namespace's enums are introspected under,
  * for keying `readExistingEnumValues` lookups. The unbound namespace's
@@ -149,9 +152,10 @@ export type EnumDiff =
 
 /**
  * Reads existing enum values for `(schemaName, nativeType)` from the
- * Postgres-introspected `schema.annotations.pg.storageTypes` map.
+ * Postgres-introspected `schema.annotations.pg.enumTypes` map, addressed by
+ * the `(schema, nativeType)` coordinate.
  *
- * Schema IR's `storageTypes` slots are always codec-typed
+ * Schema IR's enum entries are always codec-typed
  * (`{codecId: PG_ENUM_CODEC_ID, typeParams.values}`): the introspector
  * writes that shape, and the Contract→Schema IR projector resolves
  * `PostgresEnumType` instances down to the same codec-typed triple before
@@ -165,8 +169,8 @@ export function readExistingEnumValues(
   schemaName: string,
   nativeType: string,
 ): readonly string[] | null {
-  const storageTypes = readPostgresSchemaIrAnnotations(schema).storageTypes;
-  const existing = storageTypes?.[enumStorageCompoundKey(schemaName, nativeType)];
+  const enumTypes = readPostgresSchemaIrAnnotations(schema).enumTypes;
+  const existing = enumTypes?.[schemaName]?.[nativeType];
   if (!existing || existing.codecId !== PG_ENUM_CODEC_ID) {
     return null;
   }

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

@@ -8,7 +8,7 @@
  * through `mapIssueToCall` for the default case.
  */
 
-import type { Contract } from '@prisma-next/contract/types';
+import type { Contract, JsonValue } from '@prisma-next/contract/types';
 import type {
   CodecControlHooks,
   MigrationOperationPolicy,
@@ -25,9 +25,11 @@ import type {
   StorageTable,
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
-import type { DdlColumn, DdlTableConstraint } from '@prisma-next/sql-relational-core/ast';
+import type { CodecRef, DdlColumn, DdlTableConstraint } from '@prisma-next/sql-relational-core/ast';
 import * as contractFree from '@prisma-next/sql-relational-core/contract-free';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+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 } from '@prisma-next/utils/result';
 import { PostgresEnumType } from '../postgres-enum-type';
@@ -65,6 +67,7 @@ import {
   type StrategyContext,
   tableAt,
 } from './planner-strategies';
+import { resolveColumnTypeMetadata } from './planner-type-resolution';
 
 export type { CallMigrationStrategy, StrategyContext };
 
@@ -214,9 +217,27 @@ function toDdlColumn(
 ): DdlColumn {
   const typeSql = buildColumnTypeSql(column, codecHooks, storageTypes);
   const ddlDefault = postgresDefaultToDdlColumnDefault(column.default);
+  const resolved = resolveColumnTypeMetadata(
+    column,
+    storageTypes as Record<string, StorageTypeInstance | PostgresEnumStorageEntry>,
+  );
+  const codecRef: CodecRef | undefined = resolved.codecId
+    ? {
+        codecId: resolved.codecId,
+        ...(resolved.typeParams !== undefined
+          ? {
+              typeParams: blindCast<
+                JsonValue,
+                'resolved.typeParams is JsonValue-shaped storage metadata; the narrowed (non-undefined) value lands in CodecRef.typeParams which is JsonValue'
+              >(resolved.typeParams),
+            }
+          : {}),
+      }
+    : undefined;
   return contractFree.col(name, typeSql, {
     ...(!column.nullable ? { notNull: true } : {}),
-    ...(ddlDefault ? { default: ddlDefault } : {}),
+    ...ifDefined('default', ddlDefault),
+    ...ifDefined('codecRef', codecRef),
   });
 }
 

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

@@ -22,7 +22,7 @@
 
 import { errorUnfilledPlaceholder } from '@prisma-next/errors/migration';
 import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
-import type { Lowerer } from '@prisma-next/family-sql/control-adapter';
+import type { ExecuteRequestLowerer, Lowerer } from '@prisma-next/family-sql/control-adapter';
 import type {
   OpFactoryCall as FrameworkOpFactoryCall,
   MigrationOperationClass,
@@ -36,6 +36,7 @@ import type {
 import { FunctionColumnDefault, LiteralColumnDefault } from '@prisma-next/sql-relational-core/ast';
 import { type ImportRequirement, jsonToTsSource, TsExpression } from '@prisma-next/ts-render';
 import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
 import * as contractFreeDdl from '../../contract-free/ddl';
 import { escapeLiteral, quoteIdentifier } from '../sql-utils';
 import type { PostgresColumnDefault } from '../types';
@@ -85,7 +86,7 @@ abstract class PostgresOpFactoryCallNode extends TsExpression implements Framewo
   abstract readonly factoryName: string;
   abstract readonly operationClass: MigrationOperationClass;
   abstract readonly label: string;
-  abstract toOp(lowerer?: Lowerer): Op;
+  abstract toOp(lowerer?: Lowerer): Op | Promise<Op>;
 
   importRequirements(): readonly ImportRequirement[] {
     return [{ moduleSpecifier: POSTGRES_MIGRATION_FACADE, symbol: this.factoryName }];
@@ -213,7 +214,7 @@ export class CreateTableCall extends PostgresOpFactoryCallNode {
     this.freeze();
   }
 
-  toOp(lowerer?: Lowerer): Op {
+  async toOp(lowerer?: ExecuteRequestLowerer): Promise<Op> {
     if (lowerer === undefined) {
       throw new Error(
         `CreateTableCall.toOp: a DDL lowerer is required on the Postgres planner path (table "${this.tableName}"). Pass the control adapter to createPostgresMigrationPlanner.`,
@@ -223,9 +224,9 @@ export class CreateTableCall extends PostgresOpFactoryCallNode {
       ...(this.schemaName !== UNBOUND_NAMESPACE_ID ? { schema: this.schemaName } : {}),
       table: this.tableName,
       columns: this.columns,
-      ...(this.constraints ? { constraints: this.constraints } : {}),
+      ...ifDefined('constraints', this.constraints),
     });
-    const { sql } = lowerer.lower(ddlNode, { contract: {} });
+    const statement = await lowerer.lowerToExecuteRequest(ddlNode);
     const schemaName = this.schemaName;
     const tableName = this.tableName;
     return {
@@ -240,7 +241,13 @@ export class CreateTableCall extends PostgresOpFactoryCallNode {
           `SELECT to_regclass(${toRegclassLiteral(schemaName, tableName)}) IS NULL`,
         ),
       ],
-      execute: [step(`create table "${tableName}"`, sql)],
+      execute: [
+        {
+          description: `create table "${tableName}"`,
+          sql: statement.sql,
+          params: statement.params ?? [],
+        },
+      ],
       postcheck: [
         step(
           `verify table "${tableName}" exists`,
@@ -1016,14 +1023,14 @@ export class CreateSchemaCall extends PostgresOpFactoryCallNode {
     this.freeze();
   }
 
-  toOp(lowerer?: Lowerer): Op {
+  async toOp(lowerer?: ExecuteRequestLowerer): Promise<Op> {
     if (lowerer === undefined) {
       throw new Error(
         `CreateSchemaCall.toOp: a DDL lowerer is required on the Postgres planner path (schema "${this.schemaName}"). Pass the control adapter to createPostgresMigrationPlanner.`,
       );
     }
     const ddlNode = contractFreeDdl.createSchema({ schema: this.schemaName, ifNotExists: true });
-    const { sql } = lowerer.lower(ddlNode, { contract: {} });
+    const statement = await lowerer.lowerToExecuteRequest(ddlNode);
     const schemaName = this.schemaName;
     return {
       id: `schema.${schemaName}`,
@@ -1031,7 +1038,13 @@ export class CreateSchemaCall extends PostgresOpFactoryCallNode {
       operationClass: 'additive',
       target: { id: 'postgres' },
       precheck: [],
-      execute: [step(`Create schema "${schemaName}"`, sql)],
+      execute: [
+        {
+          description: `Create schema "${schemaName}"`,
+          sql: statement.sql,
+          params: statement.params ?? [],
+        },
+      ],
       postcheck: [],
     };
   }

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

@@ -61,8 +61,8 @@ import type {
   SqlMigrationPlanOperationStep,
 } from '@prisma-next/family-sql/control';
 import type { SqlControlAdapter } from '@prisma-next/family-sql/control-adapter';
-import type { SerializedQueryPlan } from '@prisma-next/framework-components/control';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlExecuteRequest } from '@prisma-next/sql-relational-core/ast';
 import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { PostgresPlanTargetDetails } from '../planner-target-details';
@@ -96,25 +96,29 @@ export interface DataTransformOptions {
   readonly run: DataTransformClosure | readonly DataTransformClosure[];
 }
 
-export function dataTransform<TContract extends Contract<SqlStorage>>(
+export async function dataTransform<TContract extends Contract<SqlStorage>>(
   contract: TContract,
   name: string,
   options: DataTransformOptions,
   adapter: SqlControlAdapter<'postgres'>,
-): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
   const runClosures: readonly DataTransformClosure[] = Array.isArray(options.run)
     ? options.run
     : [options.run as DataTransformClosure];
 
-  const checkPlan = options.check ? invokeAndLower(options.check, contract, adapter, name) : null;
-  const runPlans = runClosures.map((closure) => invokeAndLower(closure, contract, adapter, name));
+  const checkPlan = options.check
+    ? await invokeAndLower(options.check, contract, adapter, name)
+    : null;
+  const runPlans = await Promise.all(
+    runClosures.map((closure) => invokeAndLower(closure, contract, adapter, name)),
+  );
 
   const precheck: readonly SqlMigrationPlanOperationStep[] = checkPlan
     ? [
         {
           description: `Check ${name} has work to do`,
           sql: `SELECT EXISTS (${checkPlan.sql}) AS ok`,
-          params: checkPlan.params,
+          params: checkPlan.params ?? [],
         },
       ]
     : [];
@@ -122,7 +126,7 @@ export function dataTransform<TContract extends Contract<SqlStorage>>(
   const execute: readonly SqlMigrationPlanOperationStep[] = runPlans.map((plan) => ({
     description: `Run ${name}`,
     sql: plan.sql,
-    params: plan.params,
+    params: plan.params ?? [],
   }));
 
   const postcheck: readonly SqlMigrationPlanOperationStep[] = checkPlan
@@ -130,7 +134,7 @@ export function dataTransform<TContract extends Contract<SqlStorage>>(
         {
           description: `Verify ${name} resolved all violations`,
           sql: `SELECT NOT EXISTS (${checkPlan.sql}) AS ok`,
-          params: checkPlan.params,
+          params: checkPlan.params ?? [],
         },
       ]
     : [];
@@ -147,23 +151,16 @@ export function dataTransform<TContract extends Contract<SqlStorage>>(
   };
 }
 
-function invokeAndLower(
+async function invokeAndLower(
   closure: DataTransformClosure,
   contract: Contract<SqlStorage>,
   adapter: SqlControlAdapter<'postgres'>,
   name: string,
-): SerializedQueryPlan {
+): Promise<SqlExecuteRequest> {
   const result = closure();
   const plan = isBuildable(result) ? result.build() : result;
   assertContractMatches(plan, contract, name);
-  const lowered = adapter.lower(plan.ast, { contract });
-  const params = lowered.params.map((slot) => {
-    if (slot.kind === 'literal') return slot.value;
-    throw new Error(
-      `data-transform: bind-site slot '${slot.name}' is not allowed in migration plans`,
-    );
-  });
-  return { sql: lowered.sql, params };
+  return adapter.lowerToExecuteRequest(plan.ast, { contract });
 }
 
 function isBuildable(value: unknown): value is Buildable {

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

@@ -24,7 +24,7 @@
  */
 
 import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
-import type { Lowerer } from '@prisma-next/family-sql/control-adapter';
+import type { ExecuteRequestLowerer } from '@prisma-next/family-sql/control-adapter';
 import type {
   MigrationPlanWithAuthoringSurface,
   OpFactoryCall,
@@ -35,8 +35,6 @@ import { PostgresMigration } from './postgres-migration';
 import { renderOps } from './render-ops';
 import { renderCallsToTypeScript } from './render-typescript';
 
-type Op = SqlMigrationPlanOperation<PostgresPlanTargetDetails>;
-
 export class TypeScriptRenderablePostgresMigration
   extends PostgresMigration
   implements MigrationPlanWithAuthoringSurface
@@ -44,13 +42,19 @@ export class TypeScriptRenderablePostgresMigration
   readonly #calls: readonly OpFactoryCall[];
   readonly #meta: MigrationMeta;
   readonly #spaceId: string;
-  readonly #lowerer: Lowerer | undefined;
+  readonly #lowerer: ExecuteRequestLowerer | undefined;
+  #operationsCache:
+    | readonly (
+        | SqlMigrationPlanOperation<PostgresPlanTargetDetails>
+        | Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>>
+      )[]
+    | undefined;
 
   constructor(
     calls: readonly OpFactoryCall[],
     meta: MigrationMeta,
     spaceId: string,
-    lowerer?: Lowerer,
+    lowerer?: ExecuteRequestLowerer,
   ) {
     super();
     this.#calls = calls;
@@ -59,8 +63,12 @@ export class TypeScriptRenderablePostgresMigration
     this.#lowerer = lowerer;
   }
 
-  override get operations(): readonly Op[] {
-    return renderOps(this.#calls, this.#lowerer);
+  override get operations(): readonly (
+    | SqlMigrationPlanOperation<PostgresPlanTargetDetails>
+    | Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>>
+  )[] {
+    this.#operationsCache ??= renderOps(this.#calls, this.#lowerer);
+    return this.#operationsCache;
   }
 
   override describe(): MigrationMeta {

package/src/core/migrations/planner.ts

@@ -12,7 +12,7 @@ import {
   planFieldEventOperations,
   plannerFailure,
 } from '@prisma-next/family-sql/control';
-import type { Lowerer } from '@prisma-next/family-sql/control-adapter';
+import type { ExecuteRequestLowerer } from '@prisma-next/family-sql/control-adapter';
 import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -52,7 +52,9 @@ type VerifySqlSchemaOptionsWithComponents = Parameters<typeof verifySqlSchema>[0
   readonly frameworkComponents: PlannerFrameworkComponents;
 };
 
-export function createPostgresMigrationPlanner(lowerer: Lowerer): PostgresMigrationPlanner {
+export function createPostgresMigrationPlanner(
+  lowerer: ExecuteRequestLowerer,
+): PostgresMigrationPlanner {
   return new PostgresMigrationPlanner(lowerer);
 }
 
@@ -88,9 +90,9 @@ export type PostgresPlanResult =
  * authoring surface.
  */
 export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgres'> {
-  readonly #lowerer: Lowerer | undefined;
+  readonly #lowerer: ExecuteRequestLowerer | undefined;
 
-  constructor(lowerer?: Lowerer) {
+  constructor(lowerer?: ExecuteRequestLowerer) {
     this.#lowerer = lowerer;
   }
 

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

@@ -64,7 +64,7 @@ export abstract class PostgresMigration extends SqlMigration<
     contract: TContract,
     name: string,
     options: DataTransformOptions,
-  ): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+  ): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
     if (!this.controlAdapter) {
       throw errorPostgresMigrationStackMissing();
     }
@@ -82,7 +82,7 @@ export abstract class PostgresMigration extends SqlMigration<
     readonly ifNotExists?: boolean;
     readonly columns: readonly DdlColumn[];
     readonly constraints?: readonly DdlTableConstraint[];
-  }): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+  }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
     if (!this.controlAdapter) {
       throw errorPostgresMigrationStackMissing();
     }
@@ -102,7 +102,7 @@ export abstract class PostgresMigration extends SqlMigration<
   protected createSchema(options: {
     readonly schema: string;
     readonly ifNotExists?: boolean;
-  }): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
+  }): Promise<SqlMigrationPlanOperation<PostgresPlanTargetDetails>> {
     if (!this.controlAdapter) {
       throw errorPostgresMigrationStackMissing();
     }

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

@@ -1,7 +1,11 @@
 import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
-import type { Lowerer } from '@prisma-next/family-sql/control-adapter';
-import type { OpFactoryCall } from '@prisma-next/framework-components/control';
+import type { ExecuteRequestLowerer } from '@prisma-next/family-sql/control-adapter';
+import type {
+  MigrationPlanOperation,
+  OpFactoryCall,
+} from '@prisma-next/framework-components/control';
 import { blindCast } from '@prisma-next/utils/casts';
+import { isThenable } from '@prisma-next/utils/promise';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
 type Op = SqlMigrationPlanOperation<PostgresPlanTargetDetails>;
@@ -13,11 +17,11 @@ type Op = SqlMigrationPlanOperation<PostgresPlanTargetDetails>;
  * silently flow through to postgres-shaped renderers — exactly the
  * place to fail loudly with op metadata (`id` + `target.id`).
  */
-function assertPostgresOp(
-  op: ReturnType<OpFactoryCall['toOp']>,
-  callFactoryName: string,
-): asserts op is Op {
-  const targetId = (op as Partial<Op>).target?.id;
+function assertPostgresOp(op: MigrationPlanOperation, callFactoryName: string): asserts op is Op {
+  const targetId = blindCast<
+    { target?: { id?: string } },
+    'op.target is present on concrete SqlMigrationPlanOperation but absent on the framework MigrationPlanOperation base'
+  >(op).target?.id;
   if (targetId !== 'postgres') {
     throw new Error(
       `renderOps: expected postgres op but got target.id="${String(targetId)}" for op.id="${op.id}" (factoryName="${callFactoryName}"). An OpFactoryCall produced an op for a different target on the postgres planner path; check the call's target binding.`,
@@ -25,13 +29,22 @@ function assertPostgresOp(
   }
 }
 
-export function renderOps(calls: readonly OpFactoryCall[], lowerer?: Lowerer): Op[] {
+export function renderOps(
+  calls: readonly OpFactoryCall[],
+  lowerer?: ExecuteRequestLowerer,
+): (Op | Promise<Op>)[] {
   return calls.map((c) => {
-    const op = blindCast<
-      { toOp(lowerer?: Lowerer): ReturnType<OpFactoryCall['toOp']> },
-      'PG OpFactoryCall.toOp accepts an optional Lowerer; the framework interface omits it because not all targets need a lowerer — the PG target overrides with this extended signature'
+    const opOrPromise = blindCast<
+      { toOp(lowerer?: ExecuteRequestLowerer): Op | Promise<Op> },
+      'PG OpFactoryCall.toOp accepts an optional ExecuteRequestLowerer; the framework interface omits it because not all targets need a lowerer — the PG target overrides with this extended signature'
     >(c).toOp(lowerer);
-    assertPostgresOp(op, c.factoryName);
-    return op;
+    if (isThenable(opOrPromise)) {
+      return opOrPromise.then((op) => {
+        assertPostgresOp(op, c.factoryName);
+        return op;
+      });
+    }
+    assertPostgresOp(opOrPromise, c.factoryName);
+    return opOrPromise;
   });
 }