跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

发布说明

最后更新 查看 MarkdownAgent 设置

Subscribe to RSS

2025-11-05

D1 可配置辖区以实现数据本地化

您现在可以在创建 D1 数据库时设置辖区,以保证数据库的运行和数据存储位置。

2025-09-11

D1 自动重试只读查询

D1 现在会检测只读查询,并在因可重试错误而失败时自动尝试最多两次重试来执行这些查询。您可以在返回的响应元数据属性 total_attempts 中查看执行尝试次数。

目前只有只读查询会被重试,即仅包含以下 SQLite 关键字的查询:SELECT、EXPLAIN、WITH。包含任何会导致数据库写入的 SQLite 关键字的查询不会被重试。

在只读可重试错误中,重试成功率从 5% 到 95% 不等,具体取决于底层错误及其持续时间(例如网络错误或其他内部错误)。

在所有可重试错误中,重试成功率较低,这表明存在一些本可以重试的写入查询。因此,对于并非只读、但根据应用程序业务逻辑具有幂等性的查询,我们建议 D1 用户继续在自己的代码中实施重试。

D1 自动查询重试成功率

D1 确保任何重试尝试都不会导致数据库写入,因此即使有导致变更的查询绕过了只读检测,自动重试也不会产生副作用。D1 通过在每次查询执行后检查是否有修改来实现这一点;如果因重试尝试而发生了任何写入,该查询将被回滚。

目前只读查询的检测启发式规则还比较简单,在识别更多可重试的查询方面仍有改进空间,因此这只是一个开始。

2025-07-01

Workers 付费计划下每个账户的 D1 最大存储空间现为 1 TB

Workers 付费计划用户每个账户的 D1 最大存储空间已从 250 GB 提高到 1 TB。

2025-07-01

已移除对 D1 alpha 数据库备份的访问

继 2024-08-23 移除对 D1 alpha 数据库的查询访问之后,D1 alpha 数据库备份将无法再通过 wrangler v3 中提供的 wrangler d1 backup 访问或创建。

如果您希望保留 D1 alpha 数据库的备份,请在 2025-07-01 之前使用 wrangler d1 backup。D1 alpha 备份可用于迁移到新创建的、处于正式发布状态的 D1 数据库。

2025-05-30

D1 REST API 请求速度提升 50-500 毫秒

现在,D1 身份验证在接收请求的最近 Cloudflare 网络数据中心执行,因此使用 Cloudflare REST API 查询 D1 数据库的用户可以看到更低的端到端请求延迟。此前,身份验证要求 D1 REST API 请求代理到 Cloudflare 的核心集中式数据中心,从而增加了网络往返次数和延迟。

延迟改善幅度为 50-500 毫秒,具体取决于请求位置和数据库位置,并且仅适用于 REST API。由于 Cloudflare 的主要核心数据中心位于美国,因此美国以外的 REST API 请求和数据库获益更大。

/query 和 /raw 等 D1 查询端点的改善最为明显,因为它们不再访问 Cloudflare 的核心数据中心。用于创建和删除数据库等操作的 D1 控制平面端点改善较小,因为它们仍需访问 Cloudflare 的核心数据中心以获取其他控制平面元数据。

2025-05-02

修复 D1 HTTP API 权限问题

已修复一个权限问题:该问题允许具有 D1:Read 权限以及另一个 Cloudflare 产品 Edit 权限的 Cloudflare 账户和用户 API 令牌执行 D1 数据库写入。通过 HTTP API 进行任何数据库写入都需要 D1:Edit 权限。

如果您之前使用不具有 D1:Edit 权限的现有 API 令牌通过 HTTP API 编辑 D1 数据库,则需要创建或编辑 API 令牌,以明确包含 D1:Edit 权限。

2025-04-10

D1 读取复制公开 Beta

D1 读取复制现已进入公开 Beta 阶段,可帮助电子商务网站或内容管理工具等读取密集型应用降低平均延迟并提高整体吞吐量。

