@chidchanun/bcp 0.1.14 → 0.1.15

package/docs/database-migrations.md

@@ -0,0 +1,105 @@
+# Database Migrations
+
+BCP Framework `0.1.15` adds MySQL migration commands to the `bcp` CLI.
+
+## Requirements
+
+Database migrations currently use the MySQL adapter from `bcp/database`.
+
+Configure the same environment variables used by your application:
+
+```env
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=
+DB_NAME=bcp_app
+```
+
+A project using migrations must have `mysql2` installed. Applications created with the MySQL preset already include it.
+
+## Create a migration
+
+```bash
+bcp db create create_users
+```
+
+BCP creates an ordered TypeScript file in `migrations/`:
+
+```text
+migrations/
+  20260827040506_create_users.ts
+```
+
+A generated migration exports `up()` and `down()`:
+
+```ts
+import type {
+    TransactionDatabase,
+} from "bcp/database";
+
+export async function up(
+    db: TransactionDatabase
+): Promise<void> {
+    await db.execute(`
+        CREATE TABLE users (
+            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+            email VARCHAR(255) NOT NULL UNIQUE
+        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+    `);
+}
+
+export async function down(
+    db: TransactionDatabase
+): Promise<void> {
+    await db.execute(
+        "DROP TABLE users"
+    );
+}
+```
+
+Migration filenames use a UTC timestamp prefix so migrations have a stable execution order.
+
+## Run pending migrations
+
+```bash
+bcp db migrate
+```
+
+BCP creates the internal `_bcp_migrations` table when needed, detects files that have not been applied, and runs all pending migrations in filename order.
+
+All migrations applied by one `bcp db migrate` command share the same batch number. Each individual migration runs inside its own database transaction. The migration record is inserted in the same transaction as `up()`.
+
+## Check status
+
+```bash
+bcp db status
+```
+
+The command reports applied and pending migration files together with the batch number for applied migrations.
+
+## Roll back
+
+```bash
+bcp db rollback
+```
+
+Rollback reverses only the latest migration batch. Migrations in that batch run from newest to oldest, and each `down()` runs in a transaction together with removal of its migration record.
+
+BCP refuses to roll back an applied migration when its migration file is missing.
+
+## Project root
+
+All database commands support the normal BCP project-root option:
+
+```bash
+bcp db status --root ./apps/admin
+```
+
+## Environment files
+
+Database commands load the BCP development environment files before connecting, so the same local database settings used by `bcp dev` can be reused by migration commands.
+
+## Current scope
+
+`0.1.15` migration execution supports MySQL. PostgreSQL, SQLite and MongoDB presets remain available to `create-bcp-app`, but framework-managed migrations for those adapters are planned for later releases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",

package/packages/cli/src/args.ts

@@ -7,9 +7,17 @@ export type CliCommand =
   | "start"
   | "routes"
   | "update"
+  | "db"
   | "help"
   | "version";
 
+export type DatabaseCliAction =
+  | "migrate"
+  | "status"
+  | "rollback"
+  | "create"
+  | "help";
+
 export interface CliOptions {
   command: CliCommand;
 
@@ -24,6 +32,10 @@ export interface CliOptions {
   updateCheck?: boolean;
 
   updateDryRun?: boolean;
+
+  dbAction?: DatabaseCliAction;
+
+  dbMigrationName?: string;
 }
 
 export function parseCliArgs(
@@ -49,6 +61,12 @@ export function parseCliArgs(
   let updateDryRun =
     false;
 
+  let dbAction:
+    DatabaseCliAction | undefined;
+
+  let dbMigrationName:
+    string | undefined;
+
   let commandSet = false;
 
   for (
@@ -62,7 +80,14 @@ export function parseCliArgs(
       argument === "-h" ||
       argument === "--help"
     ) {
-      command = "help";
+      if (
+        commandSet &&
+        command === "db"
+      ) {
+        dbAction = "help";
+      } else {
+        command = "help";
+      }
       continue;
     }
 
@@ -221,6 +246,44 @@ export function parseCliArgs(
       continue;
     }
 
+    if (
+      commandSet &&
+      command === "db"
+    ) {
+      if (
+        dbAction === undefined
+      ) {
+        if (
+          argument === "migrate" ||
+          argument === "status" ||
+          argument === "rollback" ||
+          argument === "create" ||
+          argument === "help"
+        ) {
+          dbAction =
+            argument;
+          continue;
+        }
+
+        throw new Error(
+          `Unknown database command: ${argument}`
+        );
+      }
+
+      if (
+        dbAction === "create" &&
+        dbMigrationName === undefined
+      ) {
+        dbMigrationName =
+          argument;
+        continue;
+      }
+
+      throw new Error(
+        `Unexpected argument: ${argument}`
+      );
+    }
+
     if (commandSet) {
       throw new Error(
         `Unexpected argument: ${argument}`
@@ -233,6 +296,7 @@ export function parseCliArgs(
       argument === "start" ||
       argument === "routes" ||
       argument === "update" ||
+      argument === "db" ||
       argument === "help" ||
       argument === "version"
     ) {
@@ -266,6 +330,12 @@ export function parseCliArgs(
     updateTarget,
     updateCheck,
     updateDryRun,
+    ...(command === "db"
+      ? {
+          dbAction,
+          dbMigrationName,
+        }
+      : {}),
   };
 }
 

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("");
+}

package/packages/cli/src/index.ts

@@ -66,6 +66,11 @@ switch (cliOptions.command) {
     break;
   }
 
+  case "db": {
+    await runDatabaseCommand();
+    break;
+  }
+
   case "help": {
     printHelp();
     break;
@@ -381,6 +386,86 @@ async function runUpdate() {
   });
 }
 
+async function runDatabaseCommand() {
+  const action =
+    cliOptions.dbAction;
+
+  if (
+    action === undefined ||
+    action === "help"
+  ) {
+    printDatabaseHelp();
+    return;
+  }
+
+  const rootDirectory =
+    resolveProjectRoot(
+      cliOptions.rootDirectory
+    );
+
+  process.env.NODE_ENV =
+    process.env.NODE_ENV ??
+    "development";
+
+  const {
+    loadEnvironment,
+  } =
+    await import(
+      "../../env/src/index.js"
+    );
+
+  const environment =
+    loadEnvironment(
+      rootDirectory,
+      "development"
+    );
+
+  if (
+    environment.files.length > 0
+  ) {
+    console.log(
+      `[BCP Env] development: ${environment.files.join(", ")}`
+    );
+  }
+
+  const {
+    runDatabaseMigrationCommand,
+  } =
+    await import(
+      "./database-migrations.js"
+    );
+
+  if (
+    action === "create"
+  ) {
+    await runDatabaseMigrationCommand({
+      rootDirectory,
+      action,
+      name:
+        cliOptions.dbMigrationName,
+    });
+    return;
+  }
+
+  const {
+    db,
+  } =
+    await import(
+      "../../client/src/database.js"
+    );
+
+  try {
+    await runDatabaseMigrationCommand({
+      rootDirectory,
+      action,
+      database:
+        db,
+    });
+  } finally {
+    await db.close();
+  }
+}
+
 function installShutdownHandlers(
   server: {
     stop(): Promise<void>;
@@ -521,6 +606,28 @@ function formatBytes(
   ).toFixed(2)} MiB`;
 }
 
+function printDatabaseHelp() {
+  console.log(`
+BCP Database Migrations
+
+Usage:
+  bcp db <command> [arguments]
+
+Commands:
+  create <name>       Create a timestamped migration in migrations/
+  migrate             Run all pending migrations
+  status              Show applied and pending migrations
+  rollback            Roll back the latest migration batch
+  help                Show database command help
+
+Examples:
+  bcp db create create_users
+  bcp db migrate
+  bcp db status
+  bcp db rollback
+`);
+}
+
 function printHelp() {
   console.log(`
 BCP Framework v${FRAMEWORK_VERSION}
@@ -534,6 +641,7 @@ Commands:
   start              Start the standalone production build
   routes             Print discovered page and API routes
   update [target]    Update BCP Framework (default target: latest)
+  db <command>       Manage database migrations
   help               Show this help message
   version            Show framework version
 
@@ -558,6 +666,9 @@ Examples:
   bcp routes
   bcp update
   bcp update --check
-  bcp update 0.1.10
+  bcp db create create_users
+  bcp db migrate
+  bcp db status
+  bcp db rollback
 `);
 }