使用 DbGate 管理 Cloudflare D1 数据库

Published: 2026-10-19 | Jan Procházka

Cloudflare D1 是一种位于 Cloudflare Workers 附近的无服务器 SQL 数据库。它使用 SQLite，无需配置服务器，而且在应用规模扩大之前可以免费使用。但它缺少方便查看数据的工作界面。Cloudflare 控制台只有基本的查询功能，Wrangler 可以从命令行运行 SQL，两者都不是完整的数据库工具。

本指南介绍 D1 适合做什么、有哪些限制，以及如何将它连接到 DbGate，像管理其他数据库一样浏览、查询、编辑和备份 D1 数据库。

DbGate Premium 从 7.3.0 版开始支持 Cloudflare D1；D1 数据库的备份与恢复功能在 7.3.2 版加入。

什么是 Cloudflare D1？

D1 是 Cloudflare 基于 SQLite 构建的托管数据库。每个 D1 数据库都是由 Cloudflare 存储和复制的完整 SQLite 数据库。只需单击一次或运行 wrangler d1 create 即可创建数据库，然后将其绑定到 Worker，并使用普通 SQL 查询。

D1 提供以下能力：

• SQLite 功能 – 熟悉的 SQLite SQL 方言、数据类型和函数，包括 JSON 函数及使用 FTS5 的全文搜索
• 无需管理基础设施 – 不必管理服务器、连接池、补丁或容量规划
• 按使用量计费 – 根据读取行数、写入行数和存储空间付费，并提供充裕的免费额度
• 大量小型数据库 – 一个账户可容纳数千个数据库，因此为每个租户或用户设置独立数据库是可行的
• Time Travel – 无需配置备份，即可恢复到保留期内的任意一分钟（付费计划为 30 天）
• 读取副本 – 可在其他地区启用读取副本，降低全球用户的读取延迟
• 与 Workers 深度集成 – Worker 通过绑定访问数据库，无需在代码中保存凭据，也无需配置网络

访问 D1 数据库有三种方式：

1. Worker 绑定 – 生产环境中应用访问 D1 的方式
2. Wrangler CLI – 用于开发期间的迁移和临时命令
3. Cloudflare REST API – 用于从 Cloudflare 外部进行管理；DbGate 使用这种方式连接

需要了解的限制

D1 使用 SQLite，但它不是本地 SQLite 文件。选择前请确认其限制适合你的应用。以下数值截至本文撰写时有效；最新数值请参阅 D1 官方限制页面。

• 数据库大小 – 付费计划中单个数据库最多 10 GB，免费计划中最多 500 MB。D1 适合通过多个较小的数据库扩展，而不是把单个数据库扩大到很大。
• 同时只能有一个写入者 – 每个数据库依次处理查询。因此吞吐量取决于查询速度；耗时较长的查询会阻塞后续查询。
• 不支持交互式事务 – 不能先执行 BEGIN、进行一些操作，再稍后执行 COMMIT。D1 会以原子方式执行一批语句：要么全部成功，要么全部不生效。
• 语句和值的大小 – 单条 SQL 语句最长 100 KB，单行、字符串或 BLOB 最大 2 MB。大文件应放在 R2，而不是 D1。
• 查询时长 – 单次查询最长运行 30 秒。
• 按扫描行数计费 – 计费依据是查询读取的每一行，而不仅仅是返回的行。对大表进行全表扫描会增加费用，因此索引尤为重要。
• 不支持文件级 SQLite 功能 – 不允许使用 ATTACH DATABASE、加载扩展或写入 sqlite_master。外键始终强制检查；可在批处理中使用 PRAGMA defer_foreign_keys = on，而不是 PRAGMA foreign_keys = OFF。
• 保留名称 – 以 _cf_ 开头的表由 Cloudflare 内部使用，无法读取或修改。
• REST API 速率限制 – REST API 受 Cloudflare 全局 API 速率限制约束。它面向管理和工具，不适合处理生产流量。应用应使用 Worker 绑定。

典型使用场景

如果应用已运行在 Cloudflare 上，或者数据天然可以拆分为多个小型独立数据库，D1 尤其合适：

