快速指南:Bun + SQLite 配置

需要为你的 Bun 项目配置一个快速、无依赖的数据库吗?配置 Bun SQLite 只需几分钟,就能为你提供一个强大的本地数据库,无需外部依赖或复杂配置。以下是开始使用 bun:sqlite 并将其集成到项目中所需的全部内容。

Bun SQLite 入门

内置的 bun:sqlite 模块提供了一个同步、高性能的 SQLite 驱动,非常适合本地开发、原型设计和小型生产应用。无需 npm 包——它已经是 Bun 的一部分。

基本数据库连接

import { Database } from "bun:sqlite"

// Create or open a database file
const db = new Database("app.db")

// Or use an in-memory database for testing
const memDb = new Database(":memory:")

就是这样——你现在已经有了一个可用的 Bun SQLite 数据库连接。如果数据库文件不存在,会自动创建。

使用 bun:sqlite 运行第一个查询

创建表和基本操作

// Create a table
db.run(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE
  )
`)

// Insert data using parameters (prevents SQL injection)
const insertUser = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
insertUser.run("Alice", "alice@example.com")

// Query data
const getUser = db.prepare("SELECT * FROM users WHERE name = ?")
const user = getUser.get("Alice")
console.log(user) // { id: 1, name: "Alice", email: "alice@example.com" }

// Get all results
const allUsers = db.prepare("SELECT * FROM users").all()

Bun SQLite API 默认使用预处理语句,使你的查询既安全又快速。.get() 方法返回单行数据,而 .all() 返回所有匹配行的数组。

使用事务

对于需要一起成功或失败的操作,使用事务:

const insertMany = db.transaction((users) => {
  const stmt = db.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
  for (const user of users) {
    stmt.run(user.name, user.email)
  }
})

// This either inserts all users or none
insertMany([
  { name: "Bob", email: "bob@example.com" },
  { name: "Charlie", email: "charlie@example.com" }
])

Bun SQLite 高级特性

使用命名参数

命名参数使复杂查询更具可读性:

const query = db.prepare(`
  SELECT * FROM users 
  WHERE name = $name AND email = $email
`)

const result = query.get({
  $name: "Alice",
  $email: "alice@example.com"
})

处理不同的返回类型

Bun SQLite 提供多种检索数据的方法:

const stmt = db.prepare("SELECT * FROM users")

// Get first row as object
const firstUser = stmt.get()

// Get all rows as objects
const allUsers = stmt.all()

// Get values as arrays (useful for data processing)
const values = stmt.values()
// Returns: [[1, "Alice", "alice@example.com"], [2, "Bob", "bob@example.com"]]

// Execute without returning results (for INSERT/UPDATE/DELETE)
stmt.run()

与 Drizzle ORM 集成

对于大型项目,将 bun:sqlite 与 Drizzle ORM 结合使用可以提供类型安全和更好的开发体验:

// Install Drizzle
// bun add drizzle-orm drizzle-kit

import { drizzle } from 'drizzle-orm/bun-sqlite'
import { Database } from 'bun:sqlite'

const sqlite = new Database('app.db')
const db = drizzle(sqlite)

// Now use Drizzle's type-safe query builder
const users = await db.select().from(usersTable)

最佳实践和性能提示

始终关闭连接

虽然 Bun SQLite 在垃圾回收期间会自动关闭数据库,但显式关闭它们是一个好习惯:

// When done with the database
db.close()

使用预处理语句

Bun SQLite 中的预处理语句会被缓存和重用,为重复查询提供更好的性能:

// Good: Prepare once, use many times
const stmt = db.prepare("SELECT * FROM users WHERE id = ?")
for (const id of userIds) {
  const user = stmt.get(id)
  // Process user
}

// Less efficient: Creating new statement each time
for (const id of userIds) {
  const user = db.prepare("SELECT * FROM users WHERE id = ?").get(id)
}

选择正确的存储模式

• 使用基于文件的数据库 (Database("app.db")) 存储持久化数据
• 使用内存数据库 (Database(":memory:")) 用于测试或临时数据
• 使用只读模式 (Database("data.db", { readonly: true })) 用于静态数据集

总结

Bun SQLite 为本地数据库操作提供了所需的一切,无需外部依赖。无论你是在构建 CLI 工具、API 原型还是小型生产服务,内置的 bun:sqlite 模块都能在简单性和性能之间提供完美的平衡。从同步 API 开始快速编写脚本,然后在需要类型安全和迁移时添加 Drizzle ORM。只需几行代码,你就拥有了一个功能完整、随时可用的 SQL 数据库。

常见问题

Bun SQLite 能处理多个进程的并发数据库访问吗?

Bun SQLite 使用 SQLite 的默认锁定机制,支持多个读取者但同一时间只有一个写入者。对于大量并发写入,可以考虑在打开数据库后运行 db.run('PRAGMA journal_mode = WAL') 来使用 WAL 模式。

Bun SQLite 的性能与 Node.js SQLite 库相比如何?

由于其原生实现和同步 API,Bun SQLite 通常比 Node.js SQLite 库快 2-3 倍。内置特性消除了 JavaScript 到原生代码的开销,使其在本地数据库操作中特别高效。

Bun SQLite 能处理的最大数据库大小是多少?

Bun SQLite 继承了 SQLite 的限制,支持最大 281 TB 的数据库。实际上,对于 100GB 以下的数据库,性能仍然出色。对于更大的数据集,考虑实现适当的索引并使用 PRAGMA 优化。

在生产应用中使用 Bun SQLite 安全吗?

是的,Bun SQLite 对于适当的使用场景(如单服务器应用、桌面应用和微服务)已经可以用于生产环境。对于需要多个写入节点的分布式系统,建议考虑使用 PostgreSQL 或 MySQL。