mm_mysql 1.8.9 → 1.9.1

package/README.md

@@ -1,2 +1,234 @@
-# mm_mysql
-这是超级美眉mysql帮助函数模块，用于便捷操作mysql，使用await方式，可以避免嵌套函数
+# 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