@chidchanun/bcp 0.2.2 → 0.2.3

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "releaseState": "unreleased",
-  "baseline": "framework-platform",
+  "baseline": "database-platform-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -46,6 +46,11 @@
     "middlewareV2": true,
     "jwtCookieSessions": true,
     "databaseMigrations": true,
+    "databaseAdapterContract": true,
+    "databasePostgresql": true,
+    "databaseSqlite": true,
+    "databaseLifecycleV2": true,
+    "databaseMigrationProviderConsistency": true,
     "validation": true,
     "structuredErrors": true,
     "logging": true,
@@ -61,6 +66,11 @@
     "configurationDiagnostics": true,
     "configCheckCli": true
   },
+  "databaseProviders": [
+    "mysql",
+    "postgresql",
+    "sqlite"
+  ],
   "storageProviders": [
     "local",
     "amazon-s3",
@@ -68,7 +78,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.1",
+    "previousBaseline": "0.2.2",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -81,6 +91,6 @@
     "apiReference": "api-reference.md",
     "environmentValidation": "environment-validation.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.2.md"
+    "releaseNotes": "releases/0.2.3.md"
   }
 }

package/docs/releases/0.2.3.md

@@ -0,0 +1,77 @@
+# BCP Framework 0.2.3
+
+## Database Platform v2
+
+BCP `0.2.3` turns the framework database layer into a provider-neutral SQL platform while preserving the existing `bcp/database` application API.
+
+### Database adapter contract
+
+- `BcpDatabase` delegates connection, query, execute, transaction and disconnect behavior through `DatabaseAdapter`.
+- Custom adapters can be injected directly or through lazy factories.
+- Provider implementations are separated into MySQL, PostgreSQL and SQLite runtime modules.
+- Provider drivers remain optional dependencies and are loaded lazily.
+
+### PostgreSQL
+
+- Added built-in PostgreSQL support through `pg`.
+- `DATABASE_URL=postgresql://...` selects PostgreSQL automatically.
+- `DB_DRIVER=postgresql`, `postgres` and `pg` are supported provider names.
+- Query parameters use PostgreSQL `$1`, `$2`, ... placeholders.
+- Transactions use dedicated pool clients with `BEGIN`, `COMMIT`, `ROLLBACK` and guaranteed client release.
+
+### SQLite
+
+- Added built-in SQLite support through `better-sqlite3`.
+- Supports file paths, `:memory:`, `sqlite:` and `file:` database locations.
+- Common `.sqlite`, `.sqlite3` and `.db` `DATABASE_URL` values infer SQLite automatically.
+- File-backed databases create missing parent directories before opening the native database.
+- Adapter operations are serialized so async transaction callbacks do not interleave unrelated operations on one SQLite connection.
+
+### Connection lifecycle
+
+- Added explicit `database.connect()`.
+- Added explicit `database.disconnect()`.
+- Existing `database.close()` remains backward compatible and aliases the disconnect lifecycle.
+- Disconnecting resets the facade so a later operation can initialize a fresh provider connection.
+- Failed adapter initialization resets cleanly and can be retried.
+- `close()` is safe after failed adapter initialization.
+
+### Migration consistency
+
+The existing CLI remains unchanged:
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
+Migration bookkeeping now selects its internal SQL dialect from the active database provider:
+
+- MySQL uses `AUTO_INCREMENT` and `?` placeholders.
+- PostgreSQL uses `BIGSERIAL` and `$1`, `$2` placeholders.
+- SQLite uses `INTEGER PRIMARY KEY AUTOINCREMENT` and `?` placeholders.
+
+BCP only makes the internal `_bcp_migrations` bookkeeping provider-aware. Application migration SQL is intentionally not translated between SQL dialects.
+
+### Packaging and validation
+
+- Added Database Platform v2 package smoke coverage.
+- Packed framework validation checks provider modules, bundled optional-driver references, lifecycle APIs and migration dialect support.
+- Added unit coverage for SQLite option resolution, provider inference, lifecycle reconnect behavior, failed adapter initialization and migration dialects.
+
+## Compatibility
+
+`0.2.3` does not intentionally remove public application entrypoints from the `0.2.2` baseline.
+
+Existing MySQL applications can continue using:
+
+```ts
+import {
+    db,
+    createDatabase,
+} from "bcp/database";
+```
+
+without changing their application-facing database calls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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/database-migrations.ts

