Cloudflare D1

Cloudflare D1 is a Serverless SQLite database by Cloudflare, natively integrated into the Cloudflare Workers ecosystem. It requires zero configuration and zero maintenance, with pay-as-you-go pricing, making it ideal for edge computing and globally distributed applications.

ShipAny has integrated Cloudflare D1. Follow the steps below to get started quickly.

Quick Start

Create a D1 Database

Run the following command in the project root directory to create a D1 database:

pnpm wrangler d1 create your-database-name

After creation, note down the database_name and database_id, which will be used in subsequent configuration.

Configure wrangler.toml

Add the D1 database binding configuration in the wrangler.toml file at the project root:

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

binding: The binding name for the D1 database in Workers, fixed value DB
database_name: The D1 database name, use the name set during creation
database_id: The D1 database ID, use the ID obtained after creation
migrations_dir: Optional, the database migration files directory, defaults to ./migrations/, should match the DB_MIGRATIONS_OUT configuration in env files

Configure Environment Variables

Fill in the D1 database configuration in the project's environment variable files.

Local development environment file .env.development
Production environment file .env.production
Cloudflare Workers environment file wrangler.toml

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

DATABASE_PROVIDER: Required, fixed value d1
DB_SCHEMA_FILE: Required, fixed value ./src/config/db/schema.sqlite.ts
DB_MIGRATIONS_OUT: Optional, migration output path, defaults to ./src/config/db/migrations, can be customized based on database type

Note: D1 database is accessed via Workers bindings, so DATABASE_URL is not required.

Modify Database Schema File

When using D1 database, table structures are defined in ./src/config/db/schema.sqlite.ts (D1 is compatible with SQLite syntax). You need to export the tables from this file.

Open ./src/config/db/schema.ts and change its content to:

export * from './schema.sqlite';

Run Migrations

First, generate the migration files:

pnpm db:generate

Then run the following command in the project root to apply migrations to the remote D1 database:

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

Manage Database

You can view and manage the database on the D1 management page in the Cloudflare Dashboard, or use the command line:

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

Customization

Modify Tables

To add new tables or modify table fields, open ./src/config/db/schema.sqlite.ts and update the table structures.

After making changes, run the following commands to generate and apply migrations:

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

Modify Database Connection

D1 database is accessed through the Cloudflare Workers binding mechanism. Connections are automatically managed by the Workers runtime, requiring no manual configuration of connection pools or authentication.

For data operations, the default is the db() object exported from ./src/core/db/index.ts, which returns any type. In some cases, this may lack type hints.

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

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

If you prefer strongly-typed database objects, you can use the following approach:

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

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

Deploy to Cloudflare Workers

D1 is a native Cloudflare service that naturally supports deployment to Cloudflare Workers without additional Hyperdrive or external connection configuration.

Reference wrangler.toml configuration for Cloudflare Workers deployment:

[[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"

The above demonstrates connecting to a remote Cloudflare D1 database in a ShipAny project. For local development, it is recommended to use: SQLite database.