mm_sqlite 1.1.4 → 1.1.6

package/README.md

@@ -7,31 +7,21 @@
 [![node version](https://img.shields.io/node/v/mm_sqlite.svg?style=flat-square)](https://nodejs.org/en/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
 
-## 特性
-
-- 🚀 **高性能优化**：经过深度优化的SQL构建器和连接管理
-- 🔄 **完全兼容**：与mm_mysql模块API完全兼容
-- 📊 **内存优化**：优化的内存使用，减少GC压力
-- 🔧 **链式调用**：流畅的SQL构建器链式调用
-- 🛡️ **错误处理**：完善的错误处理机制
-- 📈 **性能监控**：内置性能测试和内存监控
-
 ## 安装
 
-### 使用 npm
 ```bash
 npm install mm_sqlite --save
 ```
 
-### 使用 yarn
-```bash
-yarn add mm_sqlite
-```
+## 特性
 
-### 使用 pnpm
-```bash
-pnpm add mm_sqlite
-```
+- 🚀 **高性能优化**：经过深度优化的SQL构建器和连接管理
+- 🔄 **完全兼容**：与mm_mysql模块API完全兼容
+- 📊 **内存优化**：优化的内存使用，减少GC压力
+- 🔧 **链式调用**：流畅的SQL构建器链式调用
+- 🛡️ **错误处理**：完善的错误处理机制
+- 📈 **连接池支持**：支持连接池模式，提高并发性能
+- 🔒 **事务支持**：完整的事务处理机制
 
 ## 依赖要求
 
@@ -51,10 +41,23 @@ const { Sqlite } = require('mm_sqlite');
 const sqlite = new Sqlite({
     dir: './db/',                  // 数据库文件存储目录
     database: 'test',              // 数据库文件名（不包含扩展名）
-    timeout: 30000,                // 查询超时时间（毫秒）
-    retry_count: 3,                // 失败重试次数
-    conn_timeout: 30000,           // 连接超时时间（毫秒）
-    enablePerformanceLog: false    // 是否启用性能日志
+    charset: 'utf8mb4',            // 字符集
+    timezone: '+08:00',            // 时区
+    connect_timeout: 20000,        // 连接超时时间（毫秒）
+    acquire_timeout: 20000,        // 获取连接超时时间（毫秒）
+    query_timeout: 20000,          // 查询超时时间（毫秒）
+    connection_limit: 1,           // 连接限制（>1启用连接池）
+    enable_keep_alive: true,       // 启用保活
+    keep_alive_initial_delay: 10000, // 保活初始延迟
+    enable_reconnect: true,        // 启用重连
+    reconnect_interval: 1000,      // 重连间隔
+    max_reconnect_attempts: 5,     // 最大重连尝试次数
+    wait_for_connections: true,    // 等待连接
+    pool_min: 1,                   // 连接池最小连接数
+    pool_max: 5,                   // 连接池最大连接数
+    pool_acquire_timeout: 30000,   // 连接池获取超时
+    pool_idle_timeout: 60000,      // 连接池空闲超时
+    pool_reap_interval: 1000       // 连接池清理间隔
 });
 
 // 打开数据库连接
@@ -170,34 +173,38 @@ await sqlite.close();
 
 ```javascript
 // 开始事务
-await sqlite.beginTransaction();
+const transaction = await sqlite.beginTransaction();
 
 try {
-    // 插入数据
-    await sqlite.table('users').add({
-        name: '张三',
-        email: 'zhangsan@example.com',
-        status: 'active'
-    });
-
-    // 插入关联数据
-    await sqlite.table('profiles').add({
-        user_id: 1,
-        bio: '这是一个测试用户'
-    });
+    // 在事务中执行操作
+    await transaction.exec('INSERT INTO users (username, email) VALUES (?, ?)', ['张三', 'zhangsan@example.com']);
+    await transaction.exec('INSERT INTO profiles (user_id, bio) VALUES (?, ?)', [1, '这是一个测试用户']);
 
     // 提交事务
-    await sqlite.commit();
+    await transaction.commit();
 } catch (error) {
     // 回滚事务
-    await sqlite.rollback();
+    await transaction.rollback();
     console.error('事务执行失败:', error);
 }
 ```
 
-#### 复杂查询
+#### 使用事务包装器
 
 ```javascript
+// 使用事务包装器简化事务处理
+const result = await sqlite.transaction(async (transaction) => {
+    // 在事务中执行操作
+    await transaction.exec('INSERT INTO users (username, email) VALUES (?, ?)', ['李四', 'lisi@example.com']);
+    await transaction.exec('INSERT INTO profiles (user_id, bio) VALUES (?, ?)', [2, '这是另一个测试用户']);
+    
+    return { success: true };
+});
+
+console.log('事务执行结果:', result);
+```
+
+#### 复杂查询
 // 多表连接查询
 const results = await sqlite
     .table('users')
@@ -254,111 +261,170 @@ new Sqlite(config)
 **配置参数：**
 - `config.dir` - 数据库文件存储目录，默认为`'./db/'`
 - `config.database` - 数据库文件名，默认为`'mm'`
-- `config.timeout` - 查询超时时间，默认`30000ms`
-- `config.retry_count` - 失败重试次数，默认`3`
-- `config.conn_timeout` - 连接超时时间，默认`30000ms`
-- `config.enablePerformanceLog` - 是否启用性能日志，默认`false`
-- `config.debug` - 是否启用调试模式，默认`false`
+- `config.charset` - 字符集，默认为`'utf8mb4'`
+- `config.timezone` - 时区，默认为`'+08:00'`
+- `config.connect_timeout` - 连接超时时间，默认`20000ms`
+- `config.acquire_timeout` - 获取连接超时时间，默认`20000ms`
+- `config.query_timeout` - 查询超时时间，默认`20000ms`
+- `config.connection_limit` - 连接限制（>1启用连接池），默认`1`
+- `config.enable_keep_alive` - 启用保活，默认`true`
+- `config.keep_alive_initial_delay` - 保活初始延迟，默认`10000ms`
+- `config.enable_reconnect` - 启用重连，默认`true`
+- `config.reconnect_interval` - 重连间隔，默认`1000ms`
+- `config.max_reconnect_attempts` - 最大重连尝试次数，默认`5`
+- `config.wait_for_connections` - 等待连接，默认`true`
+- `config.pool_min` - 连接池最小连接数，默认`1`
+- `config.pool_max` - 连接池最大连接数，默认`5`
+- `config.pool_acquire_timeout` - 连接池获取超时，默认`30000ms`
+- `config.pool_idle_timeout` - 连接池空闲超时，默认`60000ms`
+- `config.pool_reap_interval` - 连接池清理间隔，默认`1000ms`
 
 #### 主要方法
 
 - `open(timeout)` - 打开数据库连接，返回`Promise<Boolean>`
 - `close()` - 关闭数据库连接，返回`Promise<Boolean>`
 - `getConn(timeout)` - 获取数据库连接，返回`Promise<Connection>`
-- `run(sql, params, timeout)` - 执行SQL语句（非查询操作），返回`Promise<Object>`
-- `exec(sql, params, timeout)` - 执行SQL查询，返回`Promise<Array>`
-- `beginTransaction()` - 开始事务，返回`Promise<void>`
-- `commit()` - 提交事务，返回`Promise<void>`
-- `rollback()` - 回滚事务，返回`Promise<void>`
-- `transaction(fn)` - 执行事务，返回`Promise<any>`
-- `table(tableName)` - 设置表名，返回`Sql`实例
+- `run(sql, params, timeout)` - 执行SQL查询语句，返回`Promise<Array>`
+- `exec(sql, params, timeout)` - 执行SQL语句（非查询操作），返回`Promise<Object>`
+- `read(table, condition, options)` - 读取整张表的数据，返回`Promise<Array>`
+- `db(database)` - 获取数据库操作实例，返回`DB`实例
+- `beginTransaction()` - 开始事务，返回`Promise<Object>`（事务对象）
+- `transaction(callback)` - 在事务中执行多个操作，返回`Promise<*>`
 
-### Sql类
+#### 事务对象方法
 
-#### 数据操作方法
+- `commit()` - 提交事务
+- `rollback()` - 回滚事务
+- `exec(sql, params)` - 在事务中执行SQL语句
 
-- `add(body)` - 添加单条数据，返回Promise<Object>
-- `del(query, like)` - 删除数据，返回Promise<Object>
-- `set(query, body, like)` - 更新数据，返回Promise<Object>
-- `get(query, sort, view, like, timeout)` - 查询多条数据，返回Promise<Array>
-- `getObj(query, sort, view, like, timeout)` - 获取单条记录，返回Promise<Object|null>
+### DB类
 
-#### 批量操作方法
+DB类继承自Sql类，提供SQL构建器功能。
 
-- `addList(list, lock, batchSize, timeout)` - 批量添加数据，返回Promise<Object>
-- `delList(list, like, batchSize, timeout)` - 批量删除数据，返回Promise<Object>
-- `setList(list, like, batchSize, timeout)` - 批量更新数据，返回Promise<Object>
-
-#### 统计方法
+#### 主要方法
 
-- `count(query, like, timeout)` - 统计记录数，返回Promise<Number>
-- `getCount(query, like, timeout)` - 查询数据并返回总数，返回Promise<{count: Number, data: Array}>
-- `groupCount(query, groupby, view, sort)` - 分组统计，返回Promise<Array>
-- `groupSum(query, groupby, view, sort)` - 分组求和，返回Promise<Array>
-- `groupAvg(query, groupby, view, sort)` - 分组平均值，返回Promise<Array>
+- `table(tableName)` - 设置表名，返回当前实例
+- `add(body)` - 添加单条数据，返回`Promise<Object>`
+- `del(query, like)` - 删除数据，返回`Promise<Object>`
+- `set(query, body, like)` - 更新数据，返回`Promise<Object>`
+- `get(query, sort, view, like, timeout)` - 查询多条数据，返回`Promise<Array>`
+- `getObj(query, sort, view, like, timeout)` - 获取单条记录，返回`Promise<Object|null>`
+- `addList(list, lock, batchSize, timeout)` - 批量添加数据，返回`Promise<Object>`
+- `delList(list, like, batchSize, timeout)` - 批量删除数据，返回`Promise<Object>`
+- `count(query, like, timeout)` - 统计记录数，返回`Promise<Number>`
+- `groupCount(query, groupby, view, sort)` - 分组统计，返回`Promise<Array>`
+- `groupSum(query, groupby, view, sort)` - 分组求和，返回`Promise<Array>`
+- `groupAvg(query, groupby, view, sort)` - 分组平均值，返回`Promise<Array>`
+
+#### SQL构建器方法
+
+- `select(fields)` - 设置查询字段
+- `where(condition)` - 设置查询条件
+- `orWhere(condition)` - 设置OR查询条件
+- `like(field, value)` - 设置LIKE查询条件
+- `orderBy(field, direction)` - 设置排序
+- `groupBy(field)` - 设置分组
+- `having(condition)` - 设置HAVING条件
+- `limit(count)` - 设置限制数量
+- `offset(count)` - 设置偏移量
+- `join(table, condition)` - 设置表连接
 
 ## 错误处理
 
 模块提供完善的错误处理机制：
 
+1. **参数验证**：所有公开方法都会验证输入参数，参数不符合要求时会抛出`TypeError`
+2. **SQL错误捕获**：SQL执行错误会被捕获并记录到日志中
+3. **连接错误处理**：连接失败时会自动重连，超过最大重试次数后抛出错误
+4. **事务错误处理**：事务执行失败时会自动回滚，确保数据一致性
+
+错误处理示例：
+
 ```javascript
+// 参数验证错误
 try {
-    const result = await sqlite.table('users').where({ id: 999 }).first();
-    if (!result) {
-        throw new Error('用户不存在');
-    }
-} catch (error) {
-    console.error('查询失败:', error.message);
-    // 错误码和详细信息
-    console.error('错误码:', error.code);
-    console.error('SQL语句:', error.sql);
+    await db.add(null); // 抛出TypeError
+} catch (err) {
+    console.error('参数错误:', err.message);
+}
+
+// SQL执行错误
+try {
+    await db.exec('SELECT * FROM non_existent_table');
+} catch (err) {
+    console.error('SQL错误:', err.message);
+}
+
+// 事务错误处理
+try {
+    await sqlite.transaction(async (tx) => {
+        await tx.exec('INSERT INTO users (name) VALUES (?)', ['Alice']);
+        await tx.exec('INSERT INTO users (name) VALUES (?)', [null]); // 触发错误
+    });
+} catch (err) {
+    console.error('事务执行失败:', err.message);
 }
 ```
 
 ## 性能监控
 
-模块设计注重性能优化，您可以通过以下方式监控性能：
+模块内置连接池和性能优化功能：
+
+1. **连接池管理**：自动管理数据库连接，提高并发性能
+2. **连接复用**：连接使用完毕后自动归还到连接池
+3. **连接保活**：定期检查连接状态，自动重连失效连接
+4. **超时控制**：支持连接超时、查询超时等配置
+
+连接池配置示例：
 
 ```javascript
-// 启用性能日志
 const sqlite = new Sqlite({
-    database: './data/test.db',
-    enablePerformanceLog: true
+    connection_limit: 5, // 启用连接池，最大5个连接
+    pool_min: 1,        // 最小连接数
+    pool_max: 5,        // 最大连接数
+    pool_idle_timeout: 60000, // 空闲超时60秒
+    enable_keep_alive: true,  // 启用保活
+    enable_reconnect: true    // 启用自动重连
 });
-
-// 测试特定操作的性能
-console.time('query_test');
-const results = await sqlite.table('users').get();
-console.timeEnd('query_test');
 ```
 
 对于大规模应用，建议在生产环境前进行压力测试，确保数据库操作满足性能要求。
 
 ## 兼容性
 
-- Node.js 14.0+ (推荐使用最新的LTS版本)
-- SQLite3 3.0+
-- 与mm_mysql模块API完全兼容
+- **Node.js版本**：支持 Node.js 12.0 及以上版本
+- **SQLite版本**：支持 SQLite 3.0 及以上版本
+- **操作系统**：支持 Windows、Linux、macOS
+
+## FAQ
+
+### Q: 如何处理数据库文件不存在的情况？
+A: 模块会自动创建数据库文件，无需手动创建。
 
-## 常见问题解答 (FAQ)
+### Q: 如何优化查询性能？
+A: 建议使用索引、合理设计表结构、避免全表扫描。
 
-**Q: 如何处理大量数据的插入操作？**
-A: 对于大量数据插入，建议使用`addList`方法配合事务处理，这样可以显著提高性能。
+### Q: 如何处理并发访问？
+A: 模块内置连接池机制，支持并发访问。当连接数超过1时自动启用连接池。
 
-**Q: 为什么连接池大小设置为1？**
-A: SQLite是单文件数据库，在大多数情况下单连接已经足够高效。多连接可能会导致锁竞争，反而降低性能。
+### Q: 如何备份数据库？
+A: 可以直接复制数据库文件进行备份。
 
-**Q: 如何处理数据库文件路径？**
-A: 可以使用相对路径或绝对路径。建议使用绝对路径以避免路径解析问题。
+### Q: 如何查看SQL执行日志？
+A: 启用调试模式即可查看详细的SQL执行日志。
 
-**Q: 事务处理是否支持嵌套？**
-A: 目前不支持嵌套事务，但可以在一个事务中执行多个操作。
+### Q: 连接池如何工作？
+A: 当`connection_limit`大于1时启用连接池，连接池会自动管理连接的获取和释放。
 
-**Q: 如何启用调试模式？**
-A: 在创建Sqlite实例时，设置`debug: true`配置项即可启用调试模式。
+### Q: 事务处理是否安全？
+A: 是的，事务处理包含完整的错误处理机制，失败时会自动回滚。
+
+### Q: 支持哪些SQL操作？
+A: 支持标准的CRUD操作、复杂查询、事务处理、批量操作等。
+
+## 贡献
 
-**Q: 如何处理SQLite的锁问题？**
-A: 避免长时间运行的事务，使用适当的事务隔离级别，并确保在操作完成后及时提交或回滚事务。
+欢迎提交 Issue 和 Pull Request 来改进这个模块。
 
 ## 许可证