@prisma-next/target-postgres 0.5.0-dev.6 → 0.5.0-dev.60

package/src/core/codecs.ts

@@ -19,6 +19,7 @@ import { type as arktype } from 'arktype';
 import {
   PG_BIT_CODEC_ID,
   PG_BOOL_CODEC_ID,
+  PG_BYTEA_CODEC_ID,
   PG_CHAR_CODEC_ID,
   PG_ENUM_CODEC_ID,
   PG_FLOAT_CODEC_ID,
@@ -40,7 +41,6 @@ import {
   PG_VARBIT_CODEC_ID,
   PG_VARCHAR_CODEC_ID,
 } from './codec-ids';
-import { renderTypeScriptTypeFromJsonSchema } from './json-schema-type-expression';
 
 const lengthParamsSchema = arktype({
   length: 'number.integer > 0',
@@ -85,19 +85,13 @@ function renderPrecision(typeName: string, typeParams: Record<string, unknown>):
   return `${typeName}<${precision}>`;
 }
 
-function renderJsonOutputType(typeParams: Record<string, unknown>): string {
-  const typeName = typeParams['type'];
-  if (typeof typeName === 'string' && typeName.trim().length > 0) {
-    return typeName.trim();
-  }
-  const schema = typeParams['schemaJson'];
-  if (schema && typeof schema === 'object') {
-    return renderTypeScriptTypeFromJsonSchema(schema);
-  }
-  throw new Error(
-    `renderOutputType: JSON codec typeParams must contain "type" (string) or "schemaJson" (object), got keys: ${Object.keys(typeParams).join(', ')}`,
-  );
-}
+// Phase C: postgres' raw json/jsonb codecs no longer carry a
+// `renderOutputType` slot — the schema-typed JSON surface that drove
+// `typeParams: { schemaJson, type? }` retired in favor of the per-library
+// extension package (`@prisma-next/extension-arktype-json`). Untyped
+// json/jsonb columns have no typeParams; the framework emit path falls
+// through to the generic `CodecTypes['pg/jsonb@1']['output']` accessor
+// (which resolves to `JsonValue` via the codec-types map).
 
 function aliasCodec<
   Id extends string,
@@ -339,22 +333,15 @@ const pgFloat8Codec = codec({
 const pgTimestampCodec = codec<
   typeof PG_TIMESTAMP_CODEC_ID,
   readonly ['equality', 'order'],
-  string | Date,
-  string | Date
+  Date,
+  Date
 >({
   typeId: PG_TIMESTAMP_CODEC_ID,
   targetTypes: ['timestamp'],
   traits: ['equality', 'order'],
-  encode: (value: string | Date): string => {
-    if (value instanceof Date) return value.toISOString();
-    if (typeof value === 'string') return value;
-    return String(value);
-  },
-  decode: (wire: string | Date): string => {
-    if (wire instanceof Date) return wire.toISOString();
-    return wire;
-  },
-  encodeJson: (value: string | Date) => (value instanceof Date ? value.toISOString() : value),
+  encode: (value: Date): Date => value,
+  decode: (wire: Date): Date => wire,
+  encodeJson: (value: Date) => value.toISOString(),
   decodeJson: (json) => {
     if (typeof json !== 'string') {
       throw new Error(`Expected ISO date string for pg/timestamp@1, got ${typeof json}`);
@@ -381,22 +368,15 @@ const pgTimestampCodec = codec<
 const pgTimestamptzCodec = codec<
   typeof PG_TIMESTAMPTZ_CODEC_ID,
   readonly ['equality', 'order'],
-  string | Date,
-  string | Date
+  Date,
+  Date
 >({
   typeId: PG_TIMESTAMPTZ_CODEC_ID,
   targetTypes: ['timestamptz'],
   traits: ['equality', 'order'],
-  encode: (value: string | Date): string => {
-    if (value instanceof Date) return value.toISOString();
-    if (typeof value === 'string') return value;
-    return String(value);
-  },
-  decode: (wire: string | Date): string => {
-    if (wire instanceof Date) return wire.toISOString();
-    return wire;
-  },
-  encodeJson: (value: string | Date) => (value instanceof Date ? value.toISOString() : value),
+  encode: (value: Date): Date => value,
+  decode: (wire: Date): Date => wire,
+  encodeJson: (value: Date) => value.toISOString(),
   decodeJson: (json) => {
     if (typeof json !== 'string') {
       throw new Error(`Expected ISO date string for pg/timestamptz@1, got ${typeof json}`);
@@ -523,6 +503,40 @@ const pgVarbitCodec = codec<
   },
 });
 
+const pgByteaCodec = codec({
+  typeId: PG_BYTEA_CODEC_ID,
+  targetTypes: ['bytea'],
+  traits: ['equality'],
+  encode: (value: Uint8Array): Uint8Array => value,
+  decode: (wire: Uint8Array): Uint8Array =>
+    // Postgres node drivers commonly return Buffer instances (which extend
+    // Uint8Array) — normalize to a plain Uint8Array view so engine-agnostic
+    // consumers don't accidentally observe Buffer-specific APIs.
+    wire instanceof Uint8Array && wire.constructor === Uint8Array
+      ? wire
+      : new Uint8Array(wire.buffer, wire.byteOffset, wire.byteLength),
+  encodeJson: (value: Uint8Array): string => Buffer.from(value).toString('base64'),
+  decodeJson: (json): Uint8Array => {
+    if (typeof json !== 'string') {
+      throw new Error(`Expected base64 string for pg/bytea@1, got ${typeof json}`);
+    }
+    const decoded = Buffer.from(json, 'base64');
+    if (decoded.toString('base64') !== json) {
+      throw new Error(`Invalid base64 string for pg/bytea@1 (length: ${json.length})`);
+    }
+    return new Uint8Array(decoded);
+  },
+  meta: {
+    db: {
+      sql: {
+        postgres: {
+          nativeType: 'bytea',
+        },
+      },
+    },
+  },
+});
+
 const pgEnumCodec = codec({
   typeId: PG_ENUM_CODEC_ID,
   targetTypes: ['enum'],
@@ -576,7 +590,6 @@ const pgJsonCodec = codec({
   encode: (value: string | JsonValue): string => JSON.stringify(value),
   decode: (wire: string | JsonValue): JsonValue =>
     typeof wire === 'string' ? JSON.parse(wire) : wire,
-  renderOutputType: renderJsonOutputType,
   meta: {
     db: {
       sql: {
@@ -595,7 +608,6 @@ const pgJsonbCodec = codec({
   encode: (value: string | JsonValue): string => JSON.stringify(value),
   decode: (wire: string | JsonValue): JsonValue =>
     typeof wire === 'string' ? JSON.parse(wire) : wire,
-  renderOutputType: renderJsonOutputType,
   meta: {
     db: {
       sql: {
@@ -633,6 +645,7 @@ const codecs = defineCodecs()
   .add('bool', pgBoolCodec)
   .add('bit', pgBitCodec)
   .add('bit varying', pgVarbitCodec)
+  .add('bytea', pgByteaCodec)
   .add('interval', pgIntervalCodec)
   .add('enum', pgEnumCodec)
   .add('json', pgJsonCodec)

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

@@ -60,7 +60,6 @@ export class TypeScriptRenderablePostgresMigration
     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,3 +1,4 @@
+import type { Contract } from '@prisma-next/contract/types';
 import type {
   MigrationOperationPolicy,
   SqlMigrationPlannerPlanOptions,
@@ -83,20 +84,25 @@ 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>>;
   }): PostgresPlanResult {
-    return this.planSql(options as SqlMigrationPlannerPlanOptions, options.fromHash ?? '');
+    return this.planSql(options as SqlMigrationPlannerPlanOptions);
   }
 
   emptyMigration(context: MigrationScaffoldContext): MigrationPlanWithAuthoringSurface {
@@ -106,7 +112,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     });
   }
 
-  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 +131,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,
@@ -142,7 +148,7 @@ export class PostgresMigrationPlanner implements MigrationPlanner<'sql', 'postgr
     return Object.freeze({
       kind: 'success' as const,
       plan: new TypeScriptRenderablePostgresMigration(result.value.calls, {
-        from: fromHash,
+        from: options.fromContract?.storage.storageHash ?? null,
         to: options.contract.storage.storageHash,
       }),
     });

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-typescript.ts

@@ -14,9 +14,8 @@ import { type ImportRequirement, jsonToTsSource, renderImports } from '@prisma-n
 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[];
 }
 
@@ -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)},`);
   }