@prisma-next/family-sql 0.4.0-dev.9 → 0.4.2

package/package.json

@@ -1,35 +1,36 @@
 {
   "name": "@prisma-next/family-sql",
-  "version": "0.4.0-dev.9",
+  "version": "0.4.2",
   "type": "module",
   "sideEffects": false,
   "description": "SQL family descriptor for Prisma Next",
   "dependencies": {
     "arktype": "^2.0.0",
-    "@prisma-next/emitter": "0.4.0-dev.9",
-    "@prisma-next/framework-components": "0.4.0-dev.9",
-    "@prisma-next/contract": "0.4.0-dev.9",
-    "@prisma-next/operations": "0.4.0-dev.9",
-    "@prisma-next/runtime-executor": "0.4.0-dev.9",
-    "@prisma-next/sql-contract": "0.4.0-dev.9",
-    "@prisma-next/sql-contract-ts": "0.4.0-dev.9",
-    "@prisma-next/sql-contract-emitter": "0.4.0-dev.9",
-    "@prisma-next/sql-relational-core": "0.4.0-dev.9",
-    "@prisma-next/sql-runtime": "0.4.0-dev.9",
-    "@prisma-next/sql-schema-ir": "0.4.0-dev.9",
-    "@prisma-next/utils": "0.4.0-dev.9",
-    "@prisma-next/sql-operations": "0.4.0-dev.9"
+    "@prisma-next/contract": "0.4.2",
+    "@prisma-next/migration-tools": "0.4.2",
+    "@prisma-next/emitter": "0.4.2",
+    "@prisma-next/operations": "0.4.2",
+    "@prisma-next/sql-contract-emitter": "0.4.2",
+    "@prisma-next/sql-contract": "0.4.2",
+    "@prisma-next/framework-components": "0.4.2",
+    "@prisma-next/sql-contract-ts": "0.4.2",
+    "@prisma-next/runtime-executor": "0.4.2",
+    "@prisma-next/sql-operations": "0.4.2",
+    "@prisma-next/sql-relational-core": "0.4.2",
+    "@prisma-next/sql-runtime": "0.4.2",
+    "@prisma-next/utils": "0.4.2",
+    "@prisma-next/sql-schema-ir": "0.4.2"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/driver-postgres": "0.4.0-dev.9",
-    "@prisma-next/psl-parser": "0.4.0-dev.9",
-    "@prisma-next/sql-contract-psl": "0.4.0-dev.9",
-    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/psl-parser": "0.4.2",
+    "@prisma-next/driver-postgres": "0.4.2",
+    "@prisma-next/sql-contract-psl": "0.4.2",
     "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0"
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/test-utils": "0.0.1"
   },
   "files": [
     "dist",
@@ -38,7 +39,7 @@
   "exports": {
     "./control": "./dist/control.mjs",
     "./control-adapter": "./dist/control-adapter.mjs",
-    "./operation-descriptors": "./dist/operation-descriptors.mjs",
+    "./migration": "./dist/migration.mjs",
     "./pack": "./dist/pack.mjs",
     "./runtime": "./dist/runtime.mjs",
     "./schema-verify": "./dist/schema-verify.mjs",

package/src/core/control-adapter.ts

@@ -1,7 +1,13 @@
 import type {
   ControlAdapterInstance,
   ControlDriverInstance,
+  ControlStack,
 } from '@prisma-next/framework-components/control';
+import type {
+  AnyQueryAst,
+  LoweredStatement,
+  LowererContext,
+} from '@prisma-next/sql-relational-core/ast';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import type { DefaultNormalizer, NativeTypeNormalizer } from './schema-verify/verify-sql-schema';
 
@@ -44,6 +50,17 @@ export interface SqlControlAdapter<TTarget extends string = string>
    * before comparison with contract native types during schema verification.
    */
   readonly normalizeNativeType?: NativeTypeNormalizer;
+
+  /**
+   * Lower a SQL query AST into a target-flavored `{ sql, params }` payload.
+   *
+   * Migration tooling (e.g. the `dataTransform` operation) needs to materialize
+   * SQL at emit/plan time without instantiating the runtime adapter. The control
+   * adapter's `lower` is byte-equivalent to the runtime adapter's `lower` for the
+   * same AST and contract, ensuring planned SQL matches what the runtime would
+   * emit.
+   */
+  lower(ast: AnyQueryAst, context: LowererContext<unknown>): LoweredStatement;
 }
 
 /**
@@ -55,6 +72,9 @@ export interface SqlControlAdapter<TTarget extends string = string>
 export interface SqlControlAdapterDescriptor<TTarget extends string = string> {
   /**
    * Creates a SQL control adapter instance for control-plane operations.
+   *
+   * Receives the assembled `ControlStack` so adapters can read aggregated
+   * metadata (codec lookup, extension contributions) when materializing.
    */
-  create(): SqlControlAdapter<TTarget>;
+  create(stack: ControlStack<'sql', TTarget>): SqlControlAdapter<TTarget>;
 }

package/src/core/control-instance.ts

@@ -435,7 +435,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
 
       const contract = sqlValidateContract<Contract<SqlStorage>>(contractInput, emptyCodecLookup);
 
-      const controlAdapter = adapter.create();
+      const controlAdapter = adapter.create(stack);
       if (!isSqlControlAdapter(controlAdapter)) {
         throw new Error('Adapter does not implement SqlControlAdapter.introspect()');
       }
@@ -559,7 +559,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     }): Promise<SqlSchemaIR> {
       const { driver, contract } = options;
 
-      const controlAdapter = adapter.create();
+      const controlAdapter = adapter.create(stack);
       if (!isSqlControlAdapter(controlAdapter)) {
         throw new Error('Adapter does not implement SqlControlAdapter.introspect()');
       }

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

@@ -7,6 +7,7 @@ import type {
   SqlStorage,
   StorageColumn,
   StorageTable,
+  StorageTypeInstance,
   UniqueConstraint,
 } from '@prisma-next/sql-contract/types';
 import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
@@ -53,16 +54,26 @@ export type DefaultRenderer = (def: ColumnDefault, column: StorageColumn) => str
 function convertColumn(
   name: string,
   column: StorageColumn,
+  storageTypes: Record<string, StorageTypeInstance>,
   expandNativeType: NativeTypeExpander | undefined,
   renderDefault: DefaultRenderer | undefined,
 ): SqlColumnIR {
+  // Resolve `typeRef` so columns that delegate their `nativeType`/`codecId`/
+  // `typeParams` to a named `storage.types` entry expand the same way as
+  // columns that inline those fields. Without this resolution, a
+  // `typeRef`-based column like `post.embedding → Embedding1536` would
+  // render as the bare `"vector"` (dropping the `length` parameter), while
+  // `verify-sql-schema.ts`'s `renderExpectedNativeType` resolves the
+  // typeRef and produces `"vector(1536)"` — making diffs on the same
+  // contract falsely report a `type_mismatch`.
+  const resolved = resolveColumnTypeMetadata(column, storageTypes);
   const nativeType = expandNativeType
     ? expandNativeType({
-        nativeType: column.nativeType,
-        codecId: column.codecId,
-        ...ifDefined('typeParams', column.typeParams),
+        nativeType: resolved.nativeType,
+        codecId: resolved.codecId,
+        ...ifDefined('typeParams', resolved.typeParams),
       })
-    : column.nativeType;
+    : resolved.nativeType;
   return {
     name,
     nativeType,
@@ -74,6 +85,26 @@ function convertColumn(
   };
 }
 
+function resolveColumnTypeMetadata(
+  column: StorageColumn,
+  storageTypes: Record<string, StorageTypeInstance>,
+): Pick<StorageColumn, 'codecId' | 'nativeType' | 'typeParams'> {
+  if (!column.typeRef) {
+    return column;
+  }
+  const referenced = storageTypes[column.typeRef];
+  if (!referenced) {
+    throw new Error(
+      `Column references storage type "${column.typeRef}" but it is not defined in storage.types.`,
+    );
+  }
+  return {
+    codecId: referenced.codecId,
+    nativeType: referenced.nativeType,
+    typeParams: referenced.typeParams,
+  };
+}
+
 function convertUnique(unique: UniqueConstraint): SqlUniqueIR {
   return {
     columns: unique.columns,
@@ -101,12 +132,19 @@ function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
 function convertTable(
   name: string,
   table: StorageTable,
+  storageTypes: Record<string, StorageTypeInstance>,
   expandNativeType: NativeTypeExpander | undefined,
   renderDefault: DefaultRenderer | undefined,
 ): SqlTableIR {
   const columns: Record<string, SqlColumnIR> = {};
   for (const [colName, colDef] of Object.entries(table.columns)) {
-    columns[colName] = convertColumn(colName, colDef, expandNativeType, renderDefault);
+    columns[colName] = convertColumn(
+      colName,
+      colDef,
+      storageTypes,
+      expandNativeType,
+      renderDefault,
+    );
   }
 
   const satisfiedIndexColumns = new Set([
@@ -217,11 +255,13 @@ export function contractToSchemaIR(
   }
 
   const storage = contract.storage;
+  const storageTypes = storage.types ?? {};
   const tables: Record<string, SqlTableIR> = {};
   for (const [tableName, tableDef] of Object.entries(storage.tables)) {
     tables[tableName] = convertTable(
       tableName,
       tableDef,
+      storageTypes,
       options.expandNativeType,
       options.renderDefault,
     );

package/src/core/migrations/types.ts

@@ -4,6 +4,7 @@ import type {
   ControlAdapterDescriptor,
   ControlDriverInstance,
   ControlExtensionDescriptor,
+  DataTransformOperation,
   MigratableTargetDescriptor,
   MigrationOperationPolicy,
   MigrationPlan,
@@ -141,6 +142,18 @@ export interface SqlMigrationPlanOperationStep {
   readonly meta?: AnyRecord;
 }
 
+/**
+ * Minimal shape every SQL-family target must conform to for its per-operation
+ * `target.details` payload. Each SQL operation addresses a named database
+ * object in some schema; targets (Postgres, MySQL, SQLite, …) extend this
+ * shape with their own fields (e.g. Postgres adds `objectType` and optional
+ * `table`).
+ */
+export interface SqlPlanTargetDetails {
+  readonly schema: string;
+  readonly name: string;
+}
+
 export interface SqlMigrationPlanOperationTarget<TTargetDetails> {
   readonly id: string;
   readonly details?: TTargetDetails;
@@ -155,6 +168,19 @@ export interface SqlMigrationPlanOperation<TTargetDetails> extends MigrationPlan
   readonly meta?: AnyRecord;
 }
 
+/**
+ * Union of all operation shapes a SQL-family migration may emit: schema-facing
+ * `SqlMigrationPlanOperation`s and family-agnostic `DataTransformOperation`s.
+ *
+ * Mirrors `AnyMongoMigrationOperation` in shape — the runner already handles
+ * both branches via `isDataTransformOperation`, and authored `migration.ts`
+ * files must be able to intermix `dataTransform(endContract, …)` calls with
+ * DDL factory calls (e.g. `setNotNull(…)`) in a single `operations` array.
+ */
+export type AnySqlMigrationOperation<TTargetDetails> =
+  | SqlMigrationPlanOperation<TTargetDetails>
+  | DataTransformOperation;
+
 export interface SqlMigrationPlanContractInfo {
   readonly storageHash: string;
   readonly profileHash?: string;
@@ -216,6 +242,15 @@ export interface SqlMigrationPlannerPlanOptions {
   readonly schema: SqlSchemaIR;
   readonly policy: MigrationOperationPolicy;
   readonly schemaName?: 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. Strategies that need
+   * from/to column-shape comparisons (unsafe type change, nullability
+   * tightening) use this to decide whether to emit `dataTransform`
+   * placeholders.
+   */
+  readonly fromContract?: Contract<SqlStorage> | null;
   /**
    * Active framework components participating in this composition.
    * SQL targets can interpret this list to derive database dependencies.

package/src/core/sql-migration.ts

@@ -0,0 +1,34 @@
+import { Migration } from '@prisma-next/migration-tools/migration';
+import type { AnySqlMigrationOperation, SqlPlanTargetDetails } from './migrations/types';
+
+/**
+ * Family-owned base class for SQL migrations.
+ *
+ * Parameterized on the target-details shape because SQL-family targets
+ * (Postgres, MySQL, SQLite, …) each carry their own `target.details` payload
+ * on `SqlMigrationPlanOperation`. The type parameter is narrowed to
+ * `SqlPlanTargetDetails` so every target-specific shape must at minimum
+ * identify the object being targeted (schema + name); concrete targets
+ * extend the shape with their own fields.
+ *
+ * Each concrete target-side subclass (e.g. Postgres's
+ * `TypeScriptRenderablePostgresMigration`) fixes `targetId` to its own
+ * target-id string literal, since SQL can't hardcode a single `targetId`:
+ * `targetId` is a target-level identity, not a family-level one, and
+ * belongs on the subclass.
+ *
+ * `familyId` is intentionally not declared here. The SQL family has no
+ * family-scoped runtime identity today — consumers reach the family via
+ * target descriptors rather than by family-id lookup, so adding one would
+ * be purely decorative. Introducing it later is a non-breaking superset.
+ *
+ * The operation type parameter is `AnySqlMigrationOperation<TDetails>` — the
+ * union of DDL-shaped `SqlMigrationPlanOperation` and `DataTransformOperation`
+ * — so subclasses can return a mix of schema operations (e.g. `setNotNull`,
+ * `addColumn`) and data-transform operations (e.g. `dataTransform`). Mirrors
+ * `MongoMigration`'s parameterization on `AnyMongoMigrationOperation`.
+ */
+export abstract class SqlMigration<
+  TDetails extends SqlPlanTargetDetails,
+  TTargetId extends string = string,
+> extends Migration<AnySqlMigrationOperation<TDetails>, 'sql', TTargetId> {}

package/src/core/verify.ts

@@ -97,6 +97,27 @@ export function readMarkerSql(): { readonly sql: string; readonly params: readon
   };
 }
 
+/**
+ * Returns the SQL statement that probes for the existence of the marker table.
+ * Uses the SQL-standard `information_schema.tables` view so the query succeeds
+ * (returning zero rows) when the table has not been created yet — avoiding a
+ * `relation does not exist` error. Some Postgres wire-protocol implementations
+ * (e.g. PGlite's TCP proxy) do not fully recover from an extended-protocol
+ * parse error, so we probe first instead of relying on an error signal.
+ * @internal - Used internally by readMarker().
+ */
+export function markerTableExistsSql(): {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+} {
+  return {
+    sql: `select 1
+    from information_schema.tables
+    where table_schema = $1 and table_name = $2`,
+    params: ['prisma_contract', 'marker'],
+  };
+}
+
 /**
  * Reads the contract marker from the database using the provided driver.
  * Returns the parsed marker record or null if no marker is found.
@@ -108,41 +129,38 @@ export function readMarkerSql(): { readonly sql: string; readonly params: readon
 export async function readMarker(
   driver: ControlDriverInstance<'sql', string>,
 ): Promise<ContractMarkerRecord | null> {
-  const markerStatement = readMarkerSql();
-
-  try {
-    const queryResult = await driver.query<{
-      core_hash: string;
-      profile_hash: string;
-      contract_json: unknown | null;
-      canonical_version: number | null;
-      updated_at: Date | string;
-      app_tag: string | null;
-      meta: unknown | null;
-    }>(markerStatement.sql, markerStatement.params);
-
-    if (queryResult.rows.length === 0) {
-      return null;
-    }
+  // Probe for the marker table first so that a fresh database (no
+  // `prisma_contract` schema) returns null cleanly instead of surfacing a
+  // `relation does not exist` error. This keeps the control connection in a
+  // predictable state for driver implementations that are sensitive to
+  // extended-protocol parse errors.
+  const existsStatement = markerTableExistsSql();
+  const existsResult = await driver.query(existsStatement.sql, existsStatement.params);
+  if (existsResult.rows.length === 0) {
+    return null;
+  }
 
-    const markerRow = queryResult.rows[0];
-    if (!markerRow) {
-      // If rows array has length > 0 but first element is undefined, this is an unexpected result structure
-      throw new Error('Database query returned unexpected result structure');
-    }
+  const markerStatement = readMarkerSql();
+  const queryResult = await driver.query<{
+    core_hash: string;
+    profile_hash: string;
+    contract_json: unknown | null;
+    canonical_version: number | null;
+    updated_at: Date | string;
+    app_tag: string | null;
+    meta: unknown | null;
+  }>(markerStatement.sql, markerStatement.params);
+
+  if (queryResult.rows.length === 0) {
+    return null;
+  }
 
-    return parseContractMarkerRow(markerRow);
-  } catch (error) {
-    // Handle case where marker table doesn't exist yet (empty database)
-    // PostgreSQL error code 42P01 = undefined_table
-    if (
-      error instanceof Error &&
-      (error.message.includes('does not exist') || (error as { code?: string }).code === '42P01')
-    ) {
-      return null;
-    }
-    throw error;
+  const markerRow = queryResult.rows[0];
+  if (!markerRow) {
+    throw new Error('Database query returned unexpected result structure');
   }
+
+  return parseContractMarkerRow(markerRow);
 }
 
 /**

package/src/exports/control.ts

@@ -33,6 +33,7 @@ export {
 } from '../core/migrations/plan-helpers';
 export { INIT_ADDITIVE_POLICY } from '../core/migrations/policies';
 export type {
+  AnySqlMigrationOperation,
   CodecControlHooks,
   ComponentDatabaseDependencies,
   ComponentDatabaseDependency,
@@ -62,6 +63,7 @@ export type {
   SqlPlannerFailureResult,
   SqlPlannerResult,
   SqlPlannerSuccessResult,
+  SqlPlanTargetDetails,
   StorageTypePlanResult,
 } from '../core/migrations/types';
 export { collectInitDependencies, isDatabaseDependencyProvider } from '../core/migrations/types';

package/src/exports/migration.ts

@@ -0,0 +1 @@
+export { SqlMigration as Migration } from '../core/sql-migration';