@chidchanun/bcp 0.1.13 → 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/docs/database.md

@@ -0,0 +1,127 @@
+# Database
+
+BCP `0.1.14` adds the first framework-native database API through the server-only `bcp/database` entrypoint.
+
+The initial adapter targets MySQL. Additional adapters can be added in later releases without changing the page, loader, guard or action APIs that consume the database layer.
+
+## Create an app with MySQL
+
+```bash
+npx create-bcp-app my-app
+```
+
+Choose **MySQL** during interactive setup. The generated project installs `mysql2`, writes the database environment variables and creates `lib/database.ts` as a thin wrapper around `bcp/database`.
+
+## Environment
+
+```env
+DB_DRIVER=mysql
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=
+DB_NAME=bcp_app
+DB_CONNECTION_LIMIT=10
+DB_WAIT_FOR_CONNECTIONS=1
+DB_QUEUE_LIMIT=0
+DB_CHARSET=utf8mb4
+```
+
+Only `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME` are required for the standard generated preset. The remaining values have safe framework defaults.
+
+## Query
+
+```ts
+import {
+    db,
+} from "bcp/database";
+
+interface UserRow {
+    id: number;
+    email: string;
+}
+
+const users =
+    await db.query<UserRow[]>(
+        "SELECT id, email FROM users WHERE active = ?",
+        [
+            1,
+        ]
+    );
+```
+
+## Execute
+
+```ts
+const result =
+    await db.execute(
+        "INSERT INTO users (email) VALUES (?)",
+        [
+            "user@example.com",
+        ]
+    );
+```
+
+Use placeholders and parameter arrays instead of concatenating untrusted values into SQL strings.
+
+## Transaction
+
+```ts
+await db.transaction(
+    async (transaction) => {
+        await transaction.execute(
+            "UPDATE accounts SET balance = balance - ? WHERE id = ?",
+            [
+                100,
+                1,
+            ]
+        );
+
+        await transaction.execute(
+            "UPDATE accounts SET balance = balance + ? WHERE id = ?",
+            [
+                100,
+                2,
+            ]
+        );
+    }
+);
+```
+
+BCP commits the transaction when the callback resolves and rolls it back when the callback throws.
+
+## Custom database instance
+
+```ts
+import {
+    createDatabase,
+} from "bcp/database";
+
+export const reportingDb =
+    createDatabase({
+        host:
+            "reporting-db.internal",
+        database:
+            "analytics",
+        connectionLimit:
+            5,
+    });
+```
+
+Explicit options override environment values for that database instance.
+
+## Lifecycle
+
+Connections are lazy. Importing `bcp/database` does not open a MySQL connection. The pool is created on the first `query`, `execute` or `transaction` call.
+
+For custom shutdown handling, close the pool with:
+
+```ts
+await db.close();
+```
+
+## Server-only boundary
+
+`bcp/database` is a server-only package export. Importing it into a browser bundle is blocked by the framework's browser export boundary.
+
+The MySQL adapter loads `mysql2/promise` only when a connection is first needed. Projects that do not use MySQL do not need to install the driver.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.13",
+  "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",
@@ -43,6 +43,11 @@
       "types": "./packages/client/src/config.ts",
       "default": "./packages/client/src/config.ts"
     },
+    "./database": {
+      "types": "./packages/client/src/database.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/database.ts"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

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,
+        }
+      : {}),
   };
 }