Workers 可以通过使用 D1 Sessions API 来利用称为读取副本的只读数据库副本。会话封装了应用程序中一个逻辑会话的所有查询。例如,一个会话可能对应来自某个特定 Web 浏览器会话的所有查询。借助 Sessions API,会话中的 D1 查询保证具有顺序一致性,从而避免数据一致性陷阱。可以使用上一个会话中的 D1 书签来确保会话之间的逻辑一致性。

// retrieve bookmark from previous session stored in HTTP header
const bookmark = request.headers.get("x-d1-bookmark") ?? "first-unconstrained";

const session = env.DB.withSession(bookmark);
const result = await session
  .prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
  .run();
// store bookmark for a future session
response.headers.set("x-d1-bookmark", session.getBookmark() ?? "");

读取副本由 Cloudflare 自动创建(目前在每个受支持的 D1 区域中各有一个),会根据查询流量处于活动或非活动状态,并由 Cloudflare 透明地进行路由,不收取额外费用。

要体验 D1 读取复制,请部署以下使用 Sessions API 的 Worker 代码,系统会提示您创建一个 D1 数据库并在该数据库上启用读取复制。

Deploy to Cloudflare

要详细了解读取复制的实现方式,请参阅我们的博客文章。

2025-02-19

D1 支持 `PRAGMA optimize`

D1 现在支持 PRAGMA optimize 命令,该命令可以提升数据库查询性能。建议在架构变更后(例如创建索引后)运行此命令。有关详细信息,请参阅 PRAGMA optimize。

2025-02-04

修复通过 UI 和 /query REST API 进行 D1 只读访问时的问题。

修复了一个 D1 权限问题:该问题允许通过 UI 使用只读角色的用户,以及通过 /query REST API 使用只读 API 令牌的用户执行修改数据库的查询。通过 Tables 选项卡执行的 UI 操作(例如创建和删除表)在只读访问权限下被错误地允许。不过,通过 Console 选项卡执行的 UI 操作不受此问题影响,并正确地要求写入权限。

使用只读访问权限执行的写入查询现在将会失败。如果您之前依赖此前的错误行为,请为用户分配正确的角色或为 API 令牌分配正确的权限,以执行 D1 写入查询。

2025-01-13

D1 将从 2025 年 2 月 10 日开始执行其免费套餐限制。

D1 将从 2025-02-10 开始执行每日免费套餐限制。这些限制仅适用于使用 Workers 免费计划的账户。

从 2025-02-10 起,如果您未采取任何措施并超出每日免费套餐限制,通过 Workers API 和/或 REST API 对 D1 数据库的查询将返回错误,直到限制于每日 00:00 UTC 重置为止。

为确保服务不中断,请从计划页面将您的账户升级到 Workers 付费计划。每月最低计费金额为 5 美元。请参阅 Workers 付费计划和 D1 限制。

要更好地了解当前用量,请参阅您的计费指标中的读取行数和写入行数,这些指标可在 D1 仪表板或 GraphQL API 中找到。

2025-01-07

D1 Worker API 请求延迟降低 40-60%。

D1 通过消除每个请求中多余的网络往返,将 Worker API 的端到端请求延迟降低了 40-60%。

D1 Worker API 延迟

整个 D1 服务汇总的 p50、p90 和 p95 请求延迟。这些延迟仅作为参考,不应视为您具体工作负载的确切改善幅度。

对于每个发往 D1 数据库的请求,至少消除了两次网络往返。其中一次往返是由一个现已修复的问题导致的。其余被消除的往返则是因为在连接托管数据库的数据中心时,避免了为每个请求创建新的 TCP 连接。

消除多余网络往返的改进同样适用于 D1 的 REST API。不过,REST API 仍依赖 Cloudflare 的集中式数据中心进行身份验证,因此相对的性能提升较小。

2024-08-23

D1 alpha 数据库已停止接受 SQL 查询

继 2024-04-30 发布弃用警告之后,D1 alpha 数据库已停止接受查询(您仍然可以创建和获取备份)。

