Cloudflare D1

Cloudflare D1 是 Cloudflare 推出的 Serverless SQLite 数据库，原生集成在 Cloudflare Workers 生态中，零配置、零运维，按需计费，适合边缘计算和全球分布式应用场景。

ShipAny 已集成 Cloudflare D1，按照下面的步骤快速接入。

快速开始

创建 D1 数据库

在项目根目录下执行命令，创建 D1 数据库：

pnpm wrangler d1 create your-database-name

创建完成后，记录下数据库的 database_name 和 database_id，后续配置会用到。

配置 wrangler.toml

在项目根目录的 wrangler.toml 文件中，添加 D1 数据库绑定配置：

[[d1_databases]]
binding = "DB"
database_name = "your-database-name"
database_id = "your-database-id"
migrations_dir = "src/config/db/migrations_d1"

binding，D1 数据库在 Workers 中的绑定名称，固定值 DB
database_name，D1 数据库名称，填创建时设置的名称
database_id，D1 数据库 ID，填创建后获取的 ID
migrations_dir，选填，数据库迁移文件目录，默认值 ./migrations/，需要与 env 文件中的 DB_MIGRATIONS_OUT 配置一致

配置环境变量

在项目的环境变量文件中，填入 D1 数据库相关的配置。

本地开发环境变量文件 .env.development
生产环境变量文件 .env.production
Cloudflare Workers 环境变量文件 wrangler.toml

DATABASE_PROVIDER = "d1"
DB_SCHEMA_FILE = "./src/config/db/schema.sqlite.ts"
DB_MIGRATIONS_OUT = "./src/config/db/migrations_d1"

DATABASE_PROVIDER，必填，固定值 d1
DB_SCHEMA_FILE，必填，固定值 ./src/config/db/schema.sqlite.ts
DB_MIGRATIONS_OUT，选填，数据库迁移文件输出路径，默认值 ./src/config/db/migrations，可以根据数据库类型选择不同的输出路径

注意：D1 数据库通过 Workers 绑定访问，不需要配置 DATABASE_URL。

修改数据库 Schema 文件

使用 D1 数据库时，数据表结构定义在 ./src/config/db/schema.sqlite.ts 文件中（D1 兼容 SQLite 语法），你需要导出这个文件的数据表。

打开 ./src/config/db/schema.ts 文件，修改内容为：

export * from './schema.sqlite';

迁移数据表

先生成迁移文件：

pnpm db:generate

然后在项目根目录下执行命令，迁移数据表到远端的 D1 数据库：

pnpm wrangler d1 migrations apply your-database-name --remote

管理数据库

你可以在 Cloudflare Dashboard 的 D1 管理页面查看和管理数据库，也可以通过命令行操作：

pnpm wrangler d1 execute your-database-name --remote --command "SELECT * FROM user LIMIT 10"

自定义

修改数据表

如果你需要新增数据表，或者修改数据表字段，可以打开 ./src/config/db/schema.sqlite.ts 文件，修改数据表结构。

修改完成后，执行以下命令，生成并应用迁移：

pnpm db:generate
pnpm wrangler d1 migrations apply your-database-name --remote

修改数据库连接

D1 数据库通过 Cloudflare Workers 的绑定机制访问，连接由 Workers 运行时自动管理，无需手动配置连接池或认证信息。

在进行数据操作时，默认使用的是 ./src/core/db/index.ts 导出的 db() 对象，导出类型是 any，在某些情况下，可能会缺乏类型提示。

import { db } from '@/core/db';
import { user } from '@/config/db/schema';

const [result] = await db().select().from(user).limit(1);

如果你希望使用强类型的数据库对象，可以在操作数据时，使用以下方式获取数据库对象：

import { dbSqlite } from '@/core/db';
import { user } from '@/config/db/schema';

const [result] = await dbSqlite().select().from(user).limit(1);

部署到 Cloudflare Workers

D1 是 Cloudflare 的原生服务，天然支持部署到 Cloudflare Workers，无需额外配置 Hyperdrive 或外部连接。

在 Cloudflare Workers 部署的 wrangler.toml 部分内容参考：

[[d1_databases]]
binding = "DB"
database_name = "your-database-name"
database_id = "your-database-id"
migrations_dir = "src/config/db/migrations_d1"

[vars]
DATABASE_PROVIDER = "d1"

以上演示的是在 ShipAny 项目连接远端的 Cloudflare D1 数据库，本地开发建议使用：SQLite 数据库。

Cloudflare D1

快速开始

自定义

修改数据表

修改数据库连接

部署到 Cloudflare Workers

参考

On this page