mm_sql 1.3.7 → 1.3.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Admin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,2 +1,244 @@
-# mm_sql
- sql语句帮助类，用于封装继承到mysql、sqlite、sql server的帮助类
+# mm_sql
+
+一个通用的SQL帮助类，支持通过切换db_type实现对不同数据库的操作，包括MySQL和SQLite等。
+
+## 安装
+
+```bash
+npm install mm_sql
+```
+
+## 依赖
+
+- mm_mysql: ^2.0.3
+- mm_sqlite: ^1.0.0
+
+## 使用方法
+
+### 1. 基本使用
+
+```javascript
+// 引入模块
+const Sql = require('mm_sql');
+
+// 创建实例（默认使用MySQL）
+const sql = new Sql({
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'test_db',
+  table: 'users'
+});
+
+// 初始化连接
+await sql.init();
+
+// 查询数据
+const users = await sql.get({ status: 1 }, 'created_at DESC');
+
+// 销毁连接
+await sql.destroy();
+```
+
+### 2. 切换数据库类型
+
+```javascript
+// 创建MySQL实例
+const mysqlSql = new Sql({
+  db_type: 'mysql',
+  host: 'localhost',
+  user: 'root',
+  password: 'password',
+  database: 'mysql_db',
+  table: 'users'
+});
+
+// 切换到SQLite
+const sqliteSql = mysqlSql.use('sqlite', {
+  database: 'sqlite.db',
+  table: 'users'
+});
+
+// 使用SQLite进行操作
+await sqliteSql.init();
+const data = await sqliteSql.get({});
+```
+
+### 3. 主要方法
+
+#### 查询方法
+
+```javascript
+// 查询多条数据
+const list = await sql.get({ status: 1 }, 'id DESC');
+
+// 查询单条数据
+const user = await sql.getObj({ id: 1 });
+
+// 分页查询
+const result = await sql.getCount(
+  { status: 1 },
+  'created_at DESC',
+  'id, name, email'
+);
+// result结构: { list: [...], total: 100, page: 1, size: 20, pages: 5 }
+
+// 统计
+const count = await sql.count({ status: 1 });
+```
+
+#### 增删改方法
+
+```javascript
+// 添加数据
+const addResult = await sql.add({
+  name: '张三',
+  age: 25,
+  status: 1
+});
+
+// 修改数据
+const updateResult = await sql.set(
+  { id: 1 }, // 查询条件
+  { name: '李四', age: 26 } // 更新字段
+);
+
+// 删除数据
+const deleteResult = await sql.del({ id: 1 });
+
+// 添加或修改（如果存在则修改，不存在则添加）
+const addOrSetResult = await sql.addOrSet(
+  { id: 1 }, // 查询条件
+  { name: '王五', age: 27 } // 要设置的字段
+);
+```
+
+#### 批量操作
+
+```javascript
+// 批量添加
+const addListResult = await sql.addList([
+  { name: '用户1', status: 1 },
+  { name: '用户2', status: 1 }
+]);
+
+// 批量修改
+const setListResult = await sql.setList([
+  { query: { id: 1 }, item: { status: 0 } },
+  { query: { id: 2 }, item: { status: 0 } }
+]);
+
+// 批量删除
+const delListResult = await sql.delList([
+  { query: { id: 1 } },
+  { query: { id: 2 } }
+]);
+```
+
+#### 模型操作
+
+```javascript
+// 获取模型对象
+const model = await sql.getObj({ id: 1 });
+
+// 直接修改模型属性会自动更新到数据库
+model.name = '新名称'; // 自动执行UPDATE操作
+model.age += 1; // 自动执行UPDATE操作，增加年龄
+```
+
+### 4. 配置选项
+
+```javascript
+const sql = new Sql({
+  // 数据库类型
+  db_type: 'mysql', // 可选值: 'mysql', 'sqlite'
+  
+  // 表相关配置
+  table: 'users', // 表名
+  key: 'id', // 主键
+  
+  // 分页配置
+  page: 1, // 默认页码
+  size: 20, // 默认每页数量
+  limit: 1000, // 最大查询数量
+  
+  // MySQL配置
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: '',
+  database: '',
+  charset: 'utf8mb4',
+  
+  // SQLite配置
+  database: 'db.sqlite', // SQLite数据库文件路径
+  
+  // 其他配置
+  filter: {}, // 过滤参数
+  separator: '|' // 分隔符，用于多条件查询
+});
+```
+
+## 事务操作
+
+```javascript
+// MySQL事务示例
+const mysqlTransactionResult = await sql.exec(`
+  START TRANSACTION;
+  INSERT INTO users (name, age) VALUES ('测试用户', 30);
+  UPDATE users SET status = 1 WHERE id = LAST_INSERT_ID();
+  COMMIT;
+`);
+
+// SQLite事务示例
+const sqliteTransactionResult = await sql.exec(`
+  BEGIN TRANSACTION;
+  INSERT INTO users (name, age) VALUES ('测试用户', 30);
+  UPDATE users SET status = 1 WHERE id = last_insert_rowid();
+  COMMIT;
+`);
+
+// 注意：不同数据库的事务语法和函数可能有所不同，请根据实际使用的数据库类型调整SQL语句
+
+## 高级用法
+
+### 1. SQL模板
+
+```javascript
+// 定义SQL模板
+const sqlTemplate = {
+  name: '`name` LIKE "{0}%"',
+  age: '`age` > {0}'
+};
+
+// 使用模板构建查询条件
+const query = sql.tpl_query({ name: '张', age: 20 }, sqlTemplate);
+// 生成的查询条件: "`name` LIKE \"张%\" && `age` > 20"
+```
+
+### 2. 自定义SQL执行
+
+```javascript
+// 执行自定义查询SQL
+const result = await sql.run('SELECT * FROM users WHERE status = 1');
+
+// 执行自定义更新SQL
+const updateResult = await sql.exec('UPDATE users SET status = 0 WHERE id = 1');
+```
+
+## 注意事项
+
+1. 使用前必须先调用`init()`方法初始化连接
+2. 使用完成后应调用`destroy()`方法销毁连接，避免资源泄漏
+3. 切换数据库类型时会重新创建适配器，原来的连接会被关闭
+4. 为提高性能，系统会缓存数据库适配器，相同配置的实例会复用适配器
+
+## 支持的数据库类型
+
+- MySQL
+- SQLite
+
+## 许可证
+
+MIT