mm_mysql 2.2.0 → 2.2.2

package/README.md

@@ -64,26 +64,22 @@ new Mysql(config)
 
 ```javascript
 const config = {
-  host: "127.0.0.1",      // 服务器地址
-  port: 3306,             // 端口号
-  user: "root",          // 连接用户名
-  password: "password",   // 连接密码
-  database: "dbname",    // 数据库名
-  multipleStatements: false,  // 是否支持多个sql语句同时操作
-  debug: false,           // 是否打印调试日志
-  charset: "utf8mb4",     // 字符集
-  timezone: "+08:00",     // 时区
-  connectionLimit: 10     // 连接池大小
+  host: "127.0.0.1",          // 服务器地址
+  port: 3306,                 // 端口号
+  user: "root",              // 连接用户名
+  password: "password",       // 连接密码
+  database: "dbname",        // 数据库名
+  charset: "utf8mb4",         // 字符集
+  timezone: "+08:00",         // 时区
+  connect_timeout: 20000,      // 连接超时时间（毫秒）
+  connection_limit: 10,        // 连接池大小
+  acquire_timeout: 20000,      // 获取连接超时时间（毫秒）
+  wait_for_connections: true   // 是否等待连接
 };
 ```
 
 #### 主要方法
 
-##### setConfig(config)
-设置数据库配置参数
-- `config` {Object} 配置对象
-- 返回：{Mysql} 实例本身
-
 ##### open()
 打开数据库连接
 - 返回：{Promise<boolean>} 连接结果
@@ -92,25 +88,23 @@ const config = {
 关闭数据库连接
 - 返回：{Promise<boolean>} 关闭结果
 
-##### run(sql, params, timeout)
+##### run(sql, params)
 执行查询SQL语句
 - `sql` {String} SQL语句
 - `params` {Array} 参数数组（可选）
-- `timeout` {Number} 超时时间（毫秒，可选）
 - 返回：{Promise<Array>} 查询结果数组
 
-##### exec(sql, params, timeout)
+##### exec(sql, params)
 执行非查询SQL语句（增删改）
 - `sql` {String} SQL语句
 - `params` {Array} 参数数组（可选）
-- `timeout` {Number} 超时时间（毫秒，可选）
-- 返回：{Promise<Object>} 执行结果对象，包含affectedRows和insertId等信息
+- 返回：{Promise<Object>} 执行结果对象，包含insertId、affectedRows和changedRows等信息
 
-##### read(table, where, options)
+##### read(table, condition, options)
 读取表数据
 - `table` {String} 表名
-- `where` {Object} 查询条件
-- `options` {Object} 选项配置
+- `condition` {Object} 查询条件（可选）
+- `options` {Object} 选项配置（可选）
 - 返回：{Promise<Array>} 查询结果
 
 ##### db()
@@ -119,13 +113,29 @@ const config = {
 
 ##### beginTransaction()
 开始事务
-- 返回：{Promise<Object>} 事务连接对象
+- 返回：{Promise<Object>} 事务连接对象，包含connection、commit、rollback方法
 
 ##### transaction(callback)
 执行事务
 - `callback` {Function} 事务回调函数，接收事务连接作为参数
 - 返回：{Promise<any>} 回调函数的返回结果
 
+##### getConn()
+获取数据库连接（内部使用）
+- 返回：{Promise<Object>} 数据库连接对象
+
+##### getPoolStats()
+获取连接池状态信息
+- 返回：{Object} 连接池状态对象
+
+##### healthCheck()
+健康检查
+- 返回：{Promise<Object>} 健康检查结果
+
+##### init()
+初始化MySQL服务（兼容性方法）
+- 返回：{Promise<void>}
+
 ### DB类方法
 
 #### createTable(model, options)
@@ -187,13 +197,57 @@ const config = {
 
 #### beginTransaction()
 开始事务
-- 返回：{Promise} 事务结果
+- 返回：{Promise<Object>} 事务连接对象，包含connection、commit、rollback方法和_is_ended状态检查
 
-#### transaction(sql, params)
-在事务中执行SQL
-- `sql` {String|Array} SQL语句或语句数组
-- `params` {Array} 参数数组
-- 返回：{Promise} 执行结果
+#### transaction(callback)
+执行事务
+- `callback` {Function} 事务回调函数，接收事务连接对象作为参数
+- 返回：{Promise<any>} 回调函数的返回结果
+
+事务连接对象包含以下方法：
+- `connection` {Object} - 数据库连接对象
+- `commit()` {Function} - 提交事务
+- `rollback()` {Function} - 回滚事务
+- `_is_ended()` {Function} - 检查事务是否已结束
+
+### Mysql管理器
+
+#### mysqlAdmin(scope, config)
+获取Mysql管理器实例
+- `scope` {String} 作用域名称（可选，默认为'sys'）
+- `config` {Object} 配置参数
+- 返回：{Mysql} Mysql实例
+
+使用示例：
+```javascript
+const { mysqlAdmin } = require('mm_mysql');
+
+async function example() {
+  // 获取默认作用域的Mysql实例
+  const mysql1 = mysqlAdmin('default', {
+    host: 'localhost',
+    user: 'root',
+    password: '123456',
+    database: 'test'
+  });
+  
+  // 获取另一个作用域的Mysql实例
+  const mysql2 = mysqlAdmin('backup', {
+    host: 'localhost',
+    user: 'root',
+    password: '123456',
+    database: 'backup_db'
+  });
+  
+  await mysql1.open();
+  await mysql2.open();
+  
+  // 使用实例...
+  
+  await mysql1.close();
+  await mysql2.close();
+}
+```
 
 ### 使用示例
 
@@ -349,13 +403,13 @@ async function transactionExample() {
   
   try {
     // 使用transaction方法执行事务
-    const result = await mysql.transaction(async (conn) => {
+    const result = await mysql.transaction(async (transaction) => {
       // 在事务中执行多个操作
-      const insertResult1 = await conn.exec('INSERT INTO users (name, age) VALUES (?, ?)', ['赵六', 35]);
-      const insertResult2 = await conn.exec('INSERT INTO users (name, age) VALUES (?, ?)', ['孙七', 40]);
+      const insertResult1 = await transaction.connection.execute('INSERT INTO users (name, age) VALUES (?, ?)', ['赵六', 35]);
+      const insertResult2 = await transaction.connection.execute('INSERT INTO users (name, age) VALUES (?, ?)', ['孙七', 40]);
       
       // 如果都成功，返回结果
-      return { user1: insertResult1.insertId, user2: insertResult2.insertId };
+      return { user1: insertResult1[0].insertId, user2: insertResult2[0].insertId };
     });
     
     console.log('Transaction succeeded:', result);
@@ -383,9 +437,21 @@ transactionExample().catch(console.error);
    - `_has`: IN查询
    - `_like`: LIKE查询
 6. createTable方法会根据字段值自动推断数据类型，如需更精确的类型控制，建议直接使用SQL语句
+7. 连接池模式下，建议使用mysqlAdmin方法获取实例以确保线程安全
+8. 支持连接池状态监控和健康检查，可用于系统监控
+9. 基于mysql2/promise模块，支持async/await语法
 
 ## 更新日志
 
+### v2.3.0
+- 基于mysql2/promise模块重构，提供更好的性能和稳定性
+- 改进连接池管理，支持连接池状态监控
+- 优化事务处理机制，提供更安全的事务管理
+- 新增健康检查功能，支持连接状态监控
+- 新增mysqlAdmin管理器，支持线程安全的实例管理
+- 改进错误处理机制，提供更详细的错误信息
+- 优化配置参数，支持更多mysql2原生配置选项
+
 ### v2.2.0
 - 新增createTable方法，支持多种数据类型自动推断
 - 支持boolean类型自动转换为TINYINT(1)