@chidchanun/bcp 0.2.2 → 0.2.3

package/README.md

@@ -2,13 +2,13 @@
 
 BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, database access, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.2 — Configuration & Environment v2`
+> **Development target:** `0.2.3 — Database Platform v2`
 >
-> `0.2.2` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.3` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## 0.2 platform
 
-`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, and `0.2.2` adds typed application environment validation and configuration diagnostics without intentionally removing public application entrypoints.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, and `0.2.3` adds a provider-neutral SQL database platform with MySQL, PostgreSQL and SQLite support without intentionally removing public application entrypoints.
 
 Machine-readable platform contracts:
 
@@ -36,7 +36,7 @@ docs/api-manifest.json
 | Middleware | Middleware System v2 with onion execution |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
-| Database | MySQL helpers, transactions and migrations |
+| Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
 | Logging | Structured logger, request logger and request IDs |
 | Uploads | Buffered multipart helpers and production multipart streaming |
 | Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
@@ -52,7 +52,13 @@ docs/api-manifest.json
 - React `19`
 - npm
 
-Database framework primitives currently target MySQL.
+Database drivers are optional and provider-specific:
+
+```text
+MySQL       mysql2
+PostgreSQL  pg
+SQLite      better-sqlite3
+```
 
 ## Quick start
 
@@ -224,6 +230,53 @@ must not use `BCP_PUBLIC_`. BCP reports this as a configuration error.
 
 Read more: [Environment Validation](docs/environment-validation.md)
 
+## Database Platform v2 — 0.2.3
+
+Application code uses the same server-only entrypoint across supported SQL providers:
+
+```ts
+import {
+    db,
+    createDatabase,
+} from "bcp/database";
+```
+
+Built-in providers:
+
+```text
+mysql
+postgresql
+sqlite
+```
+
+Connections remain lazy, while explicit lifecycle control is available when needed:
+
+```ts
+await db.connect();
+
+// application work
+
+await db.disconnect();
+```
+
+`db.close()` remains available for backward-compatible shutdown handling.
+
+Database migrations use the same CLI across providers:
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
+BCP makes its internal migration bookkeeping provider-aware. Application SQL itself is not automatically translated between SQL dialects.
+
+Read more:
+
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
+
 ## Public entrypoints
 
 The current `0.2.x` platform contract recognizes:
@@ -383,7 +436,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.2` adds Configuration & Environment v2 unit/package checks covering schema parsing, project schema loading, diagnostics, CLI parsing, public `bcp/config` exports and packed-package files.
+`0.2.3` adds Database Platform v2 unit/package checks covering the adapter contract, MySQL/PostgreSQL/SQLite provider resolution, explicit connection lifecycle, failed-initialization retry behavior and provider-specific migration bookkeeping.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -400,24 +453,13 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.0` | Framework Platform |
 | `0.2.1` | Documentation Platform |
 | `0.2.2` | Configuration & Environment v2 |
+| `0.2.3` | Database Platform v2 |
 
 ## Roadmap
 
-Next planned milestone:
-
-```text
-0.2.3 — Database Platform v2
-```
-
-Planned focus:
-
-- database adapter contract,
-- PostgreSQL support,
-- SQLite support,
-- connection lifecycle improvements,
-- migration consistency across providers.
+`0.2.3 — Database Platform v2` completes the planned database adapter contract, PostgreSQL support, SQLite support, connection lifecycle improvements and migration consistency across the built-in SQL providers.
 
-Application packaging remains later `0.2.x` roadmap work.
+The next planned `0.2.x` focus is application packaging. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License
 

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -74,7 +74,7 @@
       "source": "packages/client/src/database.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-database",
-      "summary": "Database pool, prepared query/execute helpers and transaction primitives.",
+      "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
       "guides": [
         "/docs/database",
         "/docs/database-migrations"

package/docs/api-reference.md

@@ -130,16 +130,35 @@ Related guide: [Error Handling](error-handling.md).
 
 ## `bcp/database`
 
-Server-only database primitives.
+Server-only Database Platform v2 APIs.
 
 ```ts
 import {
     createDatabase,
     db,
+    resolveDatabaseOptions,
+    type DatabaseAdapter,
+    type DatabaseAdapterFactory,
+    type DatabaseConnectionOptions,
+    type DatabaseDriver,
+    type DatabaseOptions,
+    type DatabaseParameters,
+    type ResolvedDatabaseOptions,
+    type TransactionDatabase,
 } from "bcp/database";
 ```
 
-Use the public database helpers instead of importing framework-internal pool/runtime modules.
+Built-in SQL providers are:
+
+```text
+mysql
+postgresql
+sqlite
+```
+
+`BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
+
+Use the public database helpers and adapter types instead of importing framework-internal provider/pool runtime modules.
 
 Related guides: [Database](database.md), [Database Migrations](database-migrations.md).
 

