bunsql-native-migrate 0.3.0 → 0.3.2

package/README.md

@@ -261,7 +261,7 @@ Known MySQL/MariaDB limitation of `Bun.SQL` (not used by this package, good to k
 
 Bun's client also recognizes `mysql2://` and `file://` URLs — `createDriver` deliberately rejects them. Stick to the protocols listed above.
 
-`createDriver(url)` returns a `MigrationDriver` (`install`/`listExecuted`/`record`/`setChecksum`/`remove`/`close`) if you need custom tracking logic; `listExecuted` yields `ExecutedMigration` records (`name`, `checksum`). It also accepts the same `{ tableName, schema }` options as the API functions. Custom drivers may also implement the optional `tryLock(timeoutSeconds)` / `releaseLock()` pair to participate in [concurrent-run locking](#concurrent-runs) — without them, `migrateUp` simply runs unlocked — and the optional `trackingTableExists()` used by `up`'s [dry run](#dry-run) to plan against a database that has no tracking table yet.
+`createDriver(url)` returns a `MigrationDriver` (`install`/`listExecuted`/`record`/`setChecksum`/`remove`/`close`) if you need custom tracking logic; `listExecuted` yields `ExecutedMigration` records (`name`, `checksum`). It also accepts the same `{ tableName, schema }` options as the API functions. Custom drivers may also implement the optional `tryLock(timeoutSeconds)` / `releaseLock()` pair to participate in [concurrent-run locking](#concurrent-runs) — without them, `migrateUp` simply runs unlocked — the optional `trackingTableExists()` used by `up`'s [dry run](#dry-run) to plan against a database that has no tracking table yet, and the optional `trackingTableCurrent()` probe that lets `up`/`down`/`status`/`mark` skip re-running `install()` when the tracking table already has its checksum column and unique index — without the probe, those commands install the table up front as before.
 
 ### Tracking table
 
@@ -309,7 +309,7 @@ Would apply 2 migration(s).
 
 - Nothing is executed and nothing is recorded — not even the tracking table is created, so it is safe against any database, production included. A database without the table simply plans everything as pending.
 - The plan honors every option the real run would: `to`, `steps`, `--table`/`--schema`. The checksum drift check runs too — a dry run reports `ChecksumDriftError` exactly where the real run would fail (the legacy NULL-checksum backfill is the one write it skips).
-- `down --dry-run` plans the revert list in reverse apply order; on an empty history it prints `No migrations to rollback.` like the real command.
+- `down --dry-run` plans the revert list in reverse apply order; on an empty history — a database that has never seen an `up`, included — it prints `No migrations to rollback.` like the real command. A real `down` creates the tracking table when it is missing, so it degrades to the same message instead of a driver error.
 - In the API result the plan lands in `planned: string[]` while `applied`/`reverted` stay empty — existing consumers keep working untouched.
 
 ### Concurrent runs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunsql-native-migrate",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Zero-ORM SQL file migrations for Bun: PostgreSQL, MySQL/MariaDB and SQLite through the built-in Bun.SQL client",
   "keywords": [
     "bun",

package/src/api/down.ts

@@ -6,16 +6,22 @@ import type { MigrateDownOptions, MigrateDownResult } from "./options.js";
 import { runWithDriver } from "./run-with-driver.js";
 import { runMigrationStep } from "./run-step.js";
 import { isSqlMigration, loadMigration } from "./load-migration.js";
+import { ensureTrackingTable, listExecutedForPlan } from "./tracking-table.js";
 
-function resolveStepCount(steps: number | "all" | undefined, appliedCount: number): number {
+export function parseSteps(steps: number | "all" | undefined): number | "all" {
   if (steps === undefined) return 1;
-  if (steps === "all") return appliedCount;
+  if (steps === "all") return "all";
   if (!Number.isInteger(steps) || steps < 1) {
     throw new Error(`Invalid steps: ${String(steps)} — expected a positive integer or "all"`);
   }
   return steps;
 }
 
+function resolveStepCount(steps: number | "all" | undefined, appliedCount: number): number {
+  const parsed = parseSteps(steps);
+  return parsed === "all" ? appliedCount : parsed;
+}
+
 async function revertOne(driver: MigrationDriver, listDir: string, file: string): Promise<void> {
   const { down } = await loadMigration(listDir, file);
 
@@ -37,17 +43,19 @@ export async function migrateDown(options: MigrateDownOptions = {}): Promise<Mig
   const dryRun = options.dryRun ?? false;
 
   return runWithDriver(options, async (driver) => {
-    const executed = await driver.listExecuted();
+    if (!dryRun) {
+      await ensureTrackingTable(driver);
+    }
+
+    const executed = dryRun ? await listExecutedForPlan(driver) : await driver.listExecuted();
     if (executed.length === 0) {
       log({ text: "No migrations to rollback.", type: "warn" });
       return dryRun ? { reverted: [], planned: [] } : { reverted: [] };
     }
 
     const count = resolveStepCount(options.steps, executed.length);
-    const plan = executed
-      .slice(-count)
-      .reverse()
-      .map((entry) => entry.name);
+    const revertList = executed.slice(-count).reverse();
+    const plan = revertList.map((entry) => entry.name);
 
     if (dryRun) {
       log({ text: "Dry run — no changes will be made.", type: "info" });
@@ -59,7 +67,7 @@ export async function migrateDown(options: MigrateDownOptions = {}): Promise<Mig
 
     const reverted: string[] = [];
 
-    for (const entry of executed.slice(-count).reverse()) {
+    for (const entry of revertList) {
       try {
         await revertOne(driver, listDir, entry.name);
       } catch (error) {

package/src/api/mark.ts

@@ -1,35 +1,40 @@
 import path from "node:path";
 import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
-import { type MarkOptions, type MarkResult, MigrationNotFoundError } from "./options.js";
+import { type MarkOptions, type MarkResult } from "./options.js";
+import { resolvePendingToTarget } from "./pending.js";
 import { runWithDriver } from "./run-with-driver.js";
+import { ensureTrackingTable } from "./tracking-table.js";
 
 export async function markMigrationsApplied(options: MarkOptions = {}): Promise<MarkResult> {
   const listDir = resolveListDir(options.listDir);
   const target = options.to;
 
   return runWithDriver(options, async (driver) => {
-    await driver.install();
+    await ensureTrackingTable(driver);
 
     const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
-    if (target !== undefined && !allFiles.includes(target)) {
-      throw new MigrationNotFoundError(target);
-    }
-
     const executed = await driver.listExecuted();
-    const executedNames = new Set(executed.map((entry) => entry.name));
-    let pending = allFiles.filter((file) => !executedNames.has(file));
-    if (target !== undefined) {
-      if (executedNames.has(target)) {
-        log({ text: `${target} is already applied.`, type: "info" });
-        return { marked: [] };
-      }
-      pending = pending.slice(0, pending.indexOf(target) + 1);
+
+    const { pending, targetApplied } = resolvePendingToTarget({
+      allFiles,
+      executedNames: executed.map((entry) => entry.name),
+      target,
+    });
+    if (targetApplied) {
+      return { marked: [] };
     }
 
+    const checksums = new Map(
+      await Promise.all(
+        pending.map(async (file) => [file, await checksumFile(path.join(listDir, file))] as const),
+      ),
+    );
+
     const marked: string[] = [];
     for (const file of pending) {
-      const checksum = await checksumFile(path.join(listDir, file));
+      const checksum = checksums.get(file);
+      if (!checksum) continue;
       await driver.record(file, checksum);
       marked.push(file);
       log({ text: `${file} marked as applied`, type: "success" });

package/src/api/pending.ts

@@ -0,0 +1,37 @@
+import { log } from "../core/console.js";
+import { MigrationNotFoundError } from "./options.js";
+
+export interface PendingToTargetResult {
+  pending: string[];
+  targetApplied: boolean;
+}
+
+interface ResolvePendingOptions {
+  allFiles: string[];
+  executedNames: string[];
+  target: string | undefined;
+}
+
+export function resolvePendingToTarget({
+  allFiles,
+  executedNames,
+  target,
+}: ResolvePendingOptions): PendingToTargetResult {
+  const executed = new Set(executedNames);
+
+  if (target !== undefined && !allFiles.includes(target)) {
+    throw new MigrationNotFoundError(target);
+  }
+
+  let pending = allFiles.filter((file) => !executed.has(file));
+  let targetApplied = false;
+  if (target !== undefined) {
+    if (executed.has(target)) {
+      log({ text: `${target} is already applied.`, type: "info" });
+      targetApplied = true;
+    } else {
+      pending = pending.slice(0, pending.indexOf(target) + 1);
+    }
+  }
+  return { pending, targetApplied };
+}

package/src/api/status.ts

@@ -1,12 +1,13 @@
 import { listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
 import type { MigrateOptions, MigrateStatusResult } from "./options.js";
 import { runWithDriver } from "./run-with-driver.js";
+import { ensureTrackingTable } from "./tracking-table.js";
 
 export async function migrateStatus(options: MigrateOptions = {}): Promise<MigrateStatusResult> {
   const listDir = resolveListDir(options.listDir);
 
   return runWithDriver(options, async (driver) => {
-    await driver.install();
+    await ensureTrackingTable(driver);
 
     const files = await listFiles(listDir, MIGRATION_EXTENSIONS);
     const executed = await driver.listExecuted();

package/src/api/tracking-table.ts

@@ -0,0 +1,15 @@
+import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+
+export async function ensureTrackingTable(driver: MigrationDriver): Promise<void> {
+  if (driver.trackingTableCurrent !== undefined && (await driver.trackingTableCurrent())) {
+    return;
+  }
+  await driver.install();
+}
+
+export async function listExecutedForPlan(driver: MigrationDriver): Promise<ExecutedMigration[]> {
+  if ((await driver.trackingTableExists?.()) === false) {
+    return [];
+  }
+  return driver.listExecuted();
+}

package/src/api/up.ts

@@ -2,24 +2,13 @@ import path from "node:path";
 import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from "../core/fs.js";
 import { log } from "../core/console.js";
 import { formatDuration } from "../core/duration.js";
-import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
-import {
-  type MigrateUpOptions,
-  type MigrateUpResult,
-  ChecksumDriftError,
-  MigrationNotFoundError,
-} from "./options.js";
+import { type MigrateUpOptions, type MigrateUpResult, ChecksumDriftError } from "./options.js";
 import { runWithDriver } from "./run-with-driver.js";
 import { runMigrationStep } from "./run-step.js";
 import { loadMigration } from "./load-migration.js";
+import { resolvePendingToTarget } from "./pending.js";
 import { resolveLockTimeout, withMigrationLock } from "./lock.js";
-
-async function listExecutedForPlan(driver: MigrationDriver): Promise<ExecutedMigration[]> {
-  if ((await driver.trackingTableExists?.()) === false) {
-    return [];
-  }
-  return driver.listExecuted();
-}
+import { ensureTrackingTable, listExecutedForPlan } from "./tracking-table.js";
 
 export async function migrateUp(options: MigrateUpOptions = {}): Promise<MigrateUpResult> {
   const listDir = resolveListDir(options.listDir);
@@ -29,14 +18,11 @@ export async function migrateUp(options: MigrateUpOptions = {}): Promise<Migrate
 
   return runWithDriver(options, async (driver) => {
     if (!dryRun) {
-      await driver.install();
+      await ensureTrackingTable(driver);
     }
 
     const run = async (): Promise<MigrateUpResult> => {
       const allFiles = await listFiles(listDir, MIGRATION_EXTENSIONS);
-      if (target !== undefined && !allFiles.includes(target)) {
-        throw new MigrationNotFoundError(target);
-      }
 
       const checksums = new Map(
         await Promise.all(
@@ -66,13 +52,13 @@ export async function migrateUp(options: MigrateUpOptions = {}): Promise<Migrate
         }
       }
 
-      let pending = allFiles.filter((file) => !executedByName.has(file));
-      if (target !== undefined) {
-        if (executedByName.has(target)) {
-          log({ text: `${target} is already applied.`, type: "info" });
-          return dryRun ? { applied: [], planned: [] } : { applied: [] };
-        }
-        pending = pending.slice(0, pending.indexOf(target) + 1);
+      const { pending, targetApplied } = resolvePendingToTarget({
+        allFiles,
+        executedNames: executed.map((entry) => entry.name),
+        target,
+      });
+      if (targetApplied) {
+        return dryRun ? { applied: [], planned: [] } : { applied: [] };
       }
 
       if (dryRun) {

package/src/cli/main.ts

@@ -1,11 +1,12 @@
 #!/usr/bin/env bun
 import { migrateUp } from "../api/up.js";
-import { migrateDown } from "../api/down.js";
+import { migrateDown, parseSteps } from "../api/down.js";
 import { migrateStatus } from "../api/status.js";
 import { installMigrations } from "../api/install.js";
 import { createMigrationCommand, type MigrationLang } from "../api/create.js";
 import { initMigrations } from "../api/init.js";
 import { markMigrationsApplied } from "../api/mark.js";
+import { resolveLockTimeout } from "../api/lock.js";
 import { ChecksumDriftError, MigrationLockError, MigrationNotFoundError } from "../api/options.js";
 import { InvalidIdentifierError } from "../core/identifiers.js";
 import { log } from "../core/console.js";
@@ -63,15 +64,15 @@ function parseArgs(argv: string[]): CliArgs {
       }
     } else if (arg === "--lock-timeout") {
       const value = argv[++i];
-      const parsed = Number(value);
-      if (value === undefined || !Number.isInteger(parsed) || parsed < 0) {
+      try {
+        lockTimeout = resolveLockTimeout(Number(value));
+      } catch {
         log({
           text: `Invalid --lock-timeout: ${value ?? "(missing)"} (expected a non-negative integer of seconds)`,
           type: "error",
         });
         usage(1);
       }
-      lockTimeout = parsed;
     } else if (arg === "--table") {
       table = argv[++i];
       if (table === undefined) {
@@ -160,15 +161,15 @@ try {
       if (args.all) {
         steps = "all";
       } else if (stepsArg !== undefined) {
-        const parsed = Number(stepsArg);
-        if (!Number.isInteger(parsed) || parsed < 1) {
+        try {
+          steps = parseSteps(Number(stepsArg));
+        } catch {
           log({
             text: `Invalid step count: ${stepsArg} (expected a positive integer)`,
             type: "error",
           });
           usage(1);
         }
-        steps = parsed;
       }
       const { reverted, planned } = await migrateDown({
         ...listDirOptions,

package/src/core/console.ts

@@ -13,32 +13,32 @@ interface LogOptions {
   error?: unknown;
 }
 
-/* eslint-disable @typescript-eslint/no-explicit-any */
-function formatError(error: any): void {
+function formatError(error: unknown): void {
   if (error instanceof Error) {
     console.log(error.message);
     if (error.stack) console.log(error.stack);
     return;
   }
-  if (typeof error === "object" && error !== null) {
-    if ("code" in error && "detail" in error) {
-      console.table(error);
-      return;
-    }
-    if ("code" in error && "errno" in error) {
-      console.log(error.code);
-      console.log(error.errno);
-      if ("byteOffset" in error) console.log(error.byteOffset);
-      return;
-    }
-    if ("message" in error) {
-      console.log(error.message);
-      return;
-    }
+  if (typeof error !== "object" || error === null) {
+    console.log(String(error));
+    return;
+  }
+  if ("code" in error && "detail" in error) {
+    console.table(error);
+    return;
+  }
+  if ("code" in error && "errno" in error) {
+    console.log(error.code);
+    console.log(error.errno);
+    if ("byteOffset" in error) console.log(error.byteOffset);
+    return;
+  }
+  if ("message" in error) {
+    console.log(error.message);
+    return;
   }
   console.log(String(error));
 }
-/* eslint-enable @typescript-eslint/no-explicit-any */
 
 export function log({ text, type, error = null }: LogOptions): void {
   console.log(colors[type], text);

package/src/core/driver.ts

@@ -13,6 +13,7 @@ export interface MigrationDriver {
   remove(migration: string): Promise<void>;
   transaction<T>(run: (tx: SQL) => Promise<T>): Promise<T>;
   trackingTableExists?(): Promise<boolean>;
+  trackingTableCurrent?(): Promise<boolean>;
   tryLock?(timeoutSeconds: number): Promise<boolean>;
   releaseLock?(): Promise<void>;
   close(): Promise<void>;

package/src/drivers/mariadb.ts

@@ -1,26 +1,16 @@
 import { type SQL } from "bun";
 import type { DriverTableOptions, MigrationDriver } from "../core/driver.js";
-import { backtickQuoted, validateIdentifier } from "../core/identifiers.js";
-import { createReservedLock, createSqlDriver } from "./shared.js";
+import { backtickQuoted } from "../core/identifiers.js";
+import {
+  createReservedLock,
+  createSqlDriver,
+  resolveTableRef,
+  UNIQUE_INDEX_SUFFIX,
+} from "./shared.js";
 
 const LOCK_NAME_PREFIX = "bunsql-native-migrate:";
 
 const TABLE_NAME_MAX_LENGTH = 47;
-const UNIQUE_INDEX_SUFFIX = "_migration_unique";
-
-function resolveTableRef(options: DriverTableOptions): {
-  table: string;
-  index: string;
-  name: string;
-} {
-  const tableName = options.tableName ?? "migrations";
-  validateIdentifier("table", tableName, TABLE_NAME_MAX_LENGTH);
-  return {
-    table: backtickQuoted(tableName),
-    index: backtickQuoted(`${tableName}${UNIQUE_INDEX_SUFFIX}`),
-    name: tableName,
-  };
-}
 
 async function checksumColumnExists(db: SQL, tableName: string): Promise<boolean> {
   const rows = await db`SELECT column_name FROM information_schema.columns
@@ -39,7 +29,10 @@ async function uniqueIndexExists(db: SQL, tableName: string): Promise<boolean> {
 }
 
 export function create(databaseUrl: string, options: DriverTableOptions = {}): MigrationDriver {
-  const { table, index, name } = resolveTableRef(options);
+  const { table, index, name } = resolveTableRef(options, {
+    quote: backtickQuoted,
+    maxLength: TABLE_NAME_MAX_LENGTH,
+  });
   return createSqlDriver(
     databaseUrl,
     {
@@ -63,6 +56,21 @@ export function create(databaseUrl: string, options: DriverTableOptions = {}): M
             AND table_name = ${name}`;
         return rows.length > 0;
       },
+      async trackingTableCurrent(db) {
+        const rows = (await db`SELECT EXISTS (
+            SELECT 1 FROM information_schema.tables
+            WHERE table_schema = DATABASE() AND table_name = ${name}
+          ) AND EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = DATABASE() AND table_name = ${name} AND column_name = 'checksum'
+          ) AND EXISTS (
+            SELECT 1 FROM information_schema.statistics
+            WHERE table_schema = DATABASE() AND table_name = ${name}
+              AND index_name = ${`${name}${UNIQUE_INDEX_SUFFIX}`}
+          ) AS current`) as Array<{ current: number | boolean }>;
+        const current = rows[0]?.current;
+        return current === 1 || current === true;
+      },
       async record(db, migration, checksum) {
         await db`INSERT IGNORE INTO ${db.unsafe(table)} (migration, checksum)
           VALUES (${migration}, ${checksum})`;

package/src/drivers/postgres.ts

@@ -1,32 +1,34 @@
 import { type SQL } from "bun";
 import type { DriverTableOptions, MigrationDriver } from "../core/driver.js";
 import { doubleQuoted, validateIdentifier } from "../core/identifiers.js";
-import { createReservedLock, createSqlDriver } from "./shared.js";
+import {
+  createReservedLock,
+  createSqlDriver,
+  resolveTableRef,
+  UNIQUE_INDEX_SUFFIX,
+  type TableRef,
+} from "./shared.js";
 
 const LOCK_SCOPE = "bunsql-native-migrate:up";
 
 const IDENTIFIER_MAX_LENGTH = 63;
-const UNIQUE_INDEX_SUFFIX = "_migration_unique";
 
-interface TableRef {
-  table: string;
-  index: string;
-  name: string;
+interface PostgresTableRef extends TableRef {
   schemaName?: string;
 }
 
-function resolveTableRef(options: DriverTableOptions): TableRef {
-  const tableName = options.tableName ?? "migrations";
-  validateIdentifier("table", tableName, IDENTIFIER_MAX_LENGTH);
-  const index = doubleQuoted(`${tableName}${UNIQUE_INDEX_SUFFIX}`);
+function resolvePostgresTableRef(options: DriverTableOptions): PostgresTableRef {
+  const base = resolveTableRef(options, {
+    quote: doubleQuoted,
+    maxLength: IDENTIFIER_MAX_LENGTH,
+  });
   if (options.schema === undefined) {
-    return { table: doubleQuoted(tableName), index, name: tableName };
+    return base;
   }
   validateIdentifier("schema", options.schema, IDENTIFIER_MAX_LENGTH);
   return {
-    table: `${doubleQuoted(options.schema)}.${doubleQuoted(tableName)}`,
-    index,
-    name: tableName,
+    ...base,
+    table: `${doubleQuoted(options.schema)}.${base.table}`,
     schemaName: options.schema,
   };
 }
@@ -38,7 +40,7 @@ async function advisoryKeyComponents(lock: SQL): Promise<[number, number]> {
 }
 
 export function create(databaseUrl: string, options: DriverTableOptions = {}): MigrationDriver {
-  const { table, index, name, schemaName } = resolveTableRef(options);
+  const { table, index, name, schemaName } = resolvePostgresTableRef(options);
   return createSqlDriver(
     databaseUrl,
     {
@@ -59,16 +61,35 @@ export function create(databaseUrl: string, options: DriverTableOptions = {}): M
               WHERE table_schema = current_schema() AND table_name = ${name}`;
         return rows.length > 0;
       },
+      async trackingTableCurrent(db) {
+        const rows = (await db`SELECT EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = COALESCE(${schemaName ?? null}, current_schema())
+              AND table_name = ${name} AND column_name = 'checksum'
+          ) AND EXISTS (
+            SELECT 1 FROM pg_indexes
+            WHERE schemaname = COALESCE(${schemaName ?? null}, current_schema())
+              AND indexname = ${`${name}${UNIQUE_INDEX_SUFFIX}`}
+          ) AS "current"`) as Array<{ current: boolean }>;
+        return rows[0]?.current === true;
+      },
       async record(db, migration, checksum) {
         await db`INSERT INTO ${db.unsafe(table)} (migration, checksum)
           VALUES (${migration}, ${checksum})
           ON CONFLICT (migration) DO NOTHING`;
       },
-      createLock: (db) =>
-        createReservedLock(
+      createLock: (db) => {
+        let cachedKey: [number, number] | null = null;
+        const resolveAdvisoryKey = async (lock: SQL): Promise<[number, number]> => {
+          if (cachedKey === null) {
+            cachedKey = await advisoryKeyComponents(lock);
+          }
+          return cachedKey;
+        };
+        return createReservedLock(
           db,
           async (lock) => {
-            const [first, second] = await advisoryKeyComponents(lock);
+            const [first, second] = await resolveAdvisoryKey(lock);
             const rows =
               (await lock`SELECT pg_try_advisory_lock(${first}, ${second}) AS locked`) as Array<{
                 locked: boolean;
@@ -76,10 +97,11 @@ export function create(databaseUrl: string, options: DriverTableOptions = {}): M
             return rows[0]?.locked === true;
           },
           async (lock) => {
-            const [first, second] = await advisoryKeyComponents(lock);
+            const [first, second] = await resolveAdvisoryKey(lock);
             await lock`SELECT pg_advisory_unlock(${first}, ${second})`;
           },
-        ),
+        );
+      },
     },
     table,
   );

package/src/drivers/shared.ts

@@ -1,5 +1,29 @@
 import { SQL, type ReservedSQL } from "bun";
-import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
+import type { DriverTableOptions, ExecutedMigration, MigrationDriver } from "../core/driver.js";
+import { validateIdentifier } from "../core/identifiers.js";
+
+export const UNIQUE_INDEX_SUFFIX = "_migration_unique";
+
+export interface TableRef {
+  table: string;
+  index: string;
+  name: string;
+}
+
+interface TableRefSpec {
+  quote: (identifier: string) => string;
+  maxLength: number;
+}
+
+export function resolveTableRef(options: DriverTableOptions, spec: TableRefSpec): TableRef {
+  const tableName = options.tableName ?? "migrations";
+  validateIdentifier("table", tableName, spec.maxLength);
+  return {
+    table: spec.quote(tableName),
+    index: spec.quote(`${tableName}${UNIQUE_INDEX_SUFFIX}`),
+    name: tableName,
+  };
+}
 
 export interface SqlLock {
   tryLock(timeoutSeconds: number): Promise<boolean>;
@@ -11,6 +35,7 @@ export interface SqlDialect {
   install(db: SQL): Promise<void>;
   record(db: SQL, migration: string, checksum: string): Promise<void>;
   trackingTableExists?(db: SQL): Promise<boolean>;
+  trackingTableCurrent?(db: SQL): Promise<boolean>;
   createLock?(db: SQL): SqlLock;
 }
 
@@ -85,6 +110,9 @@ export function createSqlDriver(
     ...(dialect.trackingTableExists
       ? { trackingTableExists: () => dialect.trackingTableExists!(db) }
       : {}),
+    ...(dialect.trackingTableCurrent
+      ? { trackingTableCurrent: () => dialect.trackingTableCurrent!(db) }
+      : {}),
     ...(lock
       ? {
           tryLock: (timeoutSeconds: number) => lock.tryLock(timeoutSeconds),

package/src/drivers/sqlite.ts

@@ -1,26 +1,14 @@
 import type { DriverTableOptions, MigrationDriver } from "../core/driver.js";
-import { doubleQuoted, validateIdentifier } from "../core/identifiers.js";
-import { createSqlDriver } from "./shared.js";
+import { doubleQuoted } from "../core/identifiers.js";
+import { createSqlDriver, resolveTableRef, UNIQUE_INDEX_SUFFIX } from "./shared.js";
 
 const TABLE_NAME_MAX_LENGTH = 128;
-const UNIQUE_INDEX_SUFFIX = "_migration_unique";
-
-function resolveTableRef(options: DriverTableOptions): {
-  table: string;
-  index: string;
-  name: string;
-} {
-  const tableName = options.tableName ?? "migrations";
-  validateIdentifier("table", tableName, TABLE_NAME_MAX_LENGTH);
-  return {
-    table: doubleQuoted(tableName),
-    index: doubleQuoted(`${tableName}${UNIQUE_INDEX_SUFFIX}`),
-    name: tableName,
-  };
-}
 
 export function create(databaseUrl: string, options: DriverTableOptions = {}): MigrationDriver {
-  const { table, index, name } = resolveTableRef(options);
+  const { table, index, name } = resolveTableRef(options, {
+    quote: doubleQuoted,
+    maxLength: TABLE_NAME_MAX_LENGTH,
+  });
   return createSqlDriver(
     databaseUrl,
     {
@@ -43,6 +31,16 @@ export function create(databaseUrl: string, options: DriverTableOptions = {}): M
         const rows = await db`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ${name}`;
         return rows.length > 0;
       },
+      async trackingTableCurrent(db) {
+        const columns = (await db.unsafe(`PRAGMA table_info(${table})`)) as Array<{
+          name: string;
+        }>;
+        if (!columns.some((column) => column.name === "checksum")) return false;
+        const indexName = `${name}${UNIQUE_INDEX_SUFFIX}`;
+        const indexes = (await db`SELECT 1 FROM sqlite_master WHERE type = 'index'
+          AND name = ${indexName}`) as Array<unknown>;
+        return indexes.length > 0;
+      },
       async record(db, migration, checksum) {
         await db`INSERT OR IGNORE INTO ${db.unsafe(table)} (migration, checksum)
           VALUES (${migration}, ${checksum})`;