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

cloudflare-d1

数据与分析

查看项目

更新于 10-15 12:07

技能介绍

用途

Cloudflare D1 是构建在 Cloudflare 边缘网络上的无服务器 SQLite 数据库。本技能用于在 Cloudflare Workers 中集成和使用 D1，适用于需要创建数据库、编写 SQL 迁移、从 Workers 查询 D1、处理数据库错误等场景。依赖 cloudflare-worker-base（用于 Worker 设置）。资料标注状态为 Production Ready，最后更新于 2026-01-20，涉及版本 wrangler@4.59.2、@cloudflare/workers-types@4.20260109.0。

主要能力

  • 数据库创建与绑定：通过 wrangler d1 create 创建数据库，在 wrangler.jsonc 中配置 d1_databases 绑定（binding、database_name、database_id、preview_database_id）。
  • 迁移系统：支持创建、列出、应用迁移，自动版本化（如 0001_create_users_table.sql），按顺序执行，每个迁移只运行一次（记录在 d1_migrations 表），失败回滚，已应用的迁移不可修改或删除。支持自定义 migrations_dir 和 migrations_table。
  • Workers API：提供 prepare()（推荐用于用户输入，防 SQL 注入）、bind()、all()、first()、run()、batch()、exec() 等方法。batch() 顺序执行、单次网络往返，适合批量插入和关联数据获取；exec() 仅用于迁移或维护，禁止用于用户输入。
  • 查询模式：涵盖 CRUD、分页（COUNT + LIMIT/OFFSET 组合）、批量伪事务（batch 顺序执行，任一失败则停止）。
  • 错误处理：列出常见错误类型（D1_ERROR、D1_EXEC_ERROR、D1_TYPE_ERROR、D1_COLUMN_NOTFOUND）及修复方式，并提供带指数退避的重试模式。资料指出瞬时错误属预期行为，Cloudflare 文档称“每隔几小时出现少量错误并不意外”。2025 年 9 月起 D1 会自动重试只读查询（SELECT、EXPLAIN、WITH）最多 2 次，可通过 meta.total_attempts 查看重试次数；写查询仍需自定义重试。
  • 性能优化：索引最佳实践（WHERE 列、外键、排序列、多列、部分索引）、PRAGMA optimize（2025 年 2 月支持）、查询优化建议（避免 SELECT *、加 LIMIT、避免 WHERE 中使用函数）。
  • 本地开发：支持 --local 与 --remote 模式；2025 年 11 月远程绑定 GA（wrangler@4.37.0+），可通过 { "remote": true } 将本地 Worker 连接到已部署的 D1。
  • 扩展与限制：单库 10 GB 上限，可用分片（如哈希分片，10 个库 = 100 GB）扩展，每个 Worker 最多支持 50,000 个数据库；单行 2 MB 上限，大内容建议混合 D1 + R2 模式。

使用方式

快速上手（约 5 分钟）：

  1. 创建数据库：npx wrangler d1 create my-database，保存输出的 database_id。
  2. 配置绑定：在 wrangler.jsonc 中添加 d1_databases 数组，设置 binding（代码中通过 env.DB 访问）、database_name、database_id、preview_database_id。资料提醒不要将真实 database_id 提交到公开仓库，应使用环境变量或密钥。
  3. 创建迁移：npx wrangler d1 migrations create my-database create_users_table，编辑生成的 SQL 文件。
  4. 应用迁移：先本地测试 npx wrangler d1 migrations apply my-database --local，再部署到生产 npx wrangler d1 migrations apply my-database --remote。
  5. 在 Worker 中查询：使用 env.DB.prepare('SELECT * FROM users WHERE email = ?').bind(email).first() 等模式。

迁移最佳实践：使用 IF NOT EXISTS 保证幂等；架构变更后运行 PRAGMA optimize；触发器使用大写 BEGIN/END（小写本地可用但远程失败）；数据迁移使用事务；不要在迁移文件开头写 BEGIN TRANSACTION（D1 自动处理）；不要使用 MySQL/PostgreSQL 语法；外键变更可用 PRAGMA defer_foreign_keys = true。

适用场景

  • 在 Cloudflare Workers 上构建需要 SQL 数据库的应用。
  • 需要边缘低延迟读取、跨区域只读副本（2025 年 4 月公开测试）的场景。
  • 需要数据本地化合规（2025 年 11 月支持 jurisdiction）。
  • 需要从 Workers 安全查询数据库并防止 SQL 注入。
  • 需要管理数据库架构版本与迁移流程。

限制与注意事项

  • 单库 10 GB 硬上限，超出需分片；单行 2 MB 上限。
  • 不支持多语句事务，batch() 提供类似事务的顺序执行行为。
  • 瞬时错误（如 Network connection lost、storage operation exceeded timeout、isolate exceeded its memory limit）属预期行为，需实现重试逻辑。
  • 远程绑定连接在闲置 1 小时后超时（GitHub Issue #10801），可定期执行 SELECT 1 保活或重启开发服务器。
  • 多 Worker 使用 service bindings 时，辅助 Worker 无法访问其 D1 绑定（GitHub Issue #11121），需使用 --persist-to 指向同一持久化路径。
  • D1Database.exec() 处理多行 SQL 可能报 D1_EXEC_ERROR: incomplete input（Issue #9133），建议使用预处理语句或外部 .sql 文件。
  • 2025 年 1 月起开始执行免费层限制（2 月 10 日起）。
  • 资料未提供具体收费与价格信息。