@prisma-next/target-sqlite 0.5.0-dev.8 → 0.5.0-dev.81

package/src/core/migrations/op-factory-call.ts

@@ -0,0 +1,369 @@
+/**
+ * SQLite migration IR: one concrete `*Call` class per pure factory under
+ * `operations/`, plus a shared `SqliteOpFactoryCallNode` abstract base.
+ *
+ * Each call class carries fully-resolved literal arguments (flat
+ * `SqliteColumnSpec` / `SqliteTableSpec` etc.) — codec / `typeRef` / default
+ * expansion happens upstream in the issue-planner / strategies, mirroring
+ * the Postgres `ColumnSpec` pattern. As a result, `toOp()` and
+ * `renderTypeScript()` both pass the same flat data through; the rendered
+ * TypeScript scaffold is fully self-contained and does not need access to a
+ * `storageTypes` map at runtime.
+ */
+
+import { errorUnfilledPlaceholder } from '@prisma-next/errors/migration';
+import type {
+  MigrationOperationClass,
+  SqlMigrationPlanOperation,
+} from '@prisma-next/family-sql/control';
+import type { OpFactoryCall as FrameworkOpFactoryCall } from '@prisma-next/framework-components/control';
+import { type ImportRequirement, jsonToTsSource, TsExpression } from '@prisma-next/ts-render';
+import { addColumn, dropColumn } from './operations/columns';
+import { createIndex, dropIndex } from './operations/indexes';
+import type { SqliteColumnSpec, SqliteIndexSpec, SqliteTableSpec } from './operations/shared';
+import { createTable, dropTable, recreateTable } from './operations/tables';
+import type { SqlitePlanTargetDetails } from './planner-target-details';
+
+type Op = SqlMigrationPlanOperation<SqlitePlanTargetDetails>;
+
+const TARGET_MIGRATION_MODULE = '@prisma-next/target-sqlite/migration';
+
+abstract class SqliteOpFactoryCallNode extends TsExpression implements FrameworkOpFactoryCall {
+  abstract readonly factoryName: string;
+  abstract readonly operationClass: MigrationOperationClass;
+  abstract readonly label: string;
+  abstract toOp(): Op;
+
+  importRequirements(): readonly ImportRequirement[] {
+    return [{ moduleSpecifier: TARGET_MIGRATION_MODULE, symbol: this.factoryName }];
+  }
+
+  protected freeze(): void {
+    Object.freeze(this);
+  }
+}
+
+// ============================================================================
+// Table
+// ============================================================================
+
+export class CreateTableCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'createTable' as const;
+  readonly operationClass = 'additive' as const;
+  readonly tableName: string;
+  readonly spec: SqliteTableSpec;
+  readonly label: string;
+
+  constructor(tableName: string, spec: SqliteTableSpec) {
+    super();
+    this.tableName = tableName;
+    this.spec = spec;
+    this.label = `Create table ${tableName}`;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return createTable(this.tableName, this.spec);
+  }
+
+  renderTypeScript(): string {
+    return `createTable(${jsonToTsSource(this.tableName)}, ${jsonToTsSource(this.spec)})`;
+  }
+}
+
+export class DropTableCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'dropTable' as const;
+  readonly operationClass = 'destructive' as const;
+  readonly tableName: string;
+  readonly label: string;
+
+  constructor(tableName: string) {
+    super();
+    this.tableName = tableName;
+    this.label = `Drop table ${tableName}`;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return dropTable(this.tableName);
+  }
+
+  renderTypeScript(): string {
+    return `dropTable(${jsonToTsSource(this.tableName)})`;
+  }
+}
+
+export class RecreateTableCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'recreateTable' as const;
+  readonly operationClass: MigrationOperationClass;
+  readonly tableName: string;
+  readonly contractTable: SqliteTableSpec;
+  readonly schemaColumnNames: readonly string[];
+  readonly indexes: readonly SqliteIndexSpec[];
+  readonly summary: string;
+  readonly postchecks: readonly { readonly description: string; readonly sql: string }[];
+  readonly label: string;
+
+  constructor(args: {
+    tableName: string;
+    contractTable: SqliteTableSpec;
+    schemaColumnNames: readonly string[];
+    indexes: readonly SqliteIndexSpec[];
+    summary: string;
+    postchecks: readonly { readonly description: string; readonly sql: string }[];
+    operationClass: MigrationOperationClass;
+  }) {
+    super();
+    this.tableName = args.tableName;
+    this.contractTable = args.contractTable;
+    this.schemaColumnNames = args.schemaColumnNames;
+    this.indexes = args.indexes;
+    this.summary = args.summary;
+    this.postchecks = args.postchecks;
+    this.operationClass = args.operationClass;
+    this.label = `Recreate table ${args.tableName}`;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return recreateTable({
+      tableName: this.tableName,
+      contractTable: this.contractTable,
+      schemaColumnNames: this.schemaColumnNames,
+      indexes: this.indexes,
+      summary: this.summary,
+      postchecks: this.postchecks,
+      operationClass: this.operationClass,
+    });
+  }
+
+  renderTypeScript(): string {
+    const args = {
+      tableName: this.tableName,
+      contractTable: this.contractTable,
+      schemaColumnNames: this.schemaColumnNames,
+      indexes: this.indexes,
+      summary: this.summary,
+      postchecks: this.postchecks,
+      operationClass: this.operationClass,
+    };
+    return `recreateTable(${jsonToTsSource(args)})`;
+  }
+}
+
+// ============================================================================
+// Column
+// ============================================================================
+
+export class AddColumnCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'addColumn' as const;
+  readonly operationClass = 'additive' as const;
+  readonly tableName: string;
+  readonly columnName: string;
+  readonly column: SqliteColumnSpec;
+  readonly label: string;
+
+  constructor(tableName: string, column: SqliteColumnSpec) {
+    super();
+    this.tableName = tableName;
+    this.columnName = column.name;
+    this.column = column;
+    this.label = `Add column ${column.name} on ${tableName}`;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return addColumn(this.tableName, this.column);
+  }
+
+  renderTypeScript(): string {
+    return `addColumn(${jsonToTsSource(this.tableName)}, ${jsonToTsSource(this.column)})`;
+  }
+}
+
+export class DropColumnCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'dropColumn' as const;
+  readonly operationClass = 'destructive' as const;
+  readonly tableName: string;
+  readonly columnName: string;
+  readonly label: string;
+
+  constructor(tableName: string, columnName: string) {
+    super();
+    this.tableName = tableName;
+    this.columnName = columnName;
+    this.label = `Drop column ${columnName} on ${tableName}`;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return dropColumn(this.tableName, this.columnName);
+  }
+
+  renderTypeScript(): string {
+    return `dropColumn(${jsonToTsSource(this.tableName)}, ${jsonToTsSource(this.columnName)})`;
+  }
+}
+
+// ============================================================================
+// Index
+// ============================================================================
+
+export class CreateIndexCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'createIndex' as const;
+  readonly operationClass = 'additive' as const;
+  readonly tableName: string;
+  readonly indexName: string;
+  readonly columns: readonly string[];
+  readonly label: string;
+
+  constructor(tableName: string, indexName: string, columns: readonly string[]) {
+    super();
+    this.tableName = tableName;
+    this.indexName = indexName;
+    this.columns = columns;
+    this.label = `Create index ${indexName} on ${tableName}`;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return createIndex(this.tableName, this.indexName, this.columns);
+  }
+
+  renderTypeScript(): string {
+    return `createIndex(${jsonToTsSource(this.tableName)}, ${jsonToTsSource(this.indexName)}, ${jsonToTsSource(this.columns)})`;
+  }
+}
+
+export class DropIndexCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'dropIndex' as const;
+  readonly operationClass = 'destructive' as const;
+  readonly tableName: string;
+  readonly indexName: string;
+  readonly label: string;
+
+  constructor(tableName: string, indexName: string) {
+    super();
+    this.tableName = tableName;
+    this.indexName = indexName;
+    this.label = `Drop index ${indexName} on ${tableName}`;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return dropIndex(this.tableName, this.indexName);
+  }
+
+  renderTypeScript(): string {
+    return `dropIndex(${jsonToTsSource(this.tableName)}, ${jsonToTsSource(this.indexName)})`;
+  }
+}
+
+// ============================================================================
+// Data transform
+// ============================================================================
+
+/**
+ * A planner-generated data-transform stub. The current default strategy
+ * (`nullabilityTighteningBackfillStrategy`) emits one of these with a
+ * backfill-flavored `id`/`label` when the policy allows `'data'` and the
+ * contract tightens a column's nullability, but the op itself is generic —
+ * any future strategy that needs a placeholder data step can construct one
+ * with its own id/label.
+ *
+ * `toOp()` always throws `PN-MIG-2001`: the planner cannot lower a stubbed
+ * transform to a runtime op — the user must edit the rendered
+ * `migration.ts` and re-emit.
+ */
+export class DataTransformCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'dataTransform' as const;
+  readonly operationClass = 'data' as const;
+  readonly id: string;
+  readonly label: string;
+  readonly tableName: string;
+  readonly columnName: string;
+
+  constructor(id: string, label: string, tableName: string, columnName: string) {
+    super();
+    this.id = id;
+    this.label = label;
+    this.tableName = tableName;
+    this.columnName = columnName;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    throw errorUnfilledPlaceholder(this.label);
+  }
+
+  renderTypeScript(): string {
+    const slot = `${this.tableName}-${this.columnName}-backfill-sql`;
+    return [
+      'dataTransform({',
+      `  id: ${jsonToTsSource(this.id)},`,
+      `  label: ${jsonToTsSource(this.label)},`,
+      `  table: ${jsonToTsSource(this.tableName)},`,
+      `  description: ${jsonToTsSource(`Backfill NULL ${this.columnName} values in ${this.tableName}`)},`,
+      `  run: () => placeholder(${jsonToTsSource(slot)}),`,
+      '})',
+    ].join('\n');
+  }
+
+  override importRequirements(): readonly ImportRequirement[] {
+    return [
+      { moduleSpecifier: TARGET_MIGRATION_MODULE, symbol: this.factoryName },
+      { moduleSpecifier: TARGET_MIGRATION_MODULE, symbol: 'placeholder' },
+    ];
+  }
+}
+
+// ============================================================================
+// Raw SQL
+// ============================================================================
+
+/**
+ * Laundered pre-built operation. Mirrors Postgres's `RawSqlCall`: wraps an
+ * already-materialized `SqlMigrationPlanOperation` (typically produced by a
+ * SQL-family helper or a codec lifecycle hook) so the planner can carry it
+ * alongside structured call IR. `toOp()` returns the stored op unchanged;
+ * `renderTypeScript()` emits `rawSql({...})` with the op serialized as a
+ * JSON literal — round-tripping requires every field on the op to be
+ * JSON-serializable (no closures).
+ */
+export class RawSqlCall extends SqliteOpFactoryCallNode {
+  readonly factoryName = 'rawSql' as const;
+  readonly operationClass: MigrationOperationClass;
+  readonly label: string;
+  readonly op: Op;
+
+  constructor(op: Op) {
+    super();
+    this.op = op;
+    this.label = op.label;
+    this.operationClass = op.operationClass;
+    this.freeze();
+  }
+
+  toOp(): Op {
+    return this.op;
+  }
+
+  renderTypeScript(): string {
+    return `rawSql(${jsonToTsSource(this.op)})`;
+  }
+}
+
+// ============================================================================
+// Union
+// ============================================================================
+
+export type SqliteOpFactoryCall =
+  | CreateTableCall
+  | DropTableCall
+  | RecreateTableCall
+  | AddColumnCall
+  | DropColumnCall
+  | CreateIndexCall
+  | DropIndexCall
+  | DataTransformCall
+  | RawSqlCall;

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

