# Cloudflare D1 数据库 **状态**：生产就绪 ✅ **最后更新**：2025-11-23 **依赖项**：cloudflare-worker-base（用于 Worker 设置） **最新版本**：wrangler@4.50.0、@cloudflare/workers-types@4.20251121.0 **最近更新（2025）**： * **2025 年 11 月**：司法管辖区支持（数据本地化合规性）、远程绑定 GA (wrangler@4.37.0+)、自动资源配置 * **2025 年 9 月**：自动只读查询重试（最多 2 次尝试），远程绑定公开测试版 * **2025 年 7 月**：存储限制增加（250GB → 1TB），删除 alpha 备份访问，REST API 速度加快 50-500 毫秒 * **2025 年 5 月**：HTTP API 权限安全修复（D1：写入需要编辑） * **2025 年 4 月** ：读取复制公测版（跨区域只读副本） * **2025 年 2 月** ：PRAGMA 优化支持，只读访问权限错误修复 * **2025 年 1 月**：免费层限制实施（2 月 10 日开始），Worker API 查询速度提高 40-60% ** ** ## 快速入门（5 分钟） ### 1\.创建D1数据库 # 创建一个新的D1数据库 npx 牧马人 d1 创建我的数据库 # 输出包括database_id - 保存它！ # ✅ 成功创建 DB 'my-database' # # [[d1_数据库]] # 绑定=“数据库” # 数据库名称=“我的数据库” # 数据库 ID = "" ### 2\.配置绑定添加到您的“wrangler.jsonc”： { “姓名”：“我的工人”， "main": "src/index.ts", “兼容性日期”：“2025-10-11”， “d1_数据库”：[ { "binding": "DB", // 在您的 Worker 中可用作 env.DB "database_name": "my-database", // 来自 wrangler d1 创建的名称 "database_id": "", // 来自 wrangler d1 创建的 ID "preview_database_id": "local-db" // 用于本地开发 } ] } **关键：** * `binding` 是在代码中访问数据库的方式 (`env.DB`) * `database_id` 是生产数据库 UUID * `preview_database_id` 用于本地开发（可以是任何字符串） * **永远不要将真实的`database_id`值提交到公共存储库** \- 使用环境变量或秘密 ### 3\.创建您的第一个迁移 # 创建迁移文件 npx wrangler d1 迁移创建我的数据库 create_users_table # 这将创建：migrations/0001_create_users_table.sql 编辑迁移文件： -- 迁移/0001_create_users_table.sql DROP TABLE IF EXISTS 用户；如果不存在则创建表用户（ user_id 整数主键自动增量，电子邮件文本不为空唯一，用户名文本不为空，创建的_at 整数非空，更新时 INTEGER ）； -- 为常见查询创建索引如果不存在则创建索引 idx_users_email ON users(email); -- 优化数据库 PRAGMA优化； ### 4\.申请迁移 # 先在本地申请（用于测试） npx wrangler d1 迁移应用 my-database --local # 准备好后应用于生产 npx wrangler d1 迁移应用 my-database --remote ### 5\.您的工人的询问 // src/index.ts 从'hono'导入{Hono}；类型绑定 = { DB：D1数据库； }; const app = new Hono<{ 绑定: 绑定 }>(); app.get('/api/users/:email', async (c) => { const email = c.req.param('email'); 尝试{ // 始终将准备好的语句与bind()一起使用 const 结果 = 等待 c.env.DB.prepare( '从用户中选择*，其中电子邮件=？' ） .bind(电子邮件) .first(); 如果（！结果）{ return c.json({ error: '找不到用户' }, 404); } 返回c.json（结果）； } catch（错误：任何）{ console.error('D1 错误：', error.message); return c.json({ error: '数据库错误' }, 500); } }); 导出默认应用程序； ** ** ## D1 迁移系统 ### 迁移工作流程 # 1.创建迁移 npx wrangler d1 迁移创建 # 2. 列出未应用的迁移 npx wrangler d1 迁移列表 --local npx wrangler d1 迁移列表 --remote # 3. 应用迁移 npx wrangler d1 迁移 apply --local # 本地测试 npx wrangler d1 迁移 apply --remote # 部署到生产环境 ### 迁移文件命名迁移会自动进行版本控制：迁移/ ├── 0000_initial_schema.sql ├── 0001_add_users_table.sql ├── 0002_add_posts_table.sql └── 0003_add_indexes.sql **规则：** * 文件按顺序执行 * 每个迁移运行一次（在“d1_migrations”表中跟踪） * 失败的迁移回滚（事务性） * 无法修改或删除已应用的迁移 ### 自定义迁移配置 { “d1_数据库”：[ { “绑定”：“数据库”， "database_name": "我的数据库", "database_id": "", "migrations_dir": "db/migrations", // 自定义目录（默认：migrations/） "migrations_table": "schema_migrations" // 自定义跟踪表（默认：d1_migrations） } ] } ### 迁移最佳实践 #### ✅ 始终这样做： -- 使用 IF NOT EXISTS 使迁移幂等如果用户不存在则创建表（...）；如果不存在则创建索引 idx_users_email ON users(email); -- 模式更改后运行 PRAGMA 优化 PRAGMA优化； -- 使用事务进行数据迁移开始交易； UPDATE 用户 SET Updated_at = unixepoch() WHERE Updated_at IS NULL；犯罪; #### ❌ 切勿这样做： -- 开始时不要包含 BEGIN TRANSACTION （D1 处理这个）开始交易； -- ❌删除这个 -- 不要使用 MySQL/PostgreSQL 语法 ALTER TABLE 用户 MODIFY COLUMN email VARCHAR(255); -- ❌ 不是 SQLite -- 不要创建没有 IF NOT EXISTS 的表创建表用户（...）； -- ❌ 如果表存在则失败 ### 在迁移中处理外键 -- 在架构更改期间暂时禁用外键检查 PRAGMA defer_foreign_keys = true; -- 进行会违反外键的架构更改更改表帖子删除列author_id； ALTER TABLE posts 添加列 user_id INTEGER REFERENCES users(user_id); -- 迁移结束时自动重新启用外键 ** ** ## D1 工人 API **类型定义：** 接口环境 { DB: D1Database; } 类型绑定 = { DB: D1Database; }; const app = new Hono<{ 绑定: 绑定 }>(); **prepare() - 主要方法（始终用于用户输入）：** const user = wait env.DB.prepare('SELECT * FROM users WHERE email = ?') .bind(电子邮件).first(); 原因：防止 SQL 注入、可重用、性能更好、类型安全 **查询结果方法：** * `.all()` → `{ results, meta }` \- 获取所有行 * `.first()` → row 对象或 null - 获取第一行 * `.first('column')` → value - 获取单列值（例如，COUNT） * `.run()` → `{ success, meta }` \- 执行 INSERT/UPDATE/DELETE (无结果) **batch() - 对于性能至关重要：** const 结果 = 等待 env.DB.batch([ env.DB.prepare('SELECT * FROM users WHERE user_id = ?').bind(1), env.DB.prepare('SELECT * FROM posts WHERE user_id = ?').bind(1) ]); * 顺序执行，单网络往返 * 如果其中一个失败，则其余语句不执行 * 用于：批量插入、获取相关数据 **exec() - 避免在生产中使用：** 等待 env.DB.exec('从用户中选择 *;'); // 仅用于迁移/维护 * ❌ 切勿与用户输入一起使用（SQL 注入风险） * ✅ 仅用于：迁移文件、一次性任务 ** ** ## 查询模式 ### 基本增删改查操作 // 创建 const { 元 } = 等待 env.DB.prepare( '插入用户（电子邮件、用户名、创建时间）值 (?, ?, ?)' ).bind(电子邮件、用户名、Date.now()).run(); const newUserId = meta.last_row_id; // 读取（单个） const user = wait env.DB.prepare('SELECT * FROM users WHERE user_id = ?') .bind(userId).first(); // 读取（多个） const { results } = wait env.DB.prepare('SELECT * FROM users LIMIT ?') .bind(10).all(); // 更新 const { meta } = wait env.DB.prepare('UPDATE users SET username = ? WHERE user_id = ?') .bind(newUsername, userId).run(); const rowsAffected = meta.rows_writing； // 删除等待 env.DB.prepare('从用户中删除 user_id = ?').bind(userId).run(); // 计数 const count = wait env.DB.prepare('SELECT COUNT(*) as Total FROM users').first('total'); // 存在检查 const存在=等待env.DB.prepare（'从用户中选择1，其中电子邮件=？LIMIT 1'） .bind(电子邮件).first(); ### 分页模式 const page = parseInt(c.req.query('page') || '1'); 常量限制 = 20； const 偏移量 = (页 - 1) * 限制； const [countResult, usersResult] = 等待 c.env.DB.batch([ c.env.DB.prepare('SELECT COUNT(*) 作为用户总数'), c.env.DB.prepare('SELECT * FROM users ORDER BYcreated_at DESC LIMIT ? OFFSET ?') .bind(限制, 偏移量) ]); 返回 c.json({ 用户：userResult.结果，分页: { 页数, 限制, 总计: countResult.results[0].total } }); ### 批处理模式（伪交易） // D1不支持多语句事务，但batch()提供顺序执行等待 env.DB.batch([ env.DB.prepare('更新用户设置积分 = 积分 - ? WHERE user_id = ?').bind(amount, fromUserId), env.DB.prepare('更新用户设置积分 = 积分 + ? WHERE user_id = ?').bind(amount, toUserId), env.DB.prepare('INSERT INTO transactions (from_user, to_user, amount) VALUES (?, ?, ?)').bind(fromUserId, toUserId, amount) ]); // 如果任何语句失败，批处理将停止（类似事务的行为） ** ** ## 错误处理 **常见错误类型：** * `D1_ERROR` \- 一般 D1 错误 * `D1_EXEC_ERROR` \- SQL 语法错误 * `D1_TYPE_ERROR` \- 类型不匹配（未定义而不是 null） * `D1_COLUMN_NOTFOUND` \- 列不存在 **常见错误和修复：** 错误 |原因 |解决方案 ---|---|--- **声明太长** |具有 1000 多行的大型 INSERT |使用“batch()”分成 100-250 个批次 **排队的请求太多** |循环中的单个查询|使用“batch()”代替循环 **D1_TYPE_ERROR** |在bind | 中使用“未定义”使用“null”作为可选值：“.bind(email, bio || null)” **交易冲突** |开始迁移交易 |删除 BEGIN/COMMIT（D1 自动处理） **外键违规** |架构更改打破约束 |使用“PRAGMA defer_foreign_keys = true” **自动重试（2025 年 9 月）：** D1 在出现可重试错误时自动重试只读查询（SELECT、EXPLAIN、WITH）最多 2 次。检查“meta.total_attempts”以响应重试计数。 ** ** ## 性能优化 **索引最佳实践：** * ✅ WHERE 子句中的索引列：`CREATE INDEX idx_users_email ON users(email)` * ✅ 索引外键：`CREATE INDEX idx_posts_user_id ON posts(user_id)` * ✅ 用于排序的索引列：`CREATE INDEX idx_posts_created_at ON posts(created_at DESC)` * ✅ 多列索引：`CREATE INDEX idx_posts_user_published ON posts(user_id,published)` * ✅ 部分索引：`CREATE INDEX idx_users_active ON users(email) WHERE returned = 0` * ✅ 测试：`EXPLAIN QUERY PLAN SELECT ...` **PRAGMA 优化（2025 年 2 月）：** 在用户（电子邮件）上创建索引 idx_users_email； PRAGMA优化； -- 架构更改后运行 **查询优化：** * ✅ 使用特定列（不是`SELECT *`） * ✅ 在大型结果集上始终包含 LIMIT * ✅ 对 WHERE 条件使用索引 * ❌ 避免使用 WHERE 中的函数（不能使用索引）：`WHERE LOWER(email)` → 存储小写字母 ** ** ## 本地发展 **本地与远程（2025 年 11 月 - 远程绑定 GA）：** # 本地数据库（自动创建） npx wrangler d1 迁移应用 my-database --local npx wrangler d1 执行 my-database --local --command "SELECT * FROM users" # 远程数据库 npx wrangler d1 执行 my-database --remote --command "SELECT * FROM users" # 远程绑定 (wrangler@4.37.0+) - 将本地 Worker 连接到部署的 D1 # 添加到 wrangler.jsonc: { "binding": "DB", "remote": true } **本地数据库位置：** `.wrangler/state/v3/d1/miniflare-D1DatabaseObject/.sqlite` **种子本地数据库：** npx wrangler d1 执行 my-database --local --file=seed.sql ** ** ## 最佳实践总结 ### ✅ 始终这样做： 1. **使用准备好的语句**和`.bind()`来进行用户输入 2. **使用`.batch()`**进行多个查询（减少延迟） 3. **在经常查询的列上创建索引** 4. **在架构更改后运行`PRAGMA优化`** 5. **在迁移中使用`IF NOT EXISTS`**以获得幂等性 6. **在应用于生产之前在本地测试迁移** 7. **使用 try/catch 优雅地处理错误** 8. **使用`null`**代替`undefined`作为可选值 9. **在绑定到查询之前验证输入** 10. **更新/删除后检查`meta.rows_writing`** ### ❌ 切勿这样做： 1. **切勿对用户输入使用`.exec()`**（SQL注入风险） 2. **永远不要在公共仓库中硬编码`database_id`** 3. **永远不要在绑定参数中使用`undefined`**（导致D1_TYPE_ERROR） 4. **永远不要在循环中触发单个查询**（使用批处理代替） 5. **永远不要忘记潜在的大结果集上的`LIMIT`** 6. **切勿在生产中使用`SELECT ******（指定列） 7. **切勿在迁移文件中包含`BEGIN TRANSACTION`** 8. **切勿修改已应用的迁移**（创建新迁移） 9. **永远不要跳过数据库操作的错误处理** 10. **永远不要假设查询成功**（始终检查结果） ** ** ## 已预防的已知问题问题 |描述 |如何避免 ---|---|--- **声明太长** |大型 INSERT 语句超出 D1 限制 |分成 100-250 行的批次 **交易冲突** |迁移文件中的“开始事务”|删除 BEGIN/COMMIT（D1 处理这个） **外键违规** |架构更改打破外键约束 |使用“PRAGMA defer_foreign_keys = true” **速率限制/队列过载** |太多个人查询 |使用“batch()”代替循环 **超出内存限制** |查询将太多数据加载到内存中 |添加 LIMIT、分页结果、分片查询 **类型不匹配错误** |使用“undefined”代替“null” |始终使用“null”作为可选值 ** ** ## Wrangler 命令参考 # 数据库管理牧马人 d1 创建牧马人 d1 列表牧马人 d1 删除牧马人 d1 信息 # 迁移 wrangler d1 迁移创建 wrangler d1 迁移列表 --local|--remote wrangler d1 迁移适用 --local|--remote # 执行查询 wrangler d1 执行 --local|--remote --command "SELECT * FROM users" 牧马人 d1 执行 --local|--remote --file=./query.sql # 时光旅行（查看历史数据）牧马人 d1 时间旅行信息 --timestamp "2025-10-20" 牧马人 d1 时间旅行恢复 --timestamp "2025-10-20" ** ** ## 官方文档 * **D1 概述**： * **开始** ： * **迁移**： * **工作人员 API** ： * **最佳实践**： * **牧马人命令**： ** ** **准备好使用 D1 进行构建！** 🚀

Cloudflare D1

包含技能