@@ -4,8 +4,10 @@ import {
     pathToFileURL,
 } from "node:url";
 
-import type {
-    TransactionDatabase,
+import {
+    resolveDatabaseOptions,
+    type DatabaseDriver,
+    type TransactionDatabase,
 } from "../../client/src/database.js";
 
 export type DatabaseMigrationAction =
@@ -35,6 +37,7 @@ export interface DatabaseMigrationCommandOptions {
     action: DatabaseMigrationAction;
     name?: string;
     database?: MigrationDatabase;
+    driver?: DatabaseDriver;
     now?: Date;
 }
 
@@ -65,6 +68,12 @@ interface MigrationModule {
     ) => Promise<void> | void;
 }
 
+interface MigrationDialect {
+    createTableSql: string;
+    insertMigrationSql: string;
+    deleteMigrationSql: string;
+}
+
 const MIGRATION_DIRECTORY =
     "migrations";
 const MIGRATION_TABLE =
@@ -105,8 +114,15 @@ export async function runDatabaseMigrationCommand(
         );
     }
 
+    const dialect =
+        getMigrationDialect(
+            options.driver ??
+            resolveDatabaseOptions().driver
+        );
+
     await ensureMigrationTable(
-        database
+        database,
+        dialect
     );
 
     if (
@@ -129,14 +145,16 @@ export async function runDatabaseMigrationCommand(
     ) {
         await migratePending(
             rootDirectory,
-            database
+            database,
+            dialect
         );
         return;
     }
 
     await rollbackLatestBatch(
         rootDirectory,
-        database
+        database,
+        dialect
     );
 }
 
