@prisma-next/target-postgres 0.4.1 → 0.4.3

package/src/core/migrations/runner.ts

@@ -1,7 +1,3 @@
-import {
-  normalizeSchemaNativeType,
-  parsePostgresDefault,
-} from '@prisma-next/adapter-postgres/control';
 import type { ContractMarkerRecord } from '@prisma-next/contract/types';
 import type {
   MigrationOperationPolicy,
@@ -16,16 +12,17 @@ import type {
 } 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 { readMarker } from '@prisma-next/family-sql/verify';
 import type { DataTransformOperation } from '@prisma-next/framework-components/control';
 import { SqlQueryError } from '@prisma-next/sql-errors';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { Result } from '@prisma-next/utils/result';
 import { 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';
 import {
   buildLedgerInsertStatement,
-  buildWriteMarkerStatements,
+  buildMergeMarkerStatements,
   ensureLedgerTableStatement,
   ensureMarkerTableStatement,
   ensurePrismaContractSchemaStatement,
@@ -122,7 +119,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     try {
       await this.acquireLock(driver, lockKey);
       await this.ensureControlTables(driver);
-      const existingMarker = await readMarker(driver);
+      const existingMarker = await this.family.readMarker({ driver });
 
       // Validate plan origin matches existing marker (needs marker from DB)
       const markerCheck = this.ensureMarkerCompatibility(existingMarker, options.plan);
@@ -130,9 +127,14 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
         return markerCheck;
       }
 
-      // db update (origin: null) always applies; migration-apply (origin set) skips if marker matches.
+      // db update (origin: null) always applies; migration-apply (origin set,
+      // origin !== destination) skips if marker already matches destination.
+      // Self-edges (origin === destination) intentionally bypass the skip:
+      // the migration is data-only, and the data transform's own check
+      // decides whether `run` fires.
       const markerAtDestination = this.markerMatchesDestination(existingMarker, options.plan);
-      const skipOperations = markerAtDestination && options.plan.origin != null;
+      const isSelfEdge = options.plan.origin?.storageHash === options.plan.destination.storageHash;
+      const skipOperations = markerAtDestination && options.plan.origin != null && !isSelfEdge;
       let applyValue: ApplyPlanSuccessValue;
 
       if (skipOperations) {
@@ -172,9 +174,39 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
         });
       }
 
-      // Record marker and ledger entries
-      await this.upsertMarker(driver, options, existingMarker);
-      await this.recordLedgerEntry(driver, options, existingMarker, applyValue.executedOperations);
+      // Self-edge no-op detection: a self-edge migration with zero ops in
+      // the plan that brings no new invariants produced no observable
+      // change. Skip the marker + ledger writes so an idempotent re-apply
+      // of a self-edge data transform doesn't churn updatedAt or pile up
+      // empty ledger entries. db update no-ops still write a ledger entry
+      // as audit trail.
+      //
+      // TODO(invariant-routing follow-up): `executeDataTransform` always
+      // counts every op it visits (including self-skips via `check === true`
+      // or empty idempotency probe), so `operationsExecuted === 0` here
+      // means "the plan had zero ops" rather than "every op self-skipped".
+      // The CLI is unaffected today because `migration-apply.ts` marker-
+      // subtraction empties `effectiveRequired` first and short-circuits
+      // before we run; the non-CLI re-apply path needs a per-op `executed`
+      // flag threaded through `executeDataTransform` to recover the
+      // intended check. See review thread A13 / future M5 ADR draft.
+      const incomingInvariants = options.plan.providedInvariants;
+      const existingInvariants = new Set(existingMarker?.invariants ?? []);
+      const incomingIsSubsetOfExisting = incomingInvariants.every((id) =>
+        existingInvariants.has(id),
+      );
+      const isSelfEdgeNoOp =
+        isSelfEdge && applyValue.operationsExecuted === 0 && incomingIsSubsetOfExisting;
+
+      if (!isSelfEdgeNoOp) {
+        await this.upsertMarker(driver, options, existingMarker);
+        await this.recordLedgerEntry(
+          driver,
+          options,
+          existingMarker,
+          applyValue.executedOperations,
+        );
+      }
 
       await this.commitTransaction(driver);
       committed = true;
@@ -619,7 +651,8 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
     options: SqlMigrationRunnerExecuteOptions<PostgresPlanTargetDetails>,
     existingMarker: ContractMarkerRecord | null,
   ): Promise<void> {
-    const writeStatements = buildWriteMarkerStatements({
+    const incomingInvariants = options.plan.providedInvariants;
+    const writeStatements = buildMergeMarkerStatements({
       storageHash: options.plan.destination.storageHash,
       profileHash:
         options.plan.destination.profileHash ??
@@ -628,6 +661,7 @@ class PostgresMigrationRunner implements SqlMigrationRunner<PostgresPlanTargetDe
       contractJson: options.destinationContract,
       canonicalVersion: null,
       meta: {},
+      invariants: incomingInvariants,
     });
     const statement = existingMarker ? writeStatements.update : writeStatements.insert;
     await this.executeStatement(driver, statement);

package/src/core/migrations/statement-builders.ts

@@ -17,7 +17,8 @@ export const ensureMarkerTableStatement: SqlStatement = {
     canonical_version int,
     updated_at timestamptz not null default now(),
     app_tag text,
-    meta jsonb not null default '{}'
+    meta jsonb not null default '{}',
+    invariants text[] not null default '{}'
   )`,
   params: [],
 };
@@ -37,16 +38,23 @@ export const ensureLedgerTableStatement: SqlStatement = {
   params: [],
 };
 
-export interface WriteMarkerInput {
+export interface MergeMarkerInput {
   readonly storageHash: string;
   readonly profileHash: string;
   readonly contractJson?: unknown;
   readonly canonicalVersion?: number | null;
   readonly appTag?: string | null;
   readonly meta?: Record<string, unknown>;
+  /**
+   * Invariants to merge into `marker.invariants`. INSERT writes them as
+   * the initial value (callers are expected to pass a sorted, deduped
+   * array). UPDATE merges them with the existing column server-side via
+   * a single atomic SQL expression.
+   */
+  readonly invariants: readonly string[];
 }
 
-export function buildWriteMarkerStatements(input: WriteMarkerInput): {
+export function buildMergeMarkerStatements(input: MergeMarkerInput): {
   readonly insert: SqlStatement;
   readonly update: SqlStatement;
 } {
@@ -58,6 +66,7 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
     input.canonicalVersion ?? null,
     input.appTag ?? null,
     jsonParam(input.meta ?? {}),
+    input.invariants,
   ];
 
   return {
@@ -70,7 +79,8 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
         canonical_version,
         updated_at,
         app_tag,
-        meta
+        meta,
+        invariants
       ) values (
         $1,
         $2,
@@ -79,11 +89,16 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
         $5,
         now(),
         $6,
-        $7::jsonb
+        $7::jsonb,
+        $8::text[]
       )`,
       params,
     },
     update: {
+      // `invariants = array(select distinct unnest(invariants || $8::text[]) order by 1)`
+      // reads the current column value under the UPDATE's row lock, unions
+      // with the incoming array, dedupes, and sorts ascending — single
+      // statement, atomic, no read-then-write window.
       sql: `update prisma_contract.marker set
         core_hash = $2,
         profile_hash = $3,
@@ -91,7 +106,8 @@ export function buildWriteMarkerStatements(input: WriteMarkerInput): {
         canonical_version = $5,
         updated_at = now(),
         app_tag = $6,
-        meta = $7::jsonb
+        meta = $7::jsonb,
+        invariants = array(select distinct unnest(invariants || $8::text[]) order by 1)
       where id = $1`,
       params,
     },

package/src/core/native-type-normalizer.ts

@@ -0,0 +1,49 @@
+/**
+ * Postgres native-type normalization.
+ *
+ * Lives in `target-postgres` because both the migration planner/runner (control
+ * plane) and the introspection adapter (control plane) need to normalize raw
+ * native-type strings to the same canonical form for comparison.
+ */
+
+/**
+ * Lookup map for simple prefix-based type normalization.
+ *
+ * Using a Map for O(1) lookup instead of multiple startsWith checks.
+ */
+const TYPE_PREFIX_MAP: ReadonlyMap<string, string> = new Map([
+  ['varchar', 'character varying'],
+  ['bpchar', 'character'],
+  ['varbit', 'bit varying'],
+]);
+
+/**
+ * Normalizes a Postgres schema native type to its canonical form for comparison.
+ *
+ * Uses a pre-computed lookup map for simple prefix replacements (O(1))
+ * and handles complex temporal type normalization separately.
+ */
+export function normalizeSchemaNativeType(nativeType: string): string {
+  const trimmed = nativeType.trim();
+
+  for (const [prefix, replacement] of TYPE_PREFIX_MAP) {
+    if (trimmed.startsWith(prefix)) {
+      return replacement + trimmed.slice(prefix.length);
+    }
+  }
+
+  if (trimmed.includes(' with time zone')) {
+    if (trimmed.startsWith('timestamp')) {
+      return `timestamptz${trimmed.slice(9).replace(' with time zone', '')}`;
+    }
+    if (trimmed.startsWith('time')) {
+      return `timetz${trimmed.slice(4).replace(' with time zone', '')}`;
+    }
+  }
+
+  if (trimmed.includes(' without time zone')) {
+    return trimmed.replace(' without time zone', '');
+  }
+
+  return trimmed;
+}

package/src/core/sql-utils.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared SQL utility functions for the Postgres target.
+ *
+ * These functions handle safe SQL identifier and literal escaping
+ * with security validations to prevent injection and encoding issues.
+ *
+ * They live in `target-postgres` because both the control adapter (used at
+ * emit time) and the runtime adapter (used at execute time) need the same
+ * escaping/validation behavior, and the target package is the natural shared
+ * home that both adapters can depend on without crossing planes.
+ */
+
+export class SqlEscapeError extends Error {
+  constructor(
+    message: string,
+    public readonly value: string,
+    public readonly kind: 'identifier' | 'literal',
+  ) {
+    super(message);
+    this.name = 'SqlEscapeError';
+  }
+}
+
+const MAX_IDENTIFIER_LENGTH = 63;
+
+/**
+ * Validates and quotes a PostgreSQL identifier (table, column, type, schema names).
+ *
+ * Security validations:
+ * - Rejects null bytes which could cause truncation or unexpected behavior
+ * - Rejects empty identifiers
+ * - Warns on identifiers exceeding PostgreSQL's 63-character limit
+ *
+ * @throws {SqlEscapeError} If the identifier contains null bytes or is empty
+ */
+export function quoteIdentifier(identifier: string): string {
+  if (identifier.length === 0) {
+    throw new SqlEscapeError('Identifier cannot be empty', identifier, 'identifier');
+  }
+  if (identifier.includes('\0')) {
+    throw new SqlEscapeError(
+      'Identifier cannot contain null bytes',
+      identifier.replace(/\0/g, '\\0'),
+      'identifier',
+    );
+  }
+  if (identifier.length > MAX_IDENTIFIER_LENGTH) {
+    console.warn(
+      `Identifier "${identifier.slice(0, 20)}..." exceeds PostgreSQL's ${MAX_IDENTIFIER_LENGTH}-character limit and will be truncated`,
+    );
+  }
+  return `"${identifier.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Escapes a string literal for safe use in SQL statements.
+ *
+ * Security validations:
+ * - Rejects null bytes which could cause truncation or unexpected behavior
+ *
+ * Note: This assumes PostgreSQL's `standard_conforming_strings` is ON (default since PG 9.1).
+ * Backslashes are treated as literal characters, not escape sequences.
+ *
+ * @throws {SqlEscapeError} If the value contains null bytes
+ */
+export function escapeLiteral(value: string): string {
+  if (value.includes('\0')) {
+    throw new SqlEscapeError(
+      'Literal value cannot contain null bytes',
+      value.replace(/\0/g, '\\0'),
+      'literal',
+    );
+  }
+  return value.replace(/'/g, "''");
+}
+
+/**
+ * Builds a qualified name (schema.object) with proper quoting.
+ */
+export function qualifyName(schemaName: string, objectName: string): string {
+  return `${quoteIdentifier(schemaName)}.${quoteIdentifier(objectName)}`;
+}
+
+/**
+ * Validates that an enum value doesn't exceed PostgreSQL's label length limit.
+ *
+ * PostgreSQL enum labels have a maximum length of NAMEDATALEN-1 (63 bytes by default).
+ * Unlike identifiers, enum labels that exceed this limit cause an error rather than
+ * silent truncation.
+ *
+ * @param value - The enum value to validate
+ * @param enumTypeName - Name of the enum type (for error messages)
+ * @throws {SqlEscapeError} If the value exceeds the maximum length
+ */
+export function validateEnumValueLength(value: string, enumTypeName: string): void {
+  if (value.length > MAX_IDENTIFIER_LENGTH) {
+    throw new SqlEscapeError(
+      `Enum value "${value.slice(0, 20)}..." for type "${enumTypeName}" exceeds PostgreSQL's ` +
+        `${MAX_IDENTIFIER_LENGTH}-character label limit`,
+      value,
+      'literal',
+    );
+  }
+}

