快速入门 · Cloudflare D1 docs

本指南将引导您完成：

使用 D1（Cloudflare 原生无服务器 SQL 数据库）创建第一个数据库。
创建 schema 并通过命令行查询数据库。
使用绑定（binding）将 Cloudflare Worker 连接到 D1 数据库，并以编程方式查询 D1 数据库。

您可以通过 CLI 或 Cloudflare 仪表板执行这些任务。

快速开始

如果您想跳过步骤快速开始，请点击下方按钮。

这会在您的 GitHub 账户中创建仓库并将应用部署到 Cloudflare Workers。如果您熟悉 Cloudflare Workers 并希望跳过逐步指导，请使用此选项。

如果您是 Cloudflare Workers 新手，可能需要手动按步骤操作。

前提条件

注册 Cloudflare 账户 ↗。
安装 Node.js ↗。

Node.js 版本管理器

使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器，以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。

1. 创建 Worker

创建新的 Worker 作为查询数据库的方式。

运行以下命令创建名为 d1-tutorial 的新项目：
npm create cloudflare@latest -- d1-tutorial
yarn create cloudflare d1-tutorial
pnpm create cloudflare@latest d1-tutorial
进行设置时，请选择以下选项：
- 对于 What would you like to start with?，选择 Hello World example。
- 对于 Which template would you like to use?，选择 Worker only。
- 对于 Which language do you want to use?，选择 TypeScript。
- 对于 Do you want to use git for version control?，选择 Yes。
- 对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。
这将创建如下所示的新 d1-tutorial 目录。
- d1-tutorial
  - node_modules/
  - test/
  - src
    - index.ts
  - package-lock.json
  - package.json
  - testconfig.json
  - vitest.config.mts
  - worker-configuration.d.ts
  - wrangler.jsonc
新的 d1-tutorial 目录包含：
- index.ts 中的 "Hello World" Worker。
- Wrangler 配置文件。此文件定义 d1-tutorial Worker 如何访问 D1 数据库。

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。 Go to Workers & Pages ↗
选择 Create application（创建应用程序）。
选择 Start with Hello World!（从 Hello World 开始！） > Get started（开始使用）。
为 Worker 命名。在本教程中，将 Worker 命名为 d1-tutorial。
选择 Deploy（部署）。

2. 创建数据库

D1 数据库在概念上与其他许多 SQL 数据库类似：一个数据库可包含一个或多个表、查询这些表的能力，以及可选的索引。D1 使用熟悉的 SQL 查询语言 ↗（与 SQLite 相同）。

要创建第一个 D1 数据库：

进入您刚为 Workers 项目创建的目录：
```
cd d1-tutorial
```
运行以下 wrangler@latest d1 命令并为数据库命名。在本教程中，数据库命名为 prod-d1-tutorial：

说明
Wrangler 命令行接口是 Cloudflare 用于在终端中管理和部署 Workers 应用及 D1 数据库的工具。使用 npm create cloudflare@latest 初始化新项目时已安装。
虽然 Wrangler 会本地安装到项目中，您也可在项目外通过 npx wrangler 命令使用它。
```
npx wrangler@latest d1 create prod-d1-tutorial
```
```
✅ Successfully created DB 'prod-d1-tutorial' in region WEUR
Created your new D1 database.

{
	"d1_databases": [
		{
			"binding": "prod_d1_tutorial",
			"database_name": "prod-d1-tutorial",
			"database_id": "<unique-ID-for-your-database>"
		}
	]
}
```
当提示 Would you like Wrangler to add it on your behalf? 时，选择 Yes。这将自动将绑定添加到 Wrangler 配置文件。

这将创建新的 D1 数据库，并输出下一步所需的绑定（binding）配置。

在 Cloudflare 仪表板中，前往 D1 SQL database（D1 SQL 数据库） 页面。
Go to D1 SQL database ↗
选择 Create Database（创建数据库）。
为数据库命名。在本教程中，将 D1 数据库命名为 prod-d1-tutorial。
（可选）提供位置提示。位置提示是一个可选参数，用于指明您希望数据库所在的地理区域。请参阅提供位置提示了解更多信息。
选择 Create（创建）。

3. 将 Worker 绑定到 D1 数据库

您必须为 Worker 创建绑定才能连接到 D1 数据库。绑定（Bindings）允许 Worker 访问 Cloudflare 开发者平台上的 D1 等资源。

要将 D1 数据库绑定到 Worker：

运行 wrangler d1 create 命令时（2. 创建数据库的步骤 3），可自动将绑定添加到 Wrangler 配置文件。

但如果您希望手动添加绑定，请按以下步骤操作：

从终端复制 2. 创建数据库步骤 2 获得的行。
将它们添加到 Wrangler 文件末尾。
{ "d1_databases": [ { "binding": "prod_d1_tutorial", // available in your Worker on env.DB "database_name": "prod-d1-tutorial", "database_id": "<unique-ID-for-your-database>" } ] }
[[d1_databases]] binding = "prod_d1_tutorial" database_name = "prod-d1-tutorial" database_id = "<unique-ID-for-your-database>"
具体来说：
- 您为 binding 设置的值（字符串）是绑定名称，用于在 Worker 中引用此数据库。在本教程中，将绑定命名为 prod_d1_tutorial。
- 绑定名称必须是有效的 JavaScript 变量名 ↗。例如，binding = "MY_DB" 或 binding = "productionDB" 都是有效的绑定名称。
- 绑定在 Worker 中可通过 env.<BINDING_NAME> 访问，D1 Workers Binding API 在此绑定上暴露。

您也可以将 D1 数据库绑定到 Pages Function。更多信息请参阅 D1 的 Functions 绑定。

通过将绑定添加到已创建的 Worker 来创建绑定。

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。 Go to Workers & Pages ↗
选择您在步骤 1 中创建的 d1-tutorial Worker。
前往 Bindings（绑定） 选项卡。
选择 Add binding（添加绑定）。
选择 D1 database（D1 数据库） > Add binding（添加绑定）。
在 Variable name（变量名称） 中命名绑定，然后从下拉菜单中选择您在步骤 2 中创建的 prod-d1-tutorial D1 数据库。在本教程中，将绑定命名为 prod_d1_tutorial。
选择 Add binding（添加绑定）。

4. 对 D1 数据库运行查询

填充 D1 数据库

正确配置 Wrangler 配置文件后，设置数据库。使用以下 SQL 语法创建 schema.sql 文件以初始化数据库。

复制以下代码并保存为步骤 1 中创建的 d1-tutorial Worker 目录下的 schema.sql 文件：

DROP TABLE IF EXISTS Customers;
CREATE TABLE IF NOT EXISTS Customers (CustomerId INTEGER PRIMARY KEY, CompanyName TEXT, ContactName TEXT);
INSERT INTO Customers (CustomerID, CompanyName, ContactName) VALUES (1, 'Alfreds Futterkiste', 'Maria Anders'), (4, 'Around the Horn', 'Thomas Hardy'), (11, 'Bs Beverages', 'Victoria Ashworth'), (13, 'Bs Beverages', 'Random Name');

先在本地运行和测试，初始化数据库。通过运行以下命令引导新的 D1 数据库：

npx wrangler d1 execute prod-d1-tutorial --local --file=./schema.sql

⛅️ wrangler 4.13.2
-------------------

🌀 Executing on local database prod-d1-tutorial (<DATABASE_ID>) from .wrangler/state/v3/d1:
🌀 To execute on your remote database, add a --remote flag to your wrangler command.
🚣 3 commands executed successfully.

通过运行以下命令验证数据是否在数据库中：

npx wrangler d1 execute prod-d1-tutorial --local --command="SELECT * FROM Customers"

 🌀 Executing on local database jun-d1-db-gs-2025 (cf91ec5c-fa77-4d49-ad8e-e22921b996b2) from .wrangler/state/v3/d1:
 🌀 To execute on your remote database, add a --remote flag to your wrangler command.
 🚣 1 command executed successfully.
 ┌────────────┬─────────────────────┬───────────────────┐
 │ CustomerId │ CompanyName         │ ContactName       │
 ├────────────┼─────────────────────┼───────────────────┤
 │ 1          │ Alfreds Futterkiste │ Maria Anders      │
 ├────────────┼─────────────────────┼───────────────────┤
 │ 4          │ Around the Horn     │ Thomas Hardy      │
 ├────────────┼─────────────────────┼───────────────────┤
 │ 11         │ Bs Beverages        │ Victoria Ashworth │
 ├────────────┼─────────────────────┼───────────────────┤
 │ 13         │ Bs Beverages        │ Random Name       │
 └────────────┴─────────────────────┴───────────────────┘

使用仪表板创建表并填充数据。

在 Cloudflare 仪表板中，前往 D1 SQL database（D1 SQL 数据库） 页面。
Go to D1 SQL database ↗
选择您在步骤 2 中创建的 prod-d1-tutorial 数据库。
选择 Console（控制台）。

粘贴以下 SQL 片段。

DROP TABLE IF EXISTS Customers;
CREATE TABLE IF NOT EXISTS Customers (CustomerId INTEGER PRIMARY KEY, CompanyName TEXT, ContactName TEXT);
INSERT INTO Customers (CustomerID, CompanyName, ContactName) VALUES (1, 'Alfreds Futterkiste', 'Maria Anders'), (4, 'Around the Horn', 'Thomas Hardy'), (11, 'Bs Beverages', 'Victoria Ashworth'), (13, 'Bs Beverages', 'Random Name');

选择 Execute（执行）。这会在 prod-d1-tutorial 数据库中创建名为 Customers 的表。
选择 Tables（表），然后选择 Customers 表查看表内容。

在 Worker 中编写查询

设置数据库后，在 Worker 内运行 SQL 查询。

进入 d1-tutorial Worker 并打开 index.ts 文件。index.ts 是配置 Worker 与 D1 交互的地方。
清空 index.ts 的内容。

将以下代码片段粘贴到 index.ts 文件中：

index.jsjs

export default {
	async fetch(request, env) {
		const { pathname } = new URL(request.url);

		if (pathname === "/api/beverages") {
			// If you did not use `DB` as your binding name, change it here
			const { results } = await env.prod_d1_tutorial
				.prepare("SELECT * FROM Customers WHERE CompanyName = ?")
				.bind("Bs Beverages")
				.run();
			return Response.json(results);
		}

		return new Response(
			"Call /api/beverages to see everyone who works at Bs Beverages",
		);
	},
};

index.tsts

export interface Env {
	// If you set another name in the Wrangler config file for the value for 'binding',
	// replace "DB" with the variable name you defined.
	prod_d1_tutorial: D1Database;
}

export default {
	async fetch(request, env): Promise<Response> {
		const { pathname } = new URL(request.url);

		if (pathname === "/api/beverages") {
			// If you did not use `DB` as your binding name, change it here
			const { results } = await env.prod_d1_tutorial.prepare(
				"SELECT * FROM Customers WHERE CompanyName = ?",
			)
				.bind("Bs Beverages")
				.run();
			return Response.json(results);
		}

		return new Response(
			"Call /api/beverages to see everyone who works at Bs Beverages",
		);
	},
} satisfies ExportedHandler<Env>;

entry.pypython

from workers import Response, WorkerEntrypoint
from urllib.parse import urlparse

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        pathname = urlparse(request.url).path
        if pathname == "/api/beverages":
            query = (
                await self.env.prod_d1_tutorial.prepare(
                    "SELECT * FROM Customers WHERE CompanyName = ?",
                )
                .bind("Bs Beverages")
                .run()
            )
            return Response.json(query.results)
        return Response(
            "Call /api/beverages to see everyone who works at Bs Beverages"
        )

在上面的代码中，您：

在代码中定义到 D1 数据库的绑定。此绑定与 Wrangler 配置文件中 d1_databases 下设置的 binding 值匹配。
使用 env.prod_d1_tutorial.prepare 查询数据库，发出带占位符的预处理查询（查询中的 ?）。
调用 bind() 安全地将值绑定到该占位符。在实际应用中，您会允许用户传入要列出结果的 CompanyName。使用 bind() 可防止用户对应用执行任意 SQL（称为 "SQL injection"），从而删除或以其他方式修改数据库。
通过调用 run() 执行查询，返回所有行（如果查询无结果则返回空）。
使用 Response.json(results) 以 JSON 格式返回查询结果（如有）。

在全局部署之前，您可以在本地测试项目。

您可以使用 Worker 查询 D1 数据库。

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。
Go to Workers & Pages ↗
选择您创建的 d1-tutorial Worker。
选择 Edit code（编辑代码） 图标（</>）。

清空 worker.js 文件内容，然后粘贴以下代码：

export default {
	async fetch(request, env) {
		const { pathname } = new URL(request.url);

		if (pathname === "/api/beverages") {
			// If you did not use `DB` as your binding name, change it here
			const { results } = await env.prod_d1_tutorial.prepare(
				"SELECT * FROM Customers WHERE CompanyName = ?"
			)
				.bind("Bs Beverages")
				.run();
			return new Response(JSON.stringify(results), {
				headers: { 'Content-Type': 'application/json' }
			});
		}

		return new Response(
			"Call /api/beverages to see everyone who works at Bs Beverages"
		);
	},
};

选择 Save（保存）。

5. 部署应用

在 Cloudflare 全球网络上部署应用。

要使用 Wrangler 将 Worker 部署到 production，您必须首先重复数据库配置步骤，将 --local 标志替换为 --remote 标志，以便 Worker 有数据可读。这会在 production 版本的数据库中创建表并导入数据。

使用步骤 4 中创建的 schema.sql 文件在远程数据库中创建表并添加条目。输入 y 确认操作。

npx wrangler d1 execute prod-d1-tutorial --remote --file=./schema.sql

🌀 Executing on remote database prod-d1-tutorial (<DATABASE_ID>):
🌀 To execute on your local development database, remove the --remote flag from your wrangler command.
Note: if the execution fails to complete, your DB will return to its original state and you can safely retry.
├ 🌀 Uploading <DATABASE_ID>.a7f10c4651cc3a26.sql
│ 🌀 Uploading complete.
│
🌀 Starting import...
🌀 Processed 3 queries.
🚣 Executed 3 queries in 0.00 seconds (5 rows read, 6 rows written)
Database is currently at bookmark 00000000-0000000a-00004f6d-b85c16a3dbcf077cb8f258b4d4eb965e.
┌────────────────────────┬───────────┬──────────────┬────────────────────┐
│ Total queries executed │ Rows read │ Rows written │ Database size (MB) │
├────────────────────────┼───────────┼──────────────┼────────────────────┤
│ 3                      │ 5         │ 6            │ 0.02               │
└────────────────────────┴───────────┴──────────────┴────────────────────┘

通过运行以下命令验证 production 中的数据：

npx wrangler d1 execute prod-d1-tutorial --remote --command="SELECT * FROM Customers"


⛅️ wrangler 4.33.1
───────────────────
🌀 Executing on remote database jun-d1-db-gs-2025 (cf91ec5c-fa77-4d49-ad8e-e22921b996b2):
🌀 To execute on your local development database, remove the --remote flag from your wrangler command.
🚣 Executed 1 command in 0.1797ms
┌────────────┬─────────────────────┬───────────────────┐
│ CustomerId │ CompanyName         │ ContactName       │
├────────────┼─────────────────────┼───────────────────┤
│ 1          │ Alfreds Futterkiste │ Maria Anders      │
├────────────┼─────────────────────┼───────────────────┤
│ 4          │ Around the Horn     │ Thomas Hardy      │
├────────────┼─────────────────────┼───────────────────┤
│ 11         │ Bs Beverages        │ Victoria Ashworth │
├────────────┼─────────────────────┼───────────────────┤
│ 13         │ Bs Beverages        │ Random Name       │
└────────────┴─────────────────────┴───────────────────┘

部署 Worker 使项目可在互联网上访问。运行：

npx wrangler deploy

⛅️ wrangler 4.33.1
────────────────────
Total Upload: 0.52 KiB / gzip: 0.33 KiB
Your Worker has access to the following bindings:
Binding                                        Resource
env.prod_d1_tutorial (prod-d1-tutorial)        D1 Database

Uploaded prod-d1-tutorial (4.17 sec)
Deployed prod-d1-tutorial triggers (3.49 sec)
https://prod-d1-tutorial.pcx-team.workers.dev
Current Version ID: 42c82f1c-ff2b-4dce-9ea2-265adcccd0d5

您现在可以访问新创建项目的 URL 来查询实时数据库。

例如，如果新 Worker 的 URL 是 d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev，访问 https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beverages 会向 Worker 发送请求，直接查询实时数据库。

测试数据库是否成功运行。在提供的 Wrangler URL 后添加 /api/beverages。例如 https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beverages。

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。 Go to Workers & Pages ↗
选择您的 d1-tutorial Worker。
选择 Deployments（部署）。
在 Version History（版本历史） 表中，选择 Deploy version（部署版本）。
在 Deploy version（部署版本） 页面，选择 Deploy（部署）。

这将把 Worker 代码的最新版本部署到 production。

6. （可选）使用 Wrangler 进行本地开发

如果您将 D1 与 Wrangler 一起使用，可以在本地测试数据库。在项目目录中：

运行 wrangler dev：
```
npx wrangler dev
```
运行 wrangler dev 时，Wrangler 会提供一个 URL（很可能是 localhost:8787）供您查看 Worker。
访问该 URL。

页面显示 Call /api/beverages to see everyone who works at Bs Beverages。
测试数据库是否成功运行。在提供的 Wrangler URL 后添加 /api/beverages。例如 localhost:8787/api/beverages。

如果成功，浏览器会显示您的数据。

7. （可选）删除数据库

要删除数据库：

运行：

npx wrangler d1 delete prod-d1-tutorial

在 Cloudflare 仪表板中，前往 D1 SQL database（D1 SQL 数据库） 页面。
Go to D1 SQL database ↗
选择您的 prod-d1-tutorial D1 数据库。
选择 Settings（设置）。
选择 Delete（删除）。
输入数据库名称（prod-d1-tutorial）以确认删除。

如果要删除 Worker：

运行：

npx wrangler delete d1-tutorial

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。
Go to Workers & Pages ↗
选择您的 d1-tutorial Worker。
选择 Settings（设置）。
滚动到页面底部，然后选择 Delete（删除）。
输入 Worker 名称（d1-tutorial）以确认删除。

摘要

在本教程中，您：

创建了 D1 数据库
创建了访问该数据库的 Worker
在全球部署了项目

后续步骤

如果您有任何功能请求或发现任何 bug，请加入 Cloudflare Developers Discord 社区 ↗ 直接向 Cloudflare 团队分享反馈。

查看 D1 支持的 Wrangler 命令。
了解如何在 Worker 中使用 D1 Worker Binding API，并从 API playground 测试它们。
探索基于 D1 构建的社区项目。