• Workers 和 Pages 的后端 – 为运行在边缘网络上的 Web 应用存储用户账户、设置、内容和订单
• 每个租户一个数据库 – 为 SaaS 应用的每个客户提供独立数据库，便于隔离、删除和导出数据
• 内容与配置存储 – 博客、CMS 内容、功能开关、重定向等以读取为主的数据，最好通过读取副本提供服务
• 原型和个人项目 – 免费额度和简单设置便于快速开始，之后再逐步扩展
• 轻量级分析与日志 – 计数器、事件和审计日志，前提是每个数据库都保持在大小限制以内
• 其他数据的边缘缓存 – 在靠近用户的位置保存主数据库中部分数据的 SQLite 副本

D1 不适合单个大型、写入密集的 OLTP 数据库、需要长时间交互式事务的工作负载，或存储大型二进制文件。这些需求更适合 PostgreSQL、MySQL 或其他传统数据库，也可以通过 Cloudflare Hyperdrive 连接。

将 DbGate 连接到 Cloudflare D1

DbGate 通过 Cloudflare REST API 连接 D1。一个连接对应一个 Cloudflare 账户，并显示 API 令牌有权访问的所有 D1 数据库。

第 1 步 – 查找账户 ID

1. 登录 Cloudflare 控制台。
2. 打开 Storage & Databases | D1 SQL Database，或打开账户主页。
3. 复制 Account ID。它显示在账户详情中，也包含在控制台 URL 中（dash.cloudflare.com/<account-id>/...）。

第 2 步 – 创建 API 令牌

1. 前往 My Profile | API Tokens，单击 Create Token。
2. 选择 Create Custom Token。
3. 在 Permissions 下添加 Account | D1 | Edit。如果只需读取数据，选择 Read 即可。
4. 在 Account Resources 下选择数据库所在的账户。
5. 可选：将令牌限制为你的 IP 地址，并设置过期日期。
6. 创建并复制令牌。Cloudflare 只会显示一次。

请为 DbGate 单独创建令牌，以便在不影响部署流程使用的令牌的情况下撤销它。

第 3 步 – 在 DbGate 中创建连接

1. 在 DbGate 中单击 New connection。
2. 选择 Cloudflare D1 作为连接类型。
3. 填写 Cloudflare Account ID 和 Cloudflare API Token。
4. 除非需要通过自定义端点访问 API，否则将 Cloudflare API URL 留空。默认地址为 https://api.cloudflare.com/client/v4。
5. 如果网络需要，在连接设置中配置 HTTP 代理。
6. 可选：勾选 Is read only，防止意外修改数据。
7. 单击 Test，然后单击 Save（或 Connect）。

连接后，DbGate 会列出该账户中令牌可访问的所有 D1 数据库。展开数据库即可查看表、视图，以及它们的列、索引和外键。

如果连接失败，DbGate 会尽量说明原因：令牌无效或已过期、令牌缺少 D1 权限、账户 ID 错误，或数据库已不存在。

在 DbGate 中管理 D1

DbGate 在内部将 D1 视为使用不同传输方式的 SQLite。数据浏览器、SQL 生成和模式分析与本地 SQLite 文件相同，因此大部分 SQLite 操作方式都适用。

浏览和编辑数据

在数据浏览器中打开任意表，可以筛选、排序和搜索行，沿外键跳转到关联记录，或直接在表格中编辑值。保存时，修改才会写入 D1。

D1 按读取行数收费，因此浏览大表时应使用筛选条件和已建立索引的列，而不是滚动浏览所有数据。

查看数据库模式

DbGate 会加载完整的数据库结构，包括表、列、主键、外键、索引和视图。每次查询 D1 都会产生一个 HTTPS 请求，因此 DbGate 预先规划模式分析，并用少量批量请求代替数百次独立查询。对一般大小的数据库，完整分析只需两次请求。

Cloudflare 内部的 _cf_* 表会在模式中隐藏，因此你只会看到自己的对象。

运行 SQL 查询

打开 D1 数据库的查询编辑器，像往常一样编写 SQLite SQL，并使用基于已加载模式的代码补全。运行包含多条语句的脚本时，DbGate 会将它们作为一个批次发送给 D1。D1 会原子地执行该批次：脚本要么全部完成，要么完全不执行。

