Skip to content

@neosjs/sqlite ​

Node.js 环境下的 SQLite 操作库,基于 sqlite3(node-sqlite3)封装。提供 Promise 化的连接、建表、增删改查接口,并统一返回 { code, msg, data } 格式的结果,适合 Node 服务端与 Electron 桌面应用的本地数据存储。

WARNING

该仓库的 package.json 中尚未声明 name 与 version,包还未正式发布到 npm。上方的包名 @neosjs/sqlite 为预期名称,安装时请以实际发布信息为准,或直接从源码构建使用。

安装 ​

sh
pnpm add @neosjs/sqlite
sh
npm i @neosjs/sqlite
sh
yarn add @neosjs/sqlite

快速上手 ​

模块默认导出一个 Sqlite 单例(同时提供 getInstance() 获取单例)。先连接数据库,再执行建表与增删改查,最后关闭连接:

ts
import Sqlite from '@neosjs/sqlite'
import { resolve } from 'node:path'

const db = Sqlite.getInstance()

async function main() {
  // 连接数据库(文件不存在时会自动创建)
  await db.connect(resolve(process.cwd(), './test.db'))

  // 建表
  await db.create('users', 'id INTEGER PRIMARY KEY AUTOINCREMENT, username VARCHAR(30) NOT NULL')

  // 插入数据
  await db.insert('users', { username: 'neosjs' })

  // 更新数据
  await db.update('users', { username: 'new-name' }, { id: 1 })

  // 条件查询
  const res = await db.select('users', { id: 1 }, 'id desc')
  console.log(res)

  // 删除数据
  await db.delete('users', { id: 1 })

  // 关闭数据库
  await db.close()
}

main()

API ​

所有异步方法均返回 Promise,成功结果为 { code: 0, msg: 'success', data },失败为 { code: -1, msg: string }。大部分方法支持可选的 callback(err, res) 回调参数。

连接与生命周期 ​

方法说明
connect(path, callback?)连接(或创建)指定路径的 SQLite 数据库文件
close()关闭数据库连接
getInstance()获取 Sqlite 单例
serialize(callback)在 serialize 队列中执行回调,保证 SQL 串行执行

原生 SQL ​

方法说明
run(sql, params?, callback?)执行写入类 SQL(INSERT / UPDATE / DELETE / DDL 等),支持 ? 占位符参数
exec(sql)一次执行多条 SQL 语句(内部串行执行)
get(sql, params?, callback?)查询一条数据,data 为单行对象
all(sql, params?, callback?)查询所有数据,data 为行对象数组
ts
// 占位符参数
const res = await db.get('SELECT * FROM users WHERE id = ?', [1])

// 多条 SQL
await db.exec(`
  CREATE TABLE IF NOT EXISTS a (id INT);
  CREATE TABLE IF NOT EXISTS b (id INT);
`)

快捷 CRUD ​

以下方法自动拼接 SQL,无需手写 SQL 语句:

方法说明
create(table, field, callback?)建表,等价于 CREATE TABLE IF NOT EXISTS table (field)
insert(table, data, callback?)插入单条数据,data 为 { 列名: 值 } 对象
update(table, data, clause, callback?)更新数据,clause 为等值条件对象,多个条件以 AND 连接
delete(table, clause, callback?)删除数据,clause 为等值条件对象
select(table, clause?, order?, callback?)查询数据,clause 为等值条件对象,order 为排序字符串(如 id desc)
drop(table, callback?)删除数据表

查询构造器 DbSQLite ​

源码 src/sqlite.ts 中另提供了一个 DbSQLite 类,通过配置对象拼接 SQL 后执行:

ts
const result = await dbSQLite.query({
  type: 'select', // select | insert | update | delete | create
  table: 'users',
  where: ['id = 1'],
  order: ['id desc'],
  limit: 10
})

TIP

在 Electron 中使用时,建议把数据库文件放在 app.getPath('userData') 等用户数据目录下,便于随应用持久化。