---

云计算的边缘之光：Cloudflare D1 Serverless 数据库快速入门指南

引言：数据库的演进与边缘计算的挑战

在数字世界的快速发展中，数据扮演着核心角色。传统的数据库解决方案通常部署在中心化的数据中心，它们强大、成熟，但也带来了固有的挑战：运维复杂性、弹性伸缩的限制以及与用户之间的物理距离造成的延迟。随着云计算和无服务器（Serverless）架构的兴起，开发者们渴望更轻量级、更易于管理、更具弹性的数据存储方案。无服务器函数（如 AWS Lambda, Cloudflare Workers）的流行，更是将计算推向了离用户更近的边缘，但数据层往往未能同步跟进，导致“无服务器贫血”——计算在边缘，数据仍在远方，性能瓶颈依然存在。

Cloudflare，作为全球领先的边缘计算、安全和性能服务提供商，一直在积极探索如何将更多能力下沉到其庞大的全球网络边缘。D1便是 Cloudflare 在这一探索中的重要成果，它是一个内置于 Cloudflare 全球网络的 Serverless 数据库。本文将深入探讨 Cloudflare D1 的本质、优势、工作原理，并提供一个详尽的快速入门指南，帮助您在几分钟内将一个功能齐全的 Serverless 数据库与您的 Cloudflare Workers 应用集成。

什么是 Cloudflare D1？理解其核心概念

Cloudflare D1 是 Cloudflare 提供的一个 Serverless 关系型数据库。它的核心是基于 SQLite 构建的。但这并非简单地将 SQLite 运行在某个服务器上，而是将其无服务器化，并深度集成到 Cloudflare 的全球边缘网络中。

理解 D1 的几个关键点：

1. Serverless (无服务器)：这意味着您无需关心数据库服务器的配置、管理、维护、打补丁或扩容。Cloudflare 负责底层的一切运维工作，您只需专注于数据和应用逻辑。您只需为您使用的资源付费。
2. Built on SQLite (基于 SQLite)：D1 的数据存储引擎是 SQLite。SQLite 是一个轻量级、嵌入式的数据库引擎，它无需独立的服务器进程，数据通常存储在单个文件中。D1 利用了 SQLite 的成熟、可靠和 ACID 事务特性，并在此基础上构建了多租户、分布式管理和边缘访问的能力。
3. Edge Database (边缘数据库)：D1 的设计目标是将数据尽可能地推到靠近用户的位置。虽然目前 D1 的读副本能力仍在发展中（初始阶段可能只有一个主要写入位置），但其访问接口和与 Cloudflare Workers 的紧密集成，使得从边缘访问数据变得非常高效。Worker 在边缘执行，可以直接通过 Cloudflare 的内部网络低延迟地访问 D1 数据库。
4. SQL Interface (SQL 接口)：作为关系型数据库，D1 使用标准的 SQL 进行数据操作。这意味着熟悉 SQL 的开发者可以轻松上手，而无需学习新的查询语言或数据模型。
5. Integrated with Cloudflare Workers (与 Cloudflare Workers 集成)：这是 D1 的核心使用场景。通过 Cloudflare Workers KV 或 Durable Objects 类似的方式，D1 实例可以直接绑定到 Worker 脚本的环境变量中，Worker 可以直接调用 D1 提供的 API 来执行 SQL 查询。

为什么选择 Cloudflare D1？边缘数据库的优势

选择 Cloudflare D1，意味着拥抱 Serverless 和边缘计算的优势。具体来说，D1 带来了以下几个显著的好处：

