@remix-run/data-table 0.2.1 → 0.4.0

package/src/lib/migrations/runner.ts

@@ -1,21 +1,27 @@
-import { createDatabase, createDatabaseWithTransaction } from '../database.ts'
-import type { Database } from '../database.ts'
-import type { DatabaseAdapter, TransactionToken } from '../adapter.ts'
-import type { SqlStatement } from '../sql.ts'
+import type { DatabaseDriver, TransactionToken } from '../driver.ts'
 import type {
-  MigrateOptions,
+  MigrationOperationOptions,
   MigrateResult,
-  MigrationContext,
   MigrationDescriptor,
   MigrationDirection,
   MigrationJournalRow,
   MigrationRegistry,
-  MigrationRunner,
-  MigrationRunnerOptions,
   MigrationStatus,
   MigrationStatusEntry,
+  MigrationTransactionMode,
 } from '../migrations.ts'
 
+interface MigrationRunnerOptions {
+  journalTable?: string
+}
+
+interface MigrationRunner {
+  up(options?: MigrationOperationOptions): Promise<MigrateResult>
+  down(options?: MigrationOperationOptions): Promise<MigrateResult>
+  status(): Promise<MigrationStatusEntry[]>
+}
+
+import { parseTransactionDirective } from './directive.ts'
 import {
   deleteJournalRow,
   ensureMigrationJournal,
@@ -23,17 +29,18 @@ import {
   hasMigrationJournal,
   insertJournalRow,
   loadJournalRows,
-  normalizeChecksum,
+  computeChecksum,
 } from './journal-store.ts'
 import { resolveMigrations } from './registry.ts'
-import { createMigrationSchema } from './schema-api.ts'
+
+type MigrationRunnerContext = DatabaseDriver
 
 type RunMigrationsInput = {
-  adapter: DatabaseAdapter
+  driver: MigrationRunnerContext
   migrations: MigrationDescriptor[]
   journalTable: string
   direction: MigrationDirection
-  options: MigrateOptions
+  options: MigrationOperationOptions
 }
 
 function assertStepOption(step: number | undefined): void {
@@ -46,38 +53,65 @@ function assertStepOption(step: number | undefined): void {
   }
 }
 
-function assertMigrateOptions(options: MigrateOptions): void {
+function assertMigrationOperationOptions(options: MigrationOperationOptions): void {
   if (options.to !== undefined && options.step !== undefined) {
     throw new Error('Cannot combine "to" and "step" migration options in the same run')
   }
 }
 
-function assertTargetOption(migrations: MigrationDescriptor[], to: string | undefined): void {
+function resolveTargetOption(
+  migrations: MigrationDescriptor[],
+  to: string | undefined,
+): string | undefined {
   if (!to) {
-    return
+    return undefined
   }
 
-  let target = migrations.find((migration) => migration.id === to)
+  // Accept either a bare migration id or the full `id_name` directory form and
+  // normalize to the bare id so range filtering compares ids consistently.
+  let matches = migrations.filter(
+    (migration) => migration.id === to || migration.id + '_' + migration.name === to,
+  )
 
-  if (!target) {
+  if (matches.length === 0) {
     throw new Error('Unknown migration target: ' + to)
   }
+
+  if (matches.length > 1) {
+    throw new Error(
+      'Ambiguous migration target "' +
+        to +
+        '". Matches: ' +
+        matches.map((migration) => migration.id + '_' + migration.name).join(', '),
+    )
+  }
+
+  return matches[0].id
 }
 
-function assertNoMigrationDrift(
+async function assertMigrationIntegrity(
   migrations: MigrationDescriptor[],
   journal: MigrationJournalRow[],
-): void {
+  direction: MigrationDirection,
+): Promise<void> {
   let migrationMap = new Map(migrations.map((migration) => [migration.id, migration]))
 
   for (let row of journal) {
     let migration = migrationMap.get(row.id)
 
     if (!migration) {
-      continue
+      // Rolling back must stay possible when journal rows have no matching
+      // migration files, so only forward runs hard-error on orphaned entries.
+      if (direction === 'down') {
+        continue
+      }
+
+      throw new Error(
+        'Applied migration "' + row.id + '_' + row.name + '" is missing from current migrations',
+      )
     }
 
-    let expected = normalizeChecksum(migration)
+    let expected = await computeChecksum(migration)
 
     if (expected !== row.checksum) {
       throw new Error(
@@ -93,244 +127,208 @@ function assertNoMigrationDrift(
   }
 }
 
-function createDryRunDatabase(adapter: DatabaseAdapter): Database {
-  let error = new Error('Cannot execute data operations while running migrations with dryRun')
-  let throwDryRunError = async (): Promise<never> => {
-    throw error
+function resolveTransactionMode(migration: MigrationDescriptor): MigrationTransactionMode {
+  if (migration.transaction) {
+    return migration.transaction
   }
-  let dryRunAdapter: DatabaseAdapter = {
-    dialect: adapter.dialect,
-    capabilities: adapter.capabilities,
-    compileSql(operation) {
-      return adapter.compileSql(operation)
-    },
-    async hasTable(table) {
-      return adapter.hasTable(table)
-    },
-    async hasColumn(table, column) {
-      return adapter.hasColumn(table, column)
-    },
-    execute: throwDryRunError,
-    migrate: throwDryRunError,
-    beginTransaction: throwDryRunError,
-    commitTransaction: throwDryRunError,
-    rollbackTransaction: throwDryRunError,
-    createSavepoint: throwDryRunError,
-    rollbackToSavepoint: throwDryRunError,
-    releaseSavepoint: throwDryRunError,
+
+  let directive = parseTransactionDirective(migration.up)
+
+  if (directive) {
+    return directive
   }
 
-  return createDatabase(dryRunAdapter)
+  return 'auto'
 }
 
 async function runMigrations(input: RunMigrationsInput): Promise<MigrateResult> {
-  let adapter = input.adapter
+  if (input.driver.capabilities.migrationLock && !input.driver.withMigrationLock) {
+    throw new Error(
+      'Database driver reports migration lock support but does not implement withMigrationLock()',
+    )
+  }
+
+  if (input.driver.withMigrationLock) {
+    return input.driver.withMigrationLock(input.journalTable, (driver) =>
+      runMigrationsUnlocked({ ...input, driver }),
+    )
+  }
+
+  return runMigrationsUnlocked(input)
+}
+
+async function runMigrationsUnlocked(input: RunMigrationsInput): Promise<MigrateResult> {
+  let driver = input.driver
   let migrations = input.migrations
   let journalTable = input.journalTable
   let dryRun = Boolean(input.options.dryRun)
-  let target = input.options.to
   let step = input.options.step
 
-  assertMigrateOptions(input.options)
+  assertMigrationOperationOptions(input.options)
   assertStepOption(step)
-  assertTargetOption(migrations, target)
 
-  let sql: SqlStatement[] = []
+  let target = resolveTargetOption(migrations, input.options.to)
 
-  await adapter.acquireMigrationLock?.()
+  let sql: string[] = []
 
-  try {
-    let journal: MigrationJournalRow[] = []
+  let journal: MigrationJournalRow[] = []
 
-    if (dryRun) {
-      let canReadJournal = await hasMigrationJournal(adapter, journalTable)
+  if (dryRun) {
+    let canReadJournal = await hasMigrationJournal(driver, journalTable)
 
-      if (canReadJournal) {
-        journal = await loadJournalRows(adapter, journalTable)
-      }
-    } else {
-      await ensureMigrationJournal(adapter, journalTable)
-      journal = await loadJournalRows(adapter, journalTable)
+    if (canReadJournal) {
+      journal = await loadJournalRows(driver, journalTable)
     }
+  } else {
+    await ensureMigrationJournal(driver, journalTable)
+    journal = await loadJournalRows(driver, journalTable)
+  }
 
-    let appliedMap = new Map(journal.map((row) => [row.id, row]))
-    assertNoMigrationDrift(migrations, journal)
-    let toRun: MigrationDescriptor[] = []
-
-    if (input.direction === 'up') {
-      for (let migration of migrations) {
-        if (!appliedMap.has(migration.id)) {
-          toRun.push(migration)
-        }
-      }
-
-      if (target) {
-        toRun = toRun.filter((migration) => migration.id <= target)
-      }
+  let appliedMap = new Map(journal.map((row) => [row.id, row]))
+  await assertMigrationIntegrity(migrations, journal, input.direction)
+  let toRun: MigrationDescriptor[] = []
 
-      if (step !== undefined) {
-        toRun = toRun.slice(0, step)
+  if (input.direction === 'up') {
+    for (let migration of migrations) {
+      if (!appliedMap.has(migration.id)) {
+        toRun.push(migration)
       }
-    } else {
-      let appliedMigrations = migrations
-        .filter((migration) => appliedMap.has(migration.id))
-        .reverse()
+    }
 
-      if (target) {
-        appliedMigrations = appliedMigrations.filter((migration) => migration.id >= target)
-      }
+    if (target) {
+      toRun = toRun.filter((migration) => migration.id <= target)
+    }
 
-      if (step !== undefined) {
-        appliedMigrations = appliedMigrations.slice(0, step)
-      }
+    if (step !== undefined) {
+      toRun = toRun.slice(0, step)
+    }
+  } else {
+    toRun = migrations.filter((migration) => appliedMap.has(migration.id)).reverse()
 
-      toRun = appliedMigrations
+    if (target) {
+      toRun = toRun.filter((migration) => migration.id >= target)
     }
 
-    let applied: MigrationStatusEntry[] = []
-    let reverted: MigrationStatusEntry[] = []
-    let batch = getBatch(journal)
+    if (step !== undefined) {
+      toRun = toRun.slice(0, step)
+    }
 
     for (let migration of toRun) {
-      if (
-        migration.migration.transaction === 'required' &&
-        !adapter.capabilities.transactionalDdl
-      ) {
-        throw new Error(
-          'Migration "' +
-            migration.id +
-            '" requires transactional DDL, but adapter does not support it',
-        )
+      if (migration.down === undefined) {
+        throw new Error('Migration "' + migration.id + '" has no down script')
       }
+    }
+  }
 
-      let shouldUseTransaction =
-        !dryRun &&
-        migration.migration.transaction !== 'none' &&
-        adapter.capabilities.transactionalDdl
-      let token: TransactionToken | undefined
+  let applied: MigrationStatusEntry[] = []
+  let reverted: MigrationStatusEntry[] = []
+  let batch = getBatch(journal)
 
-      if (shouldUseTransaction) {
-        token = await adapter.beginTransaction()
-      }
+  for (let migration of toRun) {
+    let script = (input.direction === 'up' ? migration.up : migration.down) as string
+    let mode = resolveTransactionMode(migration)
 
-      let db = dryRun
-        ? createDryRunDatabase(adapter)
-        : token
-          ? createDatabaseWithTransaction(adapter, token)
-          : createDatabase(adapter)
-
-      let schema = createMigrationSchema(
-        db,
-        async (operation) => {
-          let compiled = adapter.compileSql(operation)
-          sql.push(...compiled)
-
-          if (!dryRun) {
-            await adapter.migrate({ operation, transaction: token })
-          }
-        },
-        { transaction: token },
+    if (mode === 'required' && !driver.capabilities.transactionalDdl) {
+      throw new Error(
+        'Migration "' +
+          migration.id +
+          '" requires transactional DDL, but the database does not support it',
       )
-      let context: MigrationContext = {
-        db,
-        schema,
-      }
+    }
 
-      try {
-        if (input.direction === 'up') {
-          await migration.migration.up(context)
-
-          if (!dryRun) {
-            await insertJournalRow(
-              adapter,
-              journalTable,
-              {
-                id: migration.id,
-                name: migration.name,
-                checksum: normalizeChecksum(migration),
-                batch,
-              },
-              token,
-            )
-          }
-
-          applied.push({
-            id: migration.id,
-            name: migration.name,
-            status: 'applied',
-          })
-        } else {
-          await migration.migration.down(context)
+    let shouldUseTransaction = !dryRun && mode !== 'none' && driver.capabilities.transactionalDdl
+    let token: TransactionToken | undefined
 
-          if (!dryRun) {
-            await deleteJournalRow(adapter, journalTable, migration.id, token)
-          }
+    if (shouldUseTransaction) {
+      token = await driver.beginTransaction()
+    }
 
-          reverted.push({
-            id: migration.id,
-            name: migration.name,
-            status: 'pending',
-          })
+    sql.push(script)
+
+    try {
+      if (!dryRun) {
+        if (script.trim().length > 0) {
+          await driver.executeScript(script, token)
         }
+      }
 
-        if (token) {
-          await adapter.commitTransaction(token)
+      if (input.direction === 'up') {
+        if (!dryRun) {
+          await insertJournalRow(
+            driver,
+            journalTable,
+            {
+              id: migration.id,
+              name: migration.name,
+              checksum: await computeChecksum(migration),
+              batch,
+            },
+            token,
+          )
         }
-      } catch (error) {
-        if (token) {
-          await adapter.rollbackTransaction(token)
+
+        applied.push({
+          id: migration.id,
+          name: migration.name,
+          status: 'applied',
+        })
+      } else {
+        if (!dryRun) {
+          await deleteJournalRow(driver, journalTable, migration.id, token)
         }
 
-        throw error
+        reverted.push({
+          id: migration.id,
+          name: migration.name,
+          status: 'pending',
+        })
       }
+    } catch (error) {
+      if (token) {
+        try {
+          await driver.rollbackTransaction(token)
+        } catch (rollbackError) {
+          throw new AggregateError([error, rollbackError], 'Migration and rollback both failed', {
+            cause: error,
+          })
+        }
+      }
+
+      throw error
     }
 
-    return {
-      applied,
-      reverted,
-      sql,
+    if (token) {
+      await driver.commitTransaction(token)
     }
-  } finally {
-    await adapter.releaseMigrationLock?.()
+  }
+
+  return {
+    applied,
+    reverted,
+    sql,
   }
 }
 
-/**
- * Creates a migration runner for applying/reverting migrations against an adapter.
- * @param adapter Database adapter used to compile and execute migration operations.
- * @param migrations Migration descriptors or registry.
- * @param options Optional runner configuration.
- * @returns A migration runner instance.
- * @example
- * ```ts
- * import { createMigrationRunner } from 'remix/data-table/migrations'
- *
- * let runner = createMigrationRunner(adapter, migrations, {
- *   journalTable: 'app_migrations',
- * })
- * await runner.up()
- * ```
- */
 export function createMigrationRunner(
-  adapter: DatabaseAdapter,
+  driver: DatabaseDriver,
   migrations: MigrationDescriptor[] | MigrationRegistry,
   options: MigrationRunnerOptions = {},
 ): MigrationRunner {
   let journalTable = options.journalTable ?? 'data_table_migrations'
 
   return {
-    async up(runOptions: MigrateOptions = {}): Promise<MigrateResult> {
+    async up(runOptions: MigrationOperationOptions = {}): Promise<MigrateResult> {
       return runMigrations({
-        adapter,
+        driver,
         migrations: resolveMigrations(migrations),
         journalTable,
         direction: 'up',
         options: runOptions,
       })
     },
-    async down(runOptions: MigrateOptions = {}): Promise<MigrateResult> {
+    async down(runOptions: MigrationOperationOptions = {}): Promise<MigrateResult> {
       return runMigrations({
-        adapter,
+        driver,
         migrations: resolveMigrations(migrations),
         journalTable,
         direction: 'down',
@@ -338,26 +336,30 @@ export function createMigrationRunner(
       })
     },
     async status(): Promise<MigrationStatusEntry[]> {
-      await ensureMigrationJournal(adapter, journalTable)
-
-      let journal = await loadJournalRows(adapter, journalTable)
+      let journal = (await hasMigrationJournal(driver, journalTable))
+        ? await loadJournalRows(driver, journalTable)
+        : []
       let journalMap = new Map(journal.map((row) => [row.id, row]))
       let sortedMigrations = resolveMigrations(migrations)
+      let migrationIds = new Set(sortedMigrations.map((migration) => migration.id))
 
-      return sortedMigrations.map((migration) => {
+      let statuses: MigrationStatusEntry[] = []
+
+      for (let migration of sortedMigrations) {
         let journalRow = journalMap.get(migration.id)
 
         if (!journalRow) {
-          return {
+          statuses.push({
             id: migration.id,
             name: migration.name,
             status: 'pending' as MigrationStatus,
-          }
+          })
+          continue
         }
 
-        let checksum = normalizeChecksum(migration)
+        let checksum = await computeChecksum(migration)
 
-        return {
+        statuses.push({
           id: migration.id,
           name: migration.name,
           status:
@@ -367,8 +369,25 @@ export function createMigrationRunner(
           appliedAt: journalRow.appliedAt,
           batch: journalRow.batch,
           checksum: journalRow.checksum,
+        })
+      }
+
+      for (let journalRow of journal) {
+        if (migrationIds.has(journalRow.id)) {
+          continue
         }
-      })
+
+        statuses.push({
+          id: journalRow.id,
+          name: journalRow.name,
+          status: 'missing',
+          appliedAt: journalRow.appliedAt,
+          batch: journalRow.batch,
+          checksum: journalRow.checksum,
+        })
+      }
+
+      return statuses.sort((left, right) => left.id.localeCompare(right.id))
     },
   }
 }