第10章 Cloudflare Workers D1 数据库应用指南
文档D1
D1 是一个 SQL 数据库,Worker 通过绑定来访问它。celld 在每个 cell 内为每个数据库分配独立的 SQLite 文件。API 详情请参阅 Cloudflare D1 文档。
示例
D1 示例用 D1 数据库实现了一个留言板。
index.js
```js const SCHEMA = ` CREATE TABLE IF NOT EXISTS entries ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, message TEXT NOT NULL, at INTEGER NOT NULL ); CREATE INDEX IF NOT EXISTS entries_at ON entries (at DESC); `;
export default { async fetch(request, env) { await env.DB.exec(SCHEMA); const url = new URL(request.url);
if (request.method === "POST") { const { name, message } = await request.json(); const written = await env.DB .prepare("INSERT INTO entries (name, message, at) VALUES (?, ?, ?)") .bind(name, message, Date.now()) .run(); return Response.json({ id: written.meta.last_row_id, changes: written.meta.changes, }, { status: 201 }); }
const count = await env.DB .prepare("SELECT count(*) AS n FROM entries") .first("n"); if (url.pathname === "/count") return Response.json({ count });
const { results } = await env.DB .prepare( "SELECT id, name, message, at FROM entries ORDER BY at DESC LIMIT ?", ) .bind(20) .all(); return Response.json({ count, entries: results }); }, }; ```
wrangler.jsonc
```jsonc { "name": "d1", "main": "index.js", "compatibility_date": "2026-01-01", "d1_databases": [ { "binding": "DB", "database_name": "guestbook", "database_id": "00000000-0000-0000-0000-000000000000" } ] } ```
API
prepare(sql) 返回一个语句对象,bind(...values) 返回携带参数值的新语句对象。 all() 返回成功标志、由行对象组成的 results 数组以及 meta。 run() 是同一个方法的别名。 first() 返回第一行或 null,first(column) 返回该行中的某一列。 raw() 以数组形式返回各行,raw({ columnNames: true }) 会把列名放在第一个数组里。 batch(statements) 在一个事务中执行多条预编译语句,并为每条语句返回一个结果。 exec(sql) 执行一条或多条不带参数的语句,比如 schema。
配置与限制
d1_databases 条目包含 binding、database_name 和 database_id。celld 以 database_id 作为数据库身份,条目没有 id 时则用 database_name。两个 Worker 引用同一个身份即访问同一个数据库。celld 在首次使用时创建数据库,所以名称打错只会打开一个空库,不会报错。
bind() 会检查每个值:数字和字符串直接通过,布尔值转为 1 或 0,ArrayBuffer、类型化数组或字节数字数组转为 BLOB,其他值会抛出 D1_TYPE_ERROR。celld 支持绑定位置参数 ? 和 ?NNN。
celld 强制执行以下 D1 限制:单条语句最多 100,000 字节,最多 100 个绑定参数,每张表最多 100 列,字符串、BLOB 或单行最多 2,200,000 字节。
预编译语句中若包含第二条语句,会失败并报错 A prepared SQL statement must contain only one statement. Use exec() or batch() for more than one statement。这两种方式都在同一事务内运行,任何一处失败都会回滚整个调用。
每条语句都会路由到拥有该数据库 cell 的节点,因此每次调用消耗一次 cell dispatch。把相关语句放进一个 batch(),全部只需一次 dispatch。100,000 行的结果上限不适用于 first()。已确认的写入能在 owner 节点宕机后保留。
withSession() 总是选择主节点。getBookmark() 返回 celld:primary,meta.served_by_primary 始终为 true,meta.served_by_region 始终为 local。
应用层 SQL 不能使用 BEGIN、COMMIT、ROLLBACK、SAVEPOINT、ATTACH、DETACH、VACUUM、load_extension(),也不能创建临时表、索引、触发器或视图。celld 允许 fts5 和 fts5vocab 虚拟表,并接受 D1 SQL 语句参考中列出的 PRAGMA。
celld d1 execute 和 celld d1 migrations apply 可以通过在线节点从命令行执行 SQL。
与 Cloudflare 的差异
一次绑定调用的结果最多包含 100,000 行或 32 MiB。 不是有效 UTF-8 的 SQLite TEXT 值会以替换字符 U+FFFD 解码(与 workerd 一致),存储的字节不变。任意字节请存为 BLOB。 每个数据库只有一个写入者。要提升写入能力,请使用多个数据库。 celld 没有只读副本。withSession() 总是选择主节点,getBookmark() 返回 celld:primary。 只读语句返回的 last_row_id 和 changes 为 0。Cloudflare 会返回连接上前一次写入留下的值。 prepare() 只接受恰好一条语句。 exec() 按语句计数,Cloudflare 按输入行计数。 dump() 会抛出异常。数据库就是操作者自己 bucket 里的一个 SQLite 文件。 应用层 SQL 不能使用 BEGIN、SAVEPOINT、ATTACH、VACUUM、load_extension(),也不能创建临时表。 celld 没有 D1 REST API,也没有 Time Travel。SQL 和迁移请使用 celld d1。
Cloudflare 的兼容性页面列出了运行时 API 和不支持的服务。