请注意：

• 显式的 BEGIN、COMMIT、ROLLBACK 和 SAVEPOINT 语句会被拒绝并显示明确提示，因为 D1 API 不支持交互式事务。D1 连接中也会隐藏事务按钮。
• 对标记为 Is read only 的连接，DbGate 只允许 SELECT、EXPLAIN 和读取模式的 PRAGMA 语句。其他语句在发送到 Cloudflare 之前就会被拒绝。要进一步加强保护，请使用具有 D1 | Read 权限的 API 令牌。
• EXPLAIN QUERY PLAN 可以显示查询使用索引还是扫描整张表，这会直接影响 D1 的费用。

导出和导入数据

查询结果和表可以导出为 CSV、Excel、JSON 以及 DbGate 支持的其他格式，也可以将文件中的数据导入 D1 表。这适用于一次性数据修复、报表，以及在 D1 与 DbGate 中连接的其他数据库之间迁移数据。

备份 D1 数据库

Time Travel 可以在保留期内帮助你从错误中恢复，但不会提供一个可长期保存、归档或在其他地方打开的文件。DbGate 可以将 D1 数据库备份为普通 SQL 文件：

1. 在连接树中右键单击数据库。
2. 选择 Create database backup。
3. 选择要包含的内容：模式、数据、数据库设置和 rowid；这些选项与本地 SQLite 备份相同。
4. 开始备份。

结果是普通的 SQLite SQL 脚本。你可以将它恢复到另一个 D1 数据库，使用命令行工具 sqlite3 打开，或加载到本地 SQLite 文件用于开发和调试。

恢复到 D1

DbGate 也能将 SQL 转储恢复到 D1 数据库，无论该备份由 DbGate 创建，还是来自其他来源的 SQLite 转储。右键单击目标数据库，选择 Restore database backup，然后选取 SQL 文件。

D1 无法直接接受原始转储，因此 DbGate 会在恢复时进行调整：

• 转储按每批最多 250 条语句（且最多 1 MB）发送。每批都作为一个 D1 事务运行，所以失败的批次不会留下部分写入。
• 转储中的事务语句会被跳过，因为每个批次都有自己的事务。
• 按照 Cloudflare 对导入的建议，使用 PRAGMA defer_foreign_keys = on 将外键检查推迟到每批结束。
• 跳过名称以保留前缀 _cf_ 开头的对象。
• D1 可能拒绝写入的语句（例如 AUTOINCREMENT 计数器、统计信息或 user_version）会在数据之后执行，相关问题只作为警告报告。
• 启用 Stop on first error 时，恢复会在第一个失败批次停止；否则会继续执行并在最后报告所有失败。

有两类内容无法通过 D1 的 SQL API 恢复：INSERT 语句超过 D1 的 100 KB 限制的行（通常包含较大的文本或 BLOB 值），以及转储通过 PRAGMA writable_schema 重建的虚拟表。DbGate 会明确报告这些情况，而不会悄然失败。

结合备份和恢复，还可以轻松地将本地 SQLite 数据库迁移到 D1：用 DbGate 备份本地文件，再将 SQL 文件恢复到空的 D1 数据库。反向操作也可行，例如将生产环境的 D1 数据复制到本地 SQLite 文件用于测试。

只读连接不允许执行恢复。

安全注意事项

• API 令牌与连接一起存储，方式与其他 DbGate 凭据相同。不要分享令牌，最好将其限制为 D1 权限、单个账户，并尽可能限制为你的 IP 地址。
• DbGate 确保令牌不会出现在日志或错误消息中。
• 在 DbGate Team Premium 中，你可以在服务器上统一设置 D1 连接，并控制哪些用户和角色可以使用它，而不必向每位团队成员分发 API 令牌。

总结

Cloudflare D1 让每个 Worker、项目或租户拥有独立 SQL 数据库变得简单。DbGate 让这些数据库易于管理：只需账户 ID 和 API 令牌，就能浏览模式、在表格中编辑数据、运行 SQL、导入导出数据，以及备份和恢复。这些功能都在你已用来管理 PostgreSQL、MySQL、SQL Server、SQLite 等数据库的同一工具中。

下载 DbGate，用你的 D1 数据库试一试。