package/src/exports/codec-ids.ts

@@ -0,0 +1 @@
+export * from '../core/codec-ids';

package/src/exports/codec-types.ts

@@ -0,0 +1,51 @@
+/**
+ * Codec type definitions for the Postgres target.
+ *
+ * This file exports type-only definitions for codec input/output types.
+ * These types are imported by generated `contract.d.ts` files for compile-time
+ * type inference.
+ *
+ * Lives in `target-postgres` because codec types describe the target's value
+ * space - both the control adapter (introspection / schema verification) and
+ * the runtime adapter (encode/decode) share the same definitions, and the
+ * target package is the natural home that both adapters depend on.
+ *
+ * Runtime codec implementations are provided by the runtime adapter's
+ * codec registry, which is built from `core/codecs.ts`.
+ */
+
+import type { JsonValue } from '@prisma-next/contract/types';
+import type { CodecTypes as CoreCodecTypes } from '../core/codecs';
+
+export type CodecTypes = CoreCodecTypes;
+
+export type { JsonValue };
+export { dataTypes } from '../core/codecs';
+
+type Branded<T, Shape extends Record<string, unknown>> = T & {
+  readonly [K in keyof Shape]: Shape[K];
+};
+
+type BrandedString<Shape extends Record<string, unknown>> = Branded<string, Shape>;
+
+export type Char<N extends number> = BrandedString<{ __charLength: N }>;
+export type Varchar<N extends number> = BrandedString<{ __varcharLength: N }>;
+export type Numeric<P extends number, S extends number | undefined = undefined> = BrandedString<{
+  __numericPrecision: P;
+  __numericScale: S;
+}>;
+export type Bit<N extends number> = BrandedString<{ __bitLength: N }>;
+export type VarBit<N extends number> = BrandedString<{ __varbitLength: N }>;
+export type Timestamp<P extends number | undefined = undefined> = BrandedString<{
+  __timestampPrecision: P;
+}>;
+export type Timestamptz<P extends number | undefined = undefined> = BrandedString<{
+  __timestamptzPrecision: P;
+}>;
+export type Time<P extends number | undefined = undefined> = BrandedString<{ __timePrecision: P }>;
+export type Timetz<P extends number | undefined = undefined> = BrandedString<{
+  __timetzPrecision: P;
+}>;
+export type Interval<P extends number | undefined = undefined> = BrandedString<{
+  __intervalPrecision: P;
+}>;