1. 极简的运维体验 (Effortless Operations)：告别数据库服务器的管理噩梦。无需担心操作系统、数据库软件的安装、配置、备份、恢复、监控、故障排除等繁琐任务。D1 将这些复杂性完全抽象掉，让开发者可以将精力集中在构建应用功能上。
2. 低延迟的数据访问 (Low Latency Data Access)：通过与 Cloudflare Workers 的紧密集成，Workers 可以在离用户最近的边缘位置执行，并通过 Cloudflare 高效的内部网络访问 D1 数据库。相比于 Worker 访问位于遥远数据中心的传统数据库，这种架构显著降低了数据访问的延迟，提升了用户体验，特别适合对延迟敏感的应用。
3. 按需付费的成本模型 (Pay-per-Use Pricing)：D1 采用按量付费的模式，通常基于存储量和执行的查询数量。对于流量波动大或初创项目，这种模式可以显著降低成本，避免为闲置的数据库资源付费。它与 Serverless 函数的成本模型完美契合。
4. 快速的开发迭代 (Rapid Development)：基于成熟的 SQL 和易于集成的 API，开发者可以快速定义数据模型、编写查询逻辑，并将其集成到 Worker 应用中。Serverless 的特性也意味着您可以快速创建、修改或删除数据库实例，无需漫长的 Provisioning 过程。
5. 内置的可靠性和可扩展性 (Built-in Reliability and Scalability)：Cloudflare 负责 D1 底层的可靠性保障和一定程度的自动扩展。虽然目前 D1 的扩展能力有其特定模式（例如未来的读副本），但其设计目标是为了在高并发环境下提供稳定服务。
6. 利用现有 SQL 知识 (Leverage Existing SQL Skills)：无需学习 NoSQL 的新范式或特定数据库的查询语言，标准的 SQL 语法即可用于 D1，大大降低了学习曲线。
7. 与 Cloudflare 生态无缝集成 (Seamless Integration with Cloudflare Ecosystem)：D1 是 Cloudflare Serverless 平台（包括 Workers, KV, Durable Objects, R2 等）的一部分，可以与这些服务轻松组合，构建强大的边缘应用。

Cloudflare D1 的工作原理与架构概览

虽然 Cloudflare 没有公开 D1 的全部底层架构细节，但我们可以基于已知信息和 Serverless 数据库的常见模式进行概览：

1. SQLite 核心：每个 D1 数据库实例内部使用一个或多个 SQLite 数据库文件作为主要存储。SQLite 以其嵌入式特性、零配置和 ACID 事务支持而闻名。
2. 多租户包装：Cloudflare 在 SQLite 外部构建了一个多租户层，负责隔离不同用户的数据、管理数据库实例的生命周期以及处理连接请求。
3. 边缘访问层：Cloudflare 的边缘网络节点提供 D1 的访问入口。当一个 Worker 需要访问 D1 时，它通过 Cloudflare 内部优化的网络路径与 D1 的服务进行通信。这个服务层负责接收来自 Worker 的 SQL 查询请求。
4. 数据持久化与一致性：D1 需要确保数据的高可用性和一致性。这可能涉及将 SQLite 数据存储在 Cloudflare 的分布式存储系统上（如 R2），并通过内部机制处理写操作的持久化和同步。初始阶段可能采用主从模式或类似机制，确保写入操作的一致性，而读操作则可能根据未来的发展从更近的副本提供服务。
5. Serverless API：D1 通过一套 API 暴露给 Cloudflare Workers。Worker 使用这些 API 来执行 SQL 语句、准备预处理语句、绑定参数、获取结果等。wrangler CLI 工具则提供了数据库管理（创建、删除、执行查询、管理迁移）的功能。

总的来说，D1 是将 SQLite 的优点（SQL 兼容性、ACID）与 Serverless 架构的优势（无运维、按需付费）以及 Cloudflare 边缘网络的低延迟特性结合起来的产物。

快速入门：从零开始使用 Cloudflare D1

本节将提供一个详细的步骤指南，帮助您快速创建您的第一个 Cloudflare D1 数据库，并将其与一个 Cloudflare Worker 集成。

准备工作：

1. 一个 Cloudflare 账号。
2. 安装 Node.js (推荐 LTS 版本)。
3. 安装 Cloudflare 的命令行工具 wrangler。如果您还没有安装，可以通过 npm 进行安装：
   bash
npm install -g wrangler
4. 使用 wrangler login 登录您的 Cloudflare 账号：
   bash
wrangler login
   这将打开浏览器窗口，授权 wrangler 访问您的账号。

步骤 1：创建一个 Cloudflare Worker 项目

