@chidchanun/bcp 0.1.13 → 0.1.15

package/packages/cli/src/database-migrations.ts

@@ -0,0 +1,708 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    pathToFileURL,
+} from "node:url";
+
+import type {
+    TransactionDatabase,
+} from "../../client/src/database.js";
+
+export type DatabaseMigrationAction =
+    | "migrate"
+    | "status"
+    | "rollback"
+    | "create";
+
+export interface MigrationDatabase {
+    query<T = unknown>(
+        sql: string,
+        parameters?: readonly unknown[] | Record<string, unknown>
+    ): Promise<T>;
+    execute<T = unknown>(
+        sql: string,
+        parameters?: readonly unknown[] | Record<string, unknown>
+    ): Promise<T>;
+    transaction<T>(
+        callback: (
+            database: TransactionDatabase
+        ) => Promise<T>
+    ): Promise<T>;
+}
+
+export interface DatabaseMigrationCommandOptions {
+    rootDirectory: string;
+    action: DatabaseMigrationAction;
+    name?: string;
+    database?: MigrationDatabase;
+    now?: Date;
+}
+
+export interface MigrationStatus {
+    name: string;
+    status: "applied" | "pending";
+    batch: number | null;
+    appliedAt: string | Date | null;
+}
+
+interface MigrationRecord {
+    name: string;
+    batch: number;
+    applied_at: string | Date;
+}
+
+interface LoadedMigration {
+    name: string;
+    filePath: string;
+}
+
+interface MigrationModule {
+    up?: (
+        database: TransactionDatabase
+    ) => Promise<void> | void;
+    down?: (
+        database: TransactionDatabase
+    ) => Promise<void> | void;
+}
+
+const MIGRATION_DIRECTORY =
+    "migrations";
+const MIGRATION_TABLE =
+    "_bcp_migrations";
+const MIGRATION_FILE_PATTERN =
+    /^\d{14}_[a-z0-9][a-z0-9_-]*\.(?:ts|mts|js|mjs)$/;
+
+export async function runDatabaseMigrationCommand(
+    options: DatabaseMigrationCommandOptions
+): Promise<void> {
+    const rootDirectory =
+        path.resolve(
+            options.rootDirectory
+        );
+
+    if (
+        options.action === "create"
+    ) {
+        const file =
+            createMigrationFile(
+                rootDirectory,
+                options.name,
+                options.now
+            );
+
+        console.log(
+            `[BCP DB] Created migration: ${path.relative(rootDirectory, file)}`
+        );
+        return;
+    }
+
+    const database =
+        options.database;
+
+    if (!database) {
+        throw new Error(
+            "BCP DB: a database connection is required for this command."
+        );
+    }
+
+    await ensureMigrationTable(
+        database
+    );
+
+    if (
+        options.action === "status"
+    ) {
+        const statuses =
+            await getMigrationStatus(
+                rootDirectory,
+                database
+            );
+
+        printMigrationStatus(
+            statuses
+        );
+        return;
+    }
+
+    if (
+        options.action === "migrate"
+    ) {
+        await migratePending(
+            rootDirectory,
+            database
+        );
+        return;
+    }
+
+    await rollbackLatestBatch(
+        rootDirectory,
+        database
+    );
+}
+
+export function createMigrationFile(
+    rootDirectory: string,
+    name: string | undefined,
+    now = new Date()
+): string {
+    const slug =
+        normalizeMigrationName(
+            name
+        );
+    const directory =
+        path.join(
+            rootDirectory,
+            MIGRATION_DIRECTORY
+        );
+
+    fs.mkdirSync(
+        directory,
+        {
+            recursive: true,
+        }
+    );
+
+    const timestamp =
+        formatMigrationTimestamp(
+            now
+        );
+    let suffix = 1;
+    let fileName =
+        `${timestamp}_${slug}.ts`;
+    let filePath =
+        path.join(
+            directory,
+            fileName
+        );
+
+    while (
+        fs.existsSync(
+            filePath
+        )
+    ) {
+        suffix++;
+        fileName =
+            `${timestamp}_${slug}_${suffix}.ts`;
+        filePath =
+            path.join(
+                directory,
+                fileName
+            );
+    }
+
+    const source =
+        `import type {\n` +
+        `    TransactionDatabase,\n` +
+        `} from "bcp/database";\n\n` +
+        `export async function up(\n` +
+        `    db: TransactionDatabase\n` +
+        `): Promise<void> {\n` +
+        `    // Write the forward migration here.\n` +
+        `    void db;\n` +
+        `}\n\n` +
+        `export async function down(\n` +
+        `    db: TransactionDatabase\n` +
+        `): Promise<void> {\n` +
+        `    // Write the rollback migration here.\n` +
+        `    void db;\n` +
+        `}\n`;
+
+    fs.writeFileSync(
+        filePath,
+        source,
+        {
+            encoding: "utf8",
+            flag: "wx",
+        }
+    );
+
+    return filePath;
+}
+
+export function listMigrationFiles(
+    rootDirectory: string
+): LoadedMigration[] {
+    const directory =
+        path.join(
+            rootDirectory,
+            MIGRATION_DIRECTORY
+        );
+
+    if (
+        !fs.existsSync(
+            directory
+        )
+    ) {
+        return [];
+    }
+
+    return fs.readdirSync(
+        directory,
+        {
+            withFileTypes: true,
+        }
+    )
+        .filter(
+            (entry) =>
+                entry.isFile() &&
+                /\.(?:ts|mts|js|mjs)$/.test(
+                    entry.name
+                )
+        )
+        .map(
+            (entry) => {
+                if (
+                    !MIGRATION_FILE_PATTERN.test(
+                        entry.name
+                    )
+                ) {
+                    throw new Error(
+                        `BCP DB: invalid migration filename "${entry.name}". Use \`bcp db create <name>\` to create ordered migrations.`
+                    );
+                }
+
+                return {
+                    name:
+                        entry.name,
+                    filePath:
+                        path.join(
+                            directory,
+                            entry.name
+                        ),
+                };
+            }
+        )
+        .sort(
+            (left, right) =>
+                left.name.localeCompare(
+                    right.name
+                )
+        );
+}
+
+export async function getMigrationStatus(
+    rootDirectory: string,
+    database: MigrationDatabase
+): Promise<MigrationStatus[]> {
+    const files =
+        listMigrationFiles(
+            rootDirectory
+        );
+    const applied =
+        await readAppliedMigrations(
+            database
+        );
+    const appliedByName =
+        new Map(
+            applied.map(
+                (record) => [
+                    record.name,
+                    record,
+                ]
+            )
+        );
+    const statuses:
+        MigrationStatus[] =
+        files.map(
+            (migration) => {
+                const record =
+                    appliedByName.get(
+                        migration.name
+                    );
+
+                return record
+                    ? {
+                        name:
+                            migration.name,
+                        status:
+                            "applied",
+                        batch:
+                            record.batch,
+                        appliedAt:
+                            record.applied_at,
+                    }
+                    : {
+                        name:
+                            migration.name,
+                        status:
+                            "pending",
+                        batch:
+                            null,
+                        appliedAt:
+                            null,
+                    };
+            }
+        );
+
+    for (
+        const record
+        of applied
+    ) {
+        if (
+            !files.some(
+                (file) =>
+                    file.name ===
+                    record.name
+            )
+        ) {
+            statuses.push({
+                name:
+                    record.name,
+                status:
+                    "applied",
+                batch:
+                    record.batch,
+                appliedAt:
+                    record.applied_at,
+            });
+        }
+    }
+
+    return statuses;
+}
+
+async function migratePending(
+    rootDirectory: string,
+    database: MigrationDatabase
+): Promise<void> {
+    const files =
+        listMigrationFiles(
+            rootDirectory
+        );
+    const applied =
+        await readAppliedMigrations(
+            database
+        );
+    const appliedNames =
+        new Set(
+            applied.map(
+                (record) =>
+                    record.name
+            )
+        );
+    const pending =
+        files.filter(
+            (migration) =>
+                !appliedNames.has(
+                    migration.name
+                )
+        );
+
+    if (
+        pending.length === 0
+    ) {
+        console.log(
+            "[BCP DB] No pending migrations."
+        );
+        return;
+    }
+
+    const batch =
+        applied.reduce(
+            (
+                maximum,
+                record
+            ) =>
+                Math.max(
+                    maximum,
+                    record.batch
+                ),
+            0
+        ) + 1;
+
+    for (
+        const migration
+        of pending
+    ) {
+        const module =
+            await loadMigrationModule(
+                migration
+            );
+
+        await database.transaction(
+            async (transaction) => {
+                await module.up?.(
+                    transaction
+                );
+                await transaction.execute(
+                    `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES (?, ?)`,
+                    [
+                        migration.name,
+                        batch,
+                    ]
+                );
+            }
+        );
+
+        console.log(
+            `[BCP DB] Migrated: ${migration.name} (batch ${batch})`
+        );
+    }
+}
+
+async function rollbackLatestBatch(
+    rootDirectory: string,
+    database: MigrationDatabase
+): Promise<void> {
+    const applied =
+        await readAppliedMigrations(
+            database
+        );
+
+    if (
+        applied.length === 0
+    ) {
+        console.log(
+            "[BCP DB] Nothing to rollback."
+        );
+        return;
+    }
+
+    const latestBatch =
+        applied.reduce(
+            (
+                maximum,
+                record
+            ) =>
+                Math.max(
+                    maximum,
+                    record.batch
+                ),
+            0
+        );
+    const files =
+        new Map(
+            listMigrationFiles(
+                rootDirectory
+            ).map(
+                (migration) => [
+                    migration.name,
+                    migration,
+                ]
+            )
+        );
+    const rollbackRecords =
+        applied
+            .filter(
+                (record) =>
+                    record.batch ===
+                    latestBatch
+            )
+            .reverse();
+
+    for (
+        const record
+        of rollbackRecords
+    ) {
+        if (
+            !files.has(
+                record.name
+            )
+        ) {
+            throw new Error(
+                `BCP DB: cannot rollback ${record.name}; the migration file is missing.`
+            );
+        }
+    }
+
+    for (
+        const record
+        of rollbackRecords
+    ) {
+        const migration =
+            files.get(
+                record.name
+            )!;
+        const module =
+            await loadMigrationModule(
+                migration
+            );
+
+        await database.transaction(
+            async (transaction) => {
+                await module.down?.(
+                    transaction
+                );
+                await transaction.execute(
+                    `DELETE FROM ${MIGRATION_TABLE} WHERE name = ?`,
+                    [
+                        record.name,
+                    ]
+                );
+            }
+        );
+
+        console.log(
+            `[BCP DB] Rolled back: ${record.name} (batch ${latestBatch})`
+        );
+    }
+}
+
+async function ensureMigrationTable(
+    database: MigrationDatabase
+): Promise<void> {
+    await database.execute(
+        `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (` +
+        `id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, ` +
+        `name VARCHAR(255) NOT NULL UNIQUE, ` +
+        `batch INT UNSIGNED NOT NULL, ` +
+        `applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP` +
+        `) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`
+    );
+}
+
+async function readAppliedMigrations(
+    database: MigrationDatabase
+): Promise<MigrationRecord[]> {
+    return database.query<
+        MigrationRecord[]
+    >(
+        `SELECT name, batch, applied_at FROM ${MIGRATION_TABLE} ORDER BY id ASC`
+    );
+}
+
+async function loadMigrationModule(
+    migration: LoadedMigration
+): Promise<Required<MigrationModule>> {
+    const url =
+        pathToFileURL(
+            migration.filePath
+        );
+
+    url.searchParams.set(
+        "bcp-migration",
+        `${Date.now()}-${Math.random()}`
+    );
+
+    const module =
+        await import(
+            url.href
+        ) as MigrationModule;
+
+    if (
+        typeof module.up !==
+        "function" ||
+        typeof module.down !==
+        "function"
+    ) {
+        throw new Error(
+            `BCP DB: migration ${migration.name} must export async up(db) and down(db) functions.`
+        );
+    }
+
+    return {
+        up:
+            module.up,
+        down:
+            module.down,
+    };
+}
+
+function normalizeMigrationName(
+    value: string | undefined
+): string {
+    const normalized =
+        String(
+            value ?? ""
+        )
+            .trim()
+            .toLowerCase()
+            .replace(
+                /[^a-z0-9]+/g,
+                "_"
+            )
+            .replace(
+                /^_+|_+$/g,
+                ""
+            );
+
+    if (!normalized) {
+        throw new Error(
+            "BCP DB: migration name is required. Example: bcp db create create_users"
+        );
+    }
+
+    return normalized;
+}
+
+function formatMigrationTimestamp(
+    value: Date
+): string {
+    if (
+        Number.isNaN(
+            value.getTime()
+        )
+    ) {
+        throw new Error(
+            "BCP DB: invalid migration timestamp."
+        );
+    }
+
+    return [
+        value.getUTCFullYear(),
+        value.getUTCMonth() + 1,
+        value.getUTCDate(),
+        value.getUTCHours(),
+        value.getUTCMinutes(),
+        value.getUTCSeconds(),
+    ]
+        .map(
+            (
+                part,
+                index
+            ) =>
+                index === 0
+                    ? String(part)
+                        .padStart(
+                            4,
+                            "0"
+                        )
+                    : String(part)
+                        .padStart(
+                            2,
+                            "0"
+                        )
+        )
+        .join("");
+}
+
+function printMigrationStatus(
+    statuses: MigrationStatus[]
+): void {
+    console.log("");
+    console.log(
+        "BCP Database Migrations"
+    );
+    console.log("");
+
+    if (
+        statuses.length === 0
+    ) {
+        console.log(
+            "  (no migrations)"
+        );
+        console.log("");
+        return;
+    }
+
+    for (
+        const migration
+        of statuses
+    ) {
+        const marker =
+            migration.status ===
+            "applied"
+                ? "✓"
+                : "○";
+        const batch =
+            migration.batch === null
+                ? "pending"
+                : `batch ${migration.batch}`;
+
+        console.log(
+            `  ${marker} ${migration.name} — ${batch}`
+        );
+    }
+
+    console.log("");
+}