用途
Cloudflare D1 是面向 Cloudflare Workers 的无服务器 SQLite 数据库，具备全球分布与零冷启动特性。本技能用于指导在 Workers 上使用 D1 进行数据持久化开发，核心原则是：在边缘使用 SQLite、将迁移纳入版本控制、用 Drizzle 获得类型安全。D1 将 SQLite 的简洁性带入无服务器环境，设计上应面向水平扩展（多个小型数据库）而非垂直扩展（单个大型数据库）。
主要能力与技术栈
技术栈包括：D1（无服务器 SQLite 数据库）、Workers（应用边缘运行时）、Wrangler（开发与部署 CLI）、Drizzle ORM（带迁移的类型安全 ORM）、Drizzle Kit（迁移工具）以及可选的 Hono（轻量 Web 框架）。
项目搭建流程：使用 npm create cloudflare@latest my-app -- --template "worker-typescript" 创建 Worker 项目，安装 drizzle-orm 与开发依赖 drizzle-kit；通过 npx wrangler d1 create my-database 创建数据库（同时创建本地与远程）；在 wrangler.toml 中配置 [[d1_databases]] 绑定、数据库名、数据库 ID、迁移目录与迁移表；使用 npx wrangler types 生成 TypeScript 类型（如 interface Env { DB: D1Database; }）。
Drizzle ORM 设置：在 src/db/schema.ts 中使用 sqliteTable、text、integer、real、blob 定义表结构，支持主键自增、非空、唯一、枚举、默认值与外键引用，并可导出 $inferSelect 与 $inferInsert 类型；在 drizzle.config.ts 中配置 schema 路径、输出目录、方言 sqlite、驱动 d1-http 以及账户 ID、数据库 ID、令牌等凭据；在 src/db/index.ts 中通过 drizzle(d1, { schema }) 创建数据库客户端。
迁移工作流：使用 npx drizzle-kit generate 从 schema 变更生成迁移文件；使用 npx wrangler d1 migrations apply my-database --local 应用到本地，或使用 --remote 应用到生产，并可用 --dry-run 预览。迁移文件为 SQL 格式，包含建表与唯一索引等语句。
使用方式
Worker 实现提供两种方式：一是基于 Hono 的示例，通过中间件注入 db，实现用户列表、按 ID 查询、创建、更新、删除等接口；二是原生 D1 API，使用 env.DB.prepare(...).all()、.bind(...).first() 等直接执行 SQL。
查询模式涵盖：基础选择、指定列、where 条件、多条件 and/or、排序与 limit、分页 offset、计数 count；内连接、左连接以及通过中间表实现多对多连接；单条与多条插入、冲突时更新（upsert）、更新、自增更新、删除；事务通过 db.batch([...]) 或原生 env.DB.batch([...]) 实现。
本地开发与管理：使用 npx wrangler dev 启动本地服务；使用 npx wrangler d1 execute my-database --local --command "SELECT * FROM users" 执行 SQL，或通过 --file ./seed.sql 执行 SQL 文件；使用 npx drizzle-kit studio 打开可视化数据库管理；种子数据可通过 SQL 文件插入并应用到本地。
多环境设置：在 wrangler.toml 中为 dev、staging、production 分别配置 [env.*] 与对应的 [[env.*.d1_databases]]；使用 npx wrangler deploy --env staging 或 --env production 部署，并使用 npx wrangler d1 migrations apply ... --remote --env staging 应用迁移。
测试：提供基于 unstable_dev 与 vitest 的集成测试示例，启动 Worker 后对接口进行断言。
CLI 快速参考涵盖数据库创建、列表、信息、删除；迁移列表、本地应用、远程应用；SQL 执行（命令、文件、本地、远程）；开发（dev、types、deploy）；Drizzle（generate、migrate、studio、push）。
适用场景
适用于在 Cloudflare Workers 上构建需要边缘数据持久化的应用，例如 API 服务、多租户应用（按租户拆分多个小型数据库）、需要类型安全查询与版本化迁移的项目，以及希望以 SQLite 简洁性实现无服务器数据层的场景。
限制与注意事项
D1 限制包括：数据库最大 10 GB、单行最大 1 MB、单条 SQL 语句最大 100 KB、批处理最多 1000 条语句、免费额度每天读取 500 万次、每天写入 10 万次。
应避免的反模式：使用单一大型数据库（应设计为多个小型数据库，如按租户拆分）、缺少迁移（应始终对 schema 变更进行版本控制）、到处写原始 SQL（应使用 Drizzle 获得类型安全）、未连接远程（部署前应始终针对真实 D1 测试）、在 D1 中存储大文件（应使用 R2 存储文件）、复杂连接（D1 是 SQLite，应保持查询简单）、不使用批处理（多个操作应使用 batch）、忽视限制（应监控免费额度使用情况）。