如果您已经有一个 Worker 项目，可以跳过此步骤。否则，使用 wrangler init 命令创建一个新的 Worker 项目：

bash
wrangler init my-d1-worker

按照提示操作，选择一个简单的模板（如 Hello World）。进入项目目录：

bash
cd my-d1-worker

步骤 2：创建一个 D1 数据库实例

使用 wrangler d1 create 命令创建一个新的 D1 数据库。给您的数据库起一个名字（例如 my-first-d1-db）。

bash
wrangler d1 create my-first-d1-db

执行此命令后，wrangler 会在 Cloudflare 平台上为您创建一个 D1 数据库实例，并输出相关信息，包括数据库的名称和它的 database_id。请记下这些信息，特别是 database_id。

“`

示例输出：

🌀 Creating DB ‘my-first-d1-db’ in Cloudflare account…
✅ Created DB ‘my-first-d1-db’ (ID: )
“`

步骤 3：将 D1 数据库绑定到您的 Worker

要让 Worker 能够访问这个 D1 数据库，您需要在 Worker 的配置文件 wrangler.toml 中进行绑定。打开项目根目录下的 wrangler.toml 文件，在文件末尾添加或修改 [[d1_databases]] 字段：

“`toml
name = “my-d1-worker” # Your worker name
main = “src/index.ts” # Or your entry file
compatibility_date = “2023-10-26” # Use a recent date

Add this section

[[d1_databases]]
binding = “DB” # The name you’ll use in your Worker script (e.g., env.DB)
database_name = “my-first-d1-db” # The name you gave the database
database_id = “” # The ID provided by ‘wrangler d1 create’
“`

请将 <your-database-id> 替换为您在步骤 2 中获得的实际数据库 ID。binding = "DB" 定义了在 Worker 脚本中访问该数据库的环境变量名称，这里我们使用 DB。

步骤 4：在 D1 数据库中创建表

在能够存储数据之前，您需要在数据库中创建表结构。您可以使用 wrangler d1 execute 命令来执行 SQL 语句。

首先，定义您的表结构。例如，我们创建一个名为 users 的表，包含 id, name 和 email 字段。您可以将 SQL 语句保存在一个文件中（例如 schema.sql）：

sql
-- schema.sql
DROP TABLE IF EXISTS users;
CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE
);

然后，使用 wrangler d1 execute 命令执行这个 SQL 文件。您需要指定数据库的名称或 ID。使用名称更方便：

bash
wrangler d1 execute my-first-d1-db --local --file ./schema.sql

这里使用了 --local 标志，这意味着 wrangler 会尝试在您的本地机器上查找同名的数据库进行操作。如果您想直接在 Cloudflare 平台上执行，可以省略 --local。但对于 schema 初始化，本地执行通常更快速方便（wrangler 会与 Cloudflare API 通信完成）。

步骤 5：在 Worker 中编写代码与 D1 交互

现在，修改您的 Worker 脚本（通常是 src/index.ts 或 src/index.js），编写代码来访问绑定的 D1 数据库。

首先，假设您的 Worker 使用 TypeScript 并且 wrangler init 生成了类型定义，您需要在入口文件（src/index.ts）中定义您的环境变量类型，包含 D1 绑定：

“`typescript
// src/index.ts (or src/index.js if using JavaScript)

// For TypeScript, define the Env interface
interface Env {
DB: D1Database; // D1Database is a global type provided by @cloudflare/workers-types
}

export default {
async fetch(request: Request, env: Env): Promise {
const url = new URL(request.url);
let responseText = “”;

    try {
        if (url.pathname === '/insert') {
            // 插入数据
            const result = await env.DB.prepare(
                "INSERT INTO users (name, email) VALUES (?, ?)"
            )
            .bind("Alice", "[email protected]")
            .run();
            responseText = `Inserted 1 row. Result: ${JSON.stringify(result)}`;

        } else if (url.pathname === '/query') {
            // 查询数据
            const { results } = await env.DB.prepare(
                "SELECT * FROM users WHERE name = ?"
            )
            .bind("Alice")
            .all();
            responseText = `Query results: ${JSON.stringify(results)}`;

        } else if (url.pathname === '/query-first') {
            // 查询第一条数据
            const user = await env.DB.prepare(
                "SELECT * FROM users LIMIT 1"
            ).first();
             responseText = `First user: ${JSON.stringify(user)}`;


        } else if (url.pathname === '/update') {
            // 更新数据
             const result = await env.DB.prepare(
                "UPDATE users SET name = ? WHERE email = ?"
            )
            .bind("Alice Updated", "[email protected]")
            .run();
            responseText = `Updated ${result.meta.changes} row(s). Result: ${JSON.stringify(result)}`;

        } else if (url.pathname === '/delete') {
            // 删除数据
             const result = await env.DB.prepare(
                "DELETE FROM users WHERE email = ?"
            )
            .bind("[email protected]")
            .run();
             responseText = `Deleted ${result.meta.changes} row(s). Result: ${JSON.stringify(result)}`;


        } else if (url.pathname === '/all-users') {
             // 查询所有数据
             const { results } = await env.DB.prepare("SELECT * FROM users").all();
             responseText = `All users: ${JSON.stringify(results)}`;

        } else {
            responseText = "Welcome to the D1 Worker! Try /insert, /query, /update, /delete, /all-users";
        }

    } catch (error: any) {
        responseText = `Error: ${error.message}`;
    }

    return new Response(responseText);
},

};

“`

代码解释：

• interface Env { DB: D1Database; }: 这定义了一个类型，告诉 TypeScript 我们的 Worker 环境对象（env）包含一个名为 DB 的属性，它的类型是 D1Database。D1Database 是 @cloudflare/workers-types 包提供的类型，代表了 D1 数据库连接对象。
• env.DB: 在 Worker 中，通过 env 对象访问在 wrangler.toml 中绑定的 D1 数据库。绑定名称 DB 对应于 [[d1_databases]] 中的 binding = "DB"。
• env.DB.prepare(sql): 这个方法用于准备一个 SQL 语句。使用预处理语句（prepared statements）是安全的做法，可以防止 SQL 注入攻击。
• .bind(param1, param2, ...): 用于绑定参数到预处理语句中的占位符（?）。参数的顺序必须与 SQL 语句中的占位符顺序一致。
• .run(): 执行一个 SQL 语句， typically used for INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE, etc., statements that modify data or schema and don’t return rows. Returns metadata about the execution (e.g., number of changes).
• .all(): Executes a SQL SELECT query and returns all matching rows as an array of objects.
• .first(columnName?: string): Executes a SQL SELECT query and returns only the first matching row. Optionally, you can pass a column name to get only the value of that specific column from the first row.
• .bind() 和执行方法（.run(), .all(), .first()）是链式调用的。
• 我们创建了不同的路由 (/insert, /query, etc.) 来演示不同的数据库操作。

步骤 6：部署 Worker

使用 wrangler deploy 命令将您的 Worker 部署到 Cloudflare：

bash
wrangler deploy

Wrangler 会打包您的代码并将其上传到 Cloudflare。部署完成后，wrangler 会输出您的 Worker 的 URL。

步骤 7：测试您的应用

使用浏览器或 curl 命令访问您的 Worker URL，并尝试不同的路径：

• 访问 /：应该看到欢迎信息。
• 访问 /insert：执行插入操作。如果成功，会返回插入结果的 JSON。
• 再次访问 /insert：由于 email 是 UNIQUE 约束，第二次插入应该会失败，并返回错误信息。
• 访问 /all-users：查询所有用户，应该能看到刚刚插入的用户数据。
• 访问 /update：更新用户数据。
• 访问 /all-users：再次查询所有用户，应该能看到更新后的数据。
• 访问 /query?name=Alice Updated：按名称查询特定用户（注意：我们的代码是硬编码查询 “Alice”，您可以修改代码使其接受 URL 参数）。
• 访问 /delete：删除用户数据。
• 访问 /all-users：再次查询所有用户，应该看到用户已被删除或结果集为空。

恭喜！您已经成功创建了一个 Cloudflare D1 数据库，并将其与一个 Worker 集成，实现了基本的 CRUD（创建、读取、更新、删除）操作。

