drizzle-orm-d1

Cloudflare D1 向け Drizzle ORM

ステータス：本番環境で利用可能 ✅ 最終更新日：2025-12-14 最新バージョン：[email protected]、[email protected] 依存関係：cloudflare-d1、cloudflare-worker-base

---

クイックスタート（10 分）

1. Drizzle をインストールする

bun add drizzle-orm drizzle-kit

2. Drizzle Kit を設定する

drizzle.config.ts を作成します：

import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/db/schema.ts',
  out: './migrations',
  dialect: 'sqlite',          // MANDATORY since drizzle-kit 0.21 (D1 = sqlite)
  driver: 'd1-http',          // D1 HTTP driver for remote migrations/Studio
  dbCredentials: {            // MANDATORY: drizzle-kit 0.30+ tightened zod validation
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
    token: process.env.CLOUDFLARE_D1_TOKEN!,
  },
});

drizzle-kit 0.30/0.31 に関する注意：dialect と dbCredentials の検証が厳格になりました。dialect が省略されている設定や、古い connectionString／uri キーを使用する設定は、検証に失敗します。D1 では、accountId／databaseId／token（または wrangler ベースの認証情報）とともに、dialect: 'sqlite' + driver: 'd1-http' を使用してください。drizzle-orm/<driver>/migrator の実行時 migrate() シグネチャは、0.36 から 0.45 まで変更されていません（変更されるのは 1.0-beta のみで、^0.45 の対象外です）。

3. スキーマを定義する

src/db/schema.ts を作成します：

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
import { relations } from 'drizzle-orm';

export const users = sqliteTable('users', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(() => new Date()),
});

export const posts = sqliteTable('posts', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  title: text('title').notNull(),
  content: text('content').notNull(),
  authorId: integer('author_id')
    .notNull()
    .references(() => users.id, { onDelete: 'cascade' }),
});

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

4. マイグレーションを生成して適用する

bunx drizzle-kit generate                           # Generate SQL
bunx wrangler d1 migrations apply my-database --local   # Apply local
bunx wrangler d1 migrations apply my-database --remote  # Apply prod

5. Worker でクエリを実行する

import { drizzle } from 'drizzle-orm/d1';
import { users } from './db/schema';
import { eq } from 'drizzle-orm';

export default {
  async fetch(request: Request, env: { DB: D1Database }): Promise<Response> {
    const db = drizzle(env.DB);
    const allUsers = await db.select().from(users).all();
    return Response.json(allUsers);
  },
};

---

重要なルール

必ず行うこと

ルール	理由
マイグレーションには drizzle-kit generate を使用する	SQL を手動で記述しないでください
まずローカルでマイグレーションをテストする	--remote の前に --local を実行します
単一の結果には .get() を使用する	最初の行、または undefined を返します
トランザクションには db.batch() を使用する	D1 は SQL の BEGIN／COMMIT をサポートしていません
日付には mode: 'timestamp' を指定した integer を使用する	D1 にはネイティブの日付型がありません
動的なデフォルト値には .$defaultFn() を使用する	関数には .default() を使用しないでください

絶対に行わないこと

ルール	理由
SQL の BEGIN TRANSACTION を使用する	D1 では batch API が必要です（エラー #1）
drizzle-kit migrate と wrangler apply を併用する	Wrangler のみを使用してください
本番環境で drizzle-kit push を使用する	generate + apply を使用してください
認証情報を drizzle.config.ts にコミットする	環境変数を使用してください
関数呼び出しに .default() を使用する	代わりに .$defaultFn() を使用してください

---

重大なエラーのトップ 5

#	エラー	解決策
1	D1_ERROR: Cannot use BEGIN TRANSACTION	db.transaction() の代わりに db.batch([...]) を使用します
2	FOREIGN KEY constraint failed	.references(() => users.id, { onDelete: 'cascade' }) でカスケードを定義します
3	env.DB is undefined	wrangler.jsonc のバインディングが env.DB と一致することを確認します
4	No such module "wrangler"	import { drizzle } from 'drizzle-orm/d1' を使用します
5	Type instantiation excessively deep	明示的な型には InferSelectModel<typeof users> を使用します

