blog.dopana

戻る

wrangler devを起動した瞬間、Cloudflareのエッジで動くD1データベースがローカルに出現する。しかし、その裏側で何が起きているのか?この記事では、EmDashがローカル開発環境でSQLite3とAPIをどう処理するかを深掘りする。

1. ローカル開発の全体像#

ローカル開発環境ローカル本番ローカル本番ブラウザhttp://localhost:4321Astro Dev ServerNode.jsEmDash RuntimeDB Adapterbetter-sqlite3data.dbCloudflare D1env.DBStorage Adapterlocal filesystem./uploadsCloudflare R2env.MEDIA

2. Miniflare:ローカルのD1シミュレーター#

wrangler devを実行すると、Miniflare(Cloudflareのローカルシミュレーター)が起動する。

Miniflareの仕組み#

wrangler devMiniflare初期化.sqliteファイル作成データ読み書きWorker Runtime提供localhost:4321 起動開発者wrangler devMiniflareSQLite3ファイル開発者wrangler devMiniflareSQLite3ファイル

SQLiteファイルの構造#

.wrangler/
  state/
    v3/
      d1/
        miniflare-D1DatabaseObject/
          <hash>.sqlite          # データベースファイル
          <hash>.sqlite-shm      # 共有メモリ(WAL用)
          <hash>.sqlite-wal      # Write-Ahead Log
text
ファイル役割
<hash>.sqlite実際のSQLiteデータベース
<hash>.sqlite-shmWALモード用共有メモリ
<hash>.sqlite-wal書き込み先読みログ(同時アクセス制御)

[!NOTE] <hash>はdatabase_idからHMACで生成された16進ハッシュ。同じBinding IDは常に同じハッシュにマッピングされる。

WALモードの利点#

デフォルトでWAL(Write-Ahead Logging)モードが使われる:

  • 読み書きを同時に行える
  • 書き込みが読み込みをブロックしない
  • 本番のD1と同じ動作モード

ローカルDBに直接アクセス#

外部ツールで直接SQLiteファイルを開ける:

# SQLite CLIで接続
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite

# Beekeeper Studio、SQLiteFlowなどでも接続可能
bash

3. EmDashの2つのDBアダプター#

EmDashはastro.config.mjsでDBアダプターを選択する。ローカルと本番で異なるアダプターが使われる。

ローカル開発:sqlite()アダプター#

astro.config.mjs(ローカル開発向け)
import emdash from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
  integrations: [
    emdash({
      database: sqlite({
        url: "file:./data.db",  // ローカルSQLiteファイル
      }),
    }),
  ],
});
js

本番環境:d1()アダプター#

astro.config.mjs(本番向け)
import emdash from "emdash/astro";
import { d1 } from "emdash/db";

export default defineConfig({
  integrations: [
    emdash({
      database: d1(),  // Cloudflare D1バインディング
    }),
  ],
});
js

比較表#

項目ローカル(sqlite())本番(d1())
エンジンbetter-sqlite3Cloudflare D1
ストレージdata.dbファイルCloudflareインフラ
トランザクション標準SQLitebatch() API
同時アクセス単一ライターCloudflare管理
スキーマ共通共通

[!TIP] 両方のアダプターはKysely(SQLクエリビルダー)を共有している。スキーマとマイグレーションはローカルと本番で同じ。

4. ローカルのデータフロー#

GET /postsgetEmDashCollection("posts")SELECT * FROM postsSQLクエリ実行レスポンスデータコンテンツHTML応答ブラウザAstro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 DatabaseブラウザAstro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 Database

5. EmDash REST APIエンドポイント#

EmDashはAstro Dev Serverと同じポートでAPIを提供する。

ローカル開発URL#

http://localhost:4321/_emdash/api/    # REST API
http://localhost:4321/_emdash/admin/  # 管理画面
text

主要APIエンドポイント#

カテゴリエンドポイント
コンテンツCRUDGET/POST /content/{collection}, GET/PUT/DELETE /content/{collection}/{id}
公開管理POST /content/{collection}/{id}/publish, /unpublish, /schedule
メディアGET/POST /media, POST /media/upload-url
スキーマGET/POST /schema/collections
タクソノミーGET/POST /taxonomies, GET/POST /taxonomies/{name}/terms
メニューGET/POST /menus, GET/PUT/DELETE /menus/{name}
設定GET/PUT /settings
検索GET /search, GET /search/suggest, POST /search/rebuild

認証#

# Bearerトークン認証
curl -H "Authorization: Bearer $EMDASH_TOKEN" \
  http://localhost:4321/_emdash/api/content/posts

# セッション認証(管理画面から)
# CSRF保護:X-EmDash-Request: 1 ヘッダーが必要
bash

OpenAPI仕様#

# API仕様を取得
curl http://localhost:4321/_emdash/api/openapi.json
bash

6. シードデータの適用#

初回起動時、データベースが空の場合にseed/seed.jsonからシードデータが適用される。

手動適用#

# ローカルDBにシードを適用
npx emdash seed seed/seed.json --local

# スキーマをエクスポート
npx emdash export-seed > .emdash/seed.json
bash

適用フロー#

はいいいえwrangler dev 起動初回リクエストDB空?seed.json適用通常処理マイグレーション実行コレクション作成タクソノミー作成メニュー作成設定適用

7. ローカル vs リモート:完全比較#

項目ローカル(SQLite)リモート(D1)
エンジンbetter-sqlite3Cloudflare D1
DBアダプターsqlite({ url: "file:./data.db" })d1({ binding: "DB" })
ストレージアダプターlocal({ directory: "./uploads" })r2({ binding: "MEDIA" })
永続化.wrangler/state/ またはdata.dbCloudflareインフラ
同時書き込み単一ライター(SQLite制限)Cloudflare管理(ただし単一ライター)
トランザクション標準SQLitebatch() API
読み取りレプリカ対象外D1 Sessions API
バックアップ.sqliteファイルをコピーwrangler d1 export

8. 開発時のTips#

データをリセットしたい場合#

# SQLiteファイルを削除してリセット
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite-*

# 再起動で自動再作成
wrangler dev
bash

共有チームデータベース#

# 共有ディレクトリに永続化
wrangler dev --persist-to=./shared-db
bash

ローカルDBの内容を確認#

# テーブル一覧
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite ".tables"

# データ確認
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite \
  "SELECT * FROM posts LIMIT 5;"
bash

9. まとめ#

コンポーネントローカル開発時の動作
MiniflareSQLite3ファイルを.wrangler/state/に作成
better-sqlite3ローカルSQLiteとのブリッジ
KyselySQLクエリビルダー(ローカル/本番共通)
EmDash API/_emdash/api/でREST API提供
seed.json初回起動時にスキーマをブートストラップ

EmDash + Cloudflareのローカル開発環境は、本番と同じD1のSQLセマンティクスをSQLite3で再現する。Miniflareがその橋渡しを担い、開発者はローカルで本番と同じ動作を確認できる。

参考文献#