コンテンツにスキップ

ローカル開発

D1は、Cloudflareがグローバルに実行しているのと同じバージョンのD1を使用して、ローカル開発のための完全なサポートを提供します。ローカル開発では、Wranglerを使用して、ローカル開発セッションと状態を管理します。

ローカル開発セッションの開始

ローカル開発セッションは、D1が実行されている本番環境を反映したスタンドアロンのローカル専用環境を作成し、デプロイする前にWorkerとD1をテストできるようにします。

ローカルで実行しているとき、既存のD1バインディングであるDBがWorkerに利用可能です。

ローカル開発セッションを開始するには：

  1. wrangler v3.0+を使用していることを確認します。

    Terminal window
    wrangler --version
    ⛅️ wrangler 3.0.0

  2. ローカル開発セッションを開始します。

    Terminal window
    wrangler dev
    ------------------
    wrangler devはデフォルトでローカルモードを使用し、🔥 Miniflareと👷 workerdによって動作します。
    Workerのエッジプレビューセッションを実行するには、wrangler dev --remoteを使用します。
    あなたのWorkerは以下のバインディングにアクセスできます：
    - D1データベース：
      - DB: test-db (c020574a-5623-407b-be0c-cd192bab9545)
    ⎔ ローカルサーバーを起動中...
    

    [mf:inf] http://127.0.0.1:8787/で準備完了
    [b] ブラウザを開く, [d] Devtoolsを開く, [l] ローカルモードをオフにする, [c] コンソールをクリア, [x] 終了

この例では、Workerはローカル専用のD1データベースにアクセスできます。wrangler.toml設定ファイル内の対応するD1バインディングは以下のようになります：

wrangler.toml
[[d1_databases]]
binding = "DB"
database_name = "test-db"
database_id = "c020574a-5623-407b-be0c-cd192bab9545"

wrangler devはローカルデータと本番（リモート）データを分離します。ローカルセッションはデフォルトで本番データにアクセスできません。本番（リモート）データベースにアクセスするには、wrangler devを呼び出す際に--remoteフラグを渡します。--remoteモードで実行中に行った変更は元に戻せません。

ローカル開発セッションの設定方法については、wrangler devドキュメントを参照してください。

Pagesでのローカル開発

Cloudflare Pagesを使用する際、最小限のwrangler.tomlをPagesプロジェクトのルートに作成することで、ローカル D1データベースに対してのみ開発できます。これは、スキーマの作成、データのシード、またはアプリケーションロジックを追加せずにD1データベースを直接管理する際に便利です。

あなたのwrangler.tomlは以下のようになります：

# Pages + D1のみを使用する場合、D1とローカルで対話するために以下のみが必要です。
[[d1_databases]]
binding = "DB" # プレビューデータベースIDと一致する必要があります
database_name = "YOUR_DATABASE_NAME"
database_id = "the-id-of-your-D1-database-goes-here" # wrangler d1 info YOUR_DATABASE_NAME
preview_database_id = "DB" # Pagesのローカル開発に必要

次に、--localフラグをwranglerに渡すことで、ローカルデータベースに対してクエリを実行したり、マイグレーションを実行したりできます：

Terminal window
wrangler d1 execute YOUR_DATABASE_NAME \
  --local --command "CREATE TABLE IF NOT EXISTS users ( user_id INTEGER PRIMARY KEY, email_address TEXT, created_at INTEGER, deleted INTEGER, settings TEXT);"

前述のコマンドは、ローカル専用のD1データベースに対してクエリを実行します。--localフラグがない場合、コマンドはCloudflareのネットワーク上で実行されているリモート版のD1データベースに対して実行されます。

データの永続化

wrangler dev --persist-to=/path/to/fileを使用して、特定の場所にデータを永続化します。これは、チームで作業する際に同じコピーを共有したり、CI/CDを介してデプロイする際に同じ開始状態を確保したり、マシン間で移行する際にデータを保持する方法として便利です。

wrangler 2.xのユーザーは、--persistフラグを使用する必要があります：以前のバージョンのwranglerはデフォルトでデータを永続化しませんでした。

プログラム的にテスト

Miniflare

Miniflare ↗を使用すると、WorkersやD1のリソースを本番で使用されるのと同じ基盤のランタイムとコードを使用してシミュレートできます。

MiniflareのD1サポート ↗を使用して、テスト用のD1データベースを作成できます：

[[d1_databases]]
binding = "DB"
database_name = "test-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
const mf = new Miniflare({
  d1Databases: {
    DB: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  },
});

次に、getD1Database()メソッドを使用してシミュレートされたデータベースを取得し、実際の本番D1データベースのようにクエリを実行できます：

const db = await mf.getD1Database("DB");


const stmt = db.prepare("SELECT name, age FROM users LIMIT 3");
const { results } = await stmt.all();


console.log(results);

unstable_dev

Wranglerは、WorkersとD1をテストするためのローカルHTTPサーバーを実行できるunstable_dev()を公開しています。wrangler.toml設定でpreview_database_idを設定することで、ローカルデータベースに対してマイグレーションを実行できます。

以下のwrangler.toml設定を考慮してください：

[[ d1_databases ]]
binding = "DB" # 例えば、これを"DB"に設定すると、Worker内で`env.DB`として利用可能になります
database_name = "your-database" # 作成時に設定したD1データベースの名前
database_id = "<UUID>" # データベースを作成したときに返されるD1データベースの一意のID
preview_database_id = "local-test-db" # ローカルテストデータベースのユーザー定義ID

マイグレーションは、wranglerに--localフラグを渡すことで、CI/CDセットアップの一部としてローカルで実行できます：

Terminal window
wrangler d1 migrations apply your-database --local

使用例

以下の例は、Wranglerのunstable_dev() APIを使用して、次のことを示しています：

  • preview_database_idで定義されたローカルテストデータベースに対してマイグレーションを実行します。
  • Workerで定義されたエンドポイントにリクエストを送信します。この例では/api/users/?limit=2を使用します。
  • 返された結果が一致することを検証します。これにはResponse.statusとAPIが返すJSONが含まれます。
import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";


describe("D1 Workerエンドポイントのテスト", () => {
  let worker: UnstableDevWorker;


  beforeAll(async () => {
    // オプション：`--local`データベースをセットアップするためにマイグレーションを実行します
    // デフォルトでは、これはpreview_database_idにデフォルト設定されます
    execSync(`NO_D1_WARNING=true wrangler d1 migrations apply db --local`);


    worker = await unstable_dev("src/index.ts", {
      experimental: { disableExperimentalWarning: true },
    });
  });


  afterAll(async () => {
    await worker.stop();
  });


  it("ユーザーの配列を返すべきです", async () => {
    // 期待される結果
    const expectedResults = `{"results": [{"user_id": 1234, "email": "foo@example.com"},{"user_id": 6789, "email": "bar@example.com"}]}`;
    // Worker内のルーティングをトリガーするためにオプションのURLを渡します
    const resp = await worker.fetch("/api/users/?limit=2");
    if (resp) {
      // https://jestjs.io/docs/expect#tobevalue
      expect(resp.status).toBe(200);
      const data = await resp.json();
      // https://jestjs.io/docs/expect#tomatchobjectobject
      expect(data).toMatchObject(expectedResults);
    }
  });
});

APIをテスト内で使用する方法の詳細については、unstable_dev()ドキュメントを参照してください。

関連リソース

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings