mm_mysql 2.0.2 → 2.0.4

package/README.md

@@ -1,234 +1,266 @@
-# mm_mysql
-这是超级美眉mysql帮助函数模块，用于便捷操作mysql，使用await方式，可以避免嵌套函数
-
-## 安装
-
-```bash
-npm install mm_mysql
-```
-
-## 基本使用
-
-```javascript
-const { mysql_admin } = require('mm_mysql');
-
-// 创建mysql实例
-const mysql = mysql_admin();
-
-// 配置数据库连接
-mysql.setConfig({
-  host: "127.0.0.1",
-  port: 3306,
-  user: "root",
-  password: "your_password",
-  database: "your_database",
-  multipleStatements: false,
-  log: false
-});
-
-// 打开数据库连接
-mysql.open();
-
-// 获取数据库管理器
-const db = mysql.db();
-
-// 使用完后关闭连接
-mysql.close();
-```
-
-## API文档
-
-### Mysql类
-
-#### 构造函数
-
-```javascript
-new Mysql(scope, dir)
-```
-
-参数说明：
-- `scope` {String} 作用域
-- `dir` {String} 当前路径
-
-#### 配置参数
-
-```javascript
-mysql.config = {
-  host: "127.0.0.1",      // 服务器地址
-  port: 3306,             // 端口号
-  user: "root",          // 连接用户名
-  password: "password",   // 连接密码
-  database: "dbname",    // 数据库名
-  multipleStatements: false,  // 是否支持多个sql语句同时操作
-  log: false,            // 是否打印SQL语句
-  log_ignore: [1062]     // 需要排除打印的错误码
-};
-```
-
-#### 主要方法
-
-##### setConfig(config)
-设置数据库配置参数
-- `config` {Object|String} 配置对象或配置文件路径
-
-##### open(reset)
-打开数据库连接
-- `reset` {Boolean} 是否重置连接
-
-##### close()
-关闭数据库连接
-
-##### run(sql, val)
-执行查询SQL语句
-- `sql` {String} SQL语句
-- `val` {Array} 替换值
-- 返回：{Promise|Array} 查询结果数组
-
-##### exec(sql, val)
-执行增删改SQL语句
-- `sql` {String} SQL语句
-- `val` {Array} 替换值
-- 返回：{Promise|Number} 影响的行数
-
-##### db()
-获取数据库管理器
-- 返回：{DB} 数据库管理器实例
-
-##### dbs(key, value, clear_prefix, ...arr_table)
-获取关联数据库管理器
-- `key` {String} 主键
-- `value` {String|Number} 对象值
-- `clear_prefix` {Boolean} 是否清除前缀
-- `arr_table` {Array} 关联的数据表
-- 返回：{Object} 管理模型
-
-### 使用示例
-
-#### 基本查询操作
-
-```javascript
-const { mysql_admin } = require('mm_mysql');
-
-async function main() {
-  const mysql = mysql_admin();
-  mysql.setConfig({
-    host: "localhost",
-    user: "root",
-    password: "123456",
-    database: "test"
-  });
-  
-  mysql.open();
-  const db = mysql.db();
-  
-  // 设置操作的表名
-  db.table = "users";
-  
-  // 查询数据
-  const users = await db.get({id: 1});
-  console.log(users);
-  
-  // 添加数据
-  const result = await db.add({
-    name: "张三",
-    age: 25
-  });
-  
-  // 修改数据
-  await db.set({id: 1}, {name: "李四"});
-  
-  // 删除数据
-  await db.del({id: 1});
-  
-  mysql.close();
-}
-
-main().catch(console.error);
-```
-
-#### 事务操作
-
-```javascript
-const { mysql_admin } = require('mm_mysql');
-
-async function transaction() {
-  const mysql = mysql_admin();
-  mysql.setConfig({
-    host: "localhost",
-    user: "root",
-    password: "123456",
-    database: "test"
-  });
-  
-  mysql.open();
-  const db = mysql.db();
-  
-  try {
-    // 开始事务
-    await db.start();
-    
-    // 执行多个操作
-    await db.exec("INSERT INTO users (name) VALUES ('张三')");
-    await db.exec("UPDATE accounts SET balance = balance - 100 WHERE user_id = 1");
-    
-    // 提交事务
-    await db.commit();
-  } catch (err) {
-    // 发生错误时回滚
-    await db.back();
-    console.error(err);
-  } finally {
-    // 结束事务
-    await db.end();
-    mysql.close();
-  }
-}
-
-transaction().catch(console.error);
-```
-
-#### 关联查询
-
-```javascript
-const { mysql_admin } = require('mm_mysql');
-
-async function linkQuery() {
-  const mysql = mysql_admin();
-  mysql.setConfig({
-    host: "localhost",
-    user: "root",
-    password: "123456",
-    database: "test"
-  });
-  
-  mysql.open();
-  
-  // 创建关联查询管理器
-  const model = await mysql.dbs("user_id", 1, true, "users", "orders", "order_items");
-  
-  // 获取用户及其订单信息
-  const result = await model.get();
-  console.log(result);
-  
-  mysql.close();
-}
-
-linkQuery().catch(console.error);
-```
-
-## 注意事项
-
-1. 使用前请确保已正确配置数据库连接信息
-2. 建议使用try-catch处理可能出现的错误
-3. 在程序结束时调用close()关闭数据库连接
-4. 使用事务时，记得正确处理commit、back和end
-5. 查询条件支持多种格式：
-   - `_min`: 大于等于
-   - `_max`: 小于等于
-   - `_not`: 不等于
-   - `_has`: IN查询
-   - `_like`: LIKE查询
-
-## 许可证
-
-ISC License
+# mm_mysql
+这是超级美眉mysql帮助函数模块，用于便捷操作mysql，使用await方式，可以避免嵌套函数
+
+## 安装
+
+```bash
+npm install mm_mysql
+```
+
+## 基本使用
+
+```javascript
+const { Mysql } = require('mm_mysql');
+
+// 创建mysql实例
+const mysql = new Mysql({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "your_password",
+  database: "your_database"
+});
+
+// 初始化并打开连接
+await mysql.init();
+await mysql.open();
+
+// 获取数据库管理器
+const db = mysql.db();
+
+// 执行操作...
+
+// 使用完后关闭连接
+await mysql.close();
+await mysql.destroy();
+```
+
+## API文档
+
+### Mysql类
+
+#### 构造函数
+
+```javascript
+new Mysql(config)
+```
+
+参数说明：
+- `config` {Object} 数据库配置对象
+
+#### 配置参数
+
+```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     // 连接池大小
+};
+```
+
+#### 主要方法
+
+##### setConfig(config)
+设置数据库配置参数
+- `config` {Object} 配置对象
+- 返回：{Mysql} 实例本身
+
+##### init()
+初始化服务
+- 返回：{Promise} 初始化结果
+
+##### open(reset)
+打开数据库连接
+- `reset` {Boolean} 是否重置连接
+- 返回：{Promise} 连接结果
+
+##### close()
+关闭数据库连接
+- 返回：{Promise} 关闭结果
+
+##### destroy()
+销毁服务，释放资源
+- 返回：{Promise} 销毁结果
+
+##### run(sql, params)
+执行查询SQL语句
+- `sql` {String} SQL语句
+- `params` {Array} 参数数组
+- 返回：{Promise|Array} 查询结果数组
+
+##### exec(sql, params)
+执行非查询SQL语句（增删改）
+- `sql` {String} SQL语句
+- `params` {Array} 参数数组
+- 返回：{Promise|Number} 影响的行数
+
+##### 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} 加载结果
+
+##### db()
+获取数据库管理器
+- 返回：{DB} 数据库管理器实例
+
+### DB类方法
+
+#### add(table, data)
+添加数据
+- `table` {String} 表名
+- `data` {Object} 数据对象
+- 返回：{Promise|Number} 新增的ID或影响行数
+
+#### set(table, where, data)
+修改数据
+- `table` {String} 表名
+- `where` {Object} 条件对象
+- `data` {Object} 数据对象
+- 返回：{Promise|Number} 影响行数
+
+#### get(table, where, options)
+查询数据
+- `table` {String} 表名
+- `where` {Object} 条件对象
+- `options` {Object} 选项（fields, order, group, limit等）
+- 返回：{Promise|Array} 查询结果数组
+
+#### del(table, where)
+删除数据
+- `table` {String} 表名
+- `where` {Object} 条件对象
+- 返回：{Promise|Number} 影响行数
+
+#### exec(sql, params)
+执行SQL语句
+- `sql` {String} SQL语句
+- `params` {Array} 参数数组
+- 返回：{Promise|Object} 执行结果
+
+#### run(sql, params)
+执行查询SQL语句
+- `sql` {String} SQL语句
+- `params` {Array} 参数数组
+- 返回：{Promise|Array} 查询结果
+
+### 事务操作
+
+#### beginTransaction()
+开始事务
+- 返回：{Promise} 事务结果
+
+#### transaction(sql, params)
+在事务中执行SQL
+- `sql` {String|Array} SQL语句或语句数组
+- `params` {Array} 参数数组
+- 返回：{Promise} 执行结果
+
+### 使用示例
+
+#### 基本查询操作
+
+```javascript
+const { Mysql } = require('mm_mysql');
+
+async function main() {
+  const db = new Mysql({
+    host: "localhost",
+    user: "root",
+    password: "123456",
+    database: "test",
+    debug: true
+  });
+  
+  await db.init();
+  await db.open();
+  
+  // 执行查询
+  const users = await db.run('SELECT * FROM users WHERE age > ?', [20]);
+  console.log(users);
+  
+  // 添加数据
+  const insertId = await db.exec('INSERT INTO users (name, age) VALUES (?, ?)', ['张三', 25]);
+  
+  // 使用db管理器
+  const dbManager = db.db();
+  dbManager.table = 'users';
+  const result = await dbManager.add({name: '李四', age: 26});
+  
+  await db.close();
+  await db.destroy();
+}
+
+main().catch(console.error);
+```
+
+#### 数据库结构导入导出
+
+```javascript
+const { Mysql } = require('mm_mysql');
+
+async function exportAndImport() {
+  const db = new Mysql({
+    host: "localhost",
+    user: "root",
+    password: "123456",
+    database: "test"
+  });
+  
+  await db.init();
+  await db.open();
+  
+  try {
+    // 创建文件对象（需实现相应接口）
+    const file = { /* 文件对象实现 */ };
+    
+    // 导出数据库结构到文件
+    await db.save(file);
+    console.log('数据库结构已导出');
+    
+    // 从文件导入数据库结构
+    await db.load(file);
+    console.log('数据库结构已导入');
+  } finally {
+    await db.close();
+    await db.destroy();
+  }
+}
+
+exportAndImport().catch(console.error);
+```
+
+## 注意事项
+
+1. 使用前请确保已正确配置数据库连接信息
+2. 建议使用try-catch处理可能出现的错误
+3. 在程序结束时调用close()和destroy()关闭数据库连接并释放资源
+4. 使用事务时，记得正确处理事务的提交和回滚
+5. 查询条件支持多种格式：
+   - `_min`: 大于等于
+   - `_max`: 小于等于
+   - `_not`: 不等于
+   - `_has`: IN查询
+   - `_like`: LIKE查询
+
+## 许可证
+
+ISC License