@fragno-dev/db 0.1.14 → 0.2.0

package/src/adapters/generic-sql/migration/prepared-migrations.ts

@@ -0,0 +1,214 @@
+import type { AnySchema } from "../../../schema/create";
+import type { SqlDriverAdapter } from "../../../sql-driver/sql-driver-adapter";
+import type { TableNameMapper } from "../../shared/table-name-mapper";
+import { generateMigrationFromSchema } from "../../../migration-engine/auto-from-schema";
+import { createColdKysely } from "./cold-kysely";
+import { type SQLGenerator } from "./sql-generator";
+import { SQLiteSQLGenerator } from "./dialect/sqlite";
+import { PostgresSQLGenerator } from "./dialect/postgres";
+import { MySQLSQLGenerator } from "./dialect/mysql";
+import { executeMigration, type CompiledMigration } from "./executor";
+import type { SupportedDatabase } from "../driver-config";
+import type { Kysely } from "kysely";
+/**
+ * Options for executing a migration.
+ */
+export interface ExecuteOptions {
+  /**
+   * Whether to automatically update the schema version in the database after migration.
+   * If not specified, uses the value from PreparedMigrationsConfig.
+   */
+  updateVersionInMigration?: boolean;
+}
+
+/**
+ * Interface for preparing and executing migrations.
+ * Provides a clean separation between compilation (SQL generation) and execution.
+ */
+export interface PreparedMigrations {
+  /**
+   * Execute migration from one version to another.
+   * This performs all three phases:
+   * - Phase 1: schema → operations
+   * - Phase 2: operations → SQL
+   * - Phase 3: SQL → database
+   *
+   * @param fromVersion - Current database version (0 for new database)
+   * @param toVersion - Target schema version (defaults to schema.version)
+   * @param options - Optional execution options (overrides config defaults)
+   */
+  execute(fromVersion: number, toVersion?: number, options?: ExecuteOptions): Promise<void>;
+
+  /**
+   * Execute migration using a specific driver.
+   * Useful for testing or when you need to use a different driver than the one provided in config.
+   *
+   * @param driver - SQL driver to use for execution
+   * @param fromVersion - Current database version (0 for new database)
+   * @param toVersion - Target schema version (defaults to schema.version)
+   * @param options - Optional execution options (overrides config defaults)
+   */
+  executeWithDriver(
+    driver: SqlDriverAdapter,
+    fromVersion: number,
+    toVersion?: number,
+    options?: ExecuteOptions,
+  ): Promise<void>;
+
+  /**
+   * Get the SQL for a migration from one version to another without executing it.
+   * Useful for generating migration files or previewing changes.
+   *
+   * @param fromVersion - Current database version (0 for new database)
+   * @param toVersion - Target schema version (defaults to schema.version)
+   * @param options - Optional execution options (affects version update SQL)
+   * @returns SQL string for the migration
+   */
+  getSQL(fromVersion: number, toVersion?: number, options?: ExecuteOptions): string;
+
+  /**
+   * Get the compiled migration for a version range.
+   * Returns both the SQL statements and the version information.
+   *
+   * @param fromVersion - Current database version (0 for new database)
+   * @param toVersion - Target schema version (defaults to schema.version)
+   * @param options - Optional execution options (affects version update SQL)
+   * @returns Compiled migration with statements and version info
+   */
+  compile(fromVersion: number, toVersion?: number, options?: ExecuteOptions): CompiledMigration;
+}
+
+/**
+ * Configuration for creating a PreparedMigrations instance.
+ */
+export interface PreparedMigrationsConfig {
+  schema: AnySchema;
+  namespace: string;
+  database: SupportedDatabase;
+  mapper?: TableNameMapper;
+  driver?: SqlDriverAdapter;
+  /**
+   * Whether to automatically update the schema version in the database after migration.
+   * Defaults to true. Can be overridden per execution via ExecuteOptions.
+   */
+  updateVersionInMigration?: boolean;
+}
+
+/**
+ * Create a PreparedMigrations instance for a schema and namespace.
+ */
+export function createPreparedMigrations(config: PreparedMigrationsConfig): PreparedMigrations {
+  const {
+    schema,
+    namespace,
+    database,
+    driver,
+    updateVersionInMigration: defaultUpdateVersion = true,
+  } = config;
+
+  // Create the cold Kysely instance for SQL generation
+  const coldKysely = createColdKysely(database);
+
+  // Create the appropriate SQL generator for the database
+  const generator = createSQLGenerator(database, coldKysely);
+
+  /**
+   * Internal method to compile a migration for a given version range.
+   */
+  function compile(
+    fromVersion: number,
+    toVersion: number,
+    updateVersionInMigration: boolean,
+  ): CompiledMigration {
+    // Validate version numbers
+    if (fromVersion < 0) {
+      throw new Error(`fromVersion cannot be negative: ${fromVersion}`);
+    }
+    if (toVersion < 0) {
+      throw new Error(`toVersion cannot be negative: ${toVersion}`);
+    }
+    if (toVersion < fromVersion) {
+      throw new Error(
+        `Cannot migrate backwards: fromVersion (${fromVersion}) > toVersion (${toVersion})`,
+      );
+    }
+    if (toVersion > schema.version) {
+      throw new Error(`toVersion (${toVersion}) exceeds schema version (${schema.version})`);
+    }
+
+    // Phase 1: Generate migration operations from schema
+    const operations = generateMigrationFromSchema(schema, fromVersion, toVersion);
+
+    // Phase 2: Compile operations to SQL
+    const statements = generator.compile(operations, config.mapper);
+
+    // Add version update SQL if requested
+    if (updateVersionInMigration && toVersion !== fromVersion) {
+      const versionUpdate = generator.generateVersionUpdateSQL(namespace, fromVersion, toVersion);
+      statements.push(versionUpdate);
+    }
+
+    return {
+      statements,
+      fromVersion,
+      toVersion,
+    };
+  }
+
+  return {
+    async execute(fromVersion, toVersion, options) {
+      if (!driver) {
+        throw new Error(
+          "Driver not provided. Cannot execute migration. Use `executeWithDriver` instead.",
+        );
+      }
+
+      return this.executeWithDriver(driver, fromVersion, toVersion, options);
+    },
+
+    async executeWithDriver(driverToUse, fromVersion, toVersion, options) {
+      // Use option if provided, otherwise use config default
+      const updateVersionInMigration = options?.updateVersionInMigration ?? defaultUpdateVersion;
+      const targetVersion = toVersion ?? schema.version;
+
+      // Compile the migration (this will validate the version numbers)
+      const migration = compile(fromVersion, targetVersion, updateVersionInMigration);
+
+      // Execute the migration
+      await executeMigration(driverToUse, migration);
+    },
+
+    getSQL(fromVersion, toVersion, options) {
+      const updateVersionInMigration = options?.updateVersionInMigration ?? defaultUpdateVersion;
+      const targetVersion = toVersion ?? schema.version;
+
+      const migration = compile(fromVersion, targetVersion, updateVersionInMigration);
+      return migration.statements.map((stmt) => stmt.sql + ";").join("\n\n");
+    },
+
+    compile(fromVersion, toVersion, options) {
+      const updateVersionInMigration = options?.updateVersionInMigration ?? defaultUpdateVersion;
+      const targetVersion = toVersion ?? schema.version;
+
+      return compile(fromVersion, targetVersion, updateVersionInMigration);
+    },
+  };
+}
+
+/**
+ * Create the appropriate SQL generator for a database type.
+ */
+function createSQLGenerator(
+  database: SupportedDatabase,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  coldKysely: Kysely<any>,
+): SQLGenerator {
+  switch (database) {
+    case "sqlite":
+      return new SQLiteSQLGenerator(coldKysely, database);
+    case "postgresql":
+      return new PostgresSQLGenerator(coldKysely, database);
+    case "mysql":
+      return new MySQLSQLGenerator(coldKysely, database);
+  }
+}