参照：すべての 12 件のエラーと完全な解決策については、references/error-catalog.md を参照してください。

---

よく使われるパターンの概要

パターン	用途	テンプレート
CRUD 操作	基本的なデータベース操作	templates/basic-queries.ts
リレーションと結合	ネストされたクエリ、手動での結合	templates/relations-queries.ts
バッチ操作	トランザクション（D1 batch API）	templates/transactions.ts
スキーマ設計	命名、インデックス、論理削除	references/schema-patterns.md

---

設定の概要

ファイル	目的	テンプレート
drizzle.config.ts	Drizzle Kit の設定	templates/drizzle.config.ts
wrangler.jsonc	D1 バインディングの設定	references/wrangler-setup.md
package.json	マイグレーション用 npm スクリプト	templates/package.json

npm スクリプト：

{
  "db:generate": "drizzle-kit generate",
  "db:migrate:local": "wrangler d1 migrations apply my-database --local",
  "db:migrate:remote": "wrangler d1 migrations apply my-database --remote"
}

---

マイグレーションのワークフロー

手順	コマンド	備考
1. スキーマを編集	src/db/schema.ts を編集	変更を加えます
2. 生成	npm run db:generate	SQL マイグレーションを作成します
3. ローカルでテスト	npm run db:migrate:local	ローカルで確認します
4. コードをデプロイ	npm run deploy	Cloudflare にプッシュします
5. 本番環境に適用	npm run db:migrate:remote	マイグレーションを適用します

参照：ワークフロー全体については、references/migration-workflow.md を参照してください。

---

TypeScript の型推論

import { InferSelectModel, InferInsertModel } from 'drizzle-orm';
import { users } from './db/schema';

export type User = InferSelectModel<typeof users>;
export type NewUser = InferInsertModel<typeof users>;

---

リファレンスを読み込むタイミング

リファレンス	読み込むタイミング
references/error-catalog.md	D1 のエラー、トランザクションの失敗、バインディングの問題をデバッグするとき
references/schema-patterns.md	スキーマ、命名規則、インデックス、論理削除を設計するとき
references/migration-workflow.md	マイグレーションを設定またはトラブルシューティングするとき
references/query-builder-api.md	複雑なクエリ、演算子、JOIN 構文を扱うとき
references/wrangler-setup.md	D1 用に wrangler.jsonc を設定するとき
references/common-errors.md	エラーをすばやく検索するとき

---

同梱リソース

テンプレート: basic-schema.ts、basic-queries.ts、transactions.ts、relations-queries.ts、prepared-statements.ts、drizzle.config.ts、package.json

リファレンス: error-catalog.md、schema-patterns.md、migration-workflow.md、query-builder-api.md、wrangler-setup.md、common-errors.md、links-to-official-docs.md

---

依存関係

{
  "dependencies": {
    "drizzle-orm": "^0.45.2"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.10"
  }
}

---

安全なインストール

Drizzle ORM と D1 ドライバーパッケージをインストールする際は、サプライチェーンセキュリティのベストプラクティスに従ってください。

• インストール後スクリプトをブロックする — npm config set ignore-scripts true（または Bun：デフォルトで無効）
• クールダウン期間を設ける — 新しいパッケージバージョンがコミュニティによって審査されるまで、7 日間待ちます
• インストール前に監査する — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使用してパッケージを確認します

Socket CLI との連携、クールダウンの設定、ロックファイルの検証、CI での適用を含む、セキュリティ設定の詳細については、dependency-upgrade スキルを読み込んでください。

公式ドキュメント

• Drizzle ORM: https://orm.drizzle.team/
• Drizzle と D1: https://orm.drizzle.team/docs/connect-cloudflare-d1
• Drizzle Kit: https://orm.drizzle.team/docs/kit-overview
• GitHub: https://github.com/drizzle-team/drizzle-orm

---

トークン削減率: 約 65%（包括的なパターンをリファレンスに収録） エラー防止率: 100%（文書化された 12 件すべての問題に対応） 本番環境で使用できます！ ✅