对 D1 alpha 数据库的请求现在会返回 HTTP 400 错误,并包含以下文本:

You can no longer query a D1 alpha database. Please follow https://developers.cloudflare.com/d1/platform/alpha-migration/ to migrate your alpha database and resume querying.

您可以按照 alpha 数据库迁移指南升级到新的、正式发布的 D1 版本。

2024-07-26

修复 run() API 的 TypeScript 类型定义问题

D1 Client API 中 run() 方法的类型定义不正确(已过时),该问题已在 @cloudflare/workers-types 4.20240725.0 版本中得到解决。

正确的类型定义是 stmt.run<T>(): D1Result,因为 run() 会返回查询的结果行。之前_不正确_的类型定义是 stmt.run(): D1Response,它仅返回查询元数据而不返回结果。

2024-06-17

对于过载的 D1 数据库,HTTP API 现在返回 HTTP 429 错误

此前,当 D1 数据库过载时,对于在此期间传入的查询,D1 的 HTTP API 会返回 HTTP 500 Internal Server 错误。这些请求现在会正确地返回 HTTP 429 Too Many Requests 错误。

D1 的 Workers API 不受此变更影响。

2024-04-30

D1 alpha 数据库将于 2024 年 8 月 15 日停止接受实时 SQL 查询

此前已弃用的 alpha D1 数据库需要在 2024 年 8 月 15 日之前完成迁移,才能继续接受新的查询。

请参阅 alpha 数据库迁移指南,迁移到新的、正式发布的数据库架构。

2024-04-12

对于无效查询,HTTP API 现在返回 HTTP 400 错误

此前,对于无效查询,D1 的 HTTP API 会返回 HTTP 500 Internal Server 错误。现在,无效的 SQL 查询会正确地返回 HTTP 400 Bad Request 错误。

D1 的 Workers API 不受此变更影响。

2024-04-05

D1 alpha 数据库已弃用

由于 D1 现已正式发布并可用于生产环境,alpha 版 D1 数据库已弃用,应进行迁移以获得更好的性能、可靠性和持续支持。

请参阅 alpha 数据库迁移指南,迁移到新的、正式发布的数据库架构。

2024-04-01

D1 正式发布

D1 现已正式发布,并可用于生产环境。阅读博客文章,详细了解正式版中的新功能以及即将推出的 D1 读取复制 API。

  • 使用 Workers 付费计划的开发者现在拥有每个数据库 10 GB 的限制(此前为 2 GB),并且可以与每个账户 50,000 个数据库的现有限制叠加使用。
  • 使用 Workers 免费计划的开发者仍保留每个数据库 500 MB 的限制,并且每个账户最多可创建 10 个数据库。
  • D1 数据库可以导出为 SQL 文件。

2024-03-12

`wrangler d1 execute` 默认行为变更

自 [email protected] 起,wrangler d1 execute 和 wrangler d1 migrations apply 现在默认使用本地数据库,以与 wrangler dev 的默认行为保持一致。

现在还可以指定 --local 或 --remote 之一,明确告知 wrangler 您希望针对哪个环境运行命令。

2024-03-05

D1 用量计费

自 2024-03-05 起,D1 用量将开始计入,并可能在账户后续的计费周期中产生费用。

使用 Workers 付费计划的开发者,如果 D1 用量超出所含限制,将按照 D1 的定价收费。

使用 Workers 免费计划的开发者最多可以使用所含的限额。超出以下限制的用量需要订阅每月 5 美元的 Workers 付费计划。

账户的计费指标可在 Cloudflare 仪表板和 GraphQL API 中查看。

2024-02-16

`run()` 的 API 变更

此前(2024-02-13)对 run() 查询语句方法所做的变更已被回退。

run() 现在返回包含结果行的 D1Result,与 2024-02-13 变更之前的原始行为一致。

将来,run() 会按照最初的设计和文档说明改为返回 D1ExecResult,但该变更将受兼容性日期控制,以避免破坏依赖 run() 当前工作方式的现有 Workers。