@@ -0,0 +1,62 @@
+import { escapeLiteral, quoteIdentifier } from '../../sql-utils';
+import { buildTargetDetails } from '../planner-target-details';
+import { type Op, type SqliteColumnSpec, step } from './shared';
+
+export function addColumn(tableName: string, column: SqliteColumnSpec): Op {
+  const parts = [
+    `ALTER TABLE ${quoteIdentifier(tableName)}`,
+    `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} on ${tableName}`,
+    summary: `Adds column ${column.name} on ${tableName}`,
+    operationClass: 'additive',
+    target: { id: 'sqlite', details: buildTargetDetails('column', column.name, tableName) },
+    precheck: [
+      step(
+        `ensure column "${column.name}" is missing`,
+        `SELECT COUNT(*) = 0 FROM pragma_table_info('${escapeLiteral(tableName)}') WHERE name = '${escapeLiteral(column.name)}'`,
+      ),
+    ],
+    execute: [step(`add column "${column.name}"`, addSql)],
+    postcheck: [
+      step(
+        `verify column "${column.name}" exists`,
+        `SELECT COUNT(*) > 0 FROM pragma_table_info('${escapeLiteral(tableName)}') WHERE name = '${escapeLiteral(column.name)}'`,
+      ),
+    ],
+  };
+}
+
+export function dropColumn(tableName: string, columnName: string): Op {
+  return {
+    id: `dropColumn.${tableName}.${columnName}`,
+    label: `Drop column ${columnName} on ${tableName}`,
+    summary: `Drops column ${columnName} on ${tableName} which is not in the contract`,
+    operationClass: 'destructive',
+    target: { id: 'sqlite', details: buildTargetDetails('column', columnName, tableName) },
+    precheck: [
+      step(
+        `ensure column "${columnName}" exists on "${tableName}"`,
+        `SELECT COUNT(*) > 0 FROM pragma_table_info('${escapeLiteral(tableName)}') WHERE name = '${escapeLiteral(columnName)}'`,
+      ),
+    ],
+    execute: [
+      step(
+        `drop column "${columnName}" from "${tableName}"`,
+        `ALTER TABLE ${quoteIdentifier(tableName)} DROP COLUMN ${quoteIdentifier(columnName)}`,
+      ),
+    ],
+    postcheck: [
+      step(
+        `verify column "${columnName}" is gone from "${tableName}"`,
+        `SELECT COUNT(*) = 0 FROM pragma_table_info('${escapeLiteral(tableName)}') WHERE name = '${escapeLiteral(columnName)}'`,
+      ),
+    ],
+  };
+}

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

@@ -0,0 +1,51 @@
+/**
+ * User-facing `dataTransform` factory for the SQLite migration authoring
+ * surface. Invoked directly inside a `migration.ts` file to supply a
+ * user-authored SQL statement that runs with operation class `'data'`.
+ *
+ * Typical use: the planner emits a `DataTransformCall` stub when a NOT NULL
+ * tightening requires a backfill. The rendered `migration.ts` exposes the
+ * backfill as a `placeholder("…")` slot the user fills in with an
+ * `UPDATE … WHERE col IS NULL` statement. The filled-in `dataTransform(...)`
+ * invocation returns a runnable operation the runner executes before the
+ * subsequent recreate-table op copies data into the tightened schema.
+ */
+
+import { buildTargetDetails } from '../planner-target-details';
+import { type Op, step } from './shared';
+
+export interface DataTransformOptions {
+  /** Stable id used in the ledger / for runner idempotency tracking. */
+  readonly id: string;
+  /** Human-readable label surfaced in CLI output. */
+  readonly label: string;
+  /** Table the backfill targets; informs `target.details`. */
+  readonly table: string;
+  /**
+   * Short description of the step (shown by the runner on execute). The
+   * planner leaves this as `placeholder(...)` for users to replace.
+   */
+  readonly description: string;
+  /**
+   * Producer of the SQL string to execute. Invoked eagerly by
+   * `dataTransform(...)`, mirroring the Postgres factory — by the time the
+   * user calls this factory in `migration.ts`, the SQL is expected to be
+   * ready. Planner-emitted stubs that need to defer until the user fills
+   * in the SQL go through `DataTransformCall.renderTypeScript()` instead;
+   * this factory is only for the post-fill, runnable form.
+   */
+  readonly run: () => string;
+}
+
+export function dataTransform(opts: DataTransformOptions): Op {
+  return {
+    id: opts.id,
+    label: opts.label,
+    summary: opts.description,
+    operationClass: 'data',
+    target: { id: 'sqlite', details: buildTargetDetails('table', opts.table) },
+    precheck: [],
+    execute: [step(opts.description, opts.run())],
+    postcheck: [],
+  };
+}

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

@@ -0,0 +1,52 @@
+import { escapeLiteral } from '../../sql-utils';
+import { buildCreateIndexSql, buildDropIndexSql } from '../planner-ddl-builders';
+import { buildTargetDetails } from '../planner-target-details';
+import { type Op, step } from './shared';
+
+export function createIndex(tableName: string, indexName: string, columns: readonly string[]): Op {
+  return {
+    id: `index.${tableName}.${indexName}`,
+    label: `Create index ${indexName} on ${tableName}`,
+    summary: `Creates index ${indexName} on ${tableName}`,
+    operationClass: 'additive',
+    target: { id: 'sqlite', details: buildTargetDetails('index', indexName, tableName) },
+    precheck: [
+      step(
+        `ensure index "${indexName}" is missing`,
+        `SELECT COUNT(*) = 0 FROM sqlite_master WHERE type = 'index' AND name = '${escapeLiteral(indexName)}'`,
+      ),
+    ],
+    execute: [
+      step(`create index "${indexName}"`, buildCreateIndexSql(tableName, indexName, columns)),
+    ],
+    postcheck: [
+      step(
+        `verify index "${indexName}" exists`,
+        `SELECT COUNT(*) > 0 FROM sqlite_master WHERE type = 'index' AND name = '${escapeLiteral(indexName)}'`,
+      ),
+    ],
+  };
+}
+
+export function dropIndex(tableName: string, indexName: string): Op {
+  return {
+    id: `dropIndex.${tableName}.${indexName}`,
+    label: `Drop index ${indexName} on ${tableName}`,
+    summary: `Drops index ${indexName} on ${tableName} which is not in the contract`,
+    operationClass: 'destructive',
+    target: { id: 'sqlite', details: buildTargetDetails('index', indexName, tableName) },
+    precheck: [
+      step(
+        `ensure index "${indexName}" exists`,
+        `SELECT COUNT(*) > 0 FROM sqlite_master WHERE type = 'index' AND name = '${escapeLiteral(indexName)}'`,
+      ),
+    ],
+    execute: [step(`drop index "${indexName}"`, buildDropIndexSql(indexName))],
+    postcheck: [
+      step(
+        `verify index "${indexName}" is gone`,
+        `SELECT COUNT(*) = 0 FROM sqlite_master WHERE type = 'index' AND name = '${escapeLiteral(indexName)}'`,
+      ),
+    ],
+  };
+}

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

@@ -0,0 +1,12 @@
+import type { Op } from './shared';
+
+/**
+ * Identity factory for an already-materialized
+ * `SqlMigrationPlanOperation<SqlitePlanTargetDetails>`. Mirrors the Postgres
+ * `rawSql` factory: the planner uses this to carry ops produced by SQL-family
+ * paths (codec lifecycle hooks, raw-SQL escape hatches) alongside structured
+ * call IR without reverse-engineering their shape.
+ */
+export function rawSql(op: Op): Op {
+  return op;
+}

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

@@ -0,0 +1,120 @@
+import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
+import type { ReferentialAction } from '@prisma-next/sql-contract/types';
+import { quoteIdentifier } from '../../sql-utils';
+import type { SqlitePlanTargetDetails } from '../planner-target-details';
+
+export type Op = SqlMigrationPlanOperation<SqlitePlanTargetDetails>;
+
+export function step(description: string, sql: string): { description: string; sql: string } {
+  return { description, sql };
+}
+
+/**
+ * Flat, fully-resolved column shape consumed by `createTable`, `addColumn`,
+ * and `recreateTable`. Codec / `typeRef` / default expansion happens at the
+ * call-construction site (in the issue-planner / strategies) so the
+ * operation factories deal only in pre-rendered SQL fragments — mirrors the
+ * Postgres `ColumnSpec` pattern.
+ *
+ * - `typeSql` is the column's DDL type token (e.g. `"INTEGER"`, `"TEXT"`).
+ * - `defaultSql` is the full `DEFAULT …` clause (or empty when there is no
+ *   default and when the column is rendered as `INTEGER PRIMARY KEY
+ *   AUTOINCREMENT`, since SQLite forbids a default on an autoincrement PK).
+ * - `inlineAutoincrementPrimaryKey` directs the renderer to emit
+ *   `INTEGER PRIMARY KEY AUTOINCREMENT` inline and to skip the table-level
+ *   primary-key constraint for this column. SQLite-specific: the column
+ *   becomes an alias for `rowid` only when this exact form is used.
+ */
+export interface SqliteColumnSpec {
+  readonly name: string;
+  readonly typeSql: string;
+  readonly defaultSql: string;
+  readonly nullable: boolean;
+  readonly inlineAutoincrementPrimaryKey?: boolean;
+}
+
+export interface SqlitePrimaryKeySpec {
+  readonly columns: readonly string[];
+}
+
+export interface SqliteUniqueSpec {
+  readonly columns: readonly string[];
+  readonly name?: string;
+}
+
+export interface SqliteForeignKeySpec {
+  readonly columns: readonly string[];
+  readonly references: {
+    readonly table: string;
+    readonly columns: readonly string[];
+  };
+  readonly name?: string;
+  readonly onDelete?: ReferentialAction;
+  readonly onUpdate?: ReferentialAction;
+  readonly constraint: boolean;
+}
+
+/**
+ * Flat shape of a contract table for DDL emission. Used by both
+ * `createTable` (additive) and `recreateTable` (widening/destructive).
+ */
+export interface SqliteTableSpec {
+  readonly columns: readonly SqliteColumnSpec[];
+  readonly primaryKey?: SqlitePrimaryKeySpec;
+  readonly uniques?: readonly SqliteUniqueSpec[];
+  readonly foreignKeys?: readonly SqliteForeignKeySpec[];
+}
+
+/**
+ * Index recreation spec for `recreateTable`. Both declared indexes and
+ * FK-backing indexes flatten to the same shape; the planner dedupes by
+ * column-set before constructing the call.
+ */
+export interface SqliteIndexSpec {
+  readonly name: string;
+  readonly columns: readonly string[];
+}
+
+const REFERENTIAL_ACTION_SQL: Record<ReferentialAction, string> = {
+  noAction: 'NO ACTION',
+  restrict: 'RESTRICT',
+  cascade: 'CASCADE',
+  setNull: 'SET NULL',
+  setDefault: 'SET DEFAULT',
+};
+
+/**
+ * Renders a single column's inline DDL fragment within a `CREATE TABLE`
+ * statement. Honours the `inlineAutoincrementPrimaryKey` flag — SQLite
+ * treats `INTEGER PRIMARY KEY AUTOINCREMENT` as a special form that aliases
+ * `rowid`, and the column must not carry a `DEFAULT` or repeat `NOT NULL`.
+ */
+export function renderColumnDefinition(column: SqliteColumnSpec): string {
+  const parts: string[] = [quoteIdentifier(column.name), column.typeSql];
+  if (column.inlineAutoincrementPrimaryKey) {
+    parts.push('PRIMARY KEY AUTOINCREMENT');
+  } else {
+    if (column.defaultSql) parts.push(column.defaultSql);
+    if (!column.nullable) parts.push('NOT NULL');
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Renders an inline FOREIGN KEY constraint clause for a `CREATE TABLE`
+ * body. Returns the empty string when `constraint` is false (the FK is
+ * tracked at the contract level for index-creation purposes only and must
+ * not produce DDL).
+ */
+export function renderForeignKeyClause(fk: SqliteForeignKeySpec): string {
+  if (!fk.constraint) return '';
+  const name = fk.name ? `CONSTRAINT ${quoteIdentifier(fk.name)} ` : '';
+  let sql = `${name}FOREIGN KEY (${fk.columns.map(quoteIdentifier).join(', ')}) REFERENCES ${quoteIdentifier(fk.references.table)} (${fk.references.columns.map(quoteIdentifier).join(', ')})`;
+  if (fk.onDelete !== undefined) {
+    sql += ` ON DELETE ${REFERENTIAL_ACTION_SQL[fk.onDelete]}`;
+  }
+  if (fk.onUpdate !== undefined) {
+    sql += ` ON UPDATE ${REFERENTIAL_ACTION_SQL[fk.onUpdate]}`;
+  }
+  return sql;
+}