コンテンツにスキップ

始める

Last reviewed: 26 days ago

このガイドでは、以下のことを説明します：

  • D1を使用して最初のデータベースを作成する方法。D1はCloudflareのネイティブなサーバーレスSQLデータベースです。
  • スキーマを作成し、コマンドラインを介してデータベースをクエリする方法。
  • Cloudflare WorkerをD1データベースに接続して、プログラム的にD1データベースをクエリする方法。

前提条件

続行するには：

  1. まだアカウントを作成していない場合は、Cloudflareアカウント ↗にサインアップしてください。
  2. npm ↗をインストールします。
  3. Node.js ↗をインストールします。権限の問題を避け、Node.jsのバージョンを変更するために、Volta ↗やnvm ↗のようなNodeバージョンマネージャーを使用してください。Wranglerは、16.17.0以上のNodeバージョンを必要とします。

1. Workerを作成する

データベースをクエリする手段として新しいWorkerを作成します。

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

    Terminal window
    npm create cloudflare@latest -- d1-tutorial

    For setup, select the following options:

    • For What would you like to start with?, choose Hello Worldの例.
    • For Which template would you like to use?, choose Hello World Worker.
    • For Which language do you want to use?, choose TypeScript.
    • For Do you want to use git for version control?, choose Yes.
    • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

    これにより、以下のように新しい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.toml

    新しいd1-tutorialディレクトリには以下が含まれています：

    • index.tsにある「Hello World」Worker。
    • D1データベースにアクセスするためのwrangler.toml設定ファイル。wrangler.tomlは、d1-tutorial WorkerがD1データベースにアクセスする方法です。

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

D1データベースは、他の多くのデータベースと概念的に似ています：データベースは1つ以上のテーブルを含むことができ、これらのテーブルをクエリする機能とオプションのインデックスを持っています。D1は、SQLiteで使用されるSQLクエリ言語 ↗を使用します。

最初のD1データベースを作成するには：

  1. Workersプロジェクトのために作成したディレクトリに移動します：

    Terminal window
    cd d1-tutorial

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

    Terminal window
    npx wrangler d1 create prod-d1-tutorial
    ✅ DB 'prod-d1-tutorial'を正常に作成しました
    

    [[d1_databases]]
    binding = "DB" # env.DBでWorker内で利用可能
    database_name = "prod-d1-tutorial"
    database_id = "<unique-ID-for-your-database>"

これにより、新しいD1データベースが作成され、次のステップで必要なbinding設定が出力されます。

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

WorkerがD1データベースに接続するためのバインディングを作成する必要があります。Bindingsを使用すると、Cloudflare開発者プラットフォーム上のD1などのリソースにWorkersがアクセスできます。wrangler.tomlファイルを更新することでバインディングを作成します。

D1データベースをWorkerにバインドするには：

  1. ターミナルからステップ2で取得した行をコピーします。

  2. それらをwrangler.tomlファイルの末尾に追加します。

    [[d1_databases]]
    binding = "DB" # env.DBでWorker内で利用可能
    database_name = "prod-d1-tutorial"
    database_id = "<unique-ID-for-your-database>"

    具体的には：

    • bindingに設定する値（文字列）はバインディング名であり、Worker内でこのデータベースを参照するために使用されます。このチュートリアルでは、バインディング名をDBと名付けます。
    • バインディング名は有効なJavaScript変数名 ↗でなければなりません。例えば、binding = "MY_DB"やbinding = "productionDB"はどちらもバインディングの有効な名前です。
    • バインディングはenv.<BINDING_NAME>でWorker内で利用可能で、D1のクライアントAPIはこのバインディングで公開されます。

D1データベースをPages Functionにバインドすることもできます。詳細については、Functions Bindings for D1を参照してください。

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

D1データベースを構成する