package/docs/database-migrations.md

@@ -1,14 +1,33 @@
 # Database Migrations
 
-BCP Framework `0.1.15` adds MySQL migration commands to the `bcp` CLI.
+BCP `0.2.3` extends framework-managed SQL migrations across MySQL, PostgreSQL and SQLite.
 
-## Requirements
+## Supported providers
 
-Database migrations currently use the MySQL adapter from `bcp/database`.
+Migration bookkeeping uses the same provider selection as `bcp/database`:
 
-Configure the same environment variables used by your application:
+```text
+mysql
+postgresql
+sqlite
+```
+
+Install the optional driver used by the application:
+
+```bash
+npm install mysql2
+npm install pg
+npm install better-sqlite3
+```
+
+Only one driver is required when the project uses one database provider.
+
+## Provider configuration
+
+MySQL:
 
 ```env
+DB_DRIVER=mysql
 DB_HOST=localhost
 DB_PORT=3306
 DB_USER=root
@@ -16,7 +35,20 @@ DB_PASSWORD=
 DB_NAME=bcp_app
 ```
 
-A project using migrations must have `mysql2` installed. Applications created with the MySQL preset already include it.
+PostgreSQL:
+
+```env
+DATABASE_URL=postgresql://postgres:password@localhost:5432/bcp_app
+```
+
+SQLite:
+
+```env
+DB_DRIVER=sqlite
+DATABASE_URL=./data/bcp.sqlite
+```
+
+Database commands load the development environment before connecting, so migration commands and `bcp dev` use the same provider selection.
 
 ## Create a migration
 
@@ -24,14 +56,14 @@ A project using migrations must have `mysql2` installed. Applications created wi
 bcp db create create_users
 ```
 
-BCP creates an ordered TypeScript file in `migrations/`:
+BCP creates an ordered TypeScript file:
 
 ```text
 migrations/
-  20260827040506_create_users.ts
+  20260829090000_create_users.ts
 ```
 
-A generated migration exports `up()` and `down()`:
+Generated migrations export `up()` and `down()`:
 
 ```ts
 import type {
@@ -43,9 +75,9 @@ export async function up(
 ): Promise<void> {
     await db.execute(`
         CREATE TABLE users (
-            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+            id INTEGER PRIMARY KEY,
             email VARCHAR(255) NOT NULL UNIQUE
-        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+        )
     `);
 }
 
@@ -58,7 +90,24 @@ export async function down(
 }
 ```
 
-Migration filenames use a UTC timestamp prefix so migrations have a stable execution order.
+Migration filenames use a UTC timestamp prefix for stable execution order.
+
+## SQL dialect responsibility
+
+BCP keeps its own `_bcp_migrations` bookkeeping provider-aware, but it does not translate application migration SQL.
+
+This means migrations should either:
+
+- use SQL supported by every database target used by the application, or
+- intentionally target one provider and use that provider's SQL syntax.
+
+Parameter placeholders also follow the active provider:
+
+```text
+MySQL       ?
+SQLite      ?
+PostgreSQL  $1, $2, ...
+```
 
 ## Run pending migrations
 
@@ -66,9 +115,15 @@ Migration filenames use a UTC timestamp prefix so migrations have a stable execu
 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.
+BCP creates `_bcp_migrations` with provider-specific DDL, detects pending migration files, and executes them in filename order.
+
+All migrations applied by one command share the same batch number. Each migration runs inside its own transaction and its bookkeeping record is written in that same transaction.
 
-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()`.
+Provider-specific bookkeeping includes:
+
+- MySQL `AUTO_INCREMENT`,
+- PostgreSQL `BIGSERIAL`,
+- SQLite `INTEGER PRIMARY KEY AUTOINCREMENT`.
 
 ## Check status
 
@@ -84,22 +139,27 @@ The command reports applied and pending migration files together with the batch
 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.
+Rollback reverses only the latest migration batch. Migrations run from newest to oldest and each `down()` executes in a transaction together with deletion 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:
+All database commands support the normal project-root option:
 
 ```bash
 bcp db status --root ./apps/admin
 ```
 
-## Environment files
+## Database Platform v2 behavior
 
-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.
+`0.2.3` keeps migration commands consistent across the built-in SQL providers:
 
-## Current scope
+```text
+bcp db create
+bcp db migrate
+bcp db status
+bcp db rollback
+```
 
-`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.
+The command names and migration file contract stay the same regardless of whether the application uses MySQL, PostgreSQL or SQLite.

package/docs/database.md

@@ -1,18 +1,24 @@
 # Database
 
-BCP `0.1.14` adds the first framework-native database API through the server-only `bcp/database` entrypoint.
+BCP `0.2.3` completes Database Platform v2 behind 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.
+The public database facade is provider-neutral and currently includes built-in adapters for:
 
-## Create an app with MySQL
+- MySQL,
+- PostgreSQL,
+- SQLite.
+
+Applications can keep the same `db.query()`, `db.execute()`, `db.transaction()` and lifecycle API while selecting the provider through environment or explicit options.
+
+## MySQL
+
+Install the optional driver:
 
 ```bash
-npx create-bcp-app my-app
+npm install mysql2
 ```
 
-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
+Environment:
 
 ```env
 DB_DRIVER=mysql
@@ -22,20 +28,105 @@ 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.
+MySQL remains the default when no provider can be inferred.
 
-## Query
+Parameterized query:
 
 ```ts
 import {
     db,
 } from "bcp/database";
 
+const users =
+    await db.query(
+        "SELECT id, email FROM users WHERE active = ?",
+        [
+            1,
+        ]
+    );
+```
+
+## PostgreSQL
+
+Install the optional driver:
+
+```bash
+npm install pg
+```
+
+BCP can infer PostgreSQL from a connection URL:
+
+```env
+DATABASE_URL=postgresql://postgres:password@localhost:5432/bcp_app
+```
+
+or use explicit fields:
+
+```env
+DB_DRIVER=postgresql
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=password
+DB_NAME=bcp_app
+```
+
+PostgreSQL parameters use `$1`, `$2`, and later placeholders:
+
+```ts
+const users =
+    await db.query(
+        "SELECT id, email FROM users WHERE active = $1",
+        [
+            true,
+        ]
+    );
+```
+
+`postgres` and `pg` are accepted as environment aliases for the PostgreSQL driver and are normalized to `postgresql`.
+
+## SQLite
+
+Install the optional driver:
+
+```bash
+npm install better-sqlite3
+```
+
+Recommended environment:
+
+```env
+DB_DRIVER=sqlite
+DATABASE_URL=./data/bcp.sqlite
+```
+
+BCP also recognizes `:memory:`, `sqlite:` / `file:` URLs and common `.sqlite`, `.sqlite3`, and `.db` file names.
+
+Example:
+
+```ts
+import {
+    createDatabase,
+} from "bcp/database";
+
+const database =
+    createDatabase({
+        driver:
+            "sqlite",
+        database:
+            "./data/app.sqlite",
+    });
+```
+
+SQLite operations are serialized by the built-in adapter so async transaction callbacks cannot interleave unrelated queries on the same native connection.
+
+## Query and execute
+
+`query<T>()` is intended for row-returning statements:
+
+```ts
 interface UserRow {
     id: number;
     email: string;
@@ -43,28 +134,27 @@ interface UserRow {
 
 const users =
     await db.query<UserRow[]>(
-        "SELECT id, email FROM users WHERE active = ?",
-        [
-            1,
-        ]
+        "SELECT id, email FROM users"
     );
 ```
 
-## Execute
+`execute<T>()` is intended for mutations and DDL:
 
 ```ts
 const result =
     await db.execute(
-        "INSERT INTO users (email) VALUES (?)",
+        "DELETE FROM sessions WHERE expired_at < ?",
         [
-            "user@example.com",
+            new Date(),
         ]
     );
 ```
 
-Use placeholders and parameter arrays instead of concatenating untrusted values into SQL strings.
+Use the placeholder syntax of the active database provider. BCP does not rewrite application SQL between dialects.
 
-## Transaction
+## Transactions
+
+The transaction callback receives a provider-scoped `TransactionDatabase`:
 
 ```ts
 await db.transaction(
@@ -88,7 +178,33 @@ await db.transaction(
 );
 ```
 
-BCP commits the transaction when the callback resolves and rolls it back when the callback throws.
+The example above uses MySQL/SQLite placeholders. PostgreSQL migrations and application statements should use `$1`, `$2`, and so on.
+
+BCP commits when the callback resolves and rolls back when it throws.
+
+## Connection lifecycle
+
+Database instances remain lazy by default. Importing `bcp/database` does not connect to a provider.
+
+BCP `0.2.3` adds explicit lifecycle methods:
+
+```ts
+await db.connect();
+
+// application work
+
+await db.disconnect();
+```
+
+`close()` remains available as the backward-compatible shutdown method and is equivalent to `disconnect()`:
+
+```ts
+await db.close();
+```
+
+After disconnecting, the next operation or `connect()` call creates a fresh adapter connection/pool.
+
+If adapter initialization fails, BCP resets the pending lifecycle state so a later attempt can retry cleanly. Calling `close()` after a failed initialization is safe.
 
 ## Custom database instance
 
@@ -99,6 +215,8 @@ import {
 
 export const reportingDb =
     createDatabase({
+        driver:
+            "postgresql",
         host:
             "reporting-db.internal",
         database:
@@ -110,18 +228,69 @@ export const reportingDb =
 
 Explicit options override environment values for that database instance.
 
-## Lifecycle
+## Database adapter contract
 
-Connections are lazy. Importing `bcp/database` does not open a MySQL connection. The pool is created on the first `query`, `execute` or `transaction` call.
+Provider implementations use the shared adapter contract:
+
+```ts
+import type {
+    DatabaseAdapter,
+    TransactionDatabase,
+} from "bcp/database";
 
-For custom shutdown handling, close the pool with:
+const adapter: DatabaseAdapter = {
+    driver: "custom",
+
+    async connect() {},
+
+    async query<T>(sql, parameters) {
+        throw new Error("Not implemented");
+    },
+
+    async execute<T>(sql, parameters) {
+        throw new Error("Not implemented");
+    },
+
+    async transaction<T>(
+        callback: (
+            database: TransactionDatabase
+        ) => Promise<T>
+    ) {
+        throw new Error("Not implemented");
+    },
+
+    async disconnect() {},
+};
+```
+
+Inject an adapter directly or through a lazy factory:
 
 ```ts
-await db.close();
+export const customDb =
+    createDatabase({
+        adapter: () => adapter,
+    });
+```
+
+The contract lets future providers integrate without changing application-facing database calls.
+
+## Migrations
+
+Framework migration bookkeeping supports MySQL, PostgreSQL and SQLite in `0.2.3`.
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
 ```
 
+BCP selects the internal migration-table dialect from the same active database environment. Migration files themselves remain normal provider SQL and are not automatically translated between SQL dialects.
+
+Read more: [Database Migrations](database-migrations.md)
+
 ## 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.
+`bcp/database` is a server-only package export. Importing it into a browser bundle is blocked by the framework 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.
+Provider drivers are optional and loaded lazily. Projects only need to install the driver they actually use.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.2",
+  "versionTarget": "0.2.3",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -45,7 +45,7 @@
     {
       "id": "database",
       "title": "Database",
-      "description": "Database primitives, transactions and migration workflows.",
+      "description": "Provider-neutral MySQL, PostgreSQL and SQLite primitives, lifecycle and migrations.",
       "pages": [
         { "route": "/docs/database", "source": "database.md", "title": "Database" },
         { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" }
@@ -104,7 +104,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2", "state": "unreleased" },
+    { "route": "/releases/0.2.3", "source": "releases/0.2.3.md", "version": "0.2.3", "state": "unreleased" },
+    { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2" },
     { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1" },
     { "route": "/releases/0.2.0", "source": "releases/0.2.0.md", "version": "0.2.0" },
     { "route": "/releases/0.1.29", "source": "releases/0.1.29.md", "version": "0.1.29" },