Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

はじめに

最終更新 Markdown で表示Agent セットアップ

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

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

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

クイックスタート

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

Deploy to Cloudflare

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

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

前提条件

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

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

権限の問題を避け、Node.js のバージョンを切り替えられるよう、Volta ↗ や nvm ↗ などの Node バージョンマネージャーを使います。このガイドの後半で説明する Wrangler には、Node バージョン 16.17.0 以降が必要です。

1. Worker を作成する

データベースを照会する手段として、新しい Worker を作成します。

  1. 次を実行して、d1-tutorial という名前の新しいプロジェクトを作成します。

    npm 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 データベースへアクセスします。
  1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。 公式ダッシュボードで Workers & Pages を開く ↗
  2. Create application を選択します。
  3. Start with Hello World! > Get started を選択します。
  4. Worker に名前を付けます。このチュートリアルでは、Worker 名を d1-tutorial にします。
  5. Deploy を選択します。

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

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

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

  1. 先ほど作成した Workers プロジェクトのディレクトリへ移動します。

    cd d1-tutorial
  2. 次の wrangler@latest d1 コマンドを実行し、データベースに名前を付けます。このチュートリアルでは、データベース名を prod-d1-tutorial にします。

    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>"
    		}
    	]
    }
  3. Would you like Wrangler to add it on your behalf? と尋ねられたら、Yes を選びます。Wrangler 設定ファイルへバインディングが自動で追加されます。

新しい D1 データベースが作成され、次の手順で必要な バインディング 設定が出力されます。

  1. Cloudflare ダッシュボードで、D1 SQL database ページを開きます。

    公式ダッシュボードで D1 SQL database を開く ↗
  2. Create Database を選択します。

  3. データベースに名前を付けます。このチュートリアルでは、D1 データベース名を prod-d1-tutorial にします。

  4. (任意)ロケーションヒントを指定します。ロケーションヒントは、データベースの希望する地理的な場所を示す任意のパラメーターです。詳細は ロケーションヒントを指定する を参照してください。

  5. Create を選択します。

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

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

D1 データベースを Worker にバインドするには、次の手順を実行します。

wrangler d1 create コマンド(2. データベースを作成する の手順 3)を実行したときに、Wrangler 設定ファイルへバインディングを自動追加できます。

手動で追加したい場合は、次の手順に従います。

  1. 2. データベースを作成する の手順 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 に追加して作ります。

  1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。 公式ダッシュボードで Workers & Pages を開く ↗
  2. 手順 1 で作成した d1-tutorial Worker を選択します。
  3. Bindings タブを開きます。
  4. Add binding を選択します。
  5. D1 database > Add binding を選択します。
  6. Variable name にバインディング名を入力し、ドロップダウンから 手順 2 で作成した prod-d1-tutorial D1 データベースを選びます。このチュートリアルでは、バインディング名を prod_d1_tutorial にします。
  7. Add binding を選択します。

4. D1 データベースに対してクエリを実行する

D1 データベースにデータを投入する

Wrangler 設定ファイル を正しく用意したら、データベースをセットアップします。次の SQL 構文で schema.sql ファイルを作成し、データベースを初期化します。

  1. 次のコードをコピーし、手順 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');
  2. まずローカルで実行してテストできるよう、データベースを初期化します。次を実行して、新しい 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.
  3. データがデータベースに入っていることを、次を実行して確認します。

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

ダッシュボードでテーブルを作成し、データを投入します。

  1. Cloudflare ダッシュボードで、D1 SQL database ページを開きます。

    公式ダッシュボードで D1 SQL database を開く ↗
  2. 手順 2 で作成した prod-d1-tutorial データベースを選択します。

  3. Console を選択します。

  4. 次の 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');
  5. Execute を選択します。prod-d1-tutorial データベースに Customers というテーブルが作成されます。

  6. Tables を選び、Customers テーブルを選んで内容を確認します。

Worker 内でクエリを書く

データベースのセットアップが終わったら、Worker 内から SQL クエリを実行します。

  1. d1-tutorial Worker へ移動し、index.ts ファイルを開きます。index.ts は、Worker と D1 のやり取りを設定するファイルです。

  2. index.ts の内容を空にします。

  3. 次のコードスニペットを 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"
            )

    上記のコードでは、次を行っています。

    1. コード内で D1 データベースへのバインディングを定義します。このバインディングは、Wrangler 設定ファイル の d1_databases で設定した binding 値と一致します。
    2. env.prod_d1_tutorial.prepare でデータベースを照会し、プレースホルダー(クエリ内の ?)付きの 準備済みクエリ を発行します。
    3. bind() を呼んで、そのプレースホルダーへ値を安全にバインドします。実際のアプリケーションでは、結果を一覧したい CompanyName をユーザーに渡させます。bind() を使うと、ユーザーが任意の SQL を実行する(いわゆる「SQL インジェクション」)のを防ぎ、データベースの削除や改変を避けられます。
    4. run() を呼んでクエリを実行し、すべての行を返します(結果がなければ空です)。
    5. クエリ結果があれば、Response.json(results) で JSON 形式で返します。

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

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

  1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

    公式ダッシュボードで Workers & Pages を開く ↗
  2. 作成した d1-tutorial Worker を選択します。

  3. Edit code アイコン(</>)を選択します。

  4. 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"
    		);
    	},
    };
  5. Save を選択します。

5. アプリケーションをデプロイする

Cloudflare のグローバルネットワークへアプリケーションをデプロイします。

Wrangler で Worker を本番へデプロイするには、まず --local フラグを --remote フラグに置き換えて、データベース設定 の手順を繰り返します。Worker が読むデータを用意します。これで、本番版データベースにテーブルが作成され、データがインポートされます。

  1. 手順 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               │
    └────────────────────────┴───────────┴──────────────┴────────────────────┘
  2. 本番にデータがあることを、次を実行して確認します。

    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       │
    └────────────┴─────────────────────┴───────────────────┘
  3. 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 が稼働中のデータベースを直接照会します。

  4. データベースが正常に動いていることを確認します。表示された Wrangler URL に /api/beverages を付けます。例: https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beverages。

  1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。 公式ダッシュボードで Workers & Pages を開く ↗
  2. d1-tutorial Worker を選択します。
  3. Deployments を選択します。
  4. Version History テーブルから Deploy version を選択します。
  5. Deploy version ページで Deploy を選択します。

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

6. (任意)Wrangler でローカル開発する

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

  1. wrangler dev を実行します。

    npx wrangler dev

    wrangler dev を実行すると、Wrangler は Worker を確認するための URL(多くの場合 localhost:8787)を表示します。

  2. その URL を開きます。

    ページには Call /api/beverages to see everyone who works at Bs Beverages と表示されます。

  3. データベースが正常に動いていることを確認します。表示された Wrangler URL に /api/beverages を付けます。例: localhost:8787/api/beverages。

成功すると、ブラウザーにデータが表示されます。

7. (任意)データベースを削除する

データベースを削除するには、次の手順を実行します。

次を実行します。

npx wrangler d1 delete prod-d1-tutorial
  1. Cloudflare ダッシュボードで、D1 SQL database ページを開きます。

    公式ダッシュボードで D1 SQL database を開く ↗
  2. prod-d1-tutorial D1 データベースを選択します。

  3. Settings を選択します。

  4. Delete を選択します。

  5. 削除を確認するため、データベース名(prod-d1-tutorial)を入力します。

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

次を実行します。

npx wrangler delete d1-tutorial
  1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

    公式ダッシュボードで Workers & Pages を開く ↗
  2. d1-tutorial Worker を選択します。

  3. Settings を選択します。

  4. ページの最下部までスクロールし、Delete を選択します。

  5. 削除を確認するため、Worker 名(d1-tutorial)を入力します。

まとめ

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

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

次のステップ

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

役に立ちましたか?