2024-02-13

`raw()`、`all()` 和 `run()` 的 API 变更

D1 的 raw()、all() 和 run() 查询语句方法已更新,以反映其预期行为并提高与 ORM 库的兼容性。

raw() 现在会正确地以数组的数组形式返回结果,从而能够正确处理重复的列名(例如在连接表时);相比之下,all() 保持不变,返回对象数组。要在使用 raw() 时在结果中包含列名数组,请使用 raw({columnNames: true})。

run() 不再错误地返回 D1Result,而是按照最初的设计和文档说明返回 D1ExecResult。

对于期望 raw() 返回对象数组的某些应用,这可能是一项破坏性变更。

请参阅 D1 客户端 API,详细了解 D1 的查询方法、返回类型和 TypeScript 支持。

2024-01-18

支持在 UPDATE 和 DELETE 语句中使用 LIMIT

D1 现在支持在 UPDATE 和 DELETE 语句中添加 LIMIT 子句,让您可以限制潜在危险操作的影响范围。

2023-12-18

已禁用旧版 alpha 自动备份

使用 D1 旧版 alpha 后端的数据库将不再运行自动每小时备份。您仍然可以选择对这些数据库进行手动备份。

D1 团队建议迁移到 D1 新的生产后端,这需要您导出并导入现有数据。D1 的生产后端比原来的 alpha 后端更快。新后端还支持 Time Travel,让您可以将数据库恢复到过去 30 天内的任意一分钟,而无需依赖每小时快照或手动快照。

2023-10-03

最多可创建 50,000 个 D1 数据库

作为持续提高 D1 限制的一部分,在 Workers 付费计划中使用 D1 的开发者现在最多可以创建 50,000 个数据库。

  • 这进一步支持了“每个用户一个数据库”的用例,让您可以在客户之间隔离数据。
  • 每个账户的总存储空间现为 50 GB。
  • D1 的分析和指标提供按数据库划分的用量数据。

如果您需要创建超过 50,000 个数据库或需要更多的账户存储空间,请联系 D1 团队进行讨论。

2023-09-28

D1 公开 Beta 版来了

D1 现已进入公开 Beta 阶段,并且提高了存储限制:

  • 使用 Workers 付费计划的开发者现在拥有每个数据库 2 GB 的限制(此前为 500 MB),并且每个账户可以创建 25 个数据库(此前为 10 个)。在公开 Beta 期间,这些限制将继续自动提高。
  • 使用 Workers 免费计划的开发者仍保留每个数据库 500 MB 的限制,并且每个账户最多可以创建 10 个数据库。

数据库必须使用 D1 的新存储子系统,才能享受提高后的数据库限制。

阅读公告博客,详细了解 Beta 版中的新功能以及 D1 未来的规划。

2023-08-19

现在每个查询都会返回行数

D1 现在会为执行的每个查询返回 rows_written 和 rows_read 计数,让您可以从定价和索引优化两方面评估查询的成本。

D1 客户端 API 返回的 meta 对象包含该查询读取的总行数(rows_read)和写入的总行数(rows_written)。例如,对一个包含 5000 行的表执行全表扫描的查询(例如 SELECT * FROM users)将返回 5000 的 rows_read 值:

"meta": {
  "duration": 0.20472300052642825,
  "size_after": 45137920,
  "rows_read": 5000,
  "rows_written": 0
}

请参阅 D1 定价文档,了解读取和写入的计量方式。在 alpha 期间,D1 仍可免费使用。

2023-08-09

从 Cloudflare 仪表板绑定 D1

您现在可以直接在 Cloudflare 仪表板中将 D1 数据库绑定到您的 Workers。要从 Cloudflare 仪表板绑定 D1,请选择您的 Worker 项目 -> Settings(设置) -> Variables(变量) ->,然后选择 D1 Database Bindings(D1 数据库绑定)。