package/src/exports/codecs.ts

@@ -0,0 +1,2 @@
+export type { CodecTypes } from '../core/codecs';
+export { codecDefinitions, dataTypes } from '../core/codecs';

package/src/exports/data-transform.ts

@@ -0,0 +1 @@
+export { dataTransform } from '../core/migrations/operations/data-transform';

package/src/exports/default-normalizer.ts

@@ -0,0 +1 @@
+export { parsePostgresDefault } from '../core/default-normalizer';

package/src/exports/errors.ts

@@ -0,0 +1 @@
+export { errorPostgresMigrationStackMissing } from '../core/errors';

package/src/exports/issue-planner.ts

@@ -0,0 +1 @@
+export { planIssues } from '../core/migrations/issue-planner';

package/src/exports/migration.ts

@@ -1,3 +1,9 @@
+// Re-exported so a Postgres `migration.ts` only needs the single
+// `@prisma-next/target-postgres/migration` import for its base class
+// and the CLI entrypoint, mirroring how `placeholder` is surfaced
+// here. The renderer emits the entrypoint call as
+// `MigrationCLI.run(import.meta.url, M)`.
+export { MigrationCLI } from '@prisma-next/cli/migration-cli';
 // Re-exported so user-edited migration.ts files only need to depend on
 // `@prisma-next/target-postgres/migration` to fill in planner-emitted
 // `placeholder("…")` slots, instead of pulling in `@prisma-next/errors`

package/src/exports/native-type-normalizer.ts

@@ -0,0 +1 @@
+export { normalizeSchemaNativeType } from '../core/native-type-normalizer';

package/src/exports/op-factory-call.ts

@@ -0,0 +1,25 @@
+export {
+  AddColumnCall,
+  AddEnumValuesCall,
+  AddForeignKeyCall,
+  AddPrimaryKeyCall,
+  AddUniqueCall,
+  AlterColumnTypeCall,
+  CreateEnumTypeCall,
+  CreateExtensionCall,
+  CreateIndexCall,
+  CreateSchemaCall,
+  CreateTableCall,
+  DataTransformCall,
+  DropColumnCall,
+  DropConstraintCall,
+  DropDefaultCall,
+  DropEnumTypeCall,
+  DropIndexCall,
+  DropNotNullCall,
+  DropTableCall,
+  RawSqlCall,
+  RenameTypeCall,
+  SetDefaultCall,
+  SetNotNullCall,
+} from '../core/migrations/op-factory-call';

package/src/exports/planner-ddl-builders.ts

@@ -0,0 +1,8 @@
+export {
+  buildAddColumnSql,
+  buildColumnDefaultSql,
+  buildColumnTypeSql,
+  buildCreateTableSql,
+  buildForeignKeySql,
+  renderDefaultLiteral,
+} from '../core/migrations/planner-ddl-builders';

package/src/exports/planner-identity-values.ts

@@ -0,0 +1 @@
+export { buildBuiltinIdentityValue } from '../core/migrations/planner-identity-values';

package/src/exports/planner-produced-postgres-migration.ts

@@ -0,0 +1 @@
+export { TypeScriptRenderablePostgresMigration } from '../core/migrations/planner-produced-postgres-migration';

package/src/exports/planner-schema-lookup.ts

@@ -0,0 +1,6 @@
+export {
+  buildSchemaLookupMap,
+  hasForeignKey,
+  hasIndex,
+  hasUniqueConstraint,
+} from '../core/migrations/planner-schema-lookup';

package/src/exports/planner-sql-checks.ts

@@ -0,0 +1,11 @@
+export {
+  buildExpectedFormatType,
+  columnExistsCheck,
+  columnHasNoDefaultCheck,
+  columnNullabilityCheck,
+  constraintExistsCheck,
+  qualifyTableName,
+  tableHasPrimaryKeyCheck,
+  tableIsEmptyCheck,
+  toRegclassLiteral,
+} from '../core/migrations/planner-sql-checks';

package/src/exports/planner-target-details.ts

@@ -0,0 +1 @@
+export type { PostgresPlanTargetDetails } from '../core/migrations/planner-target-details';

package/src/exports/planner.ts

@@ -0,0 +1 @@
+export { createPostgresMigrationPlanner } from '../core/migrations/planner';

package/src/exports/render-ops.ts

@@ -0,0 +1 @@
+export { renderOps } from '../core/migrations/render-ops';

package/src/exports/render-typescript.ts

@@ -0,0 +1 @@
+export { renderCallsToTypeScript } from '../core/migrations/render-typescript';

package/src/exports/runtime.ts

@@ -1,14 +1,29 @@
-import type { RuntimeTargetInstance } from '@prisma-next/framework-components/execution';
+import type {
+  RuntimeTargetDescriptor,
+  RuntimeTargetInstance,
+} from '@prisma-next/framework-components/execution';
 import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
-import type { SqlRuntimeTargetDescriptor } from '@prisma-next/sql-runtime';
 import { postgresTargetDescriptorMeta } from '../core/descriptor-meta';
 
 export interface PostgresRuntimeTargetInstance extends RuntimeTargetInstance<'sql', 'postgres'> {}
 
-const postgresRuntimeTargetDescriptor: SqlRuntimeTargetDescriptor<
+/**
+ * Target-postgres deliberately does NOT import `SqlRuntimeTargetDescriptor`
+ * from `@prisma-next/sql-runtime`. The target package is a control-plane
+ * residence and must not pull the SQL execution-plane package into its
+ * dependency closure. The runtime descriptor here is shaped to satisfy the
+ * framework's `RuntimeTargetDescriptor` plus the structural
+ * `SqlStaticContributions` (`codecs`, `parameterizedCodecs`) that
+ * `@prisma-next/sql-runtime` consumers narrow to at composition time.
+ */
+const postgresRuntimeTargetDescriptor: RuntimeTargetDescriptor<
+  'sql',
   'postgres',
   PostgresRuntimeTargetInstance
-> = {
+> & {
+  readonly codecs: () => ReturnType<typeof createCodecRegistry>;
+  readonly parameterizedCodecs: () => readonly never[];
+} = {
   ...postgresTargetDescriptorMeta,
   codecs: () => createCodecRegistry(),
   parameterizedCodecs: () => [],

package/src/exports/sql-utils.ts

@@ -0,0 +1,7 @@
+export {
+  escapeLiteral,
+  qualifyName,
+  quoteIdentifier,
+  SqlEscapeError,
+  validateEnumValueLength,
+} from '../core/sql-utils';

package/src/exports/statement-builders.ts

@@ -0,0 +1,7 @@
+export type { SqlStatement } from '../core/migrations/statement-builders';
+export {
+  buildMergeMarkerStatements,
+  ensureLedgerTableStatement,
+  ensureMarkerTableStatement,
+  ensurePrismaContractSchemaStatement,
+} from '../core/migrations/statement-builders';

package/src/exports/types.ts

@@ -0,0 +1 @@
+export type { PostgresColumnDefault } from '../core/types';