EmDash + Cloudflare:ローカル開発でのSQLite3とAPI
EmDashがローカル開発環境でSQLite3とAPIをどう処理するか。Miniflare、D1、REST APIエンドポイントの完全解説。
wrangler devを起動した瞬間、Cloudflareのエッジで動くD1データベースがローカルに出現する。しかし、その裏側で何が起きているのか?この記事では、EmDashがローカル開発環境でSQLite3とAPIをどう処理するかを深掘りする。
1. ローカル開発の全体像#
2. Miniflare:ローカルのD1シミュレーター#
wrangler devを実行すると、Miniflare(Cloudflareのローカルシミュレーター)が起動する。
Miniflareの仕組み#
SQLiteファイルの構造#
.wrangler/
state/
v3/
d1/
miniflare-D1DatabaseObject/
<hash>.sqlite # データベースファイル
<hash>.sqlite-shm # 共有メモリ(WAL用)
<hash>.sqlite-wal # Write-Ahead Logtext| ファイル | 役割 |
|---|---|
<hash>.sqlite | 実際のSQLiteデータベース |
<hash>.sqlite-shm | WALモード用共有メモリ |
<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などでも接続可能bash3. 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-sqlite3 | Cloudflare D1 |
| ストレージ | data.dbファイル | Cloudflareインフラ |
| トランザクション | 標準SQLite | batch() API |
| 同時アクセス | 単一ライター | Cloudflare管理 |
| スキーマ | 共通 | 共通 |
[!TIP] 両方のアダプターはKysely(SQLクエリビルダー)を共有している。スキーマとマイグレーションはローカルと本番で同じ。
4. ローカルのデータフロー#
5. EmDash REST APIエンドポイント#
EmDashはAstro Dev Serverと同じポートでAPIを提供する。
ローカル開発URL#
http://localhost:4321/_emdash/api/ # REST API
http://localhost:4321/_emdash/admin/ # 管理画面text主要APIエンドポイント#
| カテゴリ | エンドポイント |
|---|---|
| コンテンツCRUD | GET/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 ヘッダーが必要bashOpenAPI仕様#
# API仕様を取得
curl http://localhost:4321/_emdash/api/openapi.jsonbash6. シードデータの適用#
初回起動時、データベースが空の場合にseed/seed.jsonからシードデータが適用される。
手動適用#
# ローカルDBにシードを適用
npx emdash seed seed/seed.json --local
# スキーマをエクスポート
npx emdash export-seed > .emdash/seed.jsonbash適用フロー#
7. ローカル vs リモート:完全比較#
| 項目 | ローカル(SQLite) | リモート(D1) |
|---|---|---|
| エンジン | better-sqlite3 | Cloudflare D1 |
| DBアダプター | sqlite({ url: "file:./data.db" }) | d1({ binding: "DB" }) |
| ストレージアダプター | local({ directory: "./uploads" }) | r2({ binding: "MEDIA" }) |
| 永続化 | .wrangler/state/ またはdata.db | Cloudflareインフラ |
| 同時書き込み | 単一ライター(SQLite制限) | Cloudflare管理(ただし単一ライター) |
| トランザクション | 標準SQLite | batch() 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 devbash共有チームデータベース#
# 共有ディレクトリに永続化
wrangler dev --persist-to=./shared-dbbashローカル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;"bash9. まとめ#
| コンポーネント | ローカル開発時の動作 |
|---|---|
| Miniflare | SQLite3ファイルを.wrangler/state/に作成 |
| better-sqlite3 | ローカルSQLiteとのブリッジ |
| Kysely | SQLクエリビルダー(ローカル/本番共通) |
| EmDash API | /_emdash/api/でREST API提供 |
| seed.json | 初回起動時にスキーマをブートストラップ |
EmDash + Cloudflareのローカル開発環境は、本番と同じD1のSQLセマンティクスをSQLite3で再現する。Miniflareがその橋渡しを担い、開発者はローカルで本番と同じ動作を確認できる。