当前位置：首页 > article >正文

一个轻量级的 SQLite ORM 工具包

article 2025/3/27 18:50:56

一个轻量级的 SQLite ORM 工具包，专为 Node.js 应用程序设计【Alpha版】

由来

在开发《Electron + Vite + Vue 桌面应用模板》时为了方便数据库操作延伸而来。

特性

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

后期实现

装饰器支持
实体类字段优化
初始化优化
更多实现

安装

npm install quicklite better-sqlite3

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

基本用法

数据库连接

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();

定义实体模型

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'] }
      ]
    };
  }
}

数据库初始化和表创建

import { DbInitializer } from 'quicklite';

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

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

使用服务类进行CRUD操作

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);

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

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();

事务支持

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

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

// 执行事务
transaction();

工具类

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

备份工具 (BackupUtil)

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

import { BackupUtil } from 'quicklite';

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

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

数据传输工具 (DataTransferUtil)

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

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 查询性能分析和优化建议：

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);