@@ -197,13 +215,13 @@ export function createMigrationFile(
         `export async function up(\n` +
         `    db: TransactionDatabase\n` +
         `): Promise<void> {\n` +
-        `    // Write the forward migration here.\n` +
+        `    // Write provider-compatible forward SQL here.\n` +
         `    void db;\n` +
         `}\n\n` +
         `export async function down(\n` +
         `    db: TransactionDatabase\n` +
         `): Promise<void> {\n` +
-        `    // Write the rollback migration here.\n` +
+        `    // Write provider-compatible rollback SQL here.\n` +
         `    void db;\n` +
         `}\n`;
 
@@ -363,7 +381,8 @@ export async function getMigrationStatus(
 
 async function migratePending(
     rootDirectory: string,
-    database: MigrationDatabase
+    database: MigrationDatabase,
+    dialect: MigrationDialect
 ): Promise<void> {
     const files =
         listMigrationFiles(
@@ -421,11 +440,11 @@ async function migratePending(
 
         await database.transaction(
             async (transaction) => {
-                await module.up?.(
+                await module.up(
                     transaction
                 );
                 await transaction.execute(
-                    `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES (?, ?)`,
+                    dialect.insertMigrationSql,
                     [
                         migration.name,
                         batch,
@@ -442,7 +461,8 @@ async function migratePending(
 
 async function rollbackLatestBatch(
     rootDirectory: string,
-    database: MigrationDatabase
+    database: MigrationDatabase,
+    dialect: MigrationDialect
 ): Promise<void> {
     const applied =
         await readAppliedMigrations(
@@ -520,11 +540,11 @@ async function rollbackLatestBatch(
 
         await database.transaction(
             async (transaction) => {
-                await module.down?.(
+                await module.down(
                     transaction
                 );
                 await transaction.execute(
-                    `DELETE FROM ${MIGRATION_TABLE} WHERE name = ?`,
+                    dialect.deleteMigrationSql,
                     [
                         record.name,
                     ]
@@ -539,15 +559,11 @@ async function rollbackLatestBatch(
 }
 
 async function ensureMigrationTable(
-    database: MigrationDatabase
+    database: MigrationDatabase,
+    dialect: MigrationDialect
 ): 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`
+        dialect.createTableSql
     );
 }
 
@@ -561,6 +577,60 @@ async function readAppliedMigrations(
     );
 }
 
+function getMigrationDialect(
+    driver: DatabaseDriver
+): MigrationDialect {
+    if (
+        driver === "postgresql"
+    ) {
+        return {
+            createTableSql:
+                `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (` +
+                `id BIGSERIAL PRIMARY KEY, ` +
+                `name VARCHAR(255) NOT NULL UNIQUE, ` +
+                `batch INTEGER NOT NULL, ` +
+                `applied_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` +
+                `)`,
+            insertMigrationSql:
+                `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES ($1, $2)`,
+            deleteMigrationSql:
+                `DELETE FROM ${MIGRATION_TABLE} WHERE name = $1`,
+        };
+    }
+
+    if (
+        driver === "sqlite"
+    ) {
+        return {
+            createTableSql:
+                `CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (` +
+                `id INTEGER PRIMARY KEY AUTOINCREMENT, ` +
+                `name TEXT NOT NULL UNIQUE, ` +
+                `batch INTEGER NOT NULL, ` +
+                `applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP` +
+                `)`,
+            insertMigrationSql:
+                `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES (?, ?)`,
+            deleteMigrationSql:
+                `DELETE FROM ${MIGRATION_TABLE} WHERE name = ?`,
+        };
+    }
+
+    return {
+        createTableSql:
+            `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`,
+        insertMigrationSql:
+            `INSERT INTO ${MIGRATION_TABLE} (name, batch) VALUES (?, ?)`,
+        deleteMigrationSql:
+            `DELETE FROM ${MIGRATION_TABLE} WHERE name = ?`,
+    };
+}
+
 async function loadMigrationModule(
     migration: LoadedMigration
 ): Promise<Required<MigrationModule>> {
@@ -595,7 +665,7 @@ async function loadMigrationModule(
             module.up,
         down:
             module.down,
-    };
+    } as Required<MigrationModule>;
 }
 
 function normalizeMigrationName(

package/packages/client/src/database-mysql.ts

@@ -0,0 +1,291 @@
+import type {
+    DatabaseAdapter,
+    DatabaseParameters,
+    ResolvedDatabaseOptions,
+    TransactionDatabase,
+} from "./database.js";
+
+interface MysqlExecutor {
+    query(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<[unknown, unknown]>;
+    execute(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<[unknown, unknown]>;
+}
+
+interface MysqlConnection extends MysqlExecutor {
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    release(): void;
+}
+
+interface MysqlPool extends MysqlExecutor {
+    getConnection(): Promise<MysqlConnection>;
+    end(): Promise<void>;
+}
+
+interface MysqlModule {
+    createPool(
+        options: Record<string, unknown>
+    ): MysqlPool;
+}
+
+const MYSQL_MODULE_SPECIFIER =
+    "mysql2/promise";
+
+export function createMysqlDatabaseAdapter(
+    options: ResolvedDatabaseOptions
+): DatabaseAdapter {
+    return new MysqlDatabaseAdapter(
+        options
+    );
+}
+
+class MysqlDatabaseAdapter
+implements DatabaseAdapter {
+    readonly driver = "mysql";
+
+    private readonly options:
+        ResolvedDatabaseOptions;
+
+    private poolPromise:
+        Promise<MysqlPool> | null =
+        null;
+
+    constructor(
+        options: ResolvedDatabaseOptions
+    ) {
+        this.options =
+            options;
+    }
+
+    async connect(): Promise<void> {
+        if (!this.poolPromise) {
+            this.poolPromise =
+                createMysqlPool(
+                    this.options
+                );
+        }
+
+        await this.poolPromise;
+    }
+
+    async query<T = unknown>(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<T> {
+        assertSql(
+            sql
+        );
+
+        const pool =
+            await this.getPool();
+        const [rows] =
+            await pool.query(
+                sql,
+                parameters
+            );
+
+        return rows as T;
+    }
+
+    async execute<T = unknown>(
+        sql: string,
+        parameters?: DatabaseParameters
+    ): Promise<T> {
+        assertSql(
+            sql
+        );
+
+        const pool =
+            await this.getPool();
+        const [result] =
+            await pool.execute(
+                sql,
+                parameters
+            );
+
+        return result as T;
+    }
+
+    async transaction<T>(
+        callback: (
+            database: TransactionDatabase
+        ) => Promise<T>
+    ): Promise<T> {
+        assertTransactionCallback(
+            callback
+        );
+
+        const pool =
+            await this.getPool();
+        const connection =
+            await pool.getConnection();
+
+        await connection.beginTransaction();
+
+        const transactionDatabase:
+            TransactionDatabase = {
+            query: async <R = unknown>(
+                sql: string,
+                parameters?: DatabaseParameters
+            ): Promise<R> => {
+                assertSql(
+                    sql
+                );
+
+                const [rows] =
+                    await connection.query(
+                        sql,
+                        parameters
+                    );
+
+                return rows as R;
+            },
+            execute: async <R = unknown>(
+                sql: string,
+                parameters?: DatabaseParameters
+            ): Promise<R> => {
+                assertSql(
+                    sql
+                );
+
+                const [result] =
+                    await connection.execute(
+                        sql,
+                        parameters
+                    );
+
+                return result as R;
+            },
+        };
+
+        try {
+            const result =
+                await callback(
+                    transactionDatabase
+                );
+
+            await connection.commit();
+
+            return result;
+        } catch (error) {
+            try {
+                await connection.rollback();
+            } catch {
+                // Preserve the original transaction error.
+            }
+
+            throw error;
+        } finally {
+            connection.release();
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        const pendingPool =
+            this.poolPromise;
+
+        this.poolPromise =
+            null;
+
+        if (!pendingPool) {
+            return;
+        }
+
+        let pool:
+            MysqlPool;
+
+        try {
+            pool =
+                await pendingPool;
+        } catch {
+            return;
+        }
+
+        await pool.end();
+    }
+
+    private async getPool():
+        Promise<MysqlPool> {
+        await this.connect();
+
+        return this.poolPromise as
+            Promise<MysqlPool>;
+    }
+}
+
+async function createMysqlPool(
+    options: ResolvedDatabaseOptions
+): Promise<MysqlPool> {
+    let mysqlModule:
+        MysqlModule;
+
+    try {
+        mysqlModule =
+            await import(
+                MYSQL_MODULE_SPECIFIER
+            ) as unknown as MysqlModule;
+    } catch (error) {
+        throw new Error(
+            "BCP Database: MySQL requires the optional dependency mysql2. Install it with `npm install mysql2` or create the app with the MySQL preset.",
+            {
+                cause:
+                    error,
+            }
+        );
+    }
+
+    return mysqlModule.createPool({
+        host:
+            options.host,
+        port:
+            options.port,
+        user:
+            options.user,
+        password:
+            options.password,
+        database:
+            options.database,
+        waitForConnections:
+            options.waitForConnections,
+        connectionLimit:
+            options.connectionLimit,
+        queueLimit:
+            options.queueLimit,
+        charset:
+            options.charset,
+    });
+}
+
+function assertSql(
+    sql: string
+): void {
+    if (
+        typeof sql !== "string" ||
+        sql.trim() === ""
+    ) {
+        throw new TypeError(
+            "BCP Database: SQL must be a non-empty string."
+        );
+    }
+}
+
+function assertTransactionCallback(
+    callback: unknown
+): asserts callback is (
+    database: TransactionDatabase
+) => Promise<unknown> {
+    if (
+        typeof callback !==
+        "function"
+    ) {
+        throw new TypeError(
+            "BCP Database: transaction callback must be a function."
+        );
+    }
+}