SQLite 客户端

使用 sqlite（v5+）和 sqlite3 库操作 SQLite 数据库。所有 API 都返回 ES6 Promise，支持 async/await。

使用场景

• 创建 SQLite 数据库和数据表
• 执行 SQL 查询（SELECT / INSERT / UPDATE / DELETE）
• 数据库迁移
• 读取或分析 .db 文件的内容
• 从 SQLite 导入/导出数据
• 使用内存数据库进行快速原型开发

前置条件

在执行任何数据库操作之前，请确保项目已安装所需依赖：

npm install sqlite3 sqlite

快速开始

打开数据库

const sqlite3 = require('sqlite3')
const { open } = require('sqlite')

async function getDb() {
  return open({
    filename: './data.db',       // 文件路径，或使用 ':memory:' 创建内存数据库
    driver: sqlite3.Database
  })
}

使用缓存实例

driver: sqlite3.cached.Database  // 对同一文件复用连接

关闭数据库

await db.close()

核心操作

创建表与插入数据

await db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)')
await db.exec(`INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')`)

查询单行数据

const row = await db.get('SELECT * FROM users WHERE id = ?', [1])
// row = { id: 1, name: 'Alice', email: 'alice@example.com' }（若未找到则为 undefined）

查询多行数据

const rows = await db.all('SELECT * FROM users WHERE name LIKE ?', ['%li%'])
// rows = [{ id: 1, name: 'Alice', ... }]

插入一行数据

const result = await db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['Bob', 'bob@example.com'])
// result.lastID  → 新行的 ID
// result.changes → 受影响的行数

更新 / 删除行数据

const result = await db.run('UPDATE users SET name = ? WHERE id = ?', ['Bob Updated', 2])
// result.changes → 受影响的行数

await db.run('DELETE FROM users WHERE id = ?', [2])

命名参数

await db.get('SELECT * FROM users WHERE name = :name', { ':name': 'Alice' })
await db.run('INSERT INTO users (name, email) VALUES (:name, :email)', { ':name': 'Carol', ':email': 'carol@example.com' })

预编译语句

const stmt = await db.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
await stmt.run('Dave', 'dave@example.com')
await stmt.run('Eve', 'eve@example.com')
await stmt.finalize()  // 使用后必须 finalize

逐行迭代（each）

const rowCount = await db.each(
  'SELECT * FROM users',
  [],
  (err, row) => {
    if (err) throw err
    console.log(row.name)
  }
)
// rowCount → 处理的总行数

迁移

在项目目录下创建 migrations/ 文件夹，将 SQL 文件按顺序命名（例如 001-init.sql），然后执行：

await db.migrate({
  force: false,                    // 若为 true，则回滚并重新应用最新的迁移
  table: 'migrations',             // 迁移记录表的名称
  migrationsPath: './migrations'   // 迁移文件所在路径
})

迁移文件示例 migrations/001-init.sql：

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

实用函数

读取 .db 文件内容的常见模式：

// 列出所有表
const tables = await db.all("SELECT name FROM sqlite_master WHERE type='table'")

// 获取表结构
const info = await db.all(`PRAGMA table_info(${tableName})`)

// 获取行数
const { count } = await db.get(`SELECT COUNT(*) as count FROM ${tableName}`)

调试

const sqlite3 = require('sqlite3')
sqlite3.verbose()  // 启用详细日志

db.on('trace', (sql) => {
  console.log('SQL:', sql)
})

注意事项

• open() 返回的 db 对象封装了 sqlite3.Database，所有方法均返回 Promise。
• db.exec() 用于执行多条 SQL 语句（无返回值）；db.run() 用于单次写操作。
• 预编译语句在使用后必须 finalize()，以防止内存泄漏。
• SQLite 支持最大数据库文件大小为 281 TB，单行大小上限约为 1 GB。
• 对于并发写操作，可使用 WAL 模式：await db.exec('PRAGMA journal_mode=WAL')

高级参考

有关详细的 API 文档和更多使用模式，请参见 [references/api.md](references/api.md)。