wrangler.tomlが正しく構成されたら、データベースをセットアップします。以下の例の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データベースをブートストラップします：

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

  3. 次のコマンドを実行して、データがデータベースに存在することを確認します：

    Terminal window
    npx wrangler d1 execute prod-d1-tutorial --local --command="SELECT * FROM Customers"
    🌀 SQL入力をステートメントの配列にマッピング中
    🌀 ローカルデータベースproduction-db-backend (5f092302-3fbd-4247-a873-bf1afc5150b)で実行中 .wrangler/state/v3/d1:
    ┌────────────┬─────────────────────┬───────────────────┐
    │ 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内でクエリを書く

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

  1. d1-tutorial Workerに移動し、index.tsファイルを開きます。index.tsファイルは、D1とのWorkerの相互作用を構成する場所です。

  2. index.tsの内容をクリアします。

  3. 次のコードスニペットをindex.tsファイルに貼り付けます：

    export interface Env {
      // wrangler.tomlで'binding'の値に別の名前を設定した場合は、
      // "DB"を定義した変数名に置き換えてください。
      DB: D1Database;
    }
    

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

        if (pathname === "/api/beverages") {
          // `DB`をバインディング名として使用しなかった場合は、ここで変更してください
          const { results } = await env.DB.prepare(
            "SELECT * FROM Customers WHERE CompanyName = ?",
          )
            .bind("Bs Beverages")
            .all();
          return Response.json(results);
        }
    

        return new Response(
          "Bs Beveragesで働いている全員を見るには/api/beveragesを呼び出してください",
        );
      },
    } satisfies ExportedHandler<Env>;

    上記のコードでは、以下のことを行います：

    1. TypeScriptコード内でD1データベースへのバインディングを定義します。このバインディングは、wrangler.tomlの[[d1_databases]]で設定したbinding値と一致します。
    2. プレースホルダー（クエリ内の?）を使用して、env.DB.prepareを使用してデータベースをクエリします。
    3. bind()を呼び出して、そのプレースホルダーに安全かつセキュアに値をバインドします。実際のアプリケーションでは、ユーザーが結果をリストするためのCompanyNameを定義できるようにします。bind()を使用することで、ユーザーがアプリケーションに対して任意のSQLを実行すること（いわゆる「SQLインジェクション」）を防ぎ、データベースを削除または変更することを防ぎます。
    4. all()を呼び出して、すべての行（またはクエリが返さない場合はなし）を返します。
    5. クエリ結果があれば、Response.json(results)を使用してJSON形式で返します。

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

5. Wranglerを使用してローカルで開発する

プロジェクトディレクトリ内で、データベースをローカルでテストします。

  1. wrangler devを実行します：

    Terminal window
    npx wrangler dev

    wrangler devを実行すると、WranglerはWorkerを確認するためのURL（おそらくlocalhost:8787）を提供します。

  2. URLに移動します。

    ページには「Bs Beveragesで働いている全員を見るには/api/beveragesを呼び出してください」と表示されます。

  3. データベースが正常に動作しているかテストします。提供されたWrangler URLに/api/beveragesを追加します。例えば、localhost:8787/api/beveragesです。

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

6. データベースをデプロイする

Workerを本番環境にデプロイするには、最初にデータベースのブートストラップ手順を繰り返す必要がありますが、--localフラグを--remoteフラグに置き換えて、Workerに読み取るデータを提供します。これにより、データベーステーブルが作成され、Cloudflareのグローバルネットワーク上で実行される本番版のデータベースにデータがインポートされます。

  1. ステップ4で作成したschema.sqlファイルを使用してデータベースをブートストラップします：

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

  2. データが本番環境に存在することを確認するために、次のコマンドを実行します：

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

  3. Workerをデプロイして、プロジェクトをインターネット上でアクセス可能にします。次のコマンドを実行します：

    Terminal window
    npx wrangler deploy
    Outputs: https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev

これで、新しく作成したプロジェクトのURLにアクセスして、ライブデータベースをクエリできます。

例えば、新しいWorkerのURLがd1-tutorial.<YOUR_SUBDOMAIN>.workers.devの場合、https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beveragesにアクセスすると、ライブデータベースを直接クエリするWorkerにリクエストが送信されます。

7. （オプション）データベースを削除する

データベースを削除するには、次のコマンドを実行します：

Terminal window
npx wrangler d1 delete prod-d1-tutorial

Workerを削除したい場合は、次のコマンドを実行します：

Terminal window
npx wrangler delete d1-tutorial

まとめ

このチュートリアルでは、以下のことを行いました：

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

次のステップ

機能リクエストがある場合やバグを見つけた場合は、Cloudflare DevelopersコミュニティのDiscord ↗に参加して、Cloudflareチームに直接フィードバックを共有してください。

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings