quicklite/README.zh-CN.md

A lightweight ORM toolkit for SQLite in Node.js applications

# QuickLite

一个轻量级的 SQLite ORM 工具包，专为 Node.js 和 Electron 应用程序设计。

## 特性

- 简单高效的数据库连接管理
- 基于实体的表结构定义
- 自动表创建和迁移
- 类型安全的查询构建器
- 通用仓储模式实现 CRUD 操作
- 支持事务、索引和外键
- 除 better-sqlite3 外零依赖
- 完美适配 Electron 和 Node.js 应用

## 安装

```bash
npm install quicklite better-sqlite3
```

> 需要 Node.js v14.21.1 或更高版本。本工具包使用 better-sqlite3 v11.8.1 (包含 SQLite 3.48.0)。

## 基本用法

### 数据库连接

```typescript
import { DatabaseManager } from 'quicklite';

// 在 Node.js 中
const dbManager = DatabaseManager.getInstance({
  dbPath: './myapp.db',
  enableWAL: true,
  enableForeignKeys: true
});

// 在 Electron 中，通常在主进程中
import path from 'path';
import { app } from 'electron';

const userDataPath = app.getPath('userData');
const dbPath = path.join(userDataPath, 'database/myapp.db');

const dbManager = DatabaseManager.getInstance({
  dbPath,
  enableWAL: true,
  enableForeignKeys: true
});

// 获取数据库实例
const db = dbManager.getDatabase();
```

### 定义实体模型

```typescript
import { BaseEntity, TableInfo } from 'quicklite';

class User extends BaseEntity {
  id!: number;
  username!: string;
  email!: string;
  age?: number;
  createdAt!: number;
  
  // 定义表名
  static getTableName(): string {
    return 'users';
  }
  
  // 定义表结构
  static getTableInfo(): TableInfo {
    return {
      columns: [
        { name: 'id', type: 'INTEGER', primaryKey: true, autoIncrement: true },
        { name: 'username', type: 'TEXT', notNull: true },
        { name: 'email', type: 'TEXT', notNull: true, unique: true },
        { name: 'age', type: 'INTEGER' },
        { name: 'createdAt', type: 'INTEGER', notNull: true, default: 'CURRENT_TIMESTAMP' }
      ],
      indexes: [
        { name: 'idx_users_username', columns: ['username'] },
        { name: 'idx_users_email', columns: ['email'] }
      ]
    };
  }
}
```

### 数据库初始化和表创建

```typescript
import { DbInitializer } from 'quicklite';

// 获取数据库实例
const db = dbManager.getDatabase();

// 初始化数据库，创建所有实体对应的表
const entities = [User, Post, Comment];
const initializer = new DbInitializer(db);
initializer.initializeTables(entities);
```

### 使用服务类进行CRUD操作

```typescript
import { BaseService } from 'quicklite';

// 创建连接实例，包装数据库对象
const connection = new DbConnection(db);

// 创建服务类实例
const userService = new BaseService<User>(connection, User);

// 插入新用户
const newUser = {
  username: 'john_doe',
  email: 'john@example.com',
  age: 30,
  createdAt: Date.now()
};

const userId = userService.insert(newUser);

// 通过ID获取用户
const user = userService.findById(userId);

// 使用条件查询用户
const users = userService.find({
  where: { email: 'john@example.com' },
  orderBy: 'createdAt DESC',
  limit: 10
});

// 更新用户
userService.update({
  id: userId,
  email: 'newemail@example.com'
});

// 删除用户
userService.deleteById(userId);
```

### 使用查询构建器进行复杂查询

```typescript
import { QueryBuilder } from 'quicklite';

// 获取数据库实例
const db = dbManager.getDatabase();

// 构建复杂查询
const query = new QueryBuilder(db, 'users')
  .select('users.*', 'COUNT(posts.id) as postCount')
  .leftJoin('posts', 'posts.userId = users.id')
  .where('users.createdAt', '>', Date.now() - 30 * 24 * 60 * 60 * 1000)
  .andWhere(qb => {
    qb.where('users.username', 'LIKE', '%john%')
      .or(subQb => {
        subQb.where('users.email', 'LIKE', '%john%');
      });
  })
  .groupBy('users.id')
  .having('postCount', '>', 5)
  .orderBy('postCount', 'DESC')
  .limit(10);

// 执行查询
const activeUsers = query.all();

// 获取第一个结果
const topUser = query.first();

// 计数匹配记录
const userCount = query.count();
```

## 事务支持

```typescript
// 获取数据库实例
const db = dbManager.getDatabase();

// 创建事务
const transaction = db.transaction(() => {
  userService.insert({ username: 'user1' });
  userService.insert({ username: 'user2' });
  // 如果任何操作失败，所有更改都将回滚
});

// 执行事务
transaction();
```

## 工具类

QuickLite 提供了一系列实用工具类，用于辅助数据库操作、性能优化和数据管理。

### 备份工具 (BackupUtil)

提供 SQLite 数据库备份和恢复功能：

```typescript
import { BackupUtil } from 'quicklite';

// 备份数据库
await BackupUtil.backup(sourceDb, 'backup.db');

// 恢复数据库
await BackupUtil.restore('backup.db', targetDb);
```

### 数据传输工具 (DataTransferUtil)

提供数据导入导出和数据传输功能：

```typescript
import { DataTransferUtil } from 'quicklite';

// 将表数据导出为JSON
await DataTransferUtil.exportToJson(userService, 'users.json');

// 从JSON导入数据
await DataTransferUtil.importFromJson(userService, 'users.json');

// 将查询结果导出为CSV
await DataTransferUtil.exportQueryToCsv(
  db, 
  'SELECT * FROM users WHERE age > 30', 
  'filtered_users.csv'
);

// 在数据库之间复制表数据
await DataTransferUtil.copyTableData(
  sourceDb, 
  targetDb, 
  'users', 
  'users'
);
```

### 查询分析器 (QueryAnalyzer)

提供 SQL 查询性能分析和优化建议：

```typescript
import { QueryAnalyzer } from 'quicklite';

// 分析SQL查询
const analysis = QueryAnalyzer.analyze(
  db,
  'SELECT * FROM users WHERE age > 30'
);

console.log('执行时间:', analysis.executionTime, 'ms');
console.log('性能建议:', analysis.suggestions);

// 获取索引建议
const indexSuggestions = QueryAnalyzer.suggestIndices(
  db,
  `SELECT u.name, o.product, SUM(o.amount) as total
   FROM users u 
   JOIN orders o ON u.id = o.user_id 
   WHERE u.age > 30 
   GROUP BY u.id
   ORDER BY total DESC`
);

console.log('索引建议:', indexSuggestions);
```

#### 主要功能

1. **查询执行计划分析**：解析 SQLite EXPLAIN QUERY PLAN 输出，识别可能的性能问题
2. **索引使用检测**：检查查询是否正在使用可用索引，识别索引扫描和表扫描
3. **性能建议生成**：根据查询结构和表结构生成优化建议
4. **执行时间测量**：测量查询执行时间，帮助识别慢查询
5. **索引建议**：基于查询模式自动建议创建索引

#### 使用场景

- 优化应用程序中的关键查询
- 在开发阶段诊断潜在的性能问题
- 为复杂查询找到最佳索引策略
- 监控查询执行时间并识别瓶颈

## 文档

- [English](README.md)
- [中文文档](README.zh-CN.md)

### 详细文档

- [查询分析器](docs/zh-CN/QueryAnalyzer.md)
- [Query Analyzer English](docs/QueryAnalyzer.md)

## 许可证

MIT