メインコンテンツまでスキップ

Cloudflare D1 を使ってみよう！ (初心者向け)

はじめに

  • このレジュメについて
  • 前提条件 (Node.js, pnpm インストール済み)
  • 学習のゴール

1. Hono を使ったシンプルな Web サーバーをローカルで起動しよう (Cloudflare Workers テンプレート)​

1.1. プロジェクトの作成と Hono アプリケーションの初期化​

  • 新しいディレクトリを作成し、Hono アプリケーションを初期化します。 
    mkdir hono-d1-tutorial
    cd hono-d1-tutorial
    pnpm create hono@latest
  • コマンドを実行すると、Hono のスターターテンプレートを選択するプロンプトが表示されます。cloudflare-workers を選択してください。

1.2. 依存関係のインストール​

  • テンプレートの選択後、必要な依存関係（wrangler を含む）がインストールされます。完了するまでお待ちください。

1.3. ローカルサーバーの起動 (Wrangler Dev)​

  • プロジェクトのディレクトリで、開発サーバーを起動します。cloudflare-workers テンプレートの package.json に設定されている dev スクリプト (wrangler dev) を実行します。 
    pnpm dev
  • Wrangler CLI が起動し、ローカル開発サーバーが立ち上がります。ターミナルにローカルサーバーの URL（通常は http://localhost:8787）が表示されます。

1.4. ブラウザでのアクセス確認​

  • ブラウザで表示された URL にアクセスし、「Hello Hono!」などのメッセージが表示されることを確認します。cloudflare-workers テンプレートの内容によって表示されるメッセージは異なる場合があります。

2. Cloudflare にデプロイしよう！ - Wrangler CLI の利用​

2.1. Cloudflare アカウントの作成​

  • まだお持ちでない場合は、Cloudflare のウェブサイト にアクセスし、アカウントを作成してください (無料プランでOKです)。

2.2. Cloudflare へのログイン​

  • Cloudflare にログインします。ブラウザが開き、認証を求められます。 
    wrangler login

2.3. Cloudflare Workers プロジェクトの設定 (wrangler.jsonc)​

  • hono-d1-tutorial ディレクトリに wrangler.jsonc ファイルが pnpm create hono@latest によって自動的に生成されているはずです。内容を確認し、必要に応じて修正します。基本的な内容は以下のようになっていることが多いです。 
    {
      "name": "hono-d1-worker", // Workers の名前（自動生成される場合があります）
      "main": "./src/index.js", // エントリーポイントのファイル（テンプレートによって異なる場合があります）
      "compatibility_date": "2024-04-09", // 互換性のある日付
      "compatibility_flags": []
    }
    • main のパスは、cloudflare-workers テンプレートで生成されるエントリポイントのファイル名に合わせてください（通常は src/index.js）。
    • nodejs_compat は、必要に応じて "compatibility_flags" 配列に追加できます。
    • .jsonc は JSON with Comments の拡張子で、JSON ファイルにコメントを記述できます。Wrangler はこの形式をサポートしています。

2.4. Hono のコード (src/index.js など)​

  • cloudflare-workers テンプレートで生成された Hono のコード (src/index.js など) を確認します。基本的なルーティングなどが設定されているはずです。

2.5. Cloudflare Workers へのデプロイ​

  • Workers をデプロイします。 
    wrangler deploy
  • デプロイが成功すると、Workers の URL が表示されます。ブラウザでアクセスし、動作を確認します。

3. Cloudflare D1 で簡単なデータベース連携をしてみよう​

3.1. Cloudflare D1 データベースの作成​

  • Cloudflare ダッシュボードにアクセスし、D1 セクションで新しいデータベースを作成します。データベース名を設定してください。

3.2. D1 データベースへのスキーマ定義​

  • Cloudflare ダッシュボードで作成した D1 データベースを選択し、「スキーマ」タブを開きます。

  • 「テーブルを追加」ボタンをクリックします。

  • テーブル名として Customers を入力し、「保存」をクリックします。

  • 作成された Customers テーブルを選択し、「列を追加」ボタンをクリックして、以下の列情報を順番に入力します。

    1. 列名: CustomerID

      • タイプ: INTEGER
      • 制約:
        • 「Primary Key」にチェックを入れます
        • 「Autoincrement」にチェックを入れる項目があれば入れます（もしあれば）

    2. 列名: Name

      • タイプ: TEXT
      • 制約:
        • 「Not Null」にチェックを入れます

    3. 列名: Email

      • タイプ: TEXT
      • 制約:
        • 「Unique」にチェックを入れます
        • 「Not Null」にチェックを入れます

  • 全ての列情報を入力したら、「保存」ボタンをクリックしてテーブルのスキーマを確定します。

3.3. Wrangler で D1 データベースを Workers にバインド (wrangler.jsonc)​

  • hono-d1-tutorial ディレクトリの wrangler.jsonc ファイルを編集し、D1 データベースを Workers にバインドします。

    {
      "name": "hono-d1-worker",
      "main": "./src/index.js",
      "compatibility_date": "2024-04-09",
      "compatibility_flags": [],
      "d1_databases": [
        {
          "binding": "DB", // Workers 内でアクセスする際の変数名
          "database_name": "<作成した D1 データベースの名前>",
          "database_id": "<作成した D1 データベースの ID>"
        }
      ]
    }
    • "binding" には、Workers のコード内で D1 データベースにアクセスするための変数名を指定します（例: DB）。
    • "database_name" には、Cloudflare ダッシュボードで作成した D1 データベースの名前を入力します。
    • "database_id" には、Cloudflare ダッシュボードの D1 セクションで確認できるデータベースの ID を入力します。

3.4. Workers のコードから D1 データベースにアクセス (src/index.js など)​

  • エントリーポイントのファイル (src/index.js など) を以下のように修正し、D1 データベースとの連携処理を追加します。 
    import { Hono } from 'hono'

    const app = new Hono()

    app.get('/', (c) => c.text('Hello from Cloudflare Workers with D1!'))

    app.get('/customers', async (c) => {
      const { results } = await c.env.DB.prepare("SELECT * FROM Customers").all();
      return c.json(results);
    })

    app.post('/customers', async (c) => {
      const body = await c.req.json();
      const { results } = await c.env.DB.prepare(
        "INSERT INTO Customers (Name, Email) VALUES (?, ?)"
      ).bind(body.name, body.email).run();
      return c.json({ message: 'Customer added successfully!', results });
    })

    export default app
    • ファイル名が異なる場合は、上記コードを適切なファイルに記述してください。

3.5. ローカルでの D1 連携のテスト (wrangler dev --local または --remote)​

  • ローカルで D1 データベースとの連携をテストします。

    • --local オプション (推奨 - 課金なし): ローカルの D1 エミュレーターを使用します。ただし、環境によっては正しく動作しない場合があります。

      pnpm exec wrangler dev --local

      ローカルサーバーが起動したら、http://localhost:8787/customers に GET リクエストを送信してデータを確認したり、http://localhost:8787/customers に JSON ボディ ({"name": "Taro", "email": "taro@example.com"}) を付けて POST リクエストを送信してデータの追加を試したりします。

    • --remote オプション (注意 - 課金が発生する可能性あり): Cloudflare の本番環境に近い形でテストを行います。ローカルにデータが存在しない場合や、より正確なテストが必要な場合に利用できます。

      pnpm exec wrangler dev --remote

      ローカルサーバーが起動したら、同様に API エンドポイントにリクエストを送信して動作を確認します。--remote オプションを使用すると、実際の Cloudflare アカウントのリソースにアクセスするため、D1 の利用状況に応じて課金が発生する可能性があることに注意してください。また、本番環境のデータが直接操作されるため、意図しない変更を加えないように十分注意してください。

3.6. Cloudflare への再デプロイと動作確認​

  • 変更を Cloudflare にデプロイします。 
    wrangler deploy
  • デプロイ後、発行された Workers の URL の /customers エンドポイントに GET リクエストを送信し、ブラウザでデータが取得できることを確認します。
  • POST リクエストをテストするには、以下のいずれかの方法を試してください。
    • ブラウザの開発者ツール (コンソール): ブラウザで Workers の URL を開いた状態で、開発者ツールを開き、「コンソール」タブに以下の JavaScript コードを入力して実行します（<YOUR_WORKER_URL> は実際の URL に置き換えてください）。 
      fetch('<YOUR_WORKER_URL>/customers', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ name: 'Shingo', email: 'shingo@example.com' })
      })
      .then(response => response.json())
      .then(data => console.log(data))
      .catch(error => console.error('Error:', error));
    • curl コマンド (ターミナル): ターミナルを開き、以下のコマンドを実行します（<YOUR_WORKER_URL> は実際の URL に置き換えてください）。 
      curl -X POST -H "Content-Type: application/json" -d '{"name": "Kenji", "email": "kenji@example.com"}' <YOUR_WORKER_URL>/customers
  • Cloudflare ダッシュボードの D1 セクションでデータが追加されていることも確認してください。