3454 字
17 分钟
D1 数据库实战:给 Worker 一个原生的 SQL 数据库

开头就踩的坑:给 Worker 配一台 MySQL#

你写好了一个 Worker,想给它存点结构化数据——用户提交的表单、每次任务的运行记录、探活的历史结果。第一反应往往很自然:手头正好有台 VPS,装个 MySQL,把连接串填进 Worker 的环境变量,收工。

真跑起来才发现处处别扭:

  • Worker 没有常驻进程,它跑在 Cloudflare 的边缘节点上,每次请求由离访客最近的节点执行,位置天天在变;
  • 没有常驻进程就没有连接池,每次查询都要重新走一遍 TCP 握手、TLS 协商和数据库鉴权,数据还没查,先花几十上百毫秒在「打招呼」上;
  • 你的 MySQL 在法兰克福,请求可能从新加坡的节点发起,一来一回的物理延迟谁也救不了;
  • 数据库还得开着公网端口等连接,防火墙、白名单、弱口令扫描全套伺候,或者再套一层转发,又多一层要维护的东西;
  • 最后,这台数据库的备份、升级、监控、磁盘,全是你的活。

说到底,Worker 的运行模型和「长连接连一台固定数据库」这套老范式天生不对付。Cloudflare 给出的原生答案是 D1:一个和 Worker 同平台的 SQL 数据库,查询不走公网、不建连接,通过绑定直接调用。本篇就把 D1 从建库、建表、绑定、查询到备份恢复完整走一遍。

官方文档:https://developers.cloudflare.com/d1/

D1 是什么#

D1 是 Cloudflare 的无服务器 SQL 数据库,底层是大家熟悉的 SQLite:

  • 语法就是 SQLite:建表、索引、JOIN、聚合、事务,写法和你本地玩过的 SQLite 一模一样,从 MySQL 迁移过来主要注意方言差异(排障一节有清单);
  • 无服务器:没有实例、没有规格选型,不查询时不产生计算费用,建库就是一条命令的事;
  • 和 Worker 同平台:数据库通过「绑定」挂到 Worker 上,代码里拿 env.DB 直接发查询,中间没有网络连接、没有连接串、没有账号密码;
  • 不止 Worker 能连:Pages Functions、Wrangler 命令行、REST API 都能访问同一个库,本地调试和线上运维用同一套工具;
  • 边界也要先说清:单库容量有限(免费版单库最大 500 MB),写入是 SQLite 的单写者模型,它是给中小规模结构化数据准备的,不是拿来替代大型业务数据库的。

同样是给 Worker 存数据,D1、自建 MySQL、KV 三条路线的差别一目了然:

维度D1自建 MySQLWorkers KV
数据模型关系型,完整 SQL关系型,完整 SQL键值对
与 Worker 的连接绑定注入,无网络连接每次请求新建连接或套转发绑定注入
运维负担零运维装机、备份、升级、监控全包零运维
查询能力筛选、排序、聚合、JOIN 都行最强只能按 key 取值
一致性强一致强一致最终一致
适合场景表单、记录、历史数据等结构化存储已有 MySQL 生态、大数据量配置、缓存、读多写少的简单状态

简单记:要按条件查、要算账,选 D1;只是存个开关、缓存个结果,KV 就够;已经有一整套 MySQL 业务系统,那是另一个话题。

用 Wrangler 建库#

先装好 Wrangler 并登录。本地电脑上跑 wrangler login 会拉起浏览器授权;在服务器这类无头环境里改用 API Token 登录,Token 的创建方法见 用 API Token 给域名做 DDNS。

建库只要一条命令:

Terminal window
wrangler d1 create uptime-db

输出里会给出这个库的 database_id,并附上一段现成的绑定配置供你抄进配置文件。查看和管理已有数据库:

Terminal window
wrangler d1 list # 列出账号下所有 D1 数据库
wrangler d1 info uptime-db # 看单个库的大小、表数量等信息

把 database_id 记下来,下一步绑定要用——它长得像一串 UUID,是这个库在 Cloudflare 上的唯一身份证。

把数据库绑定到 Worker#

在 Worker 项目的 wrangler.toml 里加上绑定段:

name = "uptime-checker"
main = "src/index.js"
compatibility_date = "2026-11-01"
[[d1_databases]]
binding = "DB"
database_name = "uptime-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
migrations_dir = "migrations"

三个字段各管一件事:binding 是代码里用的名字,写 DB 就通过 env.DB 访问(Worker 的基本结构见 Workers 入门);database_name 是建库时的名字;database_id 是上一步拿到的唯一 ID。migrations_dir 指定迁移文件放哪个目录,默认就是 migrations,可以不写。一个 Worker 要用多个库,就写多段 [[d1_databases]],靠 binding 名区分。

改完配置重新部署(或重启 wrangler dev),绑定才会生效。

建表与迁移:结构变更要版本化#

