Cloudflare D1のローカル開発でdrizzle-kit studioを使う

Posted at 2025-12-24

Cloudflare D1のローカル開発でdrizzle-kit studioを使う

はじめに

Cloudflare D1で開発していると、ローカルのデータベースをGUIで確認したくなる。drizzle-kit studio を使えばブラウザ上でテーブルの中身を確認・編集できるが、D1のローカル開発には少し設定が必要。

本記事では、D1ローカル開発環境で drizzle-kit studio を動かす方法をまとめる。

環境

Cloudflare D1 + wrangler
drizzle-orm / drizzle-kit
pnpm（npm/yarn でも可）

D1のローカル開発の仕組み

wranglerで --local オプションを使うと、D1はローカルのSQLiteファイルとして動作する。

wrangler dev --local --persist-to .wrangler/state

このSQLiteファイルは以下に保存される：

.wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite

drizzle-kit studio でこのファイルを直接読めば、ローカルD1の中身を確認できる。

なぜ better-sqlite3 なのか

ドライバーの選択肢

drizzle-kitでSQLiteを扱うドライバーは主に2つ：

ドライバー	用途	ローカルファイル対応
`d1-http`	D1リモート（本番）	不可（API経由）
`better-sqlite`	ローカルSQLite	OK
`libsql`	Turso / リモート	ローカルは問題あり

libsql の問題

@libsql/client がインストールされていると、drizzle-kitはlibsqlを優先して使おうとする。しかしlibsqlはローカルファイルパス（file:）の扱いにバグがあり、失敗することがある。

結論

D1ローカル開発では better-sqlite3 を使うのが事実上の標準。

Drizzleチームは「ローカルD1との連携は今後改善予定」としているが、2025年12月時点で公式のファーストパーティソリューションは未提供。コミュニティがこの方法を確立している。

セットアップ

1. better-sqlite3 をインストール

pnpm add -D better-sqlite3

2. ローカル用の設定ファイルを作成

// drizzle.config.local.ts
import type { Config } from 'drizzle-kit';

export default {
  schema: './src/schema/index.ts',
  out: './migrations',
  dialect: 'sqlite',
  dbCredentials: {
    // wranglerが作成するローカルD1のパス
    url: '.wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite',
  },
} satisfies Config;

<hash> の確認方法：

ls .wrangler/state/v3/d1/miniflare-D1DatabaseObject/

3. package.json にスクリプト追加

{
  "scripts": {
    "studio": "drizzle-kit studio",
    "studio:local": "drizzle-kit studio --config=drizzle.config.local.ts"
  }
}

4. 実行

pnpm studio:local

ブラウザで https://local.drizzle.studio が開き、ローカルD1の中身を確認できる。

pnpm 10 での注意点

pnpm 10を使っている場合、better-sqlite3 のネイティブバインディングエラーが発生することがある。

Error: Could not locate the bindings file. Tried:
 → .../better-sqlite3/build/better_sqlite3.node
 ...

原因

pnpm 10から、セキュリティ強化のためネイティブモジュールのビルドがデフォルトでスキップされるようになった。better-sqlite3 はC++のネイティブバインディングをコンパイルする必要があるが、これが実行されない。

解決方法

ルートの package.json に以下を追加：

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "better-sqlite3"
    ]
  }
}

その後、node_modulesを削除して再インストール：

rm -rf node_modules
pnpm install

重要: pnpm install だけでは既存のキャッシュが使われるため再ビルドされない。

リモートD1への接続

本番のCloudflare D1に接続したい場合は d1-http ドライバーを使用：

// drizzle.config.ts
import type { Config } from 'drizzle-kit';

export default {
  schema: './src/schema/index.ts',
  out: './migrations',
  dialect: 'sqlite',
  driver: 'd1-http',
  dbCredentials: {
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID || '',
    databaseId: process.env.CLOUDFLARE_DB_ID || '',
    token: process.env.CLOUDFLARE_API_TOKEN || '',
  },
} satisfies Config;

まとめ

環境	ドライバー	設定ファイル
ローカル開発	`better-sqlite`	`drizzle.config.local.ts`
リモート（本番）	`d1-http`	`drizzle.config.ts`

D1のローカル開発で drizzle-kit studio を使うには：

better-sqlite3 をインストール
ローカル用の設定ファイルを作成（SQLiteファイルパスを指定）
studio:local スクリプトを追加
pnpm 10の場合は onlyBuiltDependencies を設定

本記事の内容は drizzle-kit 0.31.x / pnpm 10.25.0 で動作確認済みです（2025-12時点）。

参考

noteでは「AI × 技術 × ビジネス」視点で書いています

Qiitaでは純粋な技術Tipsを、noteでは「その技術をどう活かすか」というPM/事業視点の記事を書いています。

Qiita: ハマりポイント、解決策、設定方法
note: AI駆動開発の実践、技術選定の判断軸、放置プロジェクトの救い方

👉 note.com/ebiyy

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up