@prisma-next/target-postgres 0.4.0-dev.8 → 0.4.1

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

@@ -0,0 +1,285 @@
+import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import {
+  columnDefaultExistsCheck,
+  columnExistsCheck,
+  columnNullabilityCheck,
+  columnTypeCheck,
+  qualifyTableName,
+} from '../planner-sql-checks';
+import { type ColumnSpec, type Op, step, targetDetails } from './shared';
+
+export function addColumn(schemaName: string, tableName: string, column: ColumnSpec): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  const parts = [
+    `ALTER TABLE ${qualified}`,
+    `ADD COLUMN ${quoteIdentifier(column.name)} ${column.typeSql}`,
+    column.defaultSql,
+    column.nullable ? '' : 'NOT NULL',
+  ].filter(Boolean);
+  const addSql = parts.join(' ');
+
+  return {
+    id: `column.${tableName}.${column.name}`,
+    label: `Add column "${column.name}" to "${tableName}"`,
+    operationClass: 'additive',
+    target: targetDetails('column', column.name, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure column "${column.name}" is missing`,
+        columnExistsCheck({
+          schema: schemaName,
+          table: tableName,
+          column: column.name,
+          exists: false,
+        }),
+      ),
+    ],
+    execute: [step(`add column "${column.name}"`, addSql)],
+    postcheck: [
+      step(
+        `verify column "${column.name}" exists`,
+        columnExistsCheck({ schema: schemaName, table: tableName, column: column.name }),
+      ),
+    ],
+  };
+}
+
+export function dropColumn(schemaName: string, tableName: string, columnName: string): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  return {
+    id: `dropColumn.${tableName}.${columnName}`,
+    label: `Drop column "${columnName}" from "${tableName}"`,
+    operationClass: 'destructive',
+    target: targetDetails('column', columnName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure column "${columnName}" exists`,
+        columnExistsCheck({ schema: schemaName, table: tableName, column: columnName }),
+      ),
+    ],
+    execute: [
+      step(
+        `drop column "${columnName}"`,
+        `ALTER TABLE ${qualified} DROP COLUMN ${quoteIdentifier(columnName)}`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify column "${columnName}" does not exist`,
+        columnExistsCheck({
+          schema: schemaName,
+          table: tableName,
+          column: columnName,
+          exists: false,
+        }),
+      ),
+    ],
+  };
+}
+
+/**
+ * `qualifiedTargetType` is the new column type as it appears in the
+ * `ALTER COLUMN TYPE` clause (schema-qualified for user-defined types, raw
+ * native name for built-ins). `formatTypeExpected` is the unqualified
+ * `format_type` form used in the postcheck. `rawTargetTypeForLabel` is the
+ * string appearing in the human-readable label (typically `toType` when
+ * explicit, else the column's native type).
+ */
+export function alterColumnType(
+  schemaName: string,
+  tableName: string,
+  columnName: string,
+  options: {
+    readonly qualifiedTargetType: string;
+    readonly formatTypeExpected: string;
+    readonly rawTargetTypeForLabel: string;
+    readonly using?: string;
+  },
+): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  const usingClause = options.using
+    ? ` USING ${options.using}`
+    : ` USING ${quoteIdentifier(columnName)}::${options.qualifiedTargetType}`;
+  return {
+    id: `alterType.${tableName}.${columnName}`,
+    label: `Alter type of "${tableName}"."${columnName}" to ${options.rawTargetTypeForLabel}`,
+    operationClass: 'destructive',
+    target: targetDetails('column', columnName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure column "${columnName}" exists`,
+        columnExistsCheck({ schema: schemaName, table: tableName, column: columnName }),
+      ),
+    ],
+    execute: [
+      step(
+        `alter type of "${columnName}"`,
+        `ALTER TABLE ${qualified} ALTER COLUMN ${quoteIdentifier(columnName)} TYPE ${options.qualifiedTargetType}${usingClause}`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify column "${columnName}" has type "${options.formatTypeExpected}"`,
+        columnTypeCheck({
+          schema: schemaName,
+          table: tableName,
+          column: columnName,
+          expectedType: options.formatTypeExpected,
+        }),
+      ),
+    ],
+    meta: { warning: 'TABLE_REWRITE' },
+  };
+}
+
+export function setNotNull(schemaName: string, tableName: string, columnName: string): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  return {
+    id: `alterNullability.setNotNull.${tableName}.${columnName}`,
+    label: `Set NOT NULL on "${tableName}"."${columnName}"`,
+    operationClass: 'destructive',
+    target: targetDetails('column', columnName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure column "${columnName}" exists`,
+        columnExistsCheck({ schema: schemaName, table: tableName, column: columnName }),
+      ),
+      step(
+        `ensure no NULL values in "${columnName}"`,
+        `SELECT NOT EXISTS (SELECT 1 FROM ${qualified} WHERE ${quoteIdentifier(columnName)} IS NULL)`,
+      ),
+    ],
+    execute: [
+      step(
+        `set NOT NULL on "${columnName}"`,
+        `ALTER TABLE ${qualified} ALTER COLUMN ${quoteIdentifier(columnName)} SET NOT NULL`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify column "${columnName}" is NOT NULL`,
+        columnNullabilityCheck({
+          schema: schemaName,
+          table: tableName,
+          column: columnName,
+          nullable: false,
+        }),
+      ),
+    ],
+  };
+}
+
+export function dropNotNull(schemaName: string, tableName: string, columnName: string): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  return {
+    id: `alterNullability.dropNotNull.${tableName}.${columnName}`,
+    label: `Drop NOT NULL on "${tableName}"."${columnName}"`,
+    operationClass: 'widening',
+    target: targetDetails('column', columnName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure column "${columnName}" exists`,
+        columnExistsCheck({ schema: schemaName, table: tableName, column: columnName }),
+      ),
+    ],
+    execute: [
+      step(
+        `drop NOT NULL on "${columnName}"`,
+        `ALTER TABLE ${qualified} ALTER COLUMN ${quoteIdentifier(columnName)} DROP NOT NULL`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify column "${columnName}" is nullable`,
+        columnNullabilityCheck({
+          schema: schemaName,
+          table: tableName,
+          column: columnName,
+          nullable: true,
+        }),
+      ),
+    ],
+  };
+}
+
+/**
+ * `defaultSql` is the full `DEFAULT …` clause as produced by
+ * `buildColumnDefaultSql` — e.g. `"DEFAULT 42"`,
+ * `"DEFAULT (CURRENT_TIMESTAMP)"`, or `"DEFAULT nextval('seq'::regclass)"`.
+ *
+ * `operationClass` defaults to `'additive'` (setting a default on a column
+ * that currently has none). The reconciliation planner passes `'widening'`
+ * when the column already has a different default — policy enforcement
+ * treats that as a widening change rather than an additive one.
+ */
+export function setDefault(
+  schemaName: string,
+  tableName: string,
+  columnName: string,
+  defaultSql: string,
+  operationClass: 'additive' | 'widening' = 'additive',
+): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  return {
+    id: `setDefault.${tableName}.${columnName}`,
+    label: `Set default on "${tableName}"."${columnName}"`,
+    operationClass,
+    target: targetDetails('column', columnName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure column "${columnName}" exists`,
+        columnExistsCheck({ schema: schemaName, table: tableName, column: columnName }),
+      ),
+    ],
+    execute: [
+      step(
+        `set default on "${columnName}"`,
+        `ALTER TABLE ${qualified} ALTER COLUMN ${quoteIdentifier(columnName)} SET ${defaultSql}`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify column "${columnName}" has a default`,
+        columnDefaultExistsCheck({
+          schema: schemaName,
+          table: tableName,
+          column: columnName,
+          exists: true,
+        }),
+      ),
+    ],
+  };
+}
+
+export function dropDefault(schemaName: string, tableName: string, columnName: string): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  return {
+    id: `dropDefault.${tableName}.${columnName}`,
+    label: `Drop default on "${tableName}"."${columnName}"`,
+    operationClass: 'destructive',
+    target: targetDetails('column', columnName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure column "${columnName}" exists`,
+        columnExistsCheck({ schema: schemaName, table: tableName, column: columnName }),
+      ),
+    ],
+    execute: [
+      step(
+        `drop default on "${columnName}"`,
+        `ALTER TABLE ${qualified} ALTER COLUMN ${quoteIdentifier(columnName)} DROP DEFAULT`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify column "${columnName}" has no default`,
+        columnDefaultExistsCheck({
+          schema: schemaName,
+          table: tableName,
+          column: columnName,
+          exists: false,
+        }),
+      ),
+    ],
+  };
+}

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

@@ -0,0 +1,191 @@
+import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import type { ReferentialAction } from '@prisma-next/sql-contract/types';
+import { constraintExistsCheck, qualifyTableName } from '../planner-sql-checks';
+import { type ForeignKeySpec, type Op, step, targetDetails } from './shared';
+
+const REFERENTIAL_ACTION_SQL: Record<ReferentialAction, string> = {
+  noAction: 'NO ACTION',
+  restrict: 'RESTRICT',
+  cascade: 'CASCADE',
+  setNull: 'SET NULL',
+  setDefault: 'SET DEFAULT',
+};
+
+function renderForeignKeySql(schemaName: string, tableName: string, fk: ForeignKeySpec): string {
+  let sql = `ALTER TABLE ${qualifyTableName(schemaName, tableName)}
+ADD CONSTRAINT ${quoteIdentifier(fk.name)}
+FOREIGN KEY (${fk.columns.map(quoteIdentifier).join(', ')})
+REFERENCES ${qualifyTableName(schemaName, fk.references.table)} (${fk.references.columns
+    .map(quoteIdentifier)
+    .join(', ')})`;
+
+  if (fk.onDelete !== undefined) {
+    const action = REFERENTIAL_ACTION_SQL[fk.onDelete];
+    if (!action) {
+      throw new Error(`Unknown referential action for onDelete: ${String(fk.onDelete)}`);
+    }
+    sql += `\nON DELETE ${action}`;
+  }
+  if (fk.onUpdate !== undefined) {
+    const action = REFERENTIAL_ACTION_SQL[fk.onUpdate];
+    if (!action) {
+      throw new Error(`Unknown referential action for onUpdate: ${String(fk.onUpdate)}`);
+    }
+    sql += `\nON UPDATE ${action}`;
+  }
+  return sql;
+}
+
+export function addPrimaryKey(
+  schemaName: string,
+  tableName: string,
+  constraintName: string,
+  columns: readonly string[],
+): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  const columnList = columns.map(quoteIdentifier).join(', ');
+  return {
+    id: `primaryKey.${tableName}.${constraintName}`,
+    label: `Add primary key on "${tableName}"`,
+    operationClass: 'additive',
+    target: targetDetails('primaryKey', constraintName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure primary key "${constraintName}" does not exist`,
+        constraintExistsCheck({
+          constraintName,
+          schema: schemaName,
+          table: tableName,
+          exists: false,
+        }),
+      ),
+    ],
+    execute: [
+      step(
+        `add primary key "${constraintName}"`,
+        `ALTER TABLE ${qualified} ADD CONSTRAINT ${quoteIdentifier(constraintName)} PRIMARY KEY (${columnList})`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify primary key "${constraintName}" exists`,
+        constraintExistsCheck({ constraintName, schema: schemaName, table: tableName }),
+      ),
+    ],
+  };
+}
+
+export function addUnique(
+  schemaName: string,
+  tableName: string,
+  constraintName: string,
+  columns: readonly string[],
+): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  const columnList = columns.map(quoteIdentifier).join(', ');
+  return {
+    id: `unique.${tableName}.${constraintName}`,
+    label: `Add unique constraint on "${tableName}" (${columns.join(', ')})`,
+    operationClass: 'additive',
+    target: targetDetails('unique', constraintName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure constraint "${constraintName}" does not exist`,
+        constraintExistsCheck({
+          constraintName,
+          schema: schemaName,
+          table: tableName,
+          exists: false,
+        }),
+      ),
+    ],
+    execute: [
+      step(
+        `add unique constraint "${constraintName}"`,
+        `ALTER TABLE ${qualified} ADD CONSTRAINT ${quoteIdentifier(constraintName)} UNIQUE (${columnList})`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify constraint "${constraintName}" exists`,
+        constraintExistsCheck({ constraintName, schema: schemaName, table: tableName }),
+      ),
+    ],
+  };
+}
+
+export function addForeignKey(schemaName: string, tableName: string, fk: ForeignKeySpec): Op {
+  return {
+    id: `foreignKey.${tableName}.${fk.name}`,
+    label: `Add foreign key "${fk.name}" on "${tableName}"`,
+    operationClass: 'additive',
+    target: targetDetails('foreignKey', fk.name, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure FK "${fk.name}" does not exist`,
+        constraintExistsCheck({
+          constraintName: fk.name,
+          schema: schemaName,
+          table: tableName,
+          exists: false,
+        }),
+      ),
+    ],
+    execute: [step(`add FK "${fk.name}"`, renderForeignKeySql(schemaName, tableName, fk))],
+    postcheck: [
+      step(
+        `verify FK "${fk.name}" exists`,
+        constraintExistsCheck({
+          constraintName: fk.name,
+          schema: schemaName,
+          table: tableName,
+        }),
+      ),
+    ],
+  };
+}
+
+/**
+ * `kind` feeds the operation's `target.details.objectType`. Descriptor-flow
+ * does not carry kind information in its drop-constraint descriptor, so the
+ * default is `'unique'`. The reconciliation planner passes the correct kind
+ * (`'foreignKey'`, `'primaryKey'`, or `'unique'`) based on the `SchemaIssue`
+ * that produced the drop.
+ */
+export function dropConstraint(
+  schemaName: string,
+  tableName: string,
+  constraintName: string,
+  kind: 'foreignKey' | 'unique' | 'primaryKey' = 'unique',
+): Op {
+  const qualified = qualifyTableName(schemaName, tableName);
+  return {
+    id: `dropConstraint.${tableName}.${constraintName}`,
+    label: `Drop constraint "${constraintName}" on "${tableName}"`,
+    operationClass: 'destructive',
+    target: targetDetails(kind, constraintName, schemaName, tableName),
+    precheck: [
+      step(
+        `ensure constraint "${constraintName}" exists`,
+        constraintExistsCheck({ constraintName, schema: schemaName, table: tableName }),
+      ),
+    ],
+    execute: [
+      step(
+        `drop constraint "${constraintName}"`,
+        `ALTER TABLE ${qualified} DROP CONSTRAINT ${quoteIdentifier(constraintName)}`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify constraint "${constraintName}" does not exist`,
+        constraintExistsCheck({
+          constraintName,
+          schema: schemaName,
+          table: tableName,
+          exists: false,
+        }),
+      ),
+    ],
+  };
+}

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

@@ -0,0 +1,113 @@
+/**
+ * User-facing `dataTransform` factory for the Postgres migration authoring
+ * surface. Invoked directly inside a `migration.ts` file:
+ *
+ * ```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()),
+ * });
+ * ```
+ *
+ * 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`.
+ */
+
+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 {
+  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>;
+}
+
+/**
+ * A single-closure producer of a SQL query plan. Shared between
+ * `check` and each `run` entry.
+ */
+export type DataTransformClosure = () => SqlQueryPlan | Buildable;
+
+export interface DataTransformOptions {
+  /** Optional pre-flight query. `undefined` means "no check". */
+  readonly check?: DataTransformClosure;
+  /** One or more mutation queries to execute. */
+  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;
+}
+
+export function dataTransform<TContract extends Contract<SqlStorage>>(
+  contract: TContract,
+  name: string,
+  options: DataTransformOptions,
+): DataTransformOperation {
+  const adapter = getAdapter();
+  const runClosures: readonly DataTransformClosure[] = Array.isArray(options.run)
+    ? options.run
+    : [options.run as DataTransformClosure];
+  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)),
+  };
+}
+
+function invokeAndLower(
+  closure: DataTransformClosure,
+  contract: Contract<SqlStorage>,
+  adapter: ReturnType<typeof createPostgresAdapter>,
+  name: string,
+): SerializedQueryPlan {
+  const result = closure();
+  const plan = isBuildable(result) ? result.build() : result;
+  assertContractMatches(plan, contract, name);
+  const lowered = lowerSqlPlan(adapter, contract, plan);
+  return { sql: lowered.sql, params: lowered.params };
+}
+
+function isBuildable(value: unknown): value is Buildable {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'build' in value &&
+    typeof (value as { build: unknown }).build === 'function'
+  );
+}
+
+function assertContractMatches(
+  plan: SqlQueryPlan,
+  contract: Contract<SqlStorage>,
+  name: string,
+): void {
+  if (plan.meta.storageHash !== contract.storage.storageHash) {
+    throw errorDataTransformContractMismatch({
+      dataTransformName: name,
+      expected: contract.storage.storageHash,
+      actual: plan.meta.storageHash,
+    });
+  }
+}

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

@@ -0,0 +1,36 @@
+import { quoteIdentifier } from '@prisma-next/adapter-postgres/control';
+import { type Op, step } from './shared';
+
+export function createExtension(extensionName: string): Op {
+  return {
+    id: `extension.${extensionName}`,
+    label: `Create extension "${extensionName}"`,
+    operationClass: 'additive',
+    target: { id: 'postgres' },
+    precheck: [],
+    execute: [
+      step(
+        `Create extension "${extensionName}"`,
+        `CREATE EXTENSION IF NOT EXISTS ${quoteIdentifier(extensionName)}`,
+      ),
+    ],
+    postcheck: [],
+  };
+}
+
+export function createSchema(schemaName: string): Op {
+  return {
+    id: `schema.${schemaName}`,
+    label: `Create schema "${schemaName}"`,
+    operationClass: 'additive',
+    target: { id: 'postgres' },
+    precheck: [],
+    execute: [
+      step(
+        `Create schema "${schemaName}"`,
+        `CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(schemaName)}`,
+      ),
+    ],
+    postcheck: [],
+  };
+}