@prisma-next/family-sql 0.3.0-dev.6 → 0.3.0-dev.63

package/src/core/migrations/contract-to-schema-ir.ts

@@ -0,0 +1,181 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+import type { MigrationPlannerConflict } from '@prisma-next/core-control-plane/types';
+import type {
+  ForeignKey,
+  Index,
+  SqlStorage,
+  StorageColumn,
+  StorageTable,
+  UniqueConstraint,
+} from '@prisma-next/sql-contract/types';
+import type {
+  SqlColumnIR,
+  SqlForeignKeyIR,
+  SqlIndexIR,
+  SqlSchemaIR,
+  SqlTableIR,
+  SqlUniqueIR,
+} from '@prisma-next/sql-schema-ir/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+function convertDefault(def: ColumnDefault): string {
+  if (def.kind === 'function') {
+    return def.expression;
+  }
+  if (typeof def.value === 'string') {
+    return `'${def.value.replaceAll("'", "''")}'`;
+  }
+  return String(def.value);
+}
+
+/**
+ * Target-specific callback that expands a column's base `nativeType` and optional
+ * `typeParams` into the fully-qualified type string used by the database
+ * (e.g. `character` + `{ length: 36 }` → `character(36)`).
+ *
+ * This lives in the family layer as a callback rather than importing a concrete
+ * implementation because each target (Postgres, MySQL, SQLite, …) has its own
+ * parameterization syntax. The target wires its expander when calling
+ * `contractToSchemaIR`, keeping the family layer target-agnostic.
+ */
+export type NativeTypeExpander = (input: {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}) => string;
+
+function convertColumn(
+  name: string,
+  column: StorageColumn,
+  expandNativeType?: NativeTypeExpander,
+): SqlColumnIR {
+  const nativeType = expandNativeType
+    ? expandNativeType({
+        nativeType: column.nativeType,
+        codecId: column.codecId,
+        ...ifDefined('typeParams', column.typeParams),
+      })
+    : column.nativeType;
+  return {
+    name,
+    nativeType,
+    nullable: column.nullable,
+    ...(column.default != null ? { default: convertDefault(column.default) } : {}),
+  };
+}
+
+function convertUnique(unique: UniqueConstraint): SqlUniqueIR {
+  return {
+    columns: unique.columns,
+    ...(unique.name != null ? { name: unique.name } : {}),
+  };
+}
+
+function convertIndex(index: Index): SqlIndexIR {
+  return {
+    columns: index.columns,
+    unique: false,
+    ...(index.name != null ? { name: index.name } : {}),
+  };
+}
+
+function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
+  return {
+    columns: fk.columns,
+    referencedTable: fk.references.table,
+    referencedColumns: fk.references.columns,
+    ...(fk.name != null ? { name: fk.name } : {}),
+  };
+}
+
+function convertTable(
+  name: string,
+  table: StorageTable,
+  expandNativeType?: NativeTypeExpander,
+): SqlTableIR {
+  const columns: Record<string, SqlColumnIR> = {};
+  for (const [colName, colDef] of Object.entries(table.columns)) {
+    columns[colName] = convertColumn(colName, colDef, expandNativeType);
+  }
+
+  return {
+    name,
+    columns,
+    ...(table.primaryKey != null ? { primaryKey: table.primaryKey } : {}),
+    foreignKeys: table.foreignKeys.map(convertForeignKey),
+    uniques: table.uniques.map(convertUnique),
+    indexes: table.indexes.map(convertIndex),
+  };
+}
+
+/**
+ * Detects destructive changes between two contract storages.
+ *
+ * The additive-only planner silently ignores removals (tables, columns).
+ * This function detects those removals so callers can report them as conflicts
+ * rather than silently producing an empty plan.
+ *
+ * Returns an empty array if no destructive changes are found.
+ */
+export function detectDestructiveChanges(
+  from: SqlStorage | null,
+  to: SqlStorage,
+): readonly MigrationPlannerConflict[] {
+  if (!from) return [];
+
+  const hasOwn = (value: object, key: string): boolean => Object.hasOwn(value, key);
+
+  const conflicts: MigrationPlannerConflict[] = [];
+
+  for (const tableName of Object.keys(from.tables)) {
+    if (!hasOwn(to.tables, tableName)) {
+      conflicts.push({
+        kind: 'tableRemoved',
+        summary: `Table "${tableName}" was removed`,
+      });
+      continue;
+    }
+
+    const toTable = to.tables[tableName] as StorageTable;
+    const fromTable = from.tables[tableName];
+    if (!fromTable) continue;
+
+    for (const columnName of Object.keys(fromTable.columns)) {
+      if (!hasOwn(toTable.columns, columnName)) {
+        conflicts.push({
+          kind: 'columnRemoved',
+          summary: `Column "${tableName}"."${columnName}" was removed`,
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Converts a contract's `SqlStorage` to `SqlSchemaIR`.
+ *
+ * Drops codec metadata (`codecId`, `typeRef`) since the schema IR only represents structural
+ * information. When `expandNativeType` is provided, parameterized types are expanded
+ * (e.g. `character` + `{ length: 36 }` → `character(36)`) so the resulting IR compares
+ * correctly against the "to" contract during planning.
+ *
+ * `extensions` is always `[]` — the planner resolves extension dependencies from framework
+ * components, and an empty array means "nothing installed yet" which is correct for the
+ * "from" side of a diff.
+ */
+export function contractToSchemaIR(
+  storage: SqlStorage,
+  expandNativeType?: NativeTypeExpander,
+): SqlSchemaIR {
+  const tables: Record<string, SqlTableIR> = {};
+  for (const [tableName, tableDef] of Object.entries(storage.tables)) {
+    tables[tableName] = convertTable(tableName, tableDef, expandNativeType);
+  }
+
+  return {
+    tables,
+    extensions: [],
+  };
+}

package/src/core/migrations/types.ts

@@ -1,12 +1,6 @@
-/**
- * SQL-specific migration types.
- *
- * These types extend the canonical migration types from the framework control plane
- * with SQL-specific fields for execution (precheck SQL, execute SQL, etc.).
- */
-
 import type { TargetBoundComponentDescriptor } from '@prisma-next/contract/framework-components';
 import type {
+  ControlAdapterDescriptor,
   ControlDriverInstance,
   ControlExtensionDescriptor,
   ControlTargetDescriptor,
@@ -23,109 +17,100 @@ import type {
   OperationContext,
   SchemaIssue,
 } from '@prisma-next/core-control-plane/types';
-import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlContract, SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import type { SqlOperationSignature } from '@prisma-next/sql-operations';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import type { Result } from '@prisma-next/utils/result';
-import type { SqlControlFamilyInstance } from '../instance';
+import type { SqlControlFamilyInstance } from '../control-instance';
 
 export type AnyRecord = Readonly<Record<string, unknown>>;
 
-// ============================================================================
-// Component Database Dependencies
-// ============================================================================
+export interface SqlControlStaticContributions {
+  readonly operationSignatures: () => ReadonlyArray<SqlOperationSignature>;
+}
 
-/**
- * A single database dependency declared by a framework component.
- * Uses SqlMigrationPlanOperation so we inherit the existing precheck/execute/postcheck contract.
- *
- * Database dependencies allow components (extensions, adapters) to declare what database-side
- * persistence structures they require (e.g., Postgres extensions, schemas, functions).
- * The planner emits these as migration operations, and the verifier uses the pure verification
- * hook to check satisfaction against the schema IR.
- */
 export interface ComponentDatabaseDependency<TTargetDetails> {
-  /** Stable identifier for the dependency (e.g. 'postgres.extension.vector') */
   readonly id: string;
-  /** Human label for output (e.g. 'Enable vector extension') */
   readonly label: string;
-  /**
-   * Operations that install/ensure the dependency.
-   * Use SqlMigrationPlanOperation so we inherit the existing precheck/execute/postcheck contract.
-   */
   readonly install: readonly SqlMigrationPlanOperation<TTargetDetails>[];
-  /**
-   * Pure verification hook: checks whether this dependency is already installed
-   * based on the in-memory schema IR (no DB I/O).
-   *
-   * This must return structured issues suitable for CLI and tree output, not just a boolean.
-   */
   readonly verifyDatabaseDependencyInstalled: (schema: SqlSchemaIR) => readonly SchemaIssue[];
 }
 
-/**
- * Database dependencies declared by a framework component.
- */
 export interface ComponentDatabaseDependencies<TTargetDetails> {
-  /**
-   * Dependencies required for db init.
-   * Future: update dependencies can be added later (e.g. widening/destructive).
-   */
   readonly init?: readonly ComponentDatabaseDependency<TTargetDetails>[];
 }
 
-/**
- * Minimal structural type implemented by any descriptor that can expose
- * component-owned database dependencies. Targets/adapters typically omit
- * the property, while extensions provide dependency metadata.
- */
 export interface DatabaseDependencyProvider {
   readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
 }
 
-// ============================================================================
-// SQL Control Extension Descriptor
-// ============================================================================
+export interface StorageTypePlanResult<TTargetDetails> {
+  readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+}
 
 /**
- * SQL-specific extension descriptor with optional database dependencies.
- * Extends the core ControlExtensionDescriptor with SQL-specific metadata.
- *
- * Database dependencies are attached to the descriptor (not the instance) because
- * they are declarative metadata that planner/verifier need without constructing instances.
+ * Input for expanding parameterized native types.
  */
+export interface ExpandNativeTypeInput {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}
+
+export interface CodecControlHooks<TTargetDetails = unknown> {
+  planTypeOperations?: (options: {
+    readonly typeName: string;
+    readonly typeInstance: StorageTypeInstance;
+    readonly contract: SqlContract<SqlStorage>;
+    readonly schema: SqlSchemaIR;
+    readonly schemaName?: string;
+    readonly policy: MigrationOperationPolicy;
+  }) => StorageTypePlanResult<TTargetDetails>;
+  verifyType?: (options: {
+    readonly typeName: string;
+    readonly typeInstance: StorageTypeInstance;
+    readonly schema: SqlSchemaIR;
+    readonly schemaName?: string;
+  }) => readonly SchemaIssue[];
+  introspectTypes?: (options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly schemaName?: string;
+  }) => Promise<Record<string, StorageTypeInstance>>;
+  /**
+   * Expands a parameterized native type to its full SQL representation.
+   * Used by schema verification to compare contract types against database types.
+   *
+   * For example, expands:
+   * - { nativeType: 'character varying', typeParams: { length: 255 } } -> 'character varying(255)'
+   * - { nativeType: 'numeric', typeParams: { precision: 10, scale: 2 } } -> 'numeric(10,2)'
+   *
+   * Returns the expanded type string, or the original nativeType if no expansion is needed.
+   */
+  expandNativeType?: (input: ExpandNativeTypeInput) => string;
+}
+
 export interface SqlControlExtensionDescriptor<TTargetId extends string>
-  extends ControlExtensionDescriptor<'sql', TTargetId> {
-  /** Optional database dependencies this extension requires. */
+  extends ControlExtensionDescriptor<'sql', TTargetId>,
+    SqlControlStaticContributions {
   readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
 }
 
-// ============================================================================
-// SQL-Specific Plan Types
-// ============================================================================
+export interface SqlControlAdapterDescriptor<TTargetId extends string>
+  extends ControlAdapterDescriptor<'sql', TTargetId>,
+    SqlControlStaticContributions {}
 
-/**
- * A single step in a SQL migration operation (precheck, execute, or postcheck).
- */
 export interface SqlMigrationPlanOperationStep {
   readonly description: string;
   readonly sql: string;
   readonly meta?: AnyRecord;
 }
 
-/**
- * Target details for a SQL migration operation (table, column, index, etc.).
- */
 export interface SqlMigrationPlanOperationTarget<TTargetDetails> {
   readonly id: string;
   readonly details?: TTargetDetails;
 }
 
-/**
- * A single SQL migration operation with SQL-specific fields.
- * Extends the core MigrationPlanOperation with SQL execution details.
- */
 export interface SqlMigrationPlanOperation<TTargetDetails> extends MigrationPlanOperation {
-  /** Optional detailed explanation of what this operation does and why. */
   readonly summary?: string;
   readonly target: SqlMigrationPlanOperationTarget<TTargetDetails>;
   readonly precheck: readonly SqlMigrationPlanOperationStep[];
@@ -134,23 +119,15 @@ export interface SqlMigrationPlanOperation<TTargetDetails> extends MigrationPlan
   readonly meta?: AnyRecord;
 }
 
-/**
- * Contract identity information for SQL migrations.
- */
 export interface SqlMigrationPlanContractInfo {
-  readonly coreHash: string;
+  readonly storageHash: string;
   readonly profileHash?: string;
 }
 
-/**
- * A SQL migration plan with SQL-specific fields.
- * Extends the core MigrationPlan with origin tracking and metadata.
- */
 export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
   /**
    * Origin contract identity that the plan expects the database to currently be at.
-   * If omitted, the runner treats the origin as "no marker present" (empty database),
-   * and will only proceed if no marker exists (or if the marker already matches destination).
+   * If omitted or null, the runner skips origin validation entirely.
    */
   readonly origin?: SqlMigrationPlanContractInfo | null;
   /**
@@ -161,13 +138,6 @@ export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
   readonly meta?: AnyRecord;
 }
 
-// ============================================================================
-// SQL-Specific Planner Types
-// ============================================================================
-
-/**
- * Specific conflict kinds for SQL migrations.
- */
 export type SqlPlannerConflictKind =
   | 'typeMismatch'
   | 'nullabilityConflict'
@@ -178,54 +148,36 @@ export type SqlPlannerConflictKind =
   | 'extensionMissing'
   | 'unsupportedOperation';
 
-/**
- * Location information for SQL planner conflicts.
- */
 export interface SqlPlannerConflictLocation {
   readonly table?: string;
   readonly column?: string;
   readonly index?: string;
   readonly constraint?: string;
   readonly extension?: string;
+  readonly type?: string;
 }
 
-/**
- * A SQL-specific planner conflict with additional location information.
- * Extends the core MigrationPlannerConflict.
- */
 export interface SqlPlannerConflict extends MigrationPlannerConflict {
   readonly kind: SqlPlannerConflictKind;
   readonly location?: SqlPlannerConflictLocation;
   readonly meta?: AnyRecord;
 }
 
-/**
- * Successful SQL planner result with the migration plan.
- */
 export interface SqlPlannerSuccessResult<TTargetDetails>
   extends Omit<MigrationPlannerSuccessResult, 'plan'> {
   readonly kind: 'success';
   readonly plan: SqlMigrationPlan<TTargetDetails>;
 }
 
-/**
- * Failed SQL planner result with the list of conflicts.
- */
 export interface SqlPlannerFailureResult extends Omit<MigrationPlannerFailureResult, 'conflicts'> {
   readonly kind: 'failure';
   readonly conflicts: readonly SqlPlannerConflict[];
 }
 
-/**
- * Union type for SQL planner results.
- */
 export type SqlPlannerResult<TTargetDetails> =
   | SqlPlannerSuccessResult<TTargetDetails>
   | SqlPlannerFailureResult;
 
-/**
- * Options for SQL migration planner.
- */
 export interface SqlMigrationPlannerPlanOptions {
   readonly contract: SqlContract<SqlStorage>;
   readonly schema: SqlSchemaIR;
@@ -239,29 +191,15 @@ export interface SqlMigrationPlannerPlanOptions {
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
 }
 
-/**
- * SQL migration planner interface.
- * Extends the core MigrationPlanner with SQL-specific types.
- */
 export interface SqlMigrationPlanner<TTargetDetails> {
   plan(options: SqlMigrationPlannerPlanOptions): SqlPlannerResult<TTargetDetails>;
 }
 
-// ============================================================================
-// SQL-Specific Runner Types
-// ============================================================================
-
-/**
- * Callbacks for SQL migration runner execution.
- */
 export interface SqlMigrationRunnerExecuteCallbacks<TTargetDetails> {
   onOperationStart?(operation: SqlMigrationPlanOperation<TTargetDetails>): void;
   onOperationComplete?(operation: SqlMigrationPlanOperation<TTargetDetails>): void;
 }
 
-/**
- * Options for SQL migration runner execution.
- */
 export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
   readonly plan: SqlMigrationPlan<TTargetDetails>;
   readonly driver: ControlDriverInstance<'sql', string>;
@@ -292,9 +230,6 @@ export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
 }
 
-/**
- * Error codes for SQL migration runner failures.
- */
 export type SqlMigrationRunnerErrorCode =
   | 'DESTINATION_CONTRACT_MISMATCH'
   | 'MARKER_ORIGIN_MISMATCH'
@@ -304,73 +239,36 @@ export type SqlMigrationRunnerErrorCode =
   | 'SCHEMA_VERIFY_FAILED'
   | 'EXECUTION_FAILED';
 
-/**
- * Detailed information about a SQL migration runner failure.
- * Extends the core MigrationRunnerFailure with SQL-specific error codes.
- */
 export interface SqlMigrationRunnerFailure extends MigrationRunnerFailure {
   readonly code: SqlMigrationRunnerErrorCode;
   readonly meta?: AnyRecord;
 }
 
-/**
- * Success value for SQL migration runner execution.
- * Extends core type for type branding and potential SQL-specific extensions.
- */
 export interface SqlMigrationRunnerSuccessValue extends MigrationRunnerSuccessValue {}
 
-/**
- * Result type for SQL migration runner execution.
- */
 export type SqlMigrationRunnerResult = Result<
   SqlMigrationRunnerSuccessValue,
   SqlMigrationRunnerFailure
 >;
 
-/**
- * SQL migration runner interface.
- * Extends the core MigrationRunner with SQL-specific types.
- */
 export interface SqlMigrationRunner<TTargetDetails> {
   execute(
     options: SqlMigrationRunnerExecuteOptions<TTargetDetails>,
   ): Promise<SqlMigrationRunnerResult>;
 }
 
-// ============================================================================
-// SQL Control Target Descriptor
-// ============================================================================
-
-/**
- * SQL control target descriptor with migration support.
- * Extends the core ControlTargetDescriptor with SQL-specific migration methods.
- */
 export interface SqlControlTargetDescriptor<TTargetId extends string, TTargetDetails>
   extends ControlTargetDescriptor<
-    'sql',
-    TTargetId,
-    ControlTargetInstance<'sql', TTargetId>,
-    SqlControlFamilyInstance
-  > {
-  /**
-   * Creates a SQL migration planner for this target.
-   * Direct method for SQL-specific usage.
-   */
+      'sql',
+      TTargetId,
+      ControlTargetInstance<'sql', TTargetId>,
+      SqlControlFamilyInstance
+    >,
+    SqlControlStaticContributions {
   createPlanner(family: SqlControlFamilyInstance): SqlMigrationPlanner<TTargetDetails>;
-  /**
-   * Creates a SQL migration runner for this target.
-   * Direct method for SQL-specific usage.
-   */
   createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
 }
 
-// ============================================================================
-// Helper Types
-// ============================================================================
-
-/**
- * Options for creating a SQL migration plan.
- */
 export interface CreateSqlMigrationPlanOptions<TTargetDetails> {
   readonly targetId: string;
   readonly origin?: SqlMigrationPlanContractInfo | null;

package/src/core/runtime-descriptor.ts

@@ -1,45 +1,23 @@
-import type {
-  RuntimeAdapterDescriptor,
-  RuntimeDriverDescriptor,
-  RuntimeExtensionDescriptor,
-  RuntimeFamilyDescriptor,
-  RuntimeTargetDescriptor,
-} from '@prisma-next/core-execution-plane/types';
-import {
-  createSqlRuntimeFamilyInstance,
-  type SqlRuntimeAdapterInstance,
-  type SqlRuntimeDriverInstance,
-  type SqlRuntimeFamilyInstance,
-} from './runtime-instance';
+import type { RuntimeFamilyDescriptor } from '@prisma-next/core-execution-plane/types';
+import { createSqlRuntimeFamilyInstance, type SqlRuntimeFamilyInstance } from './runtime-instance';
 
 /**
- * SQL runtime family descriptor implementation.
- * Provides factory method to create SQL runtime family instance.
+ * SQL execution-plane family descriptor.
+ *
+ * Note: this is currently named `sqlRuntimeFamilyDescriptor` because the execution plane
+ * framework types are still using the `Runtime*` naming (`RuntimeFamilyDescriptor`, etc.).
+ *
+ * This will be renamed to `sqlExecutionFamilyDescriptor` as part of `TML-1842`.
  */
-export class SqlRuntimeFamilyDescriptor
-  implements RuntimeFamilyDescriptor<'sql', SqlRuntimeFamilyInstance>
-{
-  readonly kind = 'family' as const;
-  readonly id = 'sql';
-  readonly familyId = 'sql' as const;
-  readonly version = '0.0.1';
+export const sqlRuntimeFamilyDescriptor: RuntimeFamilyDescriptor<'sql', SqlRuntimeFamilyInstance> =
+  {
+    kind: 'family',
+    id: 'sql',
+    familyId: 'sql',
+    version: '0.0.1',
+    create() {
+      return createSqlRuntimeFamilyInstance();
+    },
+  };
 
-  create<TTargetId extends string>(options: {
-    readonly target: RuntimeTargetDescriptor<'sql', TTargetId>;
-    readonly adapter: RuntimeAdapterDescriptor<
-      'sql',
-      TTargetId,
-      SqlRuntimeAdapterInstance<TTargetId>
-    >;
-    readonly driver: RuntimeDriverDescriptor<'sql', TTargetId, SqlRuntimeDriverInstance<TTargetId>>;
-    readonly extensionPacks: readonly RuntimeExtensionDescriptor<'sql', TTargetId>[];
-  }): SqlRuntimeFamilyInstance {
-    return createSqlRuntimeFamilyInstance({
-      family: this,
-      target: options.target,
-      adapter: options.adapter,
-      driver: options.driver,
-      extensionPacks: options.extensionPacks,
-    });
-  }
-}
+Object.freeze(sqlRuntimeFamilyDescriptor);