注意:如果您之前使用 3.5.0 之前版本的 wrangler 部署了带有 D1 数据库绑定的 Worker,则必须先升级到 wrangler v3.5.0,然后才能在 Cloudflare 仪表板中编辑 D1 数据库绑定。新的 Workers 项目没有此限制。

之前手动为数据库绑定添加 __D1_BETA__ 前缀的旧版 D1 alpha 用户,应在此次升级中将其移除。您的 Worker 脚本应仅通过 env.BINDING_NAME 调用 D1 数据库。有关最佳实践,请参阅最新的 D1 快速入门指南。

我们建议所有 D1 alpha 用户开始使用 wrangler 3.5.0(或更高版本),以获得改进的 TypeScript 类型和未来的 D1 API 改进。

2023-08-01

每个数据库的限制现为 500 MB

使用 D1 新存储子系统的数据库现在每个最大可增长到 500 MB,此前的限制为 100 MB。这同时适用于现有数据库和新创建的数据库。

请参阅限制,了解 D1 的各项限制。

2023-07-27

新的默认存储子系统

通过 Cloudflare 仪表板和 Wrangler(自 v3.4.0 起)创建的数据库现在默认使用 D1 的新存储子系统。新后端的速度可比 D1 原来的 alpha 后端快 6 到 20 倍。

要了解您的数据库使用的是哪种存储子系统,请运行 wrangler d1 info YOUR_DATABASE 并检查输出中的 version 字段。

version: beta 的数据库使用新的存储后端,并支持 Time Travel API。version: alpha 的数据库仅使用 D1 较旧的旧版后端。

2023-07-27

Time Travel

Time Travel 现已推出。Time Travel 让您可以将 D1 数据库恢复到过去 30 天(Workers 付费计划)或 7 天(Workers 免费计划)内的任意一分钟,存储和恢复操作均不收取额外费用。

请参阅 Time Travel 文档,了解如何将数据库恢复到过去的时间点。

使用 D1 新存储子系统的数据库可以使用 Time Travel。Time Travel 取代了旧版 alpha 数据库所使用的基于快照的备份。

2023-06-28

指标和分析

您现在可以通过 Cloudflare 仪表板和 GraphQL Analytics API 查看按数据库划分的指标。

D1 目前提供每秒读取和写入次数、查询响应大小以及查询延迟百分位数。

2023-06-16

生成列文档

发布了新文档,介绍如何使用 D1 对生成列的支持来定义在写入(或读取)时动态生成的列。生成列允许您从 JSON 对象中提取数据,或使用其他 SQL 函数的输出。

2023-06-12

弃用 Error.cause

自 wrangler v3.1.1 起,D1 客户端 API 现在会在顶层 Error.message 属性中返回详细的错误消息,开发者无需再检查 Error.cause.message 属性。

为了便于从之前的 Error.cause 行为过渡,在大约 2023 年 7 月 14 日之前,详细的错误消息将继续同时填充在 Error.cause 和顶层 Error 对象中。在此日期之后,wrangler 和 D1 客户端 API 的未来版本将不再填充 Error.cause。

2023-05-19

新的实验性后端

D1 推出了新的实验性存储后端,可大幅提升查询吞吐量、延迟和可靠性。该实验性后端将在不久的将来成为默认后端。要使用实验性后端创建数据库,请使用 wrangler 并在创建数据库时设置 --experimental-backend 标志:

$ wrangler d1 create your-database --experimental-backend

请在公告博客中详细了解该实验性后端。

2023-05-19

位置提示

您现在可以在创建 D1 数据库时提供位置提示,这将影响主节点(写入节点)所在的位置。默认情况下,D1 会自动在靠近您发出创建数据库请求的位置创建数据库。在大多数情况下,这可以让 D1 代您为数据库选择最佳位置。

2023-05-17

查询 JSON

发布了新文档,介绍 D1 对 JSON 函数的广泛支持。JSON 函数允许您直接在 SQL 查询中解析、查询和修改 JSON,从而减少与数据库之间的往返次数或所查询的数据量。

这篇文档对您有帮助吗?