表结构不要靠手敲一次性的命令凑,正经做法是「迁移」:每次结构变更生成一个带序号的 SQL 文件,跟着代码一起进版本管理,哪个环境没应用、应用到哪一步,一清二楚。

先生成一个迁移:

Terminal window
wrangler d1 migrations create uptime-db create_checks_table

它会在 migrations/ 目录下生成 0001_create_checks_table.sql,把建表语句写进去。本篇实战要用的探活结果表长这样:

CREATE TABLE IF NOT EXISTS checks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
url TEXT NOT NULL,
ok INTEGER NOT NULL,
status INTEGER,
latency_ms INTEGER,
checked_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_checks_url_time ON checks (url, checked_at);

然后把迁移应用到目标环境:

Terminal window
wrangler d1 migrations apply uptime-db --local # 先应用到本地
wrangler d1 migrations apply uptime-db --remote # 再应用到远程(线上)
wrangler d1 migrations list uptime-db --remote # 确认远程的应用状态
WARNING

本地库和远程库是两个完全独立的数据库:wrangler dev 和带 --local 的命令操作的是本机模拟环境里的数据,线上 Worker 连的是 --remote 的生产库。迁移只 apply 到本地、忘了 apply 到远程,是新手最常见的翻车点:本地一切正常,一上线就报 no such table。养成习惯,所有迁移命令都显式带上 --local 或 --remote,不要靠默认值猜。

临时查个数据、导点测试数据,用 execute 直接跑 SQL:

Terminal window
wrangler d1 execute uptime-db --remote --command "SELECT COUNT(*) AS n FROM checks;"
wrangler d1 execute uptime-db --local --file ./seed.sql

在 Worker 里查询:prepare、bind 与 batch#

绑定生效后,Worker 里查询 D1 的 API 非常小,核心就是 prepare() 准备语句、bind() 填参数,再选一个执行方法:

// 查多行:all() 返回 { results: [...] }
const { results } = await env.DB
.prepare("SELECT * FROM checks WHERE url = ? ORDER BY id DESC LIMIT ?")
.bind(url, 20)
.all();
// 查一行:first() 返回一行对象,查不到返回 null
const latest = await env.DB
.prepare("SELECT * FROM checks WHERE url = ? ORDER BY id DESC")
.bind(url)
.first();
// 写入:run() 返回的结果里 meta.changes 是影响行数,meta.last_row_id 是新行 id
const info = await env.DB
.prepare("INSERT INTO checks (url, ok, status, latency_ms) VALUES (?, ?, ?, ?)")
.bind(url, 1, 200, 123)
.run();

两个要点:

  • 参数一律走 bind(),占位符用 ?。把用户输入直接拼进 SQL 字符串,等于把 SQL 注入的大门敞开,bind 既防注入,又免去手动转义引号的麻烦;
  • 一次要执行多条语句时用 batch():把多个 prepare 好的语句放进数组一次提交,它们在一个事务里执行,要么全成功要么全回滚,省往返又保一致。

每次查询返回的结果还带一个 meta 对象,里面有 rows_read、rows_written 等计数,排查「哪条查询在烧额度」时就靠它。

实战:给探活 Worker 加一张历史表#

上一篇 Workers 进阶:Cron 定时任务与 KV 存储 里的探活 Worker,把每个站点的最新状态写进 KV,状态页够用了。但 KV 里只有「当前值」,回答不了这类问题:过去 24 小时这个站挂过几次?平均延迟多少?哪几次故障分别发生在几点?

这些都是典型的历史数据问题,正是 D1 的主场。还是那个 Worker,加上刚才迁移建好的 checks 表:定时任务每跑一轮,把每个站点的探活结果各写一行;fetch 处理函数则按条件查历史。完整代码:

const TARGETS = ["https://example.com", "https://blog.example.com"];
export default {
// 定时触发:探活并把结果逐行写入 D1
async scheduled(event, env, ctx) {
const stmts = [];
for (const url of TARGETS) {
const started = Date.now();
let ok = 0;
let status = null;
try {
const res = await fetch(url, { redirect: "follow" });
status = res.status;
ok = res.ok ? 1 : 0;
} catch (e) {
ok = 0; // 网络层失败:连不上、超时、证书错误等
}
stmts.push(
env.DB.prepare(
"INSERT INTO checks (url, ok, status, latency_ms) VALUES (?, ?, ?, ?)"
).bind(url, ok, status, Date.now() - started)
);
}
await env.DB.batch(stmts); // 一轮的结果一次事务写完
},
// HTTP 请求:返回最近 50 条探活记录
async fetch(request, env) {
const { results } = await env.DB
.prepare(
"SELECT url, ok, status, latency_ms, checked_at FROM checks ORDER BY id DESC LIMIT ?"
)
.bind(50)
.all();
return Response.json(results);
},
};

历史攒起来之后,可用率这种指标就是一条聚合查询的事:

// 某个站点最近 24 小时的总次数、成功次数和平均延迟
const row = await env.DB
.prepare(
`SELECT COUNT(*) AS total,
SUM(ok) AS ok_count,
ROUND(AVG(latency_ms)) AS avg_ms
FROM checks
WHERE url = ? AND checked_at > datetime('now', '-1 day')`
)
.bind(url)
.first();
// 可用率 = row.ok_count / row.total

KV 存「现在怎么样」,D1 存「一直以来怎么样」,两个绑在同一个 Worker 上配合,这就是上一篇探活方案的完整形态。

备份与恢复:Time Travel 与导出#

数据库最怕的不是慢,是误删。D1 自带 Time Travel:不需要手动开启、不需要排备份计划,它持续记录变更,可以把整个库恢复到过去任意一分钟的状态。保留窗口是付费版 30 天、免费版 7 天。

先按时间点查出对应的书签(bookmark):

Terminal window
wrangler d1 time-travel info uptime-db --timestamp="2026-11-15T09:30:00+08:00"

拿到书签后执行恢复:

Terminal window
wrangler d1 time-travel restore uptime-db --bookmark=00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683
WARNING

restore 会用目标时间点的状态覆盖当前数据库的全部数据,正在执行的查询会被取消,执行前务必想清楚目标时间点。好的一面是:恢复操作本身会返回一个「恢复前」的书签,万一恢复错了,还能再 restore 回去。误删一行、跑飞一条没带 WHERE 的 UPDATE、迁移把表改坏,都靠它兜底——但免费版窗口只有 7 天,过期就真的没了。

想留一份能长期保存、能脱离 Cloudflare 的备份,用导出:

Terminal window
wrangler d1 export uptime-db --remote --output ./uptime-db-backup.sql

导出的是一份标准 SQL 文件(建表语句加全部数据),随时能导回任何 SQLite 环境。每周导出一份扔进对象存储或自己的备份盘里,Time Travel 的时间窗口之外也有据可查;对象存储怎么用见 R2 对象存储。

免费额度:小项目基本用不完#

D1 按「读行数、写行数、存储量」计量,免费版(Workers Free)额度如下,数字以官方文档为准:

项目免费版额度
读取每日 500 万行
写入每日 10 万行
存储账号下所有库总计 5 GB(单库最大 500 MB)
数据库个数最多 10 个

理解额度有两个关键点:

  • 读行数按扫描行数算:一张 5000 行的表全表 SELECT 一次就是 5000 行读取,返回几行不重要。给常查的字段建索引(比如上面给 url, checked_at 建的联合索引),既提速又省额度;
  • 每日额度在 UTC 零点重置,超限后当天的查询会直接报错,想放开就升到 Workers Paid,额度立刻变成按月计算的大盘子。

拿探活实战算笔账:5 分钟探一轮、每轮写 2 行,一天写入不到 600 行,离 10 万行的上限差着两个数量级——个人和小团队项目,免费额度通常根本碰不到顶。

排障#

本地查得到数据,线上查不到(或者反过来)。 本地和远程是两个独立的库,先确认自己看的是哪一边:wrangler dev 默认连本地库,线上 Worker 连远程库;用 d1 execute 时显式带 --local 或 --remote 再查一次,多半是看错库了。

Worker 报错,说 env.DB 是 undefined。 绑定没对上:检查 wrangler.toml 里 binding 的值和代码里用的名字是否完全一致(大小写敏感),改完配置有没有重新部署。九成是这两个原因。

线上查询报 no such table: checks。 表只在本地建了,迁移没应用到远程。跑 wrangler d1 migrations list uptime-db --remote 看状态,再补一条 wrangler d1 migrations apply uptime-db --remote。

绑定了却连到空库、或者报数据库不存在。 database_id 抄错了,或者抄成了另一个库的 ID。跑 wrangler d1 list,把输出里的 ID 和配置文件逐字对一遍。

从 MySQL 搬来的 SQL 在 D1 报错。 D1 是 SQLite 方言,常见差异先过一遍:自增主键写 INTEGER PRIMARY KEY AUTOINCREMENT,没有 NOW()、用 datetime('now'),没有 AUTO_INCREMENT 和反引号那一套,字符串用单引号。逐条改完再跑。

写入报错说超过每日限额。 先看是不是有失控的循环在狂写,再对照免费额度一节算总量;确认是正常业务量增长,就升级套餐或给写入加节流。

小结#

给 Worker 配数据库,别再绕远路去自建一台远程库:D1 就在同一个平台上,建库一条命令、绑定三行配置、查询就是 prepare 加 bind,本地与远程两套环境靠迁移保持一致,误删数据还有 Time Travel 和 SQL 导出两层兜底。免费额度对个人项目相当宽裕。

能用 SQL 表达的结构化数据,就放进 D1;只存当前状态的小东西,留给 KV。两件工具都绑在同一个 Worker 上,轻量后端需要的数据层就齐了。

D1 数据库实战:给 Worker 一个原生的 SQL 数据库
https://www.anexns.cloudns.org/posts/cloudflare-d1-database/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0