はじめに · Cloudflare D1 ドキュメント

このガイドでは、次の作業を順に進めます。

Cloudflare のネイティブなサーバーレス SQL データベースである D1 で、最初のデータベースを作成する。
コマンドラインでスキーマを作成し、データベースを照会する。
バインディングで Cloudflare Worker を D1 データベースに接続し、プログラムから D1 を照会する。

作業は CLI または Cloudflare ダッシュボードから行えます。

クイックスタート

手順を飛ばしてすぐに始めたい場合は、次のボタンをクリックします。

GitHub アカウントにリポジトリが作成され、アプリケーションが Cloudflare Workers へデプロイされます。Cloudflare Workers に慣れていて、手順ごとの案内を飛ばしたい場合に使います。

Cloudflare Workers が初めてなら、手順を手作業で進める方がよいことがあります。

前提条件

Cloudflare アカウント ↗ に登録します。
Node.js ↗ をインストールします。

Node.js のバージョンマネージャー

権限の問題を避け、Node.js のバージョンを切り替えられるよう、Volta ↗ や nvm ↗ などの Node バージョンマネージャーを使います。このガイドの後半で説明する 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 ページを開きます。 Workers & Pages を開く ↗
Create application を選択します。
Start with Hello World! > Get started を選択します。
Worker に名前を付けます。このチュートリアルでは、Worker 名を d1-tutorial にします。
Deploy を選択します。

2. データベースを作成する

D1 データベースは、他の多くの SQL データベースと概念的に似ています。1 つ以上のテーブルを持ち、それらのテーブルを照会でき、任意でインデックスも使えます。D1 は使い慣れた SQL クエリ言語 ↗（SQLite と同じ）を使います。

最初の D1 データベースを作成するには、次の手順を実行します。

先ほど作成した Workers プロジェクトのディレクトリへ移動します。
```
cd d1-tutorial
```
次の wrangler@latest d1 コマンドを実行し、データベースに名前を付けます。このチュートリアルでは、データベース名を prod-d1-tutorial にします。

Note
Wrangler コマンドラインインターフェイスは、ターミナルから Workers アプリケーションと D1 データベースを管理・デプロイするための Cloudflare のツールです。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 データベースが作成され、次の手順で必要なバインディング設定が出力されます。

Cloudflare ダッシュボードで、D1 SQL database ページを開きます。
D1 SQL database を開く ↗
Create Database を選択します。
データベースに名前を付けます。このチュートリアルでは、D1 データベース名を prod-d1-tutorial にします。
（任意）ロケーションヒントを指定します。ロケーションヒントは、データベースの希望する地理的な場所を示す任意のパラメーターです。詳細はロケーションヒントを指定するを参照してください。
Create を選択します。

3. Worker を D1 データベースにバインドする

Worker を D1 データベースに接続するには、バインディングを作成する必要があります。バインディングにより、Worker は D1 など Cloudflare 開発者プラットフォーム上のリソースへアクセスできます。

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 にもバインドできます。詳細は Functions Bindings for D1 を参照してください。

バインディングは、作成した Worker に追加して作ります。

Cloudflare ダッシュボードで、Workers & Pages ページを開きます。 Workers & Pages を開く ↗
手順 1 で作成した d1-tutorial Worker を選択します。
Bindings タブを開きます。
Add binding を選択します。
D1 database > 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 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 インジェクション」）のを防ぎ、データベースの削除や改変を避けられます。
run() を呼んでクエリを実行し、すべての行を返します（結果がなければ空です）。
クエリ結果があれば、Response.json(results) で JSON 形式で返します。

Worker を設定したら、グローバルにデプロイする前に、プロジェクトをローカルでテストできます。

Worker から D1 データベースを照会できます。

Cloudflare ダッシュボードで、Workers & Pages ページを開きます。
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 を本番へデプロイするには、まず --local フラグを --remote フラグに置き換えて、データベース設定の手順を繰り返します。Worker が読むデータを用意します。これで、本番版データベースにテーブルが作成され、データがインポートされます。

手順 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               │
└────────────────────────┴───────────┴──────────────┴────────────────────┘

本番にデータがあることを、次を実行して確認します。

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 ページを開きます。 Workers & Pages を開く ↗
d1-tutorial Worker を選択します。
Deployments を選択します。
Version History テーブルから Deploy version を選択します。
Deploy version ページで Deploy を選択します。

これで、最新バージョンの Worker コードが本番へデプロイされます。

6. （任意）Wrangler でローカル開発する

D1 を Wrangler と一緒に使っている場合、データベースをローカルでテストできます。プロジェクトディレクトリで次を実行します。

wrangler dev を実行します。
```
npx wrangler dev
```
wrangler dev を実行すると、Wrangler は Worker を確認するための URL（多くの場合 localhost:8787）を表示します。
その 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 database を開く ↗
prod-d1-tutorial D1 データベースを選択します。
Settings を選択します。
Delete を選択します。
削除を確認するため、データベース名（prod-d1-tutorial）を入力します。

Worker を削除したい場合は、次の手順を実行します。

次を実行します。

npx wrangler delete d1-tutorial

Cloudflare ダッシュボードで、Workers & Pages ページを開きます。
Workers & Pages を開く ↗
d1-tutorial Worker を選択します。
Settings を選択します。
ページの最下部までスクロールし、Delete を選択します。
削除を確認するため、Worker 名（d1-tutorial）を入力します。

まとめ

このチュートリアルでは、次を行いました。

D1 データベースを作成した
そのデータベースへアクセスする Worker を作成した
プロジェクトをグローバルにデプロイした

次のステップ

機能の要望や不具合を見つけた場合は、Discord の Cloudflare Developers コミュニティ ↗ に参加し、Cloudflare チームへ直接フィードバックを共有してください。

D1 向けの対応 Wrangler コマンドを確認する。
Worker 内で D1 Worker Binding APIs を使う方法を学び、API playground で試す。
D1 上のコミュニティプロジェクトを探す。