开头就踩的坑:给 Worker 配一台 MySQL
你写好了一个 Worker,想给它存点结构化数据——用户提交的表单、每次任务的运行记录、探活的历史结果。第一反应往往很自然:手头正好有台 VPS,装个 MySQL,把连接串填进 Worker 的环境变量,收工。
真跑起来才发现处处别扭:
- Worker 没有常驻进程,它跑在 Cloudflare 的边缘节点上,每次请求由离访客最近的节点执行,位置天天在变;
- 没有常驻进程就没有连接池,每次查询都要重新走一遍 TCP 握手、TLS 协商和数据库鉴权,数据还没查,先花几十上百毫秒在「打招呼」上;
- 你的 MySQL 在法兰克福,请求可能从新加坡的节点发起,一来一回的物理延迟谁也救不了;
- 数据库还得开着公网端口等连接,防火墙、白名单、弱口令扫描全套伺候,或者再套一层转发,又多一层要维护的东西;
- 最后,这台数据库的备份、升级、监控、磁盘,全是你的活。
说到底,Worker 的运行模型和「长连接连一台固定数据库」这套老范式天生不对付。Cloudflare 给出的原生答案是 D1:一个和 Worker 同平台的 SQL 数据库,查询不走公网、不建连接,通过绑定直接调用。本篇就把 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 | 自建 MySQL | Workers KV |
|---|---|---|---|
| 数据模型 | 关系型,完整 SQL | 关系型,完整 SQL | 键值对 |
| 与 Worker 的连接 | 绑定注入,无网络连接 | 每次请求新建连接或套转发 | 绑定注入 |
| 运维负担 | 零运维 | 装机、备份、升级、监控全包 | 零运维 |
| 查询能力 | 筛选、排序、聚合、JOIN 都行 | 最强 | 只能按 key 取值 |
| 一致性 | 强一致 | 强一致 | 最终一致 |
| 适合场景 | 表单、记录、历史数据等结构化存储 | 已有 MySQL 生态、大数据量 | 配置、缓存、读多写少的简单状态 |
简单记:要按条件查、要算账,选 D1;只是存个开关、缓存个结果,KV 就够;已经有一整套 MySQL 业务系统,那是另一个话题。
用 Wrangler 建库
先装好 Wrangler 并登录。本地电脑上跑 wrangler login 会拉起浏览器授权;在服务器这类无头环境里改用 API Token 登录,Token 的创建方法见 用 API Token 给域名做 DDNS。
建库只要一条命令:
wrangler d1 create uptime-db输出里会给出这个库的 database_id,并附上一段现成的绑定配置供你抄进配置文件。查看和管理已有数据库:
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 文件,跟着代码一起进版本管理,哪个环境没应用、应用到哪一步,一清二楚。
先生成一个迁移:
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);然后把迁移应用到目标环境:
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:
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() 返回一行对象,查不到返回 nullconst latest = await env.DB .prepare("SELECT * FROM checks WHERE url = ? ORDER BY id DESC") .bind(url) .first();
// 写入:run() 返回的结果里 meta.changes 是影响行数,meta.last_row_id 是新行 idconst 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.totalKV 存「现在怎么样」,D1 存「一直以来怎么样」,两个绑在同一个 Worker 上配合,这就是上一篇探活方案的完整形态。
备份与恢复:Time Travel 与导出
数据库最怕的不是慢,是误删。D1 自带 Time Travel:不需要手动开启、不需要排备份计划,它持续记录变更,可以把整个库恢复到过去任意一分钟的状态。保留窗口是付费版 30 天、免费版 7 天。
先按时间点查出对应的书签(bookmark):
wrangler d1 time-travel info uptime-db --timestamp="2026-11-15T09:30:00+08:00"拿到书签后执行恢复:
wrangler d1 time-travel restore uptime-db --bookmark=00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683WARNINGrestore 会用目标时间点的状态覆盖当前数据库的全部数据,正在执行的查询会被取消,执行前务必想清楚目标时间点。好的一面是:恢复操作本身会返回一个「恢复前」的书签,万一恢复错了,还能再 restore 回去。误删一行、跑飞一条没带
WHERE的UPDATE、迁移把表改坏,都靠它兜底——但免费版窗口只有 7 天,过期就真的没了。
想留一份能长期保存、能脱离 Cloudflare 的备份,用导出:
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 上,轻量后端需要的数据层就齐了。