@dangao/bun-server 3.1.0 → 3.2.0

package/src/database/sql-manager.ts

@@ -1,5 +1,6 @@
 import type { BunSQLConfig } from './types';
 import { getRuntime } from '../platform/runtime';
+import { resolveDriver, tagConnection } from './driver';
 
 /**
  * SQL 连接管理器
@@ -17,39 +18,52 @@ export class BunSQLManager {
     }
 
     const pool = config.pool ?? {};
+    const driver = resolveDriver(config.type, config.driver, getRuntime().engine);
     let sql: unknown;
 
-    if (getRuntime().engine === 'bun') {
+    if (driver === 'bun-sql') {
       const { SQL } = require('bun') as typeof import('bun');
-      sql = new SQL(config.url, {
-        max: pool.max ?? 10,
-        idleTimeout: pool.idleTimeout ?? 30,
-        maxLifetime: pool.maxLifetime ?? 0,
-        connectionTimeout: pool.connectionTimeout ?? 30000,
-      });
-    } else {
-      // Node.js: detect dialect from URL
-      const url = config.url.toLowerCase();
-      if (url.startsWith('mysql://') || url.startsWith('mysql2://')) {
-        const mysql2 = require('mysql2/promise') as typeof import('mysql2/promise');
-        // Create a pool in Node.js
-        sql = mysql2.createPool({
-          uri: config.url,
-          connectionLimit: pool.max ?? 10,
-          waitForConnections: true,
-        });
+      if (config.type === 'mysql') {
+        // 走 options-object 形式而非连接字符串，绕开 oven-sh/bun#26648
+        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,
+        } as unknown as string);
       } else {
-        // postgres (default)
-        const postgres = require('postgres') as typeof import('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') as typeof import('mysql2/promise');
+      sql = mysql2.createPool({
+        uri: config.url,
+        connectionLimit: pool.max ?? 10,
+        waitForConnections: true,
+      });
+    } else {
+      const postgres = require('postgres') as typeof import('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;
   }

package/src/database/types.ts

@@ -3,6 +3,19 @@
  */
 export type DatabaseType = 'sqlite' | 'postgres' | 'mysql';
 
+/**
+ * SQL 驱动选择
+ *
+ * 与运行时平台（fs/crypto/http server 等）解耦，仅决定 Postgres/MySQL 连接走哪套底层驱动。
+ *
+ * - `'auto'`（默认）：Bun 运行时使用内建 `Bun.SQL`，Node.js 运行时使用 `mysql2` / `postgres` 纯 JS 驱动（保持历史行为）。
+ * - `'mysql2'`：无论运行时是 Bun 还是 Node，都使用 `mysql2`（仅适用于 `type: 'mysql'`）。
+ *   适合 `bun build --compile` 场景，绕开编译二进制内焊死的 `Bun.SQL` MySQL 适配 bug。
+ * - `'postgres'`：无论运行时如何，都使用 `postgres` 纯 JS 驱动（仅适用于 `type: 'postgres'`）。
+ * - `'bun-sql'`：强制使用 `Bun.SQL`（仅在 Bun 运行时合法，Node.js 下会抛出清晰错误）。
+ */
+export type DatabaseDriver = 'auto' | 'bun-sql' | 'mysql2' | 'postgres';
+
 /**
  * SQLite 配置
  */
@@ -72,11 +85,13 @@ export interface MysqlConfig {
 
 /**
  * 数据库配置（联合类型）
+ *
+ * Postgres/MySQL 支持可选的 `driver` 字段，用于显式选择底层驱动（与运行时平台解耦）。
  */
 export type DatabaseConfig =
   | { type: 'sqlite'; config: SqliteConfig }
-  | { type: 'postgres'; config: PostgresConfig }
-  | { type: 'mysql'; config: MysqlConfig };
+  | { type: 'postgres'; config: PostgresConfig; driver?: DatabaseDriver }
+  | { type: 'mysql'; config: MysqlConfig; driver?: DatabaseDriver };
 
 /**
  * Bun.SQL 连接池配置
@@ -111,6 +126,11 @@ export interface BunSQLConfig {
   type: 'postgres' | 'mysql';
   url: string;
   pool?: BunSQLPoolOptions;
+  /**
+   * 显式选择底层驱动（与运行时平台解耦）。
+   * @default 'auto'
+   */
+  driver?: DatabaseDriver;
 }
 
 /**
@@ -183,6 +203,11 @@ export interface DatabaseModuleOptions {
    * 单租户：数据库类型（V2）
    */
   type?: DatabaseType;
+  /**
+   * 单租户：显式选择底层驱动（V2，与运行时平台解耦）
+   * @default 'auto'
+   */
+  driver?: DatabaseDriver;
   /**
    * 单租户：Postgres/MySQL URL（V2）
    */

package/tests/database/database-module.test.ts

@@ -9,9 +9,13 @@ import {
   SQLITE_MANAGER_TOKEN,
 } from '../../src/database';
 import { MODULE_METADATA_KEY } from '../../src/di/module';
+import { initRuntime } from '../../src/platform/runtime';
 
 describe('DatabaseModule V2', () => {
   beforeEach(() => {
+    // forRoot() 会在创建 sqlite/sql 管理器时读取 getRuntime()，确保运行时已初始化
+    // （避免依赖其他测试文件的执行顺序）
+    initRuntime('bun');
     Reflect.deleteMetadata(MODULE_METADATA_KEY, DatabaseModule);
   });
 

package/tests/database/driver-mysql2.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test, mock, beforeAll } from 'bun:test';
+
+import { initRuntime, getRuntime } from '../../src/platform/runtime';
+
+/**
+ * 验证：在 Bun 运行时下显式选用 driver: 'mysql2' 时，
+ * 连接创建 / 参数化查询 / health check / close 全部走 mysql2（而非 Bun.SQL）。
+ *
+ * 通过 mock 'mysql2/promise' 模块注入假连接，无需真实 MySQL。
+ */
+
+const createdConnections: Array<Record<string, unknown>> = [];
+const queryCalls: Array<{ sql: string; params: unknown[] }> = [];
+let endCount = 0;
+
+function makeFakeConnection() {
+  const conn = {
+    query: async (sql: string, params: unknown[]) => {
+      queryCalls.push({ sql, params });
+      // mysql2 返回 [rows, fields]
+      if (/select\s+1/i.test(sql)) {
+        return [[{ '1': 1 }], []];
+      }
+      return [[{ id: 1, name: 'alice' }], [{ name: 'id' }, { name: 'name' }]];
+    },
+    end: async () => {
+      endCount += 1;
+    },
+    close: async () => {
+      throw new Error('mysql2 connection should be closed via end(), not close()');
+    },
+  };
+  createdConnections.push(conn);
+  return conn;
+}
+
+mock.module('mysql2/promise', () => {
+  const createConnection = async (_opts: unknown) => makeFakeConnection();
+  const createPool = (_opts: unknown) => makeFakeConnection();
+  return {
+    default: { createConnection, createPool },
+    createConnection,
+    createPool,
+  };
+});
+
+describe('DatabaseService with driver: mysql2 on Bun runtime', () => {
+  beforeAll(() => {
+    initRuntime('bun');
+  });
+
+  test('runs the full lifecycle (create/query/health/close) through mysql2', async () => {
+    // 前置确认：当前进程运行在 Bun，但我们强制 mysql2
+    expect(getRuntime().engine).toBe('bun');
+
+    const { DatabaseService } = await import('../../src/database/service');
+
+    const svc = new DatabaseService({
+      database: {
+        type: 'mysql',
+        driver: 'mysql2',
+        config: {
+          host: 'localhost',
+          port: 3306,
+          database: 'testdb',
+          user: 'root',
+          password: 'secret',
+        },
+      },
+      enableHealthCheck: true,
+    });
+
+    await svc.initialize();
+
+    // 连接由 mysql2.createConnection 创建
+    expect(createdConnections.length).toBeGreaterThan(0);
+
+    // 参数化查询走 mysql2.query(sql, params)，并返回 rows（而非 [rows, fields]）
+    const rows = await svc.query<{ id: number; name: string }>(
+      'SELECT * FROM users WHERE id = ?',
+      [1],
+    );
+    expect(rows).toEqual([{ id: 1, name: 'alice' }]);
+    expect(queryCalls.some((c) => c.sql === 'SELECT * FROM users WHERE id = ?' && c.params[0] === 1)).toBe(true);
+
+    // health check 走 mysql2.query('SELECT 1')
+    const healthy = await svc.healthCheck();
+    expect(healthy).toBe(true);
+    expect(queryCalls.some((c) => /select\s+1/i.test(c.sql))).toBe(true);
+
+    // close 走 mysql2 的 end()
+    await svc.closePool();
+    expect(endCount).toBeGreaterThan(0);
+  });
+});

package/tests/database/driver.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  closeViaDriver,
+  getConnectionDriver,
+  healthCheckViaDriver,
+  queryViaDriver,
+  resolveDriver,
+  tagConnection,
+  templateQueryViaDriver,
+} from '../../src/database/driver';
+
+describe('resolveDriver', () => {
+  test("'auto' on bun resolves to bun-sql for mysql and postgres", () => {
+    expect(resolveDriver('mysql', 'auto', 'bun')).toBe('bun-sql');
+    expect(resolveDriver('postgres', 'auto', 'bun')).toBe('bun-sql');
+    expect(resolveDriver('mysql', undefined, 'bun')).toBe('bun-sql');
+  });
+
+  test("'auto' on node resolves to js drivers", () => {
+    expect(resolveDriver('mysql', 'auto', 'node')).toBe('mysql2');
+    expect(resolveDriver('postgres', 'auto', 'node')).toBe('postgres');
+  });
+
+  test("'mysql2' forces mysql2 regardless of engine", () => {
+    expect(resolveDriver('mysql', 'mysql2', 'bun')).toBe('mysql2');
+    expect(resolveDriver('mysql', 'mysql2', 'node')).toBe('mysql2');
+  });
+
+  test("'postgres' forces postgres regardless of engine", () => {
+    expect(resolveDriver('postgres', 'postgres', 'bun')).toBe('postgres');
+    expect(resolveDriver('postgres', 'postgres', 'node')).toBe('postgres');
+  });
+
+  test("'bun-sql' is valid on bun, throws on node", () => {
+    expect(resolveDriver('mysql', 'bun-sql', 'bun')).toBe('bun-sql');
+    expect(() => resolveDriver('mysql', 'bun-sql', 'node')).toThrow();
+  });
+
+  test("'mysql2' on postgres type throws", () => {
+    expect(() => resolveDriver('postgres', 'mysql2', 'bun')).toThrow();
+  });
+
+  test("'postgres' on mysql type throws", () => {
+    expect(() => resolveDriver('mysql', 'postgres', 'bun')).toThrow();
+  });
+});
+
+describe('connection tagging', () => {
+  test('tag and read back driver on object connection', () => {
+    const conn = { query: () => undefined };
+    tagConnection(conn, 'mysql2');
+    expect(getConnectionDriver(conn)).toBe('mysql2');
+  });
+
+  test('tag preserves identity', () => {
+    const conn = {};
+    expect(tagConnection(conn, 'mysql2')).toBe(conn);
+  });
+
+  test('tag is non-enumerable', () => {
+    const conn = { query: () => undefined };
+    tagConnection(conn, 'mysql2');
+    expect(Object.keys(conn)).toEqual(['query']);
+  });
+
+  test('callable connection without tag falls back to bun-sql', () => {
+    const conn = (() => undefined) as unknown;
+    expect(getConnectionDriver(conn)).toBe('bun-sql');
+  });
+
+  test('untagged plain object returns undefined', () => {
+    expect(getConnectionDriver({ query: () => undefined })).toBeUndefined();
+  });
+});
+
+describe('queryViaDriver', () => {
+  test('mysql2 connection uses .query and returns rows (not [rows, fields])', async () => {
+    const calls: Array<{ sql: string; params: unknown[] }> = [];
+    const conn = tagConnection(
+      {
+        query: async (sql: string, params: unknown[]) => {
+          calls.push({ sql, params });
+          return [[{ id: 1 }], [{ name: 'id' }]];
+        },
+      },
+      'mysql2',
+    );
+
+    const rows = await queryViaDriver(conn, 'SELECT * FROM t WHERE id = ?', [1]);
+    expect(rows).toEqual([{ id: 1 }]);
+    expect(calls).toEqual([{ sql: 'SELECT * FROM t WHERE id = ?', params: [1] }]);
+  });
+
+  test('postgres connection uses .unsafe and returns rows', async () => {
+    const calls: Array<{ sql: string; params: unknown[] }> = [];
+    const conn = tagConnection(
+      {
+        unsafe: async (sql: string, params: unknown[]) => {
+          calls.push({ sql, params });
+          return [{ ok: true }];
+        },
+      },
+      'postgres',
+    );
+
+    const rows = await queryViaDriver(conn, 'SELECT 1 WHERE x = ?', ['y']);
+    expect(rows).toEqual([{ ok: true }]);
+    expect(calls).toEqual([{ sql: 'SELECT 1 WHERE x = ?', params: ['y'] }]);
+  });
+
+  test('bun-sql connection uses template string path', async () => {
+    let received: { strings: string[]; values: unknown[] } | null = null;
+    const conn = tagConnection(
+      Object.assign(
+        async (strings: TemplateStringsArray, ...values: unknown[]) => {
+          received = { strings: Array.from(strings), values };
+          return [{ via: 'bun-sql' }];
+        },
+      ),
+      'bun-sql',
+    );
+
+    const rows = await queryViaDriver(conn, 'SELECT * FROM t WHERE id = ?', [42]);
+    expect(rows).toEqual([{ via: 'bun-sql' }]);
+    expect(received!.strings).toEqual(['SELECT * FROM t WHERE id = ', '']);
+    expect(received!.values).toEqual([42]);
+  });
+});
+
+describe('templateQueryViaDriver', () => {
+  test('mysql2 transforms template into ? placeholders', async () => {
+    const calls: Array<{ sql: string; params: unknown[] }> = [];
+    const conn = tagConnection(
+      {
+        query: async (sql: string, params: unknown[]) => {
+          calls.push({ sql, params });
+          return [[{ id: 7 }], []];
+        },
+      },
+      'mysql2',
+    );
+
+    const strings = Object.assign(['SELECT * FROM t WHERE id = ', ''], {
+      raw: ['SELECT * FROM t WHERE id = ', ''],
+    }) as unknown as TemplateStringsArray;
+
+    const rows = await templateQueryViaDriver(conn, strings, [7]);
+    expect(rows).toEqual([{ id: 7 }]);
+    expect(calls).toEqual([
+      { sql: 'SELECT * FROM t WHERE id = ?', params: [7] },
+    ]);
+  });
+
+  test('callable connection invoked directly as tagged template', async () => {
+    let received: unknown[] = [];
+    const conn = tagConnection(
+      Object.assign(
+        async (_strings: TemplateStringsArray, ...values: unknown[]) => {
+          received = values;
+          return [{ ok: 1 }];
+        },
+      ),
+      'bun-sql',
+    );
+
+    const strings = Object.assign(['SELECT ', ''], {
+      raw: ['SELECT ', ''],
+    }) as unknown as TemplateStringsArray;
+
+    const rows = await templateQueryViaDriver(conn, strings, [99]);
+    expect(rows).toEqual([{ ok: 1 }]);
+    expect(received).toEqual([99]);
+  });
+});
+
+describe('healthCheckViaDriver', () => {
+  test('mysql2 health check runs SELECT 1', async () => {
+    const conn = tagConnection(
+      {
+        query: async () => [[{ '1': 1 }], []],
+      },
+      'mysql2',
+    );
+    expect(await healthCheckViaDriver(conn)).toBe(true);
+  });
+
+  test('returns false when query throws', async () => {
+    const conn = tagConnection(
+      {
+        query: async () => {
+          throw new Error('down');
+        },
+      },
+      'mysql2',
+    );
+    expect(await healthCheckViaDriver(conn)).toBe(false);
+  });
+});
+
+describe('closeViaDriver', () => {
+  test('mysql2 connection closed via .end()', async () => {
+    let ended = false;
+    let closed = false;
+    const conn = tagConnection(
+      {
+        end: async () => {
+          ended = true;
+        },
+        close: async () => {
+          closed = true;
+        },
+      },
+      'mysql2',
+    );
+    await closeViaDriver(conn);
+    expect(ended).toBe(true);
+    expect(closed).toBe(false);
+  });
+
+  test('bun-sql connection closed via .close()', async () => {
+    let closed = false;
+    const conn = tagConnection(
+      {
+        close: async () => {
+          closed = true;
+        },
+      },
+      'bun-sql',
+    );
+    await closeViaDriver(conn);
+    expect(closed).toBe(true);
+  });
+});

package/tests/database/orm.test.ts

@@ -11,6 +11,7 @@ import {
 } from '../../src/database/orm';
 import { DatabaseService, DATABASE_SERVICE_TOKEN } from '../../src/database';
 import { Container } from '../../src/di/container';
+import { initRuntime } from '../../src/platform/runtime';
 
 // 测试实体
 @Entity('test_users')
@@ -71,6 +72,9 @@ describe('BaseRepository', () => {
   let databaseService: DatabaseService;
 
   beforeEach(async () => {
+    // DatabaseService.initialize() 会读取 getRuntime()，确保运行时已初始化
+    // （避免依赖其他测试文件的执行顺序）
+    initRuntime('bun');
     container = new Container();
     databaseService = new DatabaseService({
       database: {