@prisma-next/target-postgres 0.5.0-dev.8 → 0.5.0-dev.81

package/src/core/descriptor-meta.ts

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

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

@@ -11,7 +11,7 @@
  *   override get operations() {
  *     return [
  *       this.dataTransform(endContract, 'backfill emails', {
- *         check: () => db.users.count().where(({ email }) => email.isNull()),
+ *         check: () => db.users.select('id').where(({ email }) => email.isNull()).limit(1),
  *         run:   () => db.users.update({ email: '' }).where(({ email }) => email.isNull()),
  *       }),
  *     ];
@@ -23,20 +23,49 @@
  * 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 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.
+ * payload.
+ *
+ * The factory then lowers the data transform to the unified migration-op
+ * shape `{ precheck, execute, postcheck }`. The user's `check` plan is
+ * wrapped twice with opposite truth values:
+ *
+ * - precheck `SELECT EXISTS (<check>) AS ok` asserts there is work to do
+ *   (precheck is short-circuited by the runner's pre-satisfied-skip path
+ *   when nothing remains to backfill).
+ * - postcheck `SELECT NOT EXISTS (<check>) AS ok` asserts the work is
+ *   complete after the run steps execute.
+ *
+ * The `check` plan is therefore expected to be a **rowset query whose
+ * presence of any row signals "work remains"** — typically `select('id')
+ * .where(<violation predicate>).limit(1)`. Scalar/aggregate shapes
+ * (`count(*)`, `bool_and(...)`) do not work under this contract: they
+ * always return exactly one row, so `EXISTS` is always true and
+ * `NOT EXISTS` is always false. (This is the same row-presence contract
+ * the pre-unification runner relied on; the wrapping is just lifting it
+ * into SQL.)
+ *
+ * Each `run` plan becomes an execute step. Because the `Step.params`
+ * field threads through `driver.query(sql, params)`, the user's bound
+ * values flow through the driver's parameter binder rather than being
+ * inlined into the SQL text.
+ *
+ * The free factory remains usable standalone (tests, ad-hoc tooling,
+ * non-class contexts) by passing the adapter explicitly as the fourth
+ * argument.
  */
 
 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';
+  SqlMigrationPlanOperation,
+  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 { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { PostgresPlanTargetDetails } from '../planner-target-details';
 
 interface Buildable<R = unknown> {
   build(): SqlQueryPlan<R>;
@@ -49,36 +78,72 @@ interface Buildable<R = unknown> {
 export type DataTransformClosure = () => SqlQueryPlan | Buildable;
 
 export interface DataTransformOptions {
-  /** Optional pre-flight query. `undefined` means "no check". */
+  /**
+   * Optional opt-in routing identity. Presence opts the transform into
+   * invariant-aware routing; absence means it is path-dependent and
+   * not referenceable from refs.
+   */
+  readonly invariantId?: string;
+  /**
+   * Optional pre-flight query. `undefined` means "no check". When
+   * supplied, the closure must return a **rowset query** whose
+   * presence of any row signals "violations remain". Conventional
+   * shape: `db.<table>.select('id').where(<violation>).limit(1)`.
+   * Scalar/aggregate shapes do not satisfy this contract.
+   */
   readonly check?: DataTransformClosure;
   /** One or more mutation queries to execute. */
   readonly run: DataTransformClosure | readonly DataTransformClosure[];
 }
 
-/**
- * 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 {
+): 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 precheck: readonly SqlMigrationPlanOperationStep[] = checkPlan
+    ? [
+        {
+          description: `Check ${name} has work to do`,
+          sql: `SELECT EXISTS (${checkPlan.sql}) AS ok`,
+          params: checkPlan.params,
+        },
+      ]
+    : [];
+
+  const execute: readonly SqlMigrationPlanOperationStep[] = runPlans.map((plan) => ({
+    description: `Run ${name}`,
+    sql: plan.sql,
+    params: plan.params,
+  }));
+
+  const postcheck: readonly SqlMigrationPlanOperationStep[] = checkPlan
+    ? [
+        {
+          description: `Verify ${name} resolved all violations`,
+          sql: `SELECT NOT EXISTS (${checkPlan.sql}) AS ok`,
+          params: checkPlan.params,
+        },
+      ]
+    : [];
+
   return {
     id: `data_migration.${name}`,
     label: `Data transform: ${name}`,
     operationClass: 'data',
-    name,
-    source: 'migration.ts',
-    check: options.check ? invokeAndLower(options.check, contract, adapter, name) : null,
-    run: runClosures.map((closure) => invokeAndLower(closure, contract, adapter, name)),
+    ...ifDefined('invariantId', options.invariantId),
+    target: { id: 'postgres' },
+    precheck,
+    execute,
+    postcheck,
   };
 }
 

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

@@ -24,10 +24,12 @@
  */
 
 import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
-import type { MigrationPlanWithAuthoringSurface } from '@prisma-next/framework-components/control';
+import type {
+  MigrationPlanWithAuthoringSurface,
+  OpFactoryCall,
+} from '@prisma-next/framework-components/control';
 import type { MigrationMeta } from '@prisma-next/migration-tools/migration';
 import { ifDefined } from '@prisma-next/utils/defined';
-import type { PostgresOpFactoryCall } from './op-factory-call';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 import { PostgresMigration } from './postgres-migration';
 import { renderOps } from './render-ops';
@@ -39,13 +41,15 @@ export class TypeScriptRenderablePostgresMigration
   extends PostgresMigration
   implements MigrationPlanWithAuthoringSurface
 {
-  readonly #calls: readonly PostgresOpFactoryCall[];
+  readonly #calls: readonly OpFactoryCall[];
   readonly #meta: MigrationMeta;
+  readonly #spaceId: string;
 
-  constructor(calls: readonly PostgresOpFactoryCall[], meta: MigrationMeta) {
+  constructor(calls: readonly OpFactoryCall[], meta: MigrationMeta, spaceId: string) {
     super();
     this.#calls = calls;
     this.#meta = meta;
+    this.#spaceId = spaceId;
   }
 
   override get operations(): readonly Op[] {
@@ -56,11 +60,19 @@ export class TypeScriptRenderablePostgresMigration
     return this.#meta;
   }
 
+  /**
+   * Contract space this planner-produced plan applies to. Threaded
+   * from the planner options so the runner keys the marker row by
+   * the right space when executing the plan.
+   */
+  get spaceId(): string {
+    return this.#spaceId;
+  }
+
   renderTypeScript(): string {
     return renderCallsToTypeScript(this.#calls, {
       from: this.#meta.from,
       to: this.#meta.to,
-      ...ifDefined('kind', this.#meta.kind),
       ...ifDefined('labels', this.#meta.labels),
     });
   }

package/src/core/migrations/planner.ts

@@ -1,9 +1,14 @@
+import type { Contract } from '@prisma-next/contract/types';
 import type {
   MigrationOperationPolicy,
   SqlMigrationPlannerPlanOptions,
   SqlPlannerFailureResult,
 } from '@prisma-next/family-sql/control';
-import { extractCodecControlHooks, plannerFailure } from '@prisma-next/family-sql/control';
+import {
+  extractCodecControlHooks,
+  planFieldEventOperations,
+  plannerFailure,
+} from '@prisma-next/family-sql/control';
 import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -83,30 +88,48 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     readonly contract: unknown;
     readonly schema: unknown;
     readonly policy: MigrationOperationPolicy;
-    readonly fromHash?: string;
     /**
      * The "from" contract (state the planner assumes the database starts
-     * at). Only `migration plan` supplies this; `db update` / `db init`
-     * reconcile against the live schema with no old contract. When present
-     * alongside the `'data'` operation class, strategies that need from/to
-     * column shape comparisons (unsafe type change, nullability tightening)
-     * activate.
+     * at), or `null` for reconciliation flows. Only `migration plan` ever
+     * supplies a non-null value; `db update` / `db init` reconcile against
+     * the live schema and pass `null`. When present alongside the
+     * `'data'` operation class, strategies that need from/to column-shape
+     * comparisons (unsafe type change, nullability tightening) activate.
+     *
+     * Typed as the framework `Contract | null` to satisfy the
+     * `MigrationPlanner` interface contract; `planSql` narrows to the SQL
+     * shape via `SqlMigrationPlannerPlanOptions`. Used to populate
+     * `describe().from` on the produced plan as
+     * `fromContract?.storage.storageHash ?? null`.
      */
-    readonly fromContract?: unknown;
+    readonly fromContract: Contract | null;
     readonly schemaName?: string;
     readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+    /**
+     * Contract space this plan applies to. Stamped onto the produced
+     * {@link TypeScriptRenderablePostgresMigration.spaceId} so the runner keys
+     * the marker row by the right space.
+     */
+    readonly spaceId: string;
   }): PostgresPlanResult {
-    return this.planSql(options as SqlMigrationPlannerPlanOptions, options.fromHash ?? '');
+    return this.planSql(options as SqlMigrationPlannerPlanOptions);
   }
 
-  emptyMigration(context: MigrationScaffoldContext): MigrationPlanWithAuthoringSurface {
-    return new TypeScriptRenderablePostgresMigration([], {
-      from: context.fromHash,
-      to: context.toHash,
-    });
+  emptyMigration(
+    context: MigrationScaffoldContext,
+    spaceId: string,
+  ): MigrationPlanWithAuthoringSurface {
+    return new TypeScriptRenderablePostgresMigration(
+      [],
+      {
+        from: context.fromHash,
+        to: context.toHash,
+      },
+      spaceId,
+    );
   }
 
-  private planSql(options: SqlMigrationPlannerPlanOptions, fromHash: string): PostgresPlanResult {
+  private planSql(options: SqlMigrationPlannerPlanOptions): PostgresPlanResult {
     const schemaName = options.schemaName ?? this.config.defaultSchema;
     const policyResult = this.ensureAdditivePolicy(options.policy);
     if (policyResult) {
@@ -125,7 +148,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       // from/to comparisons (unsafe type change, nullable tightening) are
       // inapplicable there — reconciliation falls through to
       // `mapIssueToCall`'s direct destructive handlers.
-      fromContract: options.fromContract ?? null,
+      fromContract: options.fromContract,
       schemaName,
       codecHooks,
       storageTypes,
@@ -139,12 +162,31 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
       return plannerFailure(result.failure);
     }
 
+    // Inline `onFieldEvent`-emitted ops after structural DDL. The fixed
+    // ordering is `structural → added → dropped → altered`, with
+    // within-group sorting by `(tableName, fieldName)` so re-emits are
+    // byte-stable. The hook fires only at the application emitter —
+    // extension-space planning never reaches this helper.
+    const fieldEventOps = planFieldEventOperations({
+      priorContract: options.fromContract,
+      newContract: options.contract,
+      codecHooks,
+    });
+    // Codec-emitted calls already conform to `OpFactoryCall` — render +
+    // toOp + importRequirements ride directly through the same emit path
+    // as structural ops, no `RawSqlCall` wrap.
+    const calls = [...result.value.calls, ...fieldEventOps];
+
     return Object.freeze({
       kind: 'success' as const,
-      plan: new TypeScriptRenderablePostgresMigration(result.value.calls, {
-        from: fromHash,
-        to: options.contract.storage.storageHash,
-      }),
+      plan: new TypeScriptRenderablePostgresMigration(
+        calls,
+        {
+          from: options.fromContract?.storage.storageHash ?? null,
+          to: options.contract.storage.storageHash,
+        },
+        options.spaceId,
+      ),
     });
   }
 

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

@@ -1,14 +1,11 @@
 import type { Contract } from '@prisma-next/contract/types';
+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 type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { errorPostgresMigrationStackMissing } from '../errors';
-import {
-  type DataTransformOptions,
-  dataTransform,
-  type PostgresDataTransformOperation,
-} from './operations/data-transform';
+import { type DataTransformOptions, dataTransform } from './operations/data-transform';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
 /**
@@ -64,7 +61,7 @@ export abstract class PostgresMigration extends SqlMigration<
     contract: TContract,
     name: string,
     options: DataTransformOptions,
-  ): PostgresDataTransformOperation {
+  ): SqlMigrationPlanOperation<PostgresPlanTargetDetails> {
     if (!this.controlAdapter) {
       throw errorPostgresMigrationStackMissing();
     }

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

@@ -1,9 +1,32 @@
 import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
-import type { PostgresOpFactoryCall } from './op-factory-call';
+import type { OpFactoryCall } from '@prisma-next/framework-components/control';
 import type { PostgresPlanTargetDetails } from './planner-target-details';
 
 type Op = SqlMigrationPlanOperation<PostgresPlanTargetDetails>;
 
-export function renderOps(calls: readonly PostgresOpFactoryCall[]): Op[] {
-  return calls.map((c) => c.toOp());
+/**
+ * Asserts an op materialised by an `OpFactoryCall` targets postgres. The
+ * extension surface lets any contributor emit calls, so this is the
+ * integration boundary where a stray non-postgres op would otherwise
+ * 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;
+  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.`,
+    );
+  }
+}
+
+export function renderOps(calls: readonly OpFactoryCall[]): Op[] {
+  return calls.map((c) => {
+    const op = c.toOp();
+    assertPostgresOp(op, c.factoryName);
+    return op;
+  });
 }

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

@@ -1,7 +1,7 @@
 /**
  * Polymorphic TypeScript emitter for the Postgres migration IR.
  *
- * Each `PostgresOpFactoryCall` renders itself via `renderTypeScript()` and
+ * Each `OpFactoryCall` renders itself via `renderTypeScript()` and
  * declares its own `importRequirements()`; this file just composes the module
  * source around those contributions. The design mirrors the Mongo target's
  * `render-typescript.ts` deliberately — byte-for-byte alignment isn't required
@@ -9,14 +9,13 @@
  * shape is, so future consolidation to a framework-level helper is mechanical.
  */
 
+import type { OpFactoryCall } from '@prisma-next/framework-components/control';
 import { detectScaffoldRuntime, shebangLineFor } from '@prisma-next/migration-tools/migration-ts';
 import { type ImportRequirement, jsonToTsSource, renderImports } from '@prisma-next/ts-render';
-import type { PostgresOpFactoryCall } from './op-factory-call';
 
 export interface RenderMigrationMeta {
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
-  readonly kind?: string;
   readonly labels?: readonly string[];
 }
 
@@ -44,7 +43,7 @@ const BASE_IMPORTS: readonly ImportRequirement[] = [
 ];
 
 export function renderCallsToTypeScript(
-  calls: ReadonlyArray<PostgresOpFactoryCall>,
+  calls: ReadonlyArray<OpFactoryCall>,
   meta: RenderMigrationMeta,
 ): string {
   const imports = buildImports(calls);
@@ -68,7 +67,7 @@ export function renderCallsToTypeScript(
   ].join('\n');
 }
 
-function buildImports(calls: ReadonlyArray<PostgresOpFactoryCall>): string {
+function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
   const requirements: ImportRequirement[] = [...BASE_IMPORTS];
   for (const call of calls) {
     for (const req of call.importRequirements()) {
@@ -84,9 +83,6 @@ function buildDescribeMethod(meta: RenderMigrationMeta): string {
   lines.push('    return {');
   lines.push(`      from: ${JSON.stringify(meta.from)},`);
   lines.push(`      to: ${JSON.stringify(meta.to)},`);
-  if (meta.kind) {
-    lines.push(`      kind: ${JSON.stringify(meta.kind)},`);
-  }
   if (meta.labels && meta.labels.length > 0) {
     lines.push(`      labels: ${jsonToTsSource(meta.labels)},`);
   }