用途
bun-sqlite 用于在 Bun 运行时中使用内置的高性能 SQLite 驱动 bun:sqlite，完成数据库操作，包括建库建表、增删改查、预编译语句、事务和批量写入等任务。
主要能力
打开数据库
通过 import { Database } from "bun:sqlite" 引入，支持多种打开方式：
- 文件数据库：
new Database("data.sqlite") - 内存数据库：
new Database(":memory:") - 只读模式：
new Database("data.sqlite", { readonly: true }) - 不存在时创建（默认行为）：
new Database("new.sqlite", { create: true }) - 严格模式（推荐）：
new Database("strict.sqlite", { strict: true })
运行查询
- 直接执行：
db.run()用于 INSERT、UPDATE、DELETE 和 DDL；返回结果包含changes（受影响行数）与lastInsertRowid（最后插入的 ID）。 - 预编译语句（推荐）：
db.prepare()创建语句，可重复使用。
查询方法
对预编译语句可使用：
.get()：返回第一行或 null.all()：返回全部行数组.values()：以数组形式返回行数据（非对象）.iterate()：返回迭代器，适合大结果集，节省内存.run()：执行且不返回数据
参数绑定
支持位置参数 ? 与命名参数 $name、:name、@name。命名参数传入对象时键名不带前缀（如 { name: "Dave" }）。
事务
通过 db.transaction() 包装函数创建事务，支持三种模式：
tx.deferred()：默认，延迟到首次写入才加锁tx.immediate()：事务开始时立即加锁tx.exclusive()：独占锁，阻塞其他连接
批量操作与性能
可开启 WAL 模式提升并发性能：db.run("PRAGMA journal_mode = WAL")。结合事务进行批量插入。其他性能相关 PRAGMA 包括 synchronous = NORMAL、cache_size、foreign_keys = ON。
列类型映射
- INTEGER → number | bigint
- REAL → number
- TEXT → string
- BLOB → Uint8Array
- NULL → null
大整数可能返回 bigint。可通过 stmt.columnNames 获取列名，并支持 TypeScript 类型注解：
const typedStmt = db.prepare<{ id: number; name: string }, [number]>(
"SELECT id, name FROM users WHERE id = ?"
);
错误处理
引入 SQLiteError 进行捕获，error.code 可区分错误类型（如 SQLITE_CONSTRAINT_UNIQUE）。
数据库管理
db.close()：关闭数据库db.inTransaction：判断是否在事务中db.serialize()：序列化为 Buffer 用于备份Database.deserialize(data)：从 Buffer 恢复db.filename：获取路径或:memory:
常见模式
资料给出 Repository 模式示例，将预编译语句集中管理，封装 findById、findAll、create 等方法。
常见错误对照
SQLITE_CONSTRAINT：约束冲突，检查 UNIQUE/外键SQLITE_BUSY/database is locked：并发访问，启用 WAL 并加重试no such table：表不存在，先执行 CREATE TABLE
使用方式
在 Bun 项目中通过 bun:sqlite 模块导入 Database 使用，无需额外安装依赖。
适用场景
适合 Bun 应用中的本地数据持久化、结构化数据查询、事务控制与批量写入等场景。
限制
资料未提供关于收费、平台兼容范围、并发上限或性能指标的具体说明；相关事实暂未提供。加载参考文件 references/pragmas.md 可了解性能调优、journal 模式与内存配置，加载 references/fts.md 可了解全文搜索与 FTS5 配置。