@prisma-next/family-sql 0.4.2 → 0.4.3

package/package.json

@@ -1,36 +1,36 @@
 {
   "name": "@prisma-next/family-sql",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "type": "module",
   "sideEffects": false,
   "description": "SQL family descriptor for Prisma Next",
   "dependencies": {
     "arktype": "^2.0.0",
-    "@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"
+    "@prisma-next/contract": "0.4.3",
+    "@prisma-next/framework-components": "0.4.3",
+    "@prisma-next/emitter": "0.4.3",
+    "@prisma-next/migration-tools": "0.4.3",
+    "@prisma-next/operations": "0.4.3",
+    "@prisma-next/sql-contract": "0.4.3",
+    "@prisma-next/sql-contract-emitter": "0.4.3",
+    "@prisma-next/sql-contract-ts": "0.4.3",
+    "@prisma-next/sql-operations": "0.4.3",
+    "@prisma-next/sql-relational-core": "0.4.3",
+    "@prisma-next/sql-runtime": "0.4.3",
+    "@prisma-next/sql-schema-ir": "0.4.3",
+    "@prisma-next/utils": "0.4.3"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/psl-parser": "0.4.2",
-    "@prisma-next/driver-postgres": "0.4.2",
-    "@prisma-next/sql-contract-psl": "0.4.2",
+    "@prisma-next/psl-parser": "0.4.3",
+    "@prisma-next/driver-postgres": "0.4.3",
+    "@prisma-next/sql-contract-psl": "0.4.3",
+    "@prisma-next/test-utils": "0.0.1",
     "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0",
-    "@prisma-next/test-utils": "0.0.1"
+    "@prisma-next/psl-printer": "0.4.3",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",

package/src/core/control-adapter.ts

@@ -1,3 +1,4 @@
+import type { ContractMarkerRecord } from '@prisma-next/contract/types';
 import type {
   ControlAdapterInstance,
   ControlDriverInstance,
@@ -19,6 +20,17 @@ import type { DefaultNormalizer, NativeTypeNormalizer } from './schema-verify/ve
  */
 export interface SqlControlAdapter<TTarget extends string = string>
   extends ControlAdapterInstance<'sql', TTarget> {
+  /**
+   * Reads the contract marker from the database, returning `null` if the marker
+   * table or its row is missing. Implementations are responsible for the
+   * dialect-specific existence probe (e.g. Postgres `information_schema.tables`
+   * vs SQLite `sqlite_master`) and parameter placeholders.
+   *
+   * @param driver - ControlDriverInstance for executing queries (target-specific)
+   * @returns Resolved marker record, or `null` if not yet stamped.
+   */
+  readMarker(driver: ControlDriverInstance<'sql', TTarget>): Promise<ContractMarkerRecord | null>;
+
   /**
    * Introspects a database schema and returns a raw SqlSchemaIR.
    *

package/src/core/control-instance.ts

@@ -9,7 +9,11 @@ import type {
   ControlFamilyInstance,
   ControlStack,
   CoreSchemaView,
+  MigrationPlanOperation,
   OperationContext,
+  OperationPreview,
+  OperationPreviewCapable,
+  PslContractInferCapable,
   SchemaViewCapable,
   SignDatabaseResult,
   VerifyDatabaseResult,
@@ -22,6 +26,7 @@ import {
   VERIFY_CODE_TARGET_MISMATCH,
 } from '@prisma-next/framework-components/control';
 import type { TypesImportSpec } from '@prisma-next/framework-components/emission';
+import type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { validateContract as sqlValidateContract } from '@prisma-next/sql-contract/validate';
 import {
@@ -37,8 +42,10 @@ import type {
   SqlControlAdapterDescriptor,
   SqlControlExtensionDescriptor,
 } from './migrations/types';
+import { sqlOperationsToPreview } from './operation-preview';
+import { sqlSchemaIrToPslAst } from './psl-contract-infer/sql-schema-ir-to-psl-ast';
 import { verifySqlSchema } from './schema-verify/verify-sql-schema';
-import { collectSupportedCodecTypeIds, readMarker } from './verify';
+import { collectSupportedCodecTypeIds } from './verify';
 
 function extractCodecTypeIdsFromContract(contract: unknown): readonly string[] {
   const typeIds = new Set<string>();
@@ -182,6 +189,8 @@ export interface SchemaVerifyOptions {
 export interface SqlControlFamilyInstance
   extends ControlFamilyInstance<'sql', SqlSchemaIR>,
     SchemaViewCapable<SqlSchemaIR>,
+    PslContractInferCapable<SqlSchemaIR>,
+    OperationPreviewCapable,
     SqlFamilyInstanceState {
   validateContract(contractJson: unknown): Contract;
 
@@ -206,6 +215,10 @@ export interface SqlControlFamilyInstance
     readonly driver: ControlDriverInstance<'sql', string>;
     readonly contract?: unknown;
   }): Promise<SqlSchemaIR>;
+
+  inferPslContract(schemaIR: SqlSchemaIR): PslDocumentAst;
+
+  toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview;
 }
 
 export type SqlFamilyInstance = SqlControlFamilyInstance;
@@ -217,7 +230,9 @@ function isSqlControlAdapter<TTargetId extends string>(
     typeof value === 'object' &&
     value !== null &&
     'introspect' in value &&
-    typeof (value as { introspect: unknown }).introspect === 'function'
+    typeof (value as { introspect: unknown }).introspect === 'function' &&
+    'readMarker' in value &&
+    typeof (value as { readMarker: unknown }).readMarker === 'function'
   );
 }
 
@@ -293,6 +308,20 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     extensionPacks: extensions,
   });
 
+  // Family-instance methods accept `ControlDriverInstance<'sql', string>` —
+  // the family API isn't generic on the target id. Letting `isSqlControlAdapter`
+  // default its type parameter narrows the adapter to `SqlControlAdapter<string>`,
+  // which matches the family-level driver type without any cast at call sites.
+  const getControlAdapter = () => {
+    const controlAdapter = adapter.create(stack);
+    if (!isSqlControlAdapter(controlAdapter)) {
+      throw new Error(
+        'Adapter does not implement SqlControlAdapter (missing introspect or readMarker)',
+      );
+    }
+    return controlAdapter;
+  };
+
   return {
     familyId: 'sql',
     codecTypeImports,
@@ -326,7 +355,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       const contractProfileHash = contract.profileHash;
       const contractTarget = contract.target;
 
-      const marker = await readMarker(driver);
+      const marker = await getControlAdapter().readMarker(driver);
 
       let missingCodecs: readonly string[] | undefined;
       let codecCoverageSkipped = false;
@@ -435,10 +464,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
 
       const contract = sqlValidateContract<Contract<SqlStorage>>(contractInput, emptyCodecLookup);
 
-      const controlAdapter = adapter.create(stack);
-      if (!isSqlControlAdapter(controlAdapter)) {
-        throw new Error('Adapter does not implement SqlControlAdapter.introspect()');
-      }
+      const controlAdapter = getControlAdapter();
       const schemaIR = await controlAdapter.introspect(driver, contractInput);
 
       return verifySqlSchema({
@@ -474,7 +500,7 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       await driver.query(ensureSchemaStatement.sql, ensureSchemaStatement.params);
       await driver.query(ensureTableStatement.sql, ensureTableStatement.params);
 
-      const existingMarker = await readMarker(driver);
+      const existingMarker = await getControlAdapter().readMarker(driver);
 
       let markerCreated = false;
       let markerUpdated = false;
@@ -551,19 +577,21 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     async readMarker(options: {
       readonly driver: ControlDriverInstance<'sql', string>;
     }): Promise<ContractMarkerRecord | null> {
-      return readMarker(options.driver);
+      return getControlAdapter().readMarker(options.driver);
     },
     async introspect(options: {
       readonly driver: ControlDriverInstance<'sql', string>;
       readonly contract?: unknown;
     }): Promise<SqlSchemaIR> {
-      const { driver, contract } = options;
+      return getControlAdapter().introspect(options.driver, options.contract);
+    },
 
-      const controlAdapter = adapter.create(stack);
-      if (!isSqlControlAdapter(controlAdapter)) {
-        throw new Error('Adapter does not implement SqlControlAdapter.introspect()');
-      }
-      return controlAdapter.introspect(driver, contract);
+    inferPslContract(schemaIR: SqlSchemaIR): PslDocumentAst {
+      return sqlSchemaIrToPslAst(schemaIR);
+    },
+
+    toOperationPreview(operations: readonly MigrationPlanOperation[]): OperationPreview {
+      return sqlOperationsToPreview(operations);
     },
 
     toSchemaView(schema: SqlSchemaIR): CoreSchemaView {

package/src/core/migrations/plan-helpers.ts

@@ -101,6 +101,7 @@ export function createMigrationPlan<TTargetDetails>(
       : {}),
     destination: Object.freeze({ ...options.destination }),
     operations: freezeOperations(options.operations),
+    providedInvariants: Object.freeze([...options.providedInvariants]),
     ...(options.meta ? { meta: cloneRecord(options.meta) } : {}),
   });
 }

package/src/core/migrations/types.ts

@@ -197,6 +197,15 @@ export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
    */
   readonly destination: SqlMigrationPlanContractInfo;
   readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+  /**
+   * Sorted, deduplicated invariant ids declared by this plan's data-transform
+   * ops. Required at the SQL-family layer (the SQL runners consume this as
+   * the source of truth for marker writes and self-edge no-op checks); the
+   * framework-level {@link MigrationPlan.providedInvariants} stays optional
+   * because `db init` / `db update` plans don't have a corresponding
+   * migration manifest.
+   */
+  readonly providedInvariants: readonly string[];
   readonly meta?: AnyRecord;
 }
 
@@ -243,14 +252,21 @@ export interface SqlMigrationPlannerPlanOptions {
   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
+   * The "from" contract (state the planner assumes the database starts at),
+   * or `null` for reconciliation flows that have no prior contract.
+   *
+   * Required at every call site so the structural fact "I have a prior
+   * contract / I don't" is visible in the type. `migration plan` supplies
+   * the previous bundle's `metadata.toContract`; `db update` / `db init`
+   * reconcile against the live schema and pass `null`. Strategies that
+   * need from/to column-shape comparisons (unsafe type change, nullability
    * tightening) use this to decide whether to emit `dataTransform`
-   * placeholders.
+   * placeholders; they short-circuit when it is `null`.
+   *
+   * Planners also derive the "from" identity they stamp onto the produced
+   * plan's `describe()` as `fromContract?.storage.storageHash ?? null`.
    */
-  readonly fromContract?: Contract<SqlStorage> | null;
+  readonly fromContract: Contract<SqlStorage> | null;
   /**
    * Active framework components participating in this composition.
    * SQL targets can interpret this list to derive database dependencies.
@@ -305,6 +321,7 @@ export type SqlMigrationRunnerErrorCode =
   | 'PRECHECK_FAILED'
   | 'POSTCHECK_FAILED'
   | 'SCHEMA_VERIFY_FAILED'
+  | 'FOREIGN_KEY_VIOLATION'
   | 'EXECUTION_FAILED';
 
 export interface SqlMigrationRunnerFailure extends MigrationRunnerFailure {
@@ -337,5 +354,11 @@ export interface CreateSqlMigrationPlanOptions<TTargetDetails> {
   readonly origin?: SqlMigrationPlanContractInfo | null;
   readonly destination: SqlMigrationPlanContractInfo;
   readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+  /**
+   * Sorted, deduplicated invariant ids for this plan; mirrors the required
+   * field on {@link SqlMigrationPlan}. Callers without a migration manifest
+   * (`db init`, `db update`, planner-built plans) pass `[]`.
+   */
+  readonly providedInvariants: readonly string[];
   readonly meta?: AnyRecord;
 }

package/src/core/operation-preview.ts

@@ -0,0 +1,62 @@
+import type {
+  MigrationPlanOperation,
+  OperationPreview,
+} from '@prisma-next/framework-components/control';
+
+/**
+ * Shape of an SQL execute step on `SqlMigrationPlanOperation`. Used for runtime
+ * type narrowing without importing the concrete SQL type.
+ */
+interface SqlExecuteStep {
+  readonly sql: string;
+}
+
+function isDdlStatement(sqlStatement: string): boolean {
+  const trimmed = sqlStatement.trim().toLowerCase();
+  return (
+    trimmed.startsWith('create ') || trimmed.startsWith('alter ') || trimmed.startsWith('drop ')
+  );
+}
+
+function hasExecuteSteps(
+  operation: MigrationPlanOperation,
+): operation is MigrationPlanOperation & { readonly execute: readonly SqlExecuteStep[] } {
+  const candidate = operation as unknown as Record<string, unknown>;
+  if (!('execute' in candidate) || !Array.isArray(candidate['execute'])) {
+    return false;
+  }
+  return candidate['execute'].every(
+    (step: unknown) => typeof step === 'object' && step !== null && 'sql' in step,
+  );
+}
+
+/**
+ * Extracts a best-effort SQL DDL preview for CLI plan output.
+ * Presentation-only: never used to decide migration correctness.
+ */
+export function extractSqlDdl(operations: readonly MigrationPlanOperation[]): string[] {
+  const statements: string[] = [];
+  for (const operation of operations) {
+    if (!hasExecuteSteps(operation)) {
+      continue;
+    }
+    for (const step of operation.execute) {
+      if (typeof step.sql === 'string' && isDdlStatement(step.sql)) {
+        statements.push(step.sql.trim());
+      }
+    }
+  }
+  return statements;
+}
+
+/**
+ * Wraps `extractSqlDdl` into the family-agnostic `OperationPreview` shape.
+ * Each statement carries `language: 'sql'`.
+ */
+export function sqlOperationsToPreview(
+  operations: readonly MigrationPlanOperation[],
+): OperationPreview {
+  return {
+    statements: extractSqlDdl(operations).map((text) => ({ text, language: 'sql' })),
+  };
+}

package/src/core/psl-contract-infer/default-mapping.ts

@@ -0,0 +1,56 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+
+const DEFAULT_FUNCTION_ATTRIBUTES: Readonly<Record<string, string>> = {
+  'autoincrement()': '@default(autoincrement())',
+  'now()': '@default(now())',
+};
+
+export interface DefaultMappingOptions {
+  readonly functionAttributes?: Readonly<Record<string, string>>;
+  readonly fallbackFunctionAttribute?: ((expression: string) => string | undefined) | undefined;
+}
+
+export type DefaultMappingResult = { readonly attribute: string } | { readonly comment: string };
+
+export function mapDefault(
+  columnDefault: ColumnDefault,
+  options?: DefaultMappingOptions,
+): DefaultMappingResult {
+  switch (columnDefault.kind) {
+    case 'literal':
+      return { attribute: `@default(${formatLiteralValue(columnDefault.value)})` };
+    case 'function': {
+      const attribute =
+        options?.functionAttributes?.[columnDefault.expression] ??
+        DEFAULT_FUNCTION_ATTRIBUTES[columnDefault.expression] ??
+        options?.fallbackFunctionAttribute?.(columnDefault.expression);
+      return attribute
+        ? { attribute }
+        : { comment: `// Raw default: ${columnDefault.expression.replace(/[\r\n]+/g, ' ')}` };
+    }
+  }
+}
+
+function formatLiteralValue(value: unknown): string {
+  if (value === null) {
+    return 'null';
+  }
+
+  switch (typeof value) {
+    case 'boolean':
+    case 'number':
+      return String(value);
+    case 'string':
+      return quoteString(value);
+    default:
+      return quoteString(JSON.stringify(value));
+  }
+}
+
+function quoteString(str: string): string {
+  return `"${escapeString(str)}"`;
+}
+
+function escapeString(str: string): string {
+  return JSON.stringify(str).slice(1, -1);
+}

package/src/core/psl-contract-infer/name-transforms.ts

@@ -0,0 +1,178 @@
+const PSL_RESERVED_WORDS = new Set(['model', 'enum', 'types', 'type', 'generator', 'datasource']);
+
+const IDENTIFIER_PART_PATTERN = /[A-Za-z0-9]+/g;
+
+type NameResult = {
+  readonly name: string;
+  readonly map?: string;
+};
+
+function hasSeparators(input: string): boolean {
+  return /[^A-Za-z0-9]/.test(input);
+}
+
+function extractIdentifierParts(input: string): string[] {
+  return input.match(IDENTIFIER_PART_PATTERN) ?? [];
+}
+
+function createSyntheticIdentifier(input: string): string {
+  let hash = 2166136261;
+
+  for (const char of input) {
+    hash ^= char.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+
+  return `x${(hash >>> 0).toString(16)}`;
+}
+
+function sanitizeIdentifierCharacters(input: string): string {
+  const sanitized = input.replace(/[^\w]/g, '');
+  return sanitized.length > 0 ? sanitized : createSyntheticIdentifier(input);
+}
+
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+function snakeToPascalCase(input: string): string {
+  const parts = extractIdentifierParts(input);
+  if (parts.length === 0) {
+    return capitalize(sanitizeIdentifierCharacters(input));
+  }
+  return parts.map(capitalize).join('');
+}
+
+function snakeToCamelCase(input: string): string {
+  const parts = extractIdentifierParts(input);
+  if (parts.length === 0) {
+    return sanitizeIdentifierCharacters(input);
+  }
+  const [firstPart = input, ...rest] = parts;
+  return firstPart.charAt(0).toLowerCase() + firstPart.slice(1) + rest.map(capitalize).join('');
+}
+
+function needsEscaping(name: string): boolean {
+  return PSL_RESERVED_WORDS.has(name.toLowerCase()) || /^\d/.test(name);
+}
+
+function escapeName(name: string): string {
+  return `_${name}`;
+}
+
+function escapeIfNeeded(name: string): string {
+  return needsEscaping(name) ? escapeName(name) : name;
+}
+
+export function toModelName(tableName: string): NameResult {
+  let name: string;
+
+  if (hasSeparators(tableName)) {
+    name = snakeToPascalCase(tableName);
+  } else {
+    name = tableName.charAt(0).toUpperCase() + tableName.slice(1);
+  }
+
+  if (needsEscaping(name)) {
+    const escaped = escapeName(name);
+    return { name: escaped, map: tableName };
+  }
+
+  if (name !== tableName) {
+    return { name, map: tableName };
+  }
+
+  return { name };
+}
+
+export function toFieldName(columnName: string): NameResult {
+  let name: string;
+
+  if (hasSeparators(columnName)) {
+    name = snakeToCamelCase(columnName);
+  } else {
+    name = columnName.charAt(0).toLowerCase() + columnName.slice(1);
+  }
+
+  if (needsEscaping(name)) {
+    const escaped = escapeName(name);
+    return { name: escaped, map: columnName };
+  }
+
+  if (name !== columnName) {
+    return { name, map: columnName };
+  }
+
+  return { name };
+}
+
+export function toEnumName(pgTypeName: string): NameResult {
+  let name: string;
+
+  if (hasSeparators(pgTypeName)) {
+    name = snakeToPascalCase(pgTypeName);
+  } else {
+    name = pgTypeName.charAt(0).toUpperCase() + pgTypeName.slice(1);
+  }
+
+  if (needsEscaping(name)) {
+    const escaped = escapeName(name);
+    return { name: escaped, map: pgTypeName };
+  }
+
+  if (name !== pgTypeName) {
+    return { name, map: pgTypeName };
+  }
+
+  return { name };
+}
+
+export function pluralize(word: string): string {
+  if (
+    word.endsWith('s') ||
+    word.endsWith('x') ||
+    word.endsWith('z') ||
+    word.endsWith('ch') ||
+    word.endsWith('sh')
+  ) {
+    return `${word}es`;
+  }
+  if (word.endsWith('y') && !/[aeiou]y$/i.test(word)) {
+    return `${word.slice(0, -1)}ies`;
+  }
+  return `${word}s`;
+}
+
+export function deriveRelationFieldName(
+  fkColumns: readonly string[],
+  referencedTableName: string,
+): string {
+  if (fkColumns.length === 1) {
+    const [col = referencedTableName] = fkColumns;
+    const stripped = col.replace(/_id$/i, '').replace(/Id$/, '');
+
+    if (stripped.length > 0 && stripped !== col) {
+      return escapeIfNeeded(snakeToCamelCase(stripped));
+    }
+    return escapeIfNeeded(snakeToCamelCase(referencedTableName));
+  }
+
+  return escapeIfNeeded(snakeToCamelCase(referencedTableName));
+}
+
+export function deriveBackRelationFieldName(childModelName: string, isOneToOne: boolean): string {
+  const base = childModelName.charAt(0).toLowerCase() + childModelName.slice(1);
+  return isOneToOne ? base : pluralize(base);
+}
+
+export function toNamedTypeName(columnName: string): string {
+  let name: string;
+
+  if (hasSeparators(columnName)) {
+    name = snakeToPascalCase(columnName);
+  } else {
+    name = columnName.charAt(0).toUpperCase() + columnName.slice(1);
+  }
+
+  return escapeIfNeeded(name);
+}

package/src/core/psl-contract-infer/postgres-default-mapping.ts

@@ -0,0 +1,16 @@
+import type { DefaultMappingOptions } from './default-mapping';
+
+const POSTGRES_FUNCTION_ATTRIBUTES: Readonly<Record<string, string>> = {
+  'gen_random_uuid()': '@default(dbgenerated("gen_random_uuid()"))',
+};
+
+function formatDbGeneratedAttribute(expression: string): string {
+  return `@default(dbgenerated(${JSON.stringify(expression)}))`;
+}
+
+export function createPostgresDefaultMapping(): DefaultMappingOptions {
+  return {
+    functionAttributes: POSTGRES_FUNCTION_ATTRIBUTES,
+    fallbackFunctionAttribute: formatDbGeneratedAttribute,
+  };
+}