快速指南: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 数据库。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.