bunsql-native-migrate 0.1.2 → 0.3.0

package/src/core/driver.ts

@@ -12,10 +12,21 @@ export interface MigrationDriver {
   setChecksum(migration: string, checksum: string): Promise<void>;
   remove(migration: string): Promise<void>;
   transaction<T>(run: (tx: SQL) => Promise<T>): Promise<T>;
+  trackingTableExists?(): Promise<boolean>;
+  tryLock?(timeoutSeconds: number): Promise<boolean>;
+  releaseLock?(): Promise<void>;
   close(): Promise<void>;
 }
 
-export async function createDriver(databaseUrl: string): Promise<MigrationDriver> {
+export interface DriverTableOptions {
+  tableName?: string;
+  schema?: string;
+}
+
+export async function createDriver(
+  databaseUrl: string,
+  options: DriverTableOptions = {},
+): Promise<MigrationDriver> {
   let protocol: string;
   try {
     protocol = new URL(databaseUrl).protocol.replace(":", "");
@@ -26,20 +37,25 @@ export async function createDriver(databaseUrl: string): Promise<MigrationDriver
       throw new Error(`Cannot parse database URL: ${databaseUrl}`);
     }
   }
+  if (options.schema !== undefined && protocol !== "postgres" && protocol !== "postgresql") {
+    throw new Error(
+      "The schema option is only supported for postgres URLs — MySQL/MariaDB selects the database in the URL, SQLite has no schemas",
+    );
+  }
   switch (protocol) {
     case "postgres":
     case "postgresql": {
       const mod = await import("./../drivers/postgres.js");
-      return mod.create(databaseUrl);
+      return mod.create(databaseUrl, options);
     }
     case "sqlite": {
       const mod = await import("./../drivers/sqlite.js");
-      return mod.create(databaseUrl);
+      return mod.create(databaseUrl, options);
     }
     case "mariadb":
     case "mysql": {
       const mod = await import("./../drivers/mariadb.js");
-      return mod.create(databaseUrl);
+      return mod.create(databaseUrl, options);
     }
     default:
       throw new Error(

package/src/core/duration.ts

@@ -0,0 +1,7 @@
+export function formatDuration(durationMs: number): string {
+  const roundedMs = Math.round(durationMs);
+  if (roundedMs < 1000) {
+    return `${roundedMs}ms`;
+  }
+  return `${(durationMs / 1000).toFixed(1)}s`;
+}

package/src/core/fs.ts

@@ -3,11 +3,13 @@ import path from "node:path";
 
 export const DEFAULT_MIGRATIONS_DIR = "migrations";
 
-export async function listFiles(dir: string, ext: string): Promise<string[]> {
+export const MIGRATION_EXTENSIONS = ["js", "ts", "up.sql"] as const;
+
+export async function listFiles(dir: string, extensions: readonly string[]): Promise<string[]> {
   const matchedFiles: string[] = [];
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
-    if (entry.isFile() && entry.name.endsWith(`.${ext}`)) {
+    if (entry.isFile() && extensions.some((ext) => entry.name.endsWith(`.${ext}`))) {
       matchedFiles.push(entry.name);
     }
   }

package/src/core/identifiers.ts

@@ -0,0 +1,32 @@
+export type IdentifierKind = "table" | "schema";
+
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+export class InvalidIdentifierError extends Error {
+  readonly kind: IdentifierKind;
+  readonly value: string;
+
+  constructor(kind: IdentifierKind, value: string, maxLength: number) {
+    super(
+      `Invalid ${kind} name: "${value}" — expected an identifier of letters, digits, underscores and dollar signs ` +
+        `starting with a letter or underscore, at most ${maxLength} characters`,
+    );
+    this.name = "InvalidIdentifierError";
+    this.kind = kind;
+    this.value = value;
+  }
+}
+
+export function validateIdentifier(kind: IdentifierKind, value: string, maxLength: number): void {
+  if (!IDENTIFIER_PATTERN.test(value) || value.length > maxLength) {
+    throw new InvalidIdentifierError(kind, value, maxLength);
+  }
+}
+
+export function doubleQuoted(name: string): string {
+  return `"${name}"`;
+}
+
+export function backtickQuoted(name: string): string {
+  return `\`${name}\``;
+}

package/src/drivers/mariadb.ts

@@ -1,42 +1,88 @@
 import { type SQL } from "bun";
-import type { MigrationDriver } from "../core/driver.js";
-import { createSqlDriver } from "./shared.js";
+import type { DriverTableOptions, MigrationDriver } from "../core/driver.js";
+import { backtickQuoted, validateIdentifier } from "../core/identifiers.js";
+import { createReservedLock, createSqlDriver } from "./shared.js";
 
-async function checksumColumnExists(db: SQL): Promise<boolean> {
+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
     WHERE table_schema = DATABASE()
-      AND table_name = 'migrations'
+      AND table_name = ${tableName}
       AND column_name = 'checksum'`;
   return rows.length > 0;
 }
 
-async function uniqueIndexExists(db: SQL): Promise<boolean> {
+async function uniqueIndexExists(db: SQL, tableName: string): Promise<boolean> {
   const rows = await db`SELECT index_name FROM information_schema.statistics
     WHERE table_schema = DATABASE()
-      AND table_name = 'migrations'
-      AND index_name = 'migrations_migration_unique'`;
+      AND table_name = ${tableName}
+      AND index_name = ${`${tableName}${UNIQUE_INDEX_SUFFIX}`}`;
   return rows.length > 0;
 }
 
-export function create(databaseUrl: string): MigrationDriver {
-  return createSqlDriver(databaseUrl, {
-    async install(db) {
-      await db`CREATE TABLE IF NOT EXISTS migrations (
-        id INTEGER PRIMARY KEY AUTO_INCREMENT,
-        migration VARCHAR(255) NOT NULL,
-        checksum VARCHAR(64),
-        CONSTRAINT migrations_migration_unique UNIQUE (migration)
-      )`;
-      if (!(await checksumColumnExists(db))) {
-        await db`ALTER TABLE migrations ADD COLUMN checksum VARCHAR(64)`;
-      }
-      if (!(await uniqueIndexExists(db))) {
-        await db`CREATE UNIQUE INDEX migrations_migration_unique ON migrations (migration)`;
-      }
-    },
-    async record(db, migration, checksum) {
-      await db`INSERT IGNORE INTO migrations (migration, checksum)
-        VALUES (${migration}, ${checksum})`;
+export function create(databaseUrl: string, options: DriverTableOptions = {}): MigrationDriver {
+  const { table, index, name } = resolveTableRef(options);
+  return createSqlDriver(
+    databaseUrl,
+    {
+      async install(db) {
+        await db`CREATE TABLE IF NOT EXISTS ${db.unsafe(table)} (
+          id INTEGER PRIMARY KEY AUTO_INCREMENT,
+          migration VARCHAR(255) NOT NULL,
+          checksum VARCHAR(64),
+          CONSTRAINT ${db.unsafe(index)} UNIQUE (migration)
+        )`;
+        if (!(await checksumColumnExists(db, name))) {
+          await db`ALTER TABLE ${db.unsafe(table)} ADD COLUMN checksum VARCHAR(64)`;
+        }
+        if (!(await uniqueIndexExists(db, name))) {
+          await db`CREATE UNIQUE INDEX ${db.unsafe(index)} ON ${db.unsafe(table)} (migration)`;
+        }
+      },
+      async trackingTableExists(db) {
+        const rows = await db`SELECT 1 FROM information_schema.tables
+          WHERE table_schema = DATABASE()
+            AND table_name = ${name}`;
+        return rows.length > 0;
+      },
+      async record(db, migration, checksum) {
+        await db`INSERT IGNORE INTO ${db.unsafe(table)} (migration, checksum)
+          VALUES (${migration}, ${checksum})`;
+      },
+      createLock: (db) =>
+        createReservedLock(
+          db,
+          async (lock) => {
+            const rows =
+              (await lock`SELECT GET_LOCK(CONCAT(${LOCK_NAME_PREFIX}, MD5(DATABASE())), 0) AS locked`) as Array<{
+                locked: number | string | null;
+              }>;
+            const locked = rows[0]?.locked;
+            return locked === 1 || locked === "1";
+          },
+          async (lock) => {
+            await lock`SELECT RELEASE_LOCK(CONCAT(${LOCK_NAME_PREFIX}, MD5(DATABASE())))`;
+          },
+        ),
     },
-  });
+    table,
+  );
 }

package/src/drivers/postgres.ts

@@ -1,21 +1,86 @@
-import type { MigrationDriver } from "../core/driver.js";
-import { createSqlDriver } from "./shared.js";
+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";
 
-export function create(databaseUrl: string): MigrationDriver {
-  return createSqlDriver(databaseUrl, {
-    async install(db) {
-      await db`CREATE TABLE IF NOT EXISTS migrations (
-        id SERIAL PRIMARY KEY,
-        migration VARCHAR(255) NOT NULL,
-        checksum VARCHAR(64)
-      )`;
-      await db`ALTER TABLE migrations ADD COLUMN IF NOT EXISTS checksum VARCHAR(64)`;
-      await db`CREATE UNIQUE INDEX IF NOT EXISTS migrations_migration_unique ON migrations (migration)`;
-    },
-    async record(db, migration, checksum) {
-      await db`INSERT INTO migrations (migration, checksum)
-        VALUES (${migration}, ${checksum})
-        ON CONFLICT (migration) DO NOTHING`;
+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;
+  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}`);
+  if (options.schema === undefined) {
+    return { table: doubleQuoted(tableName), index, name: tableName };
+  }
+  validateIdentifier("schema", options.schema, IDENTIFIER_MAX_LENGTH);
+  return {
+    table: `${doubleQuoted(options.schema)}.${doubleQuoted(tableName)}`,
+    index,
+    name: tableName,
+    schemaName: options.schema,
+  };
+}
+
+async function advisoryKeyComponents(lock: SQL): Promise<[number, number]> {
+  const rows = (await lock`SELECT current_database() AS name`) as Array<{ name: string }>;
+  const hash = Bun.hash.wyhash(`${LOCK_SCOPE}:${rows[0]?.name ?? ""}`);
+  return [Number((hash >> 32n) & 0x7fffffffn), Number(hash & 0x7fffffffn)];
+}
+
+export function create(databaseUrl: string, options: DriverTableOptions = {}): MigrationDriver {
+  const { table, index, name, schemaName } = resolveTableRef(options);
+  return createSqlDriver(
+    databaseUrl,
+    {
+      async install(db) {
+        await db`CREATE TABLE IF NOT EXISTS ${db.unsafe(table)} (
+          id SERIAL PRIMARY KEY,
+          migration VARCHAR(255) NOT NULL,
+          checksum VARCHAR(64)
+        )`;
+        await db`ALTER TABLE ${db.unsafe(table)} ADD COLUMN IF NOT EXISTS checksum VARCHAR(64)`;
+        await db`CREATE UNIQUE INDEX IF NOT EXISTS ${db.unsafe(index)} ON ${db.unsafe(table)} (migration)`;
+      },
+      async trackingTableExists(db) {
+        const rows = schemaName
+          ? await db`SELECT 1 FROM information_schema.tables
+              WHERE table_schema = ${schemaName} AND table_name = ${name}`
+          : await db`SELECT 1 FROM information_schema.tables
+              WHERE table_schema = current_schema() AND table_name = ${name}`;
+        return rows.length > 0;
+      },
+      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(
+          db,
+          async (lock) => {
+            const [first, second] = await advisoryKeyComponents(lock);
+            const rows =
+              (await lock`SELECT pg_try_advisory_lock(${first}, ${second}) AS locked`) as Array<{
+                locked: boolean;
+              }>;
+            return rows[0]?.locked === true;
+          },
+          async (lock) => {
+            const [first, second] = await advisoryKeyComponents(lock);
+            await lock`SELECT pg_advisory_unlock(${first}, ${second})`;
+          },
+        ),
     },
-  });
+    table,
+  );
 }

package/src/drivers/shared.ts

@@ -1,18 +1,72 @@
-import { SQL } from "bun";
+import { SQL, type ReservedSQL } from "bun";
 import type { ExecutedMigration, MigrationDriver } from "../core/driver.js";
 
+export interface SqlLock {
+  tryLock(timeoutSeconds: number): Promise<boolean>;
+  releaseLock(): Promise<void>;
+  dispose(): void;
+}
+
 export interface SqlDialect {
   install(db: SQL): Promise<void>;
   record(db: SQL, migration: string, checksum: string): Promise<void>;
+  trackingTableExists?(db: SQL): Promise<boolean>;
+  createLock?(db: SQL): SqlLock;
+}
+
+export function createReservedLock(
+  db: SQL,
+  acquire: (lock: SQL) => Promise<boolean>,
+  release: (lock: SQL) => Promise<void>,
+): SqlLock {
+  let lockConnection: ReservedSQL | null = null;
+
+  return {
+    async tryLock() {
+      const connection = await db.reserve();
+      lockConnection = connection;
+      try {
+        const acquired = await acquire(connection);
+        if (!acquired) {
+          connection.release();
+          lockConnection = null;
+        }
+        return acquired;
+      } catch (error) {
+        connection.release();
+        lockConnection = null;
+        throw error;
+      }
+    },
+    async releaseLock() {
+      const connection = lockConnection;
+      if (!connection) return;
+      lockConnection = null;
+      try {
+        await release(connection);
+      } finally {
+        connection.release();
+      }
+    },
+    dispose() {
+      lockConnection?.release();
+      lockConnection = null;
+    },
+  };
 }
 
-export function createSqlDriver(databaseUrl: string, dialect: SqlDialect): MigrationDriver {
+export function createSqlDriver(
+  databaseUrl: string,
+  dialect: SqlDialect,
+  table: string,
+): MigrationDriver {
   const db = new SQL(databaseUrl);
+  const lock = dialect.createLock?.(db);
 
   return {
     install: () => dialect.install(db),
     async listExecuted() {
-      const rows = await db`SELECT migration, checksum FROM migrations ORDER BY id ASC`;
+      const rows = await db`SELECT migration, checksum FROM ${db.unsafe(table)} ORDER BY id ASC`;
       return rows.map(
         (r: { migration: string; checksum: string | null }): ExecutedMigration => ({
           name: r.migration,
@@ -22,13 +76,23 @@ export function createSqlDriver(databaseUrl: string, dialect: SqlDialect): Migra
     },
     record: (migration, checksum) => dialect.record(db, migration, checksum),
     async setChecksum(migration, checksum) {
-      await db`UPDATE migrations SET checksum = ${checksum} WHERE migration = ${migration}`;
+      await db`UPDATE ${db.unsafe(table)} SET checksum = ${checksum} WHERE migration = ${migration}`;
     },
     async remove(migration) {
-      await db`DELETE FROM migrations WHERE migration = ${migration}`;
+      await db`DELETE FROM ${db.unsafe(table)} WHERE migration = ${migration}`;
     },
     transaction: (run) => db.begin(run),
+    ...(dialect.trackingTableExists
+      ? { trackingTableExists: () => dialect.trackingTableExists!(db) }
+      : {}),
+    ...(lock
+      ? {
+          tryLock: (timeoutSeconds: number) => lock.tryLock(timeoutSeconds),
+          releaseLock: () => lock.releaseLock(),
+        }
+      : {}),
     async close() {
+      lock?.dispose();
       db.close({ timeout: 0 });
     },
   };

package/src/drivers/sqlite.ts

@@ -1,26 +1,63 @@
-import type { MigrationDriver } from "../core/driver.js";
+import type { DriverTableOptions, MigrationDriver } from "../core/driver.js";
+import { doubleQuoted, validateIdentifier } from "../core/identifiers.js";
 import { createSqlDriver } from "./shared.js";
 
-export function create(databaseUrl: string): MigrationDriver {
-  return createSqlDriver(databaseUrl, {
-    async install(db) {
-      await db`CREATE TABLE IF NOT EXISTS migrations (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        migration TEXT NOT NULL,
-        checksum TEXT
-      )`;
-      const columns = (await db`PRAGMA table_info(migrations)`) as Array<{
-        name: string;
-      }>;
-      const hasChecksum = columns.some((column) => column.name === "checksum");
-      if (!hasChecksum) {
-        await db`ALTER TABLE migrations ADD COLUMN checksum TEXT`;
-      }
-      await db`CREATE UNIQUE INDEX IF NOT EXISTS migrations_migration_unique ON migrations (migration)`;
-    },
-    async record(db, migration, checksum) {
-      await db`INSERT OR IGNORE INTO migrations (migration, checksum)
-        VALUES (${migration}, ${checksum})`;
+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);
+  return createSqlDriver(
+    databaseUrl,
+    {
+      async install(db) {
+        await db`CREATE TABLE IF NOT EXISTS ${db.unsafe(table)} (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          migration TEXT NOT NULL,
+          checksum TEXT
+        )`;
+        const columns = (await db.unsafe(`PRAGMA table_info(${table})`)) as Array<{
+          name: string;
+        }>;
+        const hasChecksum = columns.some((column) => column.name === "checksum");
+        if (!hasChecksum) {
+          await db`ALTER TABLE ${db.unsafe(table)} ADD COLUMN checksum TEXT`;
+        }
+        await db`CREATE UNIQUE INDEX IF NOT EXISTS ${db.unsafe(index)} ON ${db.unsafe(table)} (migration)`;
+      },
+      async trackingTableExists(db) {
+        const rows = await db`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ${name}`;
+        return rows.length > 0;
+      },
+      async record(db, migration, checksum) {
+        await db`INSERT OR IGNORE INTO ${db.unsafe(table)} (migration, checksum)
+          VALUES (${migration}, ${checksum})`;
+      },
+      createLock: (db) => ({
+        async tryLock(timeoutSeconds: number) {
+          await db.unsafe(`PRAGMA busy_timeout = ${timeoutSeconds * 1000}`);
+          return true;
+        },
+        async releaseLock() {
+          await db.unsafe("PRAGMA busy_timeout = 0");
+        },
+        dispose() {},
+      }),
     },
-  });
+    table,
+  );
 }

package/src/index.ts

@@ -1,29 +1,55 @@
-import { createDriver, type ExecutedMigration, type MigrationDriver } from "./core/driver.js";
+import {
+  createDriver,
+  type DriverTableOptions,
+  type ExecutedMigration,
+  type MigrationDriver,
+} from "./core/driver.js";
+import { InvalidIdentifierError } from "./core/identifiers.js";
 import { migrateUp } from "./api/up.js";
 import { migrateDown } from "./api/down.js";
+import { migrateStatus } from "./api/status.js";
 import { installMigrations } from "./api/install.js";
 import { createMigration } from "./api/create.js";
+import { markMigrationsApplied } from "./api/mark.js";
 import {
+  type MigrateDownOptions,
   type MigrateDownResult,
+  type MarkOptions,
+  type MarkResult,
   type MigrateOptions,
+  type MigrateStatusResult,
+  type MigrateUpOptions,
   type MigrateUpResult,
   ChecksumDriftError,
   GitStageError,
+  MigrationLockError,
+  MigrationNotFoundError,
 } from "./api/options.js";
 
 export {
   createDriver,
   migrateUp,
   migrateDown,
+  migrateStatus,
   installMigrations,
   createMigration,
+  markMigrationsApplied,
   ChecksumDriftError,
   GitStageError,
+  InvalidIdentifierError,
+  MigrationLockError,
+  MigrationNotFoundError,
 };
 export type {
+  DriverTableOptions,
   ExecutedMigration,
   MigrationDriver,
   MigrateOptions,
+  MigrateUpOptions,
   MigrateUpResult,
+  MigrateDownOptions,
   MigrateDownResult,
+  MarkOptions,
+  MarkResult,
+  MigrateStatusResult,
 };