SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cloudflare-d1

cloudflare-d1

数据与分析

查看项目

更新于 10-15 12:11

技能介绍

用途

Cloudflare D1 是运行在边缘上的无服务器 SQLite 数据库，提供无需服务器的 SQL 数据库、全球分布、零冷启动、标准 SQLite 语法以及面向全球性能的读复制能力。本技能用于帮助开发者在 Cloudflare Workers 环境中使用 D1 进行数据库开发，涵盖数据库、迁移、绑定配置，以及在遇到 D1_ERROR、statement too long、too many requests queued 等错误时的处理。

主要能力

  • 数据库创建与绑定配置：通过命令创建数据库并保存 database_id，在 wrangler.jsonc 中配置 d1_databases 绑定（含 binding、database_name、database_id、preview_database_id）。
  • 迁移管理：使用 migrations create 创建迁移，migrations apply 应用迁移（本地 --local 与生产 --remote），要求迁移幂等（CREATE TABLE IF NOT EXISTS、CREATE INDEX IF NOT EXISTS、DROP TABLE IF EXISTS），并在迁移末尾添加 PRAGMA optimize。
  • 查询 API：prepare() 执行查询（all、first、raw）、bind() 绑定参数、batch() 执行多条查询（单事务，全部成功或全部失败）、exec() 执行 SQL 字符串（仅用于迁移或初始化，禁止用于含用户输入的查询）。
  • 常见模式：用户 CRUD、批量操作、读复制、基于 batch 的事务、分页。
  • 读复制：通过 withSession 配置 preferredRegion（auto 或 weur、wnam、enam、apac），从最近副本读取，可查看 served_by_region。
  • 类型亲和性：INTEGER/INT 为 INTEGER，TEXT/VARCHAR/CHAR 为 TEXT，REAL/FLOAT/DOUBLE 为 REAL，BLOB 与无类型为 BLOB；建议数字用 INTEGER、字符串用 TEXT（不用 VARCHAR）、时间戳用 INTEGER（Date.now()）、二进制用 BLOB。
  • 错误预防：使用 .bind() 防止 SQL 注入、为 WHERE/JOIN 列建索引、本地测试迁移、时间戳使用 INTEGER、批处理限制在 500 条语句以内。

2025 年更新要点

  • 2025 年 1 月：性能提升，全球 P50 查询延迟降低 40-60%，针对边缘执行优化 SQLite 引擎，降低小于 100 MB 数据库的冷启动影响。
  • 2025 年 9 月：可靠性增强，读查询在瞬时故障时自动重试最多 2 次，对应用代码透明（记录于 wrangler tail）。
  • 2025 年 4 月：可扩展性增强，读复制（公开测试）可全球部署只读副本，读吞吐最高提升 2 倍，Sessions API 支持读写分离。
  • 2025 年 11 月：合规增强，数据本地化，可指定 EU/US 司法管辖区用于 GDPR/数据主权，通过 --jurisdiction 标志或 wrangler.jsonc 配置。
  • 破坏性变更（2025 年 2 月 10 日）：免费套餐强制硬性限制为 10 个数据库、每个 500 MB、每次调用 50 次查询；超出限制将返回 429 错误（此前仅为警告）。建议使用 wrangler d1 list 检查用量并按需升级。

使用方式

  1. 创建数据库：bunx wrangler d1 create my-database，保存输出中的 database_id。
  2. 配置绑定：在 wrangler.jsonc 中添加 d1_databases 配置，并设置 compatibility_date（示例为 2025-10-11）。
  3. 创建迁移：bunx wrangler d1 migrations create my-database create_users，编辑生成的 .sql 文件。
  4. 应用迁移：本地 bunx wrangler d1 migrations apply my-database --local；生产 bunx wrangler d1 migrations apply my-database --remote。
  5. 在 Worker 中查询：通过 env.DB.prepare(...).bind(...).all() 等方式执行查询，示例使用 Hono 框架。

适用场景

  • 在 Cloudflare Workers 上构建需要 SQL 数据库的全球分布式应用。
  • 用户 CRUD、批量插入、分页查询等常规数据库操作。
  • 需要原子性的事务场景（通过 batch 实现转账等操作）。
  • 读多写少、需要全球低延迟读取的场景（读复制）。
  • 需要按司法管辖区进行数据本地化的合规场景。

限制与注意事项

  • 免费套餐硬性限制：10 个数据库、每个 500 MB、每次调用 50 次查询，超出返回 429 错误。
  • 单行不得超过 1 MB。
  • 禁止将用户输入拼接进 SQL；禁止将 database_id 提交到公开仓库；禁止跳过迁移直接手动改结构；禁止对筛选列省略索引；禁止无 LIMIT 的 SELECT *；禁止未本地测试就运行迁移。
  • 时间戳不要用 DATETIME，使用 INTEGER；字符串不要用 VARCHAR，使用 TEXT。
  • 批处理语句建议限制在 500 条以内。
  • exec() 仅用于迁移或初始化，禁止用于带用户输入的查询。
  • 安装 D1 驱动包时的供应链安全建议：通过 npm config set ignore-scripts true 阻断安装后脚本（Bun 默认禁用）；对新版本设置 7 天冷却期等待社区审核；安装前使用 socket package score 或 socket npm install 审计包。

交互工具与资源

  • 代理：agents/d1-debugger.md 提供 9 阶段诊断（配置、迁移、查询、绑定、错误、限制、性能、Time Travel）；agents/d1-query-optimizer.md 提供性能分析（慢查询、缺失索引、优化建议）。
  • 命令：commands/cloudflare-d1:setup.md 为首次设置交互向导；commands/d1-create-migration.md 为带校验的迁移创建向导。
  • 参考资料：references/setup-guide.md（完整设置）、references/query-patterns.md（完整 API 参考）、references/read-replication.md（全球读副本）、references/best-practices.md（性能与优化）、references/limits.md（限制与配额）、references/metrics-analytics.md（监控与分析）、references/2025-features.md（2025 功能与破坏性变更）。
  • 模板：templates/schema-example.sql、templates/d1-worker-queries.ts、templates/cloudflare-d1:setup-migration.sh。

官方文档

  • D1 概览：https://developers.cloudflare.com/d1/
  • 快速开始：https://developers.cloudflare.com/d1/get-started/
  • 客户端 API：https://developers.cloudflare.com/d1/build-with-d1/d1-client-api/
  • 读复制：https://developers.cloudflare.com/d1/reference/read-replication/