进一步探索：D1 的高级功能和最佳实践

快速入门只是个开始，D1 还提供了更多功能和考虑事项：

1. 数据库迁移 (Migrations)：对于生产应用，直接执行 SQL 文件来改变 schema 是不够的。D1 支持使用 wrangler d1 migrations 来管理数据库 schema 的版本控制。您可以创建迁移文件（包含 UP 和 DOWN 脚本），然后使用 wrangler d1 migrations apply 来应用这些更改。这对于团队协作和持续部署至关重要。
   • 创建迁移：wrangler d1 migrations create my-first-d1-db <migration-name>
   • 应用迁移：wrangler d1 migrations apply my-first-d1-db --local (本地测试) 或 wrangler d1 migrations apply my-first-d1-db (部署到 Cloudflare)
2. 数据类型 (Data Types)：SQLite 支持多种数据类型，D1 也继承了这些。常见的包括 INTEGER, REAL, TEXT, BLOB。SQLite 的类型系统比较灵活，称为“动态类型”或“类型亲和性”，意味着您可以在任何列中存储任何类型的数据，但建议使用明确的类型定义以获得更好的兼容性和约束。
3. 索引 (Indexing)：为了提高查询性能，特别是 SELECT 语句的效率，应该为常用的查询字段创建索引。例如 CREATE INDEX idx_email ON users (email);。这同样可以通过 wrangler d1 execute 或迁移文件执行。
4. 事务 (Transactions)：D1 支持标准的 SQL 事务。您可以使用 BEGIN, COMMIT, ROLLBACK 语句来确保一系列操作的原子性。例如，在 Worker 中通过 env.DB.batch([...statements...]) 来执行事务批处理。
5. 批量执行 (Batch Execution)：D1 API 提供了 env.DB.batch(statements) 方法，可以一次性发送多个预处理语句并在一个事务中执行它们。这比单独执行每个语句效率更高。
   javascript
// Example of batch insert
const usersToInsert = [
{ name: "Bob", email: "[email protected]" },
{ name: "Charlie", email: "[email protected]" },
];
const statements = usersToInsert.map(user =>
env.DB.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
.bind(user.name, user.email)
);
const results = await env.DB.batch(statements);
console.log("Batch insert results:", results);
6. 连接与连接池：作为 Serverless 数据库，您无需管理连接池。Cloudflare 负责处理与 D1 数据库实例的连接。在 Worker 中，env.DB 对象代表了与数据库的接口，您可以直接使用它来执行查询，无需手动打开或关闭连接。
7. 错误处理：在 Worker 中与 D1 交互时，务必使用 try...catch 块来捕获可能发生的数据库错误（例如，SQL 语法错误、唯一约束冲突等），并向用户返回有意义的错误信息。
8. 性能考虑：
   • 尽量使用预处理语句 (.prepare().bind()...)。
   • 为频繁查询的列创建索引。
   • 使用 .batch() 执行多个相关的写入操作。
   • 避免在大结果集上执行 SELECT *，只选择需要的列。
   • 考虑数据模型设计，避免复杂的 JOIN 操作，尤其是在读延迟敏感的场景。
   • 理解 D1 的读写模型（当前写操作可能集中，读操作将受益于未来的副本），设计应用时考虑读多写少的场景。

Cloudflare D1 的适用场景

D1 特别适合以下应用场景：

• 边缘应用的数据存储：为 Cloudflare Workers 构建的边缘应用提供低延迟的数据持久化层，如用户偏好设置、游戏分数、实时分析数据收集等。
• 静态网站的动态后端：为 Hugo, Jekyll, Astro 等静态网站生成器构建的站点提供一个简单的后端，用于存储评论、用户提交的表单数据、简单博客文章等。
• API 后端：构建轻量级的 API 服务，使用 Worker 接收请求，D1 存储数据。
• 用户身份和配置管理：存储用户档案信息、个性化配置等。
• 内容管理：存储小型应用的内容数据。
• 事件日志和分析：在边缘收集和存储来自用户的事件或分析数据。

限制与注意事项

虽然 D1 功能强大且易于使用，但作为一个相对新兴的服务，它也有一些限制和需要注意的地方：

• 数据大小限制：虽然单个数据库实例可以存储大量数据（具体限制请参考 Cloudflare 文档），但 SQLite 本身对非常大的数据库文件或极高的数据吞吐量有其固有限制，它不是设计用来替代企业级数据仓库或大型 OLTP 集群的。
• 性能特性：当前的 D1 版本在写入操作上可能存在一定的集中性，而读操作的分布式能力（读副本）正在发展中。对于写入密集或需要全球强一致性的大规模事务场景，可能需要评估其适用性。
• 工具和生态：与成熟的数据库系统（如 PostgreSQL, MySQL）相比，D1 的第三方工具、ORM 支持和社区生态尚在发展中。
• SQL 方言：虽然基于 SQLite，但 D1 可能不支持 SQLite 的所有特性或扩展。请参考官方文档了解兼容性。
• 数据导入/导出：目前的数据导入/导出工具相对基础，对于从大型现有数据库迁移可能需要更多手动工作或自定义脚本。

随着 Cloudflare 的不断投入，这些限制中的许多可能会在未来得到改善。

与其他数据库方案的比较

• vs. 传统 RDBMS (PostgreSQL, MySQL等)：传统数据库功能更全面、生态更成熟、性能上限更高，适合复杂事务、大型数据集和高写入吞吐量。但它们需要专业的运维团队、成本较高且不天然具备边缘访问能力（需要额外的架构设计）。D1 运维成本极低，天然适合边缘和 Serverless 应用，但功能和性能上限较低。
• vs. Serverless NoSQL (DynamoDB, FaunaDB等)：这些 NoSQL 数据库提供 Serverless 特性，但它们使用非关系型模型（键值对、文档、图等）和不同的查询语言。D1 提供的是熟悉的 SQL 和关系型模型，对于习惯关系型数据的开发者更友好。性能特性和定价模型也存在差异。
• vs. Cloudflare KV：KV 是一个键值存储，非常适合存储简单的键值对或小型非结构化数据，延迟极低，非常适合查找。但它不支持关系型查询、事务或复杂的数据结构。D1 适用于结构化数据、需要复杂查询和关系的场景。
• vs. Cloudflare Durable Objects：Durable Objects 提供了有状态的 Serverless 对象，每个对象都有单线程执行和持久化存储。适合构建分布式协调、实时状态管理等场景。D1 是一个通用的数据库服务，用于存储和查询大量结构化数据。

选择哪种数据库取决于您的具体应用需求、数据模型、性能要求、运维能力和成本预算。D1 在需要轻量级、Serverless、边缘访问、基于 SQL 的关系型数据存储的场景中表现出色。

总结与展望

Cloudflare D1 是边缘计算和 Serverless 领域一个令人兴奋的进展。它解决了将关系型数据存储推向边缘的挑战，通过构建在成熟的 SQLite 之上并深度集成到 Cloudflare 的全球网络，为开发者提供了一个易于使用、高性能、低成本的 Serverless 关系型数据库。

本文从概念介绍出发，详细阐述了 D1 的优势和工作原理，并通过一个详尽的快速入门示例，手把手地指导您完成了数据库的创建、绑定、表结构初始化以及在 Worker 中的基本 CRUD 操作。我们还探讨了 D1 的高级功能、适用场景、限制以及与其他方案的比较。

随着 Serverless 和边缘计算成为构建现代应用的主流范式，Cloudflare D1 无疑将扮演越来越重要的角色。Cloudflare 也在持续投入，未来我们可以期待 D1 在全球分布能力（读副本）、性能优化、工具链支持和新特性方面取得更多进展。

如果您正在构建新的边缘应用、Serverless API 或希望为您的静态网站添加一个简单的动态层，Cloudflare D1 绝对值得您尝试。通过本文的快速入门指南，您已经迈出了第一步。现在，是时候深入探索，利用 Cloudflare D1 的强大能力，构建您的下一个创新应用了！

拥抱边缘，释放数据的力量，从 Cloudflare D1 开始吧！

---