@dangao/bun-server 3.1.0 → 3.2.0

package/dist/index.node.mjs

@@ -10865,6 +10865,197 @@ init_decorators();
 // src/database/connection-pool.ts
 init_runtime();
 
+// src/database/driver.ts
+var DRIVER_TAG = Symbol.for("@dangao/bun-server:database:driver");
+function resolveDriver(dbType, option, engine) {
+  const driver = option ?? "auto";
+  switch (driver) {
+    case "auto":
+      if (engine === "bun") {
+        return "bun-sql";
+      }
+      return dbType === "mysql" ? "mysql2" : "postgres";
+    case "bun-sql":
+      if (engine !== "bun") {
+        throw new Error(`[bun-server] driver 'bun-sql' requires the Bun runtime, but the current platform engine is '${engine}'. ` + `Use driver 'auto' / 'mysql2' / 'postgres', or run on Bun.`);
+      }
+      return "bun-sql";
+    case "mysql2":
+      if (dbType !== "mysql") {
+        throw new Error(`[bun-server] driver 'mysql2' is only valid for type 'mysql', but got type '${dbType}'.`);
+      }
+      return "mysql2";
+    case "postgres":
+      if (dbType !== "postgres") {
+        throw new Error(`[bun-server] driver 'postgres' is only valid for type 'postgres', but got type '${dbType}'.`);
+      }
+      return "postgres";
+    default:
+      throw new Error(`[bun-server] unknown driver '${String(driver)}'.`);
+  }
+}
+function tagConnection(connection, driver) {
+  if (connection && (typeof connection === "object" || typeof connection === "function")) {
+    try {
+      Object.defineProperty(connection, DRIVER_TAG, {
+        value: driver,
+        enumerable: false,
+        configurable: true,
+        writable: true
+      });
+    } catch {}
+  }
+  return connection;
+}
+function getConnectionDriver(connection) {
+  if (!connection) {
+    return;
+  }
+  if (typeof connection === "object" || typeof connection === "function") {
+    const tagged = connection[DRIVER_TAG];
+    if (tagged === "bun-sql" || tagged === "mysql2" || tagged === "postgres") {
+      return tagged;
+    }
+  }
+  if (typeof connection === "function") {
+    return "bun-sql";
+  }
+  return;
+}
+async function createPostgresConnection(config, driver) {
+  const url = `postgres://${config.user}:${config.password}@${config.host}:${config.port}/${config.database}`;
+  if (driver === "bun-sql") {
+    const { SQL } = await import("bun");
+    return tagConnection(new SQL({
+      adapter: "postgres",
+      hostname: config.host,
+      port: config.port,
+      username: config.user,
+      password: config.password,
+      database: config.database,
+      max: 1,
+      tls: config.ssl ?? false
+    }), "bun-sql");
+  }
+  if (driver === "postgres") {
+    const postgres = loadPostgres();
+    return tagConnection(postgres(url, { max: 1, ssl: config.ssl ? "require" : false }), "postgres");
+  }
+  throw new Error(`[bun-server] driver '${driver}' cannot create a postgres connection.`);
+}
+async function createMysqlConnection(config, driver) {
+  if (driver === "bun-sql") {
+    const { SQL } = await import("bun");
+    return tagConnection(new SQL({
+      adapter: "mysql",
+      hostname: config.host,
+      port: config.port,
+      username: config.user,
+      password: config.password,
+      database: config.database,
+      max: 1,
+      ssl: config.ssl ?? false
+    }), "bun-sql");
+  }
+  if (driver === "mysql2") {
+    const mysql2 = loadMysql2();
+    const conn = await mysql2.createConnection({
+      host: config.host,
+      port: config.port,
+      database: config.database,
+      user: config.user,
+      password: config.password
+    });
+    return tagConnection(conn, "mysql2");
+  }
+  throw new Error(`[bun-server] driver '${driver}' cannot create a mysql connection.`);
+}
+async function queryViaDriver(connection, sql, params) {
+  const driver = getConnectionDriver(connection);
+  if (driver === "mysql2") {
+    const conn = connection;
+    const [rows] = await conn.query(sql, params ?? []);
+    return rows ?? [];
+  }
+  if (driver === "postgres") {
+    const conn = connection;
+    const rows = await conn.unsafe(sql, params ?? []);
+    return rows ?? [];
+  }
+  if (typeof connection === "function") {
+    const { strings, values } = buildTemplateFromSql(sql, params);
+    const template = Object.assign(strings.slice(), {
+      raw: strings.slice()
+    });
+    const result = await connection(template, ...values);
+    return result;
+  }
+  if (connection && typeof connection === "object" && "query" in connection && typeof connection.query === "function") {
+    const result = await connection.query(sql, params ?? []);
+    return Array.isArray(result) ? result[0] : result;
+  }
+  throw new Error("[bun-server] invalid SQL connection for query.");
+}
+async function templateQueryViaDriver(connection, strings, values) {
+  const driver = getConnectionDriver(connection);
+  if (driver === "mysql2") {
+    const sql = strings.join("?");
+    const conn = connection;
+    const [rows] = await conn.query(sql, values);
+    return rows;
+  }
+  return await connection(strings, ...values);
+}
+async function healthCheckViaDriver(connection) {
+  try {
+    const rows = await queryViaDriver(connection, "SELECT 1");
+    return Array.isArray(rows);
+  } catch {
+    return false;
+  }
+}
+async function closeViaDriver(connection) {
+  if (!connection || typeof connection !== "object" && typeof connection !== "function") {
+    return;
+  }
+  const driver = getConnectionDriver(connection);
+  const conn = connection;
+  if (driver === "mysql2" || driver === "postgres") {
+    if (typeof conn.end === "function") {
+      await conn.end();
+      return;
+    }
+  }
+  if (driver === "bun-sql") {
+    if (typeof conn.close === "function") {
+      await conn.close();
+      return;
+    }
+  }
+  if (typeof conn.close === "function") {
+    await conn.close();
+  } else if (typeof conn.end === "function") {
+    await conn.end();
+  }
+}
+function buildTemplateFromSql(sql, params) {
+  if (!params || params.length === 0) {
+    return { strings: [sql], values: [] };
+  }
+  const strings = sql.split("?");
+  if (strings.length !== params.length + 1) {
+    throw new Error("SQL placeholders count does not match parameters count");
+  }
+  return { strings, values: params };
+}
+function loadMysql2() {
+  return __require("mysql2/promise");
+}
+function loadPostgres() {
+  return __require("postgres");
+}
+
+// src/database/connection-pool.ts
 class ConnectionPool {
   config;
   options;
@@ -10979,29 +11170,12 @@ Install it with: bun add @vscode/sqlite3@5.1.12-vscode`);
     return new sqlite3.Database(config.path);
   }
   async createPostgresConnection(config) {
-    const url = `postgres://${config.user}:${config.password}@${config.host}:${config.port}/${config.database}`;
-    if (getRuntime().engine === "bun") {
-      const { SQL } = await import("bun");
-      return new SQL(url, { max: 1, tls: config.ssl ?? false });
-    }
-    const postgres = __require("postgres");
-    return postgres(url, { max: 1, ssl: config.ssl ? "require" : false });
+    const driver = resolveDriver("postgres", this.config.type === "postgres" ? this.config.driver : undefined, getRuntime().engine);
+    return await createPostgresConnection(config, driver);
   }
   async createMysqlConnection(config) {
-    if (getRuntime().engine === "bun") {
-      const url = `mysql://${config.user}:${config.password}@${config.host}:${config.port}/${config.database}`;
-      const { SQL } = await import("bun");
-      return new SQL(url, { max: 1 });
-    }
-    const mysql2 = __require("mysql2/promise");
-    const conn = await mysql2.createConnection({
-      host: config.host,
-      port: config.port,
-      database: config.database,
-      user: config.user,
-      password: config.password
-    });
-    return conn;
+    const driver = resolveDriver("mysql", this.config.type === "mysql" ? this.config.driver : undefined, getRuntime().engine);
+    return await createMysqlConnection(config, driver);
   }
   async closeConnection(connection) {
     const dbType = this.config.type;
@@ -11018,15 +11192,11 @@ Install it with: bun add @vscode/sqlite3@5.1.12-vscode`);
       connection.close();
     }
   }
-  async closePostgresConnection(_connection) {
-    if (_connection && typeof _connection === "object" && "close" in _connection && typeof _connection.close === "function") {
-      _connection.close();
-    }
+  async closePostgresConnection(connection) {
+    await closeViaDriver(connection);
   }
-  async closeMysqlConnection(_connection) {
-    if (_connection && typeof _connection === "object" && "close" in _connection && typeof _connection.close === "function") {
-      _connection.close();
-    }
+  async closeMysqlConnection(connection) {
+    await closeViaDriver(connection);
   }
   async waitForConnection() {
     const startTime = Date.now();
@@ -11167,34 +11337,10 @@ class DatabaseConnectionManager {
     }
   }
   async healthCheckPostgres(connection) {
-    try {
-      if (connection && typeof connection === "function") {
-        const result = await connection`SELECT 1`;
-        return Array.isArray(result) && result.length > 0;
-      }
-      if (connection && typeof connection === "object" && "query" in connection && typeof connection.query === "function") {
-        await connection.query("SELECT 1");
-        return true;
-      }
-      return false;
-    } catch (_error) {
-      return false;
-    }
+    return await healthCheckViaDriver(connection);
   }
   async healthCheckMysql(connection) {
-    try {
-      if (connection && typeof connection === "function") {
-        const result = await connection`SELECT 1`;
-        return Array.isArray(result) && result.length > 0;
-      }
-      if (connection && typeof connection === "object" && "query" in connection && typeof connection.query === "function") {
-        await connection.query("SELECT 1");
-        return true;
-      }
-      return false;
-    } catch (_error) {
-      return false;
-    }
+    return await healthCheckViaDriver(connection);
   }
 }
 
@@ -11265,7 +11411,7 @@ class DatabaseService2 {
     if (dbType === "sqlite") {
       return this.querySqlite(connection, sql, params);
     } else if (dbType === "postgres" || dbType === "mysql") {
-      return this.queryBunSQL(connection, sql, params);
+      return queryViaDriver(connection, sql, params);
     }
     throw new Error(`Query not supported for database type: ${dbType}`);
   }
@@ -11288,37 +11434,6 @@ class DatabaseService2 {
     }
     throw new Error("Invalid SQLite connection");
   }
-  async queryBunSQL(connection, sql, params) {
-    if (connection && typeof connection === "function") {
-      try {
-        const { strings, values } = this.buildTemplateFromSql(sql, params);
-        const template = Object.assign(strings, {
-          raw: strings
-        });
-        const result = await connection(template, ...values);
-        return result;
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Bun.SQL parameterized queries are not fully supported. Consider using template string queries. Original error: ${errorMessage}`);
-      }
-    }
-    if (connection && typeof connection === "object" && "query" in connection && typeof connection.query === "function") {
-      const db = connection;
-      const result = await db.query(sql, ...params ?? []);
-      return result;
-    }
-    throw new Error("Invalid Bun.SQL connection");
-  }
-  buildTemplateFromSql(sql, params) {
-    if (!params || params.length === 0) {
-      return { strings: [sql], values: [] };
-    }
-    const strings = sql.split("?");
-    if (strings.length !== params.length + 1) {
-      throw new Error("SQL placeholders count does not match parameters count");
-    }
-    return { strings, values: params };
-  }
 }
 DatabaseService2 = __legacyDecorateClassTS([
   Injectable(),
@@ -11332,7 +11447,6 @@ var ORM_SERVICE_TOKEN = Symbol("@dangao/bun-server:orm:service");
 
 // src/database/sql-manager.ts
 init_runtime();
-
 class BunSQLManager2 {
   instances = new Map;
   defaultTenantId = "default";
@@ -11342,34 +11456,49 @@ class BunSQLManager2 {
       return existing;
     }
     const pool = config.pool ?? {};
+    const driver = resolveDriver(config.type, config.driver, getRuntime().engine);
     let sql;
-    if (getRuntime().engine === "bun") {
+    if (driver === "bun-sql") {
       const { SQL } = __require("bun");
-      sql = new SQL(config.url, {
-        max: pool.max ?? 10,
-        idleTimeout: pool.idleTimeout ?? 30,
-        maxLifetime: pool.maxLifetime ?? 0,
-        connectionTimeout: pool.connectionTimeout ?? 30000
-      });
-    } else {
-      const url = config.url.toLowerCase();
-      if (url.startsWith("mysql://") || url.startsWith("mysql2://")) {
-        const mysql2 = __require("mysql2/promise");
-        sql = mysql2.createPool({
-          uri: config.url,
-          connectionLimit: pool.max ?? 10,
-          waitForConnections: true
+      if (config.type === "mysql") {
+        const parsed = new URL(config.url);
+        sql = new SQL({
+          adapter: "mysql",
+          hostname: parsed.hostname,
+          port: parsed.port ? Number(parsed.port) : 3306,
+          username: decodeURIComponent(parsed.username),
+          password: decodeURIComponent(parsed.password),
+          database: parsed.pathname.replace(/^\//, ""),
+          max: pool.max ?? 10,
+          idleTimeout: pool.idleTimeout ?? 30,
+          maxLifetime: pool.maxLifetime ?? 0,
+          connectionTimeout: pool.connectionTimeout ?? 30000
         });
       } else {
-        const postgres = __require("postgres");
-        sql = postgres(config.url, {
+        sql = new SQL(config.url, {
           max: pool.max ?? 10,
-          idle_timeout: pool.idleTimeout ?? 30,
-          max_lifetime: pool.maxLifetime ?? 0,
-          connect_timeout: (pool.connectionTimeout ?? 30000) / 1000
+          idleTimeout: pool.idleTimeout ?? 30,
+          maxLifetime: pool.maxLifetime ?? 0,
+          connectionTimeout: pool.connectionTimeout ?? 30000
         });
       }
+    } else if (driver === "mysql2") {
+      const mysql2 = __require("mysql2/promise");
+      sql = mysql2.createPool({
+        uri: config.url,
+        connectionLimit: pool.max ?? 10,
+        waitForConnections: true
+      });
+    } else {
+      const postgres = __require("postgres");
+      sql = postgres(config.url, {
+        max: pool.max ?? 10,
+        idle_timeout: pool.idleTimeout ?? 30,
+        max_lifetime: pool.maxLifetime ?? 0,
+        connect_timeout: (pool.connectionTimeout ?? 30000) / 1000
+      });
     }
+    tagConnection(sql, driver);
     this.instances.set(tenantId, sql);
     return sql;
   }
@@ -11580,10 +11709,10 @@ var baseDb = async (tenantId, strings, ...values) => {
   if (tenantId) {
     const tenantSql = sqlManager.get(tenantId);
     if (tenantSql) {
-      return await tenantSql(strings, ...values);
+      return await templateQueryViaDriver(tenantSql, strings, values);
     }
   }
-  return await sqlManager.getDefault()(strings, ...values);
+  return await templateQueryViaDriver(sqlManager.getDefault(), strings, values);
 };
 function createDb(tenantId) {
   const fn = async (strings, ...values) => baseDb(tenantId, strings, ...values);
@@ -11657,7 +11786,8 @@ class DatabaseModule {
           config: {
             type: db2.type,
             url,
-            pool: options.bunSqlPool
+            pool: options.bunSqlPool,
+            driver: db2.driver ?? options.driver
           }
         }
       ];
@@ -11682,7 +11812,8 @@ class DatabaseModule {
           config: {
             type: options.type,
             url: options.url,
-            pool: options.bunSqlPool
+            pool: options.bunSqlPool,
+            driver: options.driver
           }
         }
       ];
@@ -11696,7 +11827,8 @@ class DatabaseModule {
           config: {
             type: options.type,
             url,
-            pool: options.bunSqlPool
+            pool: options.bunSqlPool,
+            driver: options.driver
           }
         }
       ];
@@ -11780,7 +11912,8 @@ class DatabaseModule {
           database: options.databasePath ?? "default",
           user: options.username ?? "root",
           password: options.password ?? ""
-        }
+        },
+        driver: normalized[0]?.config?.driver ?? options.driver
       }
     };
     const service = new DatabaseService2(legacyOptions);

package/docs/database.md

@@ -25,6 +25,50 @@ DatabaseModule.forRoot({
 });
 ```
 
+## Driver selection (decoupled from the runtime platform)
+
+> Added in v3.2.0.
+
+By default the underlying driver for Postgres/MySQL is chosen by the runtime platform: the Bun runtime uses the built-in `Bun.SQL`, while Node.js uses the pure-JS `mysql2` / `postgres` drivers.
+
+The optional `driver` field lets you **explicitly pick a pure-JS driver even under the Bun runtime**, decoupled from the platform engine (fs/crypto/http server, etc.):
+
+| driver | Behavior |
+| --- | --- |
+| `'auto'` (default) | Bun → `Bun.SQL`; Node → `mysql2` (MySQL) / `postgres` (PostgreSQL). Backward compatible. |
+| `'mysql2'` | Always use `mysql2`, regardless of runtime (only for `type: 'mysql'`). |
+| `'postgres'` | Always use `postgres`, regardless of runtime (only for `type: 'postgres'`). |
+| `'bun-sql'` | Force `Bun.SQL` (valid on Bun only; throws a clear error on Node). |
+
+```ts
+DatabaseModule.forRoot({
+  database: {
+    type: 'mysql',
+    driver: 'mysql2', // uses mysql2 even on the Bun runtime
+    config: {
+      host: '127.0.0.1',
+      port: 3306,
+      database: 'app',
+      user: 'root',
+      password: process.env.DB_PASSWORD!,
+    },
+  },
+});
+
+// The V2 single-tenant form is supported too:
+DatabaseModule.forRoot({
+  type: 'mysql',
+  url: process.env.DB_URL!,
+  driver: 'mysql2',
+});
+```
+
+### Why? MySQL under `bun build --compile`
+
+A single binary produced by `bun build --compile` freezes the Bun runtime at build time, and the built-in `Bun.SQL` MySQL adapter has several known issues. Setting `driver: 'mysql2'` lets the compiled binary connect using the statically bundled pure-JS `mysql2` driver, without falling back to SQLite and without switching the whole platform via `BUN_SERVER_PLATFORM=node` (which would also move the HTTP server to Node).
+
+The `driver` switch is orthogonal to `BUN_SERVER_PLATFORM`: the former only selects the SQL driver, while the latter selects the entire platform engine.
+
 ## Route strategy
 
 ```ts

package/docs/zh/database.md

@@ -25,6 +25,50 @@ DatabaseModule.forRoot({
 });
 ```
 
+## 驱动选择（driver，与运行时平台解耦）
+
+> v3.2.0 新增。
+
+默认情况下，Postgres/MySQL 连接的底层驱动由运行时平台决定：Bun 运行时使用内建 `Bun.SQL`，Node.js 运行时使用 `mysql2` / `postgres` 纯 JS 驱动。
+
+通过可选的 `driver` 字段，可以**在 Bun 运行时下也显式选用纯 JS 驱动**，与平台引擎（fs/crypto/http server 等）解耦：
+
+| driver | 行为 |
+| --- | --- |
+| `'auto'`（默认） | Bun → `Bun.SQL`；Node → `mysql2`（MySQL）/ `postgres`（PostgreSQL）。向后兼容。 |
+| `'mysql2'` | 无论运行时如何，都使用 `mysql2`（仅 `type: 'mysql'`）。 |
+| `'postgres'` | 无论运行时如何，都使用 `postgres`（仅 `type: 'postgres'`）。 |
+| `'bun-sql'` | 强制使用 `Bun.SQL`（仅 Bun 合法，Node 会抛出清晰错误）。 |
+
+```ts
+DatabaseModule.forRoot({
+  database: {
+    type: 'mysql',
+    driver: 'mysql2', // 即使在 Bun 运行时也走 mysql2
+    config: {
+      host: '127.0.0.1',
+      port: 3306,
+      database: 'app',
+      user: 'root',
+      password: process.env.DB_PASSWORD!,
+    },
+  },
+});
+
+// V2 单租户写法同样支持：
+DatabaseModule.forRoot({
+  type: 'mysql',
+  url: process.env.DB_URL!,
+  driver: 'mysql2',
+});
+```
+
+### 为什么需要它？`bun build --compile` 下的 MySQL
+
+`bun build --compile` 产出的单二进制会把当时的 Bun 运行时焊死，其中内建 `Bun.SQL` 的 MySQL 适配带有若干已知问题。显式设置 `driver: 'mysql2'` 即可让编译产物使用静态打包的纯 JS `mysql2` 驱动连库，无需为此回退到 SQLite，也无需用 `BUN_SERVER_PLATFORM=node` 整体切平台（那会把 HTTP server 也切到 Node）。
+
+`driver` 开关与 `BUN_SERVER_PLATFORM` 正交：前者只决定 SQL 驱动，后者决定整个平台引擎。
+
 ## 路由策略示例
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/database/connection-manager.ts

@@ -7,6 +7,7 @@ import type {
 } from './types';
 
 import { ConnectionPool } from './connection-pool';
+import { healthCheckViaDriver } from './driver';
 
 /**
  * 数据库连接管理器
@@ -189,58 +190,16 @@ export class DatabaseConnectionManager {
   }
 
   /**
-   * PostgreSQL 健康检查（使用 Bun.SQL）
+   * PostgreSQL 健康检查（按连接 driver tag 分流）
    */
   private async healthCheckPostgres(connection: unknown): Promise<boolean> {
-    try {
-      // Bun.SQL 对象可以作为函数调用（模板字符串）
-      if (connection && typeof connection === 'function') {
-        const result = await (connection as (template: TemplateStringsArray, ...values: unknown[]) => Promise<unknown[]>)`SELECT 1`;
-        return Array.isArray(result) && result.length > 0;
-      }
-      // 或者使用 query 方法（如果存在）
-      if (
-        connection &&
-        typeof connection === 'object' &&
-        'query' in connection &&
-        typeof connection.query === 'function'
-      ) {
-        await (connection as { query: (sql: string) => Promise<unknown> }).query(
-          'SELECT 1',
-        );
-        return true;
-      }
-      return false;
-    } catch (_error) {
-      return false;
-    }
+    return await healthCheckViaDriver(connection);
   }
 
   /**
-   * MySQL 健康检查（使用 Bun.SQL）
+   * MySQL 健康检查（按连接 driver tag 分流）
    */
   private async healthCheckMysql(connection: unknown): Promise<boolean> {
-    try {
-      // Bun.SQL 对象可以作为函数调用（模板字符串）
-      if (connection && typeof connection === 'function') {
-        const result = await (connection as (template: TemplateStringsArray, ...values: unknown[]) => Promise<unknown[]>)`SELECT 1`;
-        return Array.isArray(result) && result.length > 0;
-      }
-      // 或者使用 query 方法（如果存在）
-      if (
-        connection &&
-        typeof connection === 'object' &&
-        'query' in connection &&
-        typeof connection.query === 'function'
-      ) {
-        await (connection as { query: (sql: string) => Promise<unknown> }).query(
-          'SELECT 1',
-        );
-        return true;
-      }
-      return false;
-    } catch (_error) {
-      return false;
-    }
+    return await healthCheckViaDriver(connection);
   }
 }