mm_mysql 2.1.1 → 2.2.1

package/README.md

@@ -1,5 +1,5 @@
 # mm_mysql
-这是超级美眉mysql帮助函数模块，用于便捷操作mysql，使用await方式，可以避免嵌套函数
+一个简洁、高效的Node.js MySQL操作库，支持async/await语法，提供直观的API和强大的功能扩展。
 
 [![npm version](https://badge.fury.io/js/mm_mysql.svg)](https://www.npmjs.com/package/mm_mysql)
 [![GitHub issues](https://img.shields.io/github/issues/qiuwenwu91/mm_mysql.svg)](https://gitee.com/qiuwenwu91/mm_mysql/issues)
@@ -37,6 +37,16 @@ const db = mysql.db().new('users', 'id');
 await mysql.close();
 ```
 
+## 主要特性
+
+- 支持async/await语法，避免回调地狱
+- 提供简洁直观的API接口
+- 内置事务支持
+- 自动类型推断的表创建功能（支持int、float、varchar、text、datetime、date、time、boolean等多种数据类型）
+- 灵活的查询条件支持
+- 支持连接池管理
+- 调试模式支持
+
 ## API文档
 
 ### Mysql类
@@ -54,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>} 连接结果
@@ -82,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()
@@ -109,15 +113,46 @@ 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)
+自动创建数据库表，支持多种数据类型推断
+- `model` {Object} 模型对象，包含表名和字段定义
+  - `table` {String} 表名
+  - `fields` {Object} 字段定义，支持以下数据类型：
+    - 数字类型（自动推断为INT/FLOAT）
+    - 字符串类型（自动推断为VARCHAR/TEXT/DATE/DATETIME/TIME）
+    - 布尔类型（自动推断为TINYINT(1)）
+    - Date对象（自动推断为DATETIME）
+    - 时间戳（自动推断为DATETIME）
+- `options` {Object} 选项配置（可选）
+  - `primary_key` {String} 主键字段名（可选）
+  - `if_not_exists` {Boolean} 是否仅当表不存在时创建（可选，默认为true）
+- 返回：{Promise<Object>} 执行结果
+
 #### new(table, key)
 创建数据库表管理器
 - `table` {String} 表名
@@ -162,16 +197,115 @@ 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} 配置参数
+- 返回：{Promise<Mysql>} Mysql实例
+
+使用示例：
+```javascript
+const { mysqlAdmin } = require('mm_mysql');
+
+async function example() {
+  // 获取默认作用域的Mysql实例
+  const mysql1 = await mysqlAdmin('default', {
+    host: 'localhost',
+    user: 'root',
+    password: '123456',
+    database: 'test'
+  });
+  
+  // 获取另一个作用域的Mysql实例
+  const mysql2 = await mysqlAdmin('backup', {
+    host: 'localhost',
+    user: 'root',
+    password: '123456',
+    database: 'backup_db'
+  });
+  
+  await mysql1.open();
+  await mysql2.open();
+  
+  // 使用实例...
+  
+  await mysql1.close();
+  await mysql2.close();
+}
+```
 
 ### 使用示例
 
+#### 表创建示例
+
+```javascript
+const { Mysql } = require('mm_mysql');
+
+async function createTableExample() {
+  const mysql = new Mysql({
+    host: "localhost",
+    user: "root",
+    password: "123456",
+    database: "test"
+  });
+  
+  await mysql.open();
+  
+  try {
+    // 创建数据库表管理器
+    const db = mysql.db();
+    
+    // 定义表模型
+    const userModel = {
+      table: 'users',
+      fields: {
+        id: 1,                 // 整数类型 -> INT
+        username: 'test',      // 字符串类型 -> VARCHAR(255)
+        email: 'test@example.com', // 字符串类型 -> VARCHAR(255)
+        age: 25,               // 整数类型 -> INT
+        salary: 5000.50,       // 浮点数类型 -> FLOAT
+        active: true,          // 布尔类型 -> TINYINT(1)
+        birth_date: '2000-01-01', // 日期字符串 -> DATE
+        bio: '这是一个很长的个人简介...', // 长字符串 -> TEXT
+        created_at: '2023-01-01 12:00:00', // 日期时间字符串 -> DATETIME
+        login_time: new Date(), // Date对象 -> DATETIME
+        last_active: Date.now() // 时间戳 -> DATETIME
+      }
+    };
+    
+    // 创建表
+    const result = await db.createTable(userModel, {
+      primary_key: 'id',
+      if_not_exists: true
+    });
+    
+    console.log('表创建成功:', result);
+    
+  } catch (error) {
+    console.error('创建表失败:', error);
+  } finally {
+    await mysql.close();
+  }
+}
+
+createTableExample().catch(console.error);
+```
+
 #### 基本查询操作
 
 ```javascript
@@ -269,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);
@@ -302,7 +436,40 @@ transactionExample().catch(console.error);
    - `_not`: 不等于
    - `_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)
+- 支持date字符串自动识别为DATE类型
+- 支持Date对象自动识别为DATETIME类型
+- 支持时间戳自动识别为DATETIME类型
 
 ## 许可证
 
 ISC License
+
+## 贡献
+
+欢迎提交Issue和Pull Request！
+
+## 联系方式
+
+如有问题或建议，请通过以下方式联系：
+
+- 项目地址：https://gitee.com/qiuwenwu91/mm_mysql
+- 邮箱：qiuwenwu91@163.com