bunsql-native-migrate 0.3.0 → 0.3.1

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.1",
   "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,6 +6,7 @@ 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 {
   if (steps === undefined) return 1;
@@ -37,7 +38,11 @@ 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: [] };

package/src/api/mark.ts

@@ -3,13 +3,14 @@ import { checksumFile, listFiles, MIGRATION_EXTENSIONS, resolveListDir } from ".
 import { log } from "../core/console.js";
 import { type MarkOptions, type MarkResult, MigrationNotFoundError } from "./options.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)) {

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,7 +2,6 @@ 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,
@@ -13,13 +12,7 @@ import { runWithDriver } from "./run-with-driver.js";
 import { runMigrationStep } from "./run-step.js";
 import { loadMigration } from "./load-migration.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,7 +22,7 @@ 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> => {

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

@@ -63,6 +63,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

@@ -59,6 +59,18 @@ 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})

package/src/drivers/shared.ts

@@ -11,6 +11,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 +86,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

@@ -43,6 +43,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})`;