package/src/adapters/generic-sql/migration/sql-generator.ts

@@ -0,0 +1,413 @@
+import {
+  type ColumnDefinitionBuilder,
+  type CompiledQuery,
+  type CreateTableBuilder,
+  type Kysely,
+  type RawBuilder,
+  sql,
+} from "kysely";
+import { createHash } from "node:crypto";
+import type {
+  ColumnInfo,
+  ColumnOperation,
+  MigrationOperation,
+} from "../../../migration-engine/shared";
+import { SETTINGS_TABLE_NAME } from "../../../fragments/internal-fragment";
+import type { TableNameMapper } from "../../shared/table-name-mapper";
+import type { SupportedDatabase } from "../driver-config";
+import { createSQLTypeMapper } from "../../../schema/type-conversion/create-sql-type-mapper";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type KyselyAny = Kysely<any>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type CreateTableBuilderAny = CreateTableBuilder<any, any>;
+
+/**
+ * Interface for compiling migration operations to SQL.
+ */
+export interface CompilableQuery {
+  compile(): CompiledQuery;
+}
+
+/**
+ * Abstract base class for SQL generation from migration operations.
+ * Each database dialect extends this class and implements the abstract methods.
+ */
+export abstract class SQLGenerator {
+  protected readonly db: KyselyAny;
+  protected readonly database: SupportedDatabase;
+  protected readonly typeMapper: ReturnType<typeof createSQLTypeMapper>;
+
+  constructor(db: KyselyAny, database: SupportedDatabase) {
+    this.db = db;
+    this.database = database;
+    this.typeMapper = createSQLTypeMapper(database);
+  }
+
+  /**
+   * Preprocess operations before SQL generation.
+   * Dialects can override to transform operations based on database capabilities.
+   * For example, SQLite merges FK operations into create-table operations.
+   */
+  abstract preprocess(operations: MigrationOperation[]): MigrationOperation[];
+
+  /**
+   * Apply auto-increment to a column builder.
+   * PostgreSQL uses SERIAL types so this is a no-op there.
+   */
+  abstract applyAutoIncrement(builder: ColumnDefinitionBuilder): ColumnDefinitionBuilder;
+
+  /**
+   * Get the default value for a column, or undefined if not supported.
+   * MySQL returns undefined for TEXT columns since it doesn't support defaults there.
+   */
+  abstract getDefaultValue(column: ColumnInfo): RawBuilder<unknown> | undefined;
+
+  /**
+   * Generate SQL for updating the schema version in the settings table.
+   * This is the same across all databases.
+   */
+  generateVersionUpdateSQL(
+    namespace: string,
+    fromVersion: number,
+    toVersion: number,
+  ): CompiledQuery {
+    const key = `${namespace}.schema_version`;
+
+    if (fromVersion === 0) {
+      // Insert new version record
+      const id = createHash("md5").update(key).digest("base64url").replace(/=/g, "");
+      return this.db
+        .insertInto(SETTINGS_TABLE_NAME)
+        .values({
+          id: sql.lit(id),
+          key: sql.lit(key),
+          value: sql.lit(toVersion.toString()),
+        })
+        .compile();
+    } else {
+      // Update existing version record
+      return this.db
+        .updateTable(SETTINGS_TABLE_NAME)
+        .set({
+          value: sql.lit(toVersion.toString()),
+        })
+        .where("key", "=", sql.lit(key))
+        .compile();
+    }
+  }
+
+  /**
+   * Compile migration operations to SQL statements.
+   * This is the main entry point for SQL generation.
+   */
+  compile(operations: MigrationOperation[], mapper?: TableNameMapper): CompiledQuery[] {
+    const preprocessed = this.preprocess(operations);
+    const queries: CompiledQuery[] = [];
+
+    for (const operation of preprocessed) {
+      const compiled = this.compileOperation(operation, mapper);
+      if (Array.isArray(compiled)) {
+        queries.push(...compiled);
+      } else {
+        queries.push(compiled);
+      }
+    }
+
+    return queries;
+  }
+
+  /**
+   * Compile a single migration operation to SQL.
+   */
+  protected compileOperation(
+    operation: MigrationOperation,
+    mapper?: TableNameMapper,
+  ): CompiledQuery | CompiledQuery[] {
+    switch (operation.type) {
+      case "create-table":
+        return this.compileCreateTable(operation, mapper);
+      case "rename-table":
+        return this.compileRenameTable(operation, mapper);
+      case "alter-table":
+        return this.compileAlterTable(operation, mapper);
+      case "drop-table":
+        return this.compileDropTable(operation, mapper);
+      case "add-foreign-key":
+        return this.compileAddForeignKey(operation, mapper);
+      case "drop-foreign-key":
+        return this.compileDropForeignKey(operation, mapper);
+      case "add-index":
+        return this.compileAddIndex(operation, mapper);
+      case "drop-index":
+        return this.compileDropIndex(operation, mapper);
+      case "custom":
+        return this.compileCustom(operation);
+    }
+  }
+
+  /**
+   * Compile a create-table operation.
+   * Subclasses can override to add FK constraints inline (e.g., SQLite).
+   */
+  protected compileCreateTable(
+    operation: Extract<MigrationOperation, { type: "create-table" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery {
+    const tableName = this.getTableName(operation.name, mapper);
+    let builder: CreateTableBuilderAny = this.db.schema.createTable(tableName);
+
+    for (const col of operation.columns) {
+      builder = builder.addColumn(col.name, sql.raw(this.getDBType(col)), (b) =>
+        this.buildColumn(col, b),
+      );
+    }
+
+    // Allow subclasses to add inline foreign keys
+    builder = this.addInlineForeignKeys(builder, operation, mapper);
+
+    return builder.compile();
+  }
+
+  /**
+   * Hook for subclasses to add inline foreign keys to create-table.
+   * SQLite overrides this to add FKs at table creation time.
+   */
+  protected addInlineForeignKeys(
+    builder: CreateTableBuilderAny,
+    _operation: Extract<MigrationOperation, { type: "create-table" }>,
+    _mapper?: TableNameMapper,
+  ): CreateTableBuilderAny {
+    return builder;
+  }
+
+  /**
+   * Compile a rename-table operation.
+   */
+  protected compileRenameTable(
+    operation: Extract<MigrationOperation, { type: "rename-table" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery {
+    return this.db.schema
+      .alterTable(this.getTableName(operation.from, mapper))
+      .renameTo(this.getTableName(operation.to, mapper))
+      .compile();
+  }
+
+  /**
+   * Compile an alter-table operation.
+   */
+  protected compileAlterTable(
+    operation: Extract<MigrationOperation, { type: "alter-table" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery[] {
+    const queries: CompiledQuery[] = [];
+    const tableName = this.getTableName(operation.name, mapper);
+
+    for (const columnOp of operation.value) {
+      const compiled = this.compileColumnOperation(tableName, columnOp);
+      if (Array.isArray(compiled)) {
+        queries.push(...compiled);
+      } else {
+        queries.push(compiled);
+      }
+    }
+
+    return queries;
+  }
+
+  /**
+   * Compile a column operation within an alter-table.
+   * Subclasses override for database-specific handling (e.g., MySQL's modifyColumn).
+   */
+  protected compileColumnOperation(
+    tableName: string,
+    operation: ColumnOperation,
+  ): CompiledQuery | CompiledQuery[] {
+    const alter = () => this.db.schema.alterTable(tableName);
+
+    switch (operation.type) {
+      case "rename-column":
+        return alter().renameColumn(operation.from, operation.to).compile();
+
+      case "drop-column":
+        return alter().dropColumn(operation.name).compile();
+
+      case "create-column": {
+        const col = operation.value;
+        return alter()
+          .addColumn(col.name, sql.raw(this.getDBType(col)), (b) => this.buildColumn(col, b))
+          .compile();
+      }
+
+      case "update-column":
+        return this.compileUpdateColumn(tableName, operation);
+    }
+  }
+
+  /**
+   * Compile an update-column operation.
+   * Must be implemented by subclasses since each database handles this differently.
+   */
+  protected abstract compileUpdateColumn(
+    tableName: string,
+    operation: Extract<ColumnOperation, { type: "update-column" }>,
+  ): CompiledQuery | CompiledQuery[];
+
+  /**
+   * Compile a drop-table operation.
+   */
+  protected compileDropTable(
+    operation: Extract<MigrationOperation, { type: "drop-table" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery {
+    return this.db.schema.dropTable(this.getTableName(operation.name, mapper)).compile();
+  }
+
+  /**
+   * Compile an add-foreign-key operation.
+   * Subclasses can throw if not supported (e.g., SQLite).
+   */
+  protected compileAddForeignKey(
+    operation: Extract<MigrationOperation, { type: "add-foreign-key" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery {
+    const { table, value } = operation;
+    return this.db.schema
+      .alterTable(this.getTableName(table, mapper))
+      .addForeignKeyConstraint(
+        value.name,
+        value.columns,
+        this.getTableName(value.referencedTable, mapper),
+        value.referencedColumns,
+        (b) => b.onUpdate("restrict").onDelete("restrict"),
+      )
+      .compile();
+  }
+
+  /**
+   * Compile a drop-foreign-key operation.
+   * Subclasses can throw if not supported (e.g., SQLite).
+   */
+  protected compileDropForeignKey(
+    operation: Extract<MigrationOperation, { type: "drop-foreign-key" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery {
+    const { table, name } = operation;
+    return this.db.schema
+      .alterTable(this.getTableName(table, mapper))
+      .dropConstraint(name)
+      .ifExists()
+      .compile();
+  }
+
+  /**
+   * Compile an add-index operation.
+   */
+  protected compileAddIndex(
+    operation: Extract<MigrationOperation, { type: "add-index" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery {
+    const tableName = this.getTableName(operation.table, mapper);
+    const indexName = this.getIndexName(operation.name, operation.table, mapper);
+    let builder = this.db.schema.createIndex(indexName).on(tableName).columns(operation.columns);
+
+    if (operation.unique) {
+      builder = builder.unique();
+    }
+
+    return builder.compile();
+  }
+
+  /**
+   * Compile a drop-index operation.
+   */
+  protected compileDropIndex(
+    operation: Extract<MigrationOperation, { type: "drop-index" }>,
+    mapper?: TableNameMapper,
+  ): CompiledQuery {
+    const tableName = this.getTableName(operation.table, mapper);
+    const indexName = this.getIndexName(operation.name, operation.table, mapper);
+    return this.db.schema.dropIndex(indexName).ifExists().on(tableName).compile();
+  }
+
+  /**
+   * Compile a custom SQL operation.
+   */
+  protected compileCustom(
+    operation: Extract<MigrationOperation, { type: "custom" }>,
+  ): CompiledQuery {
+    // Custom operations have a 'sql' property with raw SQL
+    const rawSql = operation["sql"] as string;
+    return sql.raw(rawSql).compile(this.db);
+  }
+
+  /**
+   * Build a column with all its constraints.
+   */
+  protected buildColumn(
+    col: ColumnInfo,
+    builder: ColumnDefinitionBuilder,
+  ): ColumnDefinitionBuilder {
+    if (!col.isNullable) {
+      builder = builder.notNull();
+    }
+
+    if (col.role === "internal-id") {
+      builder = builder.primaryKey();
+      builder = this.applyAutoIncrement(builder);
+    }
+
+    if (col.role === "external-id") {
+      builder = builder.unique();
+    }
+
+    const defaultValue = this.getDefaultValue(col);
+    if (defaultValue) {
+      builder = builder.defaultTo(defaultValue);
+    }
+
+    return builder;
+  }
+
+  /**
+   * Get table name, applying namespace mapping if provided.
+   * Settings table is never namespaced.
+   */
+  protected getTableName(tableName: string, mapper?: TableNameMapper): string {
+    if (tableName === SETTINGS_TABLE_NAME) {
+      return tableName;
+    }
+    return mapper ? mapper.toPhysical(tableName) : tableName;
+  }
+
+  /**
+   * Get the physical index name, applying namespace if a mapper is provided.
+   * Index names must be globally unique in most databases, so we namespace them
+   * to avoid collisions when multiple fragments use the same logical index names.
+   */
+  protected getIndexName(indexName: string, tableName: string, mapper?: TableNameMapper): string {
+    if (!mapper) {
+      return indexName;
+    }
+    // Create a unique index name by including the physical table name
+    // This ensures index names are unique across namespaces
+    const physicalTable = mapper.toPhysical(tableName);
+    return `${indexName}_${physicalTable}`;
+  }
+
+  /**
+   * Get the database type string for a column.
+   */
+  protected getDBType(col: ColumnInfo): string {
+    return this.typeMapper.getDatabaseType(col);
+  }
+
+  /**
+   * Compile raw SQL to a CompiledQuery.
+   */
+  protected compileRaw(raw: RawBuilder<unknown>): CompiledQuery {
+    return raw.compile(this.db);
+  }
+}

package/src/adapters/generic-sql/query/create-sql-query-compiler.ts

@@ -0,0 +1,36 @@
+import type { DriverConfig } from "../driver-config";
+import type { TableNameMapper } from "../../shared/table-name-mapper";
+import { SQLQueryCompiler, type AnyKysely } from "./sql-query-compiler";
+import { PostgreSQLQueryCompiler } from "./dialect/postgres";
+import { MySQLQueryCompiler } from "./dialect/mysql";
+import { SQLiteQueryCompiler } from "./dialect/sqlite";
+
+/**
+ * Factory function to create a dialect-specific SQL query compiler.
+ *
+ * Based on the database type in DriverConfig, returns the appropriate
+ * compiler implementation (PostgreSQL, MySQL, or SQLite).
+ *
+ * @param db - Kysely database instance
+ * @param driverConfig - Driver configuration with database type and capabilities
+ * @param mapper - Optional table name mapper for namespace prefixing
+ * @returns Dialect-specific SQLQueryCompiler instance
+ */
+export function createSQLQueryCompiler(
+  db: AnyKysely,
+  driverConfig: DriverConfig,
+  mapper?: TableNameMapper,
+): SQLQueryCompiler {
+  switch (driverConfig.databaseType) {
+    case "postgresql":
+      return new PostgreSQLQueryCompiler(db, driverConfig, mapper);
+    case "mysql":
+      return new MySQLQueryCompiler(db, driverConfig, mapper);
+    case "sqlite":
+      return new SQLiteQueryCompiler(db, driverConfig, mapper);
+    default: {
+      const exhaustiveCheck: never = driverConfig.databaseType;
+      throw new Error(`Unsupported database type: ${exhaustiveCheck}`);
+    }
+  }
+}