mm_mysql 2.1.0 → 2.2.0

package/README.md

@@ -1,5 +1,9 @@
 # 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)
+[![GitHub license](https://img.shields.io/github/license/qiuwenwu91/mm_mysql.svg)](https://github.com/qiuwenwu91/mm_mysql/blob/main/LICENSE)
 
 ## 安装
 
@@ -21,20 +25,28 @@ const mysql = new Mysql({
   database: "your_database"
 });
 
-// 初始化并打开连接
-await mysql.init();
+// 打开连接（不需要调用init()方法）
 await mysql.open();
 
-// 获取数据库管理器
-const db = mysql.db();
+// 获取数据库管理器并设置表名
+const db = mysql.db().new('users', 'id');
 
 // 执行操作...
 
 // 使用完后关闭连接
 await mysql.close();
-await mysql.destroy();
 ```
 
+## 主要特性
+
+- 支持async/await语法，避免回调地狱
+- 提供简洁直观的API接口
+- 内置事务支持
+- 自动类型推断的表创建功能（支持int、float、varchar、text、datetime、date、time、boolean等多种数据类型）
+- 灵活的查询条件支持
+- 支持连接池管理
+- 调试模式支持
+
 ## API文档
 
 ### Mysql类
@@ -72,95 +84,104 @@ const config = {
 - `config` {Object} 配置对象
 - 返回：{Mysql} 实例本身
 
-##### init()
-初始化服务
-- 返回：{Promise} 初始化结果
-
-##### open(reset)
+##### open()
 打开数据库连接
-- `reset` {Boolean} 是否重置连接
-- 返回：{Promise} 连接结果
+- 返回：{Promise<boolean>} 连接结果
 
 ##### close()
 关闭数据库连接
-- 返回：{Promise} 关闭结果
-
-##### destroy()
-销毁服务，释放资源
-- 返回：{Promise} 销毁结果
+- 返回：{Promise<boolean>} 关闭结果
 
-##### run(sql, params)
+##### run(sql, params, timeout)
 执行查询SQL语句
 - `sql` {String} SQL语句
-- `params` {Array} 参数数组
-- 返回：{Promise|Array} 查询结果数组
+- `params` {Array} 参数数组（可选）
+- `timeout` {Number} 超时时间（毫秒，可选）
+- 返回：{Promise<Array>} 查询结果数组
 
-##### exec(sql, params)
+##### exec(sql, params, timeout)
 执行非查询SQL语句（增删改）
 - `sql` {String} SQL语句
-- `params` {Array} 参数数组
-- 返回：{Promise|Number} 影响的行数
+- `params` {Array} 参数数组（可选）
+- `timeout` {Number} 超时时间（毫秒，可选）
+- 返回：{Promise<Object>} 执行结果对象，包含affectedRows和insertId等信息
 
 ##### read(table, where, options)
 读取表数据
 - `table` {String} 表名
 - `where` {Object} 查询条件
 - `options` {Object} 选项配置
-- 返回：{Promise|Array} 查询结果
-
-##### save(file)
-保存数据库结构到SQL文件
-- `file` {Object} 文件对象（需实现hasFile、readText等方法）
-- 返回：{Promise} 保存结果
-
-##### load(file)
-从SQL文件加载数据库结构和数据
-- `file` {Object} 文件对象（需实现hasFile、readText等方法）
-- 返回：{Promise} 加载结果
+- 返回：{Promise<Array>} 查询结果
 
 ##### db()
 获取数据库管理器
 - 返回：{DB} 数据库管理器实例
 
+##### beginTransaction()
+开始事务
+- 返回：{Promise<Object>} 事务连接对象
+
+##### transaction(callback)
+执行事务
+- `callback` {Function} 事务回调函数，接收事务连接作为参数
+- 返回：{Promise<any>} 回调函数的返回结果
+
 ### DB类方法
 
-#### add(table, data)
-添加数据
+#### 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} 表名
-- `data` {Object} 数据对象
-- 返回：{Promise|Number} 新增的ID或影响行数
+- `key` {String} 主键名（可选，默认为{table}_id）
+- 返回：{DB} 数据库表管理器实例
 
-#### set(table, where, data)
-修改数据
-- `table` {String} 表名
-- `where` {Object} 条件对象
+#### add(data)
+添加数据
 - `data` {Object} 数据对象
-- 返回：{Promise|Number} 影响行数
+- 返回：{Promise<Number>} 插入的ID
 
-#### get(table, where, options)
-查询数据
-- `table` {String} 表名
-- `where` {Object} 条件对象
-- `options` {Object} 选项（fields, order, group, limit等）
-- 返回：{Promise|Array} 查询结果数组
+#### get(where, options)
+获取数据
+- `where` {Object} 条件对象（可选）
+- `options` {Object} 选项配置（可选）
+- 返回：{Promise<Array>} 查询结果
+
+#### set(data, where)
+更新数据
+- `data` {Object} 数据对象
+- `where` {Object} 条件对象（可选）
+- 返回：{Promise<Number>} 影响行数
 
-#### del(table, where)
+#### del(where)
 删除数据
-- `table` {String} 表名
-- `where` {Object} 条件对象
-- 返回：{Promise|Number} 影响行数
+- `where` {Object} 条件对象（可选）
+- 返回：{Promise<Number>} 影响行数
 
 #### exec(sql, params)
 执行SQL语句
 - `sql` {String} SQL语句
 - `params` {Array} 参数数组
-- 返回：{Promise|Object} 执行结果
+- 返回：{Promise<Object>} 执行结果
 
 #### run(sql, params)
 执行查询SQL语句
 - `sql` {String} SQL语句
 - `params` {Array} 参数数组
-- 返回：{Promise|Array} 查询结果
+- 返回：{Promise<Array>} 查询结果
 
 ### 事务操作
 
@@ -176,13 +197,68 @@ const config = {
 
 ### 使用示例
 
+#### 表创建示例
+
+```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
 const { Mysql } = require('mm_mysql');
 
 async function main() {
-  const db = new Mysql({
+  const mysql = new Mysql({
     host: "localhost",
     user: "root",
     password: "123456",
@@ -190,20 +266,21 @@ async function main() {
     debug: true
   });
   
-  await db.init();
-  await db.open();
+  await mysql.open();
   
   // 执行查询
-  const users = await db.run('SELECT * FROM users WHERE age > ?', [20]);
+  const users = await mysql.run('SELECT * FROM users WHERE age > ?', [20]);
   console.log(users);
   
   // 添加数据
-  const insertId = await db.exec('INSERT INTO users (name, age) VALUES (?, ?)', ['张三', 25]);
+  const result = await mysql.exec('INSERT INTO users (name, age) VALUES (?, ?)', ['张三', 25]);
+  console.log('Inserted ID:', result.insertId);
+  console.log('Affected rows:', result.affectedRows);
   
   // 使用db管理器
-  const dbManager = db.db();
-  dbManager.table = 'users';
-  const result = await dbManager.add({name: '李四', age: 26});
+  const db = mysql.db().new('users', 'id');
+  const newId = await db.add({name: '李四', age: 26});
+  console.log('New user ID:', newId);
   
   await db.close();
   await db.destroy();
@@ -212,47 +289,92 @@ async function main() {
 main().catch(console.error);
 ```
 
-#### 数据库结构导入导出
+#### 使用DB类的完整示例
+
+```javascript
+const { Mysql } = require('mm_mysql');
+
+async function dbClassExample() {
+  const mysql = new Mysql({
+    host: "localhost",
+    user: "root",
+    password: "123456",
+    database: "test"
+  });
+  
+  await mysql.open();
+  
+  try {
+    // 创建DB实例
+    const db = mysql.db().new('users', 'id');
+    
+    // 添加数据
+    const newId = await db.add({name: '王五', age: 30, email: 'wangwu@example.com'});
+    console.log('New user ID:', newId);
+    
+    // 获取数据
+    const user = await db.get({id: newId});
+    console.log('User:', user);
+    
+    // 更新数据
+    const updatedRows = await db.set({age: 31, email: 'wangwu_updated@example.com'}, {id: newId});
+    console.log('Updated rows:', updatedRows);
+    
+    // 删除数据
+    const deletedRows = await db.del({id: newId});
+    console.log('Deleted rows:', deletedRows);
+    
+  } finally {
+    await mysql.close();
+  }
+}
+
+dbClassExample().catch(console.error);
+```
+
+#### 事务操作示例
 
 ```javascript
 const { Mysql } = require('mm_mysql');
 
-async function exportAndImport() {
-  const db = new Mysql({
+async function transactionExample() {
+  const mysql = new Mysql({
     host: "localhost",
     user: "root",
     password: "123456",
     database: "test"
   });
   
-  await db.init();
-  await db.open();
+  await mysql.open();
   
   try {
-    // 创建文件对象（需实现相应接口）
-    const file = { /* 文件对象实现 */ };
+    // 使用transaction方法执行事务
+    const result = await mysql.transaction(async (conn) => {
+      // 在事务中执行多个操作
+      const insertResult1 = await conn.exec('INSERT INTO users (name, age) VALUES (?, ?)', ['赵六', 35]);
+      const insertResult2 = await conn.exec('INSERT INTO users (name, age) VALUES (?, ?)', ['孙七', 40]);
+      
+      // 如果都成功，返回结果
+      return { user1: insertResult1.insertId, user2: insertResult2.insertId };
+    });
     
-    // 导出数据库结构到文件
-    await db.save(file);
-    console.log('数据库结构已导出');
+    console.log('Transaction succeeded:', result);
     
-    // 从文件导入数据库结构
-    await db.load(file);
-    console.log('数据库结构已导入');
+  } catch (error) {
+    console.error('Transaction failed:', error);
   } finally {
-    await db.close();
-    await db.destroy();
+    await mysql.close();
   }
 }
 
-exportAndImport().catch(console.error);
+transactionExample().catch(console.error);
 ```
 
 ## 注意事项
 
 1. 使用前请确保已正确配置数据库连接信息
 2. 建议使用try-catch处理可能出现的错误
-3. 在程序结束时调用close()和destroy()关闭数据库连接并释放资源
+3. 在程序结束时调用close()关闭数据库连接
 4. 使用事务时，记得正确处理事务的提交和回滚
 5. 查询条件支持多种格式：
    - `_min`: 大于等于
@@ -260,7 +382,28 @@ exportAndImport().catch(console.error);
    - `_not`: 不等于
    - `_has`: IN查询
    - `_like`: LIKE查询
+6. createTable方法会根据字段值自动推断数据类型，如需更精确的类型控制，建议直接使用SQL语句
+
+## 更新日志
+
+### 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