drizzle-sqlite

dot-skills Drizzle SQLite ベストプラクティス

SQLite 系バックエンドで Drizzle ORM を使うためのライブラリリファレンススキルです。8 つのカテゴリーにわたる 45 のルールを、実行ライフサイクルへの影響が大きい順に並べています：スキーマ → マイグレーション → クエリ → リレーション → トランザクション → パフォーマンス → 接続 → 型。

適用するタイミング

次のような場合に、このガイドラインを参照してください：

• sqliteTable スキーマを定義するとき — カラム型、主キー、インデックス、外部キーの選択
• drizzle-kit generate / migrate / push を実行するとき、またはマイグレーション SQL ファイルを手動で編集するとき
• db.select()、db.insert()、db.update()、db.delete() を使ってクエリを書くとき
• db.query.* とリレーショナルクエリビルダーを使ってネストされたデータを取得するとき
• 複数ステートメントの書き込みを db.transaction() または db.batch()（libsql/Turso/D1）でまとめるとき
• .prepare() と sql.placeholder()、またはカバリングインデックスを使ってホットパスのクエリを最適化するとき
• Drizzle クライアントを設定するとき（プラグマ、ドライバーの選択、シングルトンのライフサイクル）
• データベースの型をアプリケーションコードに組み込むとき（$inferSelect、drizzle-zod、JSON の形状）

このスキルは特定のドライバーに限定されません。better-sqlite3、libsql、bun:sqlite、expo-sqlite、op-sqlite、Cloudflare D1 に共通する動作を扱い、ドライバー固有の違いがある場合はその旨を示します。

アーキテクチャ上の背景

SQLite は、本番データベースとしては独特な特徴があります：

• クライアント／サーバー型ではありません。 「接続」とはファイルを開くことです。ローカルファイルの場合、接続プールも認証もネットワークもありません。
• ライターは 1 つです。 接続数にかかわらず、同時に書き込めるのは 1 つだけです。WAL を使えば、読み取りは並列に実行できます。
• ネイティブなブール値や日付はありません。 すべて INTEGER、REAL、TEXT、BLOB、または NULL です。残りの型は Drizzle のカラムモードで表現します。
• ALTER TABLE の機能は限定的です。 可能なのは RENAME COLUMN、ADD COLUMN、DROP COLUMN のみです。型の変更や制約の追加には、テーブルの再構築が必要です。
• 外部キーはデフォルトで無効です。 PRAGMA foreign_keys = ON は接続ごとの設定で、永続化されません。

このスキルに多くのルールがあるのは、Drizzle の API が PostgreSQL／MySQL／SQLite を統一的に抽象化している一方で、基盤となる SQLite エンジンには、Postgres と同じように扱うと実行時に問題となる制約があるためです。

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
1	スキーマ定義	重大	schema-
2	マイグレーションと Drizzle Kit	重大	migrate-
3	クエリ構築	高	query-
4	リレーション	高	rel-
5	トランザクションとバッチ処理	中〜高	tx-
6	プリペアドステートメントとホットパス	中〜高	perf-
7	接続とドライバーの設定	中	conn-
8	型推論	中	types-

クイックリファレンス

1. スキーマ定義（重大）

• schema-integer-for-booleans — 推論される型が 0 | 1 ではなく boolean になるよう、integer({ mode: 'boolean' }) を使用します
• schema-timestamp-mode-for-dates — 日付はテキストではなく、integer({ mode: 'timestamp_ms' }) として保存します
• schema-always-primary-key — 隠れた rowid に頼らず、明示的な PK（単一または複合）を宣言します
• schema-foreign-keys-with-actions — すべての .references() に onDelete／onUpdate を指定します
• schema-index-foreign-keys-and-lookups — 外部キーのカラムと、頻繁に使う WHERE をインデックス化します。SQLite は外部キーに自動でインデックスを作成しません
• schema-text-json-not-blob-json — json_extract と JSON パスインデックスが機能するよう、text({ mode: 'json' }) を使用します
• schema-unique-constraints-for-natural-keys — onConflict の対象を指定できるよう、メールアドレス／slug／externalId には .unique() を使用します

2. マイグレーションと Drizzle Kit（CRITICAL）

• migrate-generate-not-push-in-prod — generate + migrate を使用してください。push は調整できないカラムを削除します
• migrate-explicit-renames — リネームのプロンプトに回答してください。デフォルトではリネームが削除＋追加として扱われます
• migrate-config-dialect-and-out — フラグなしでコマンドを実行できるように drizzle.config.ts を定義してください
• migrate-apply-with-migrator — 生の SQL ではなく、drizzle-kit migrate またはドライバーの migrator モジュールで適用してください
• migrate-data-backfill-as-custom-sql — DDL とアトミックにバックフィルできるよう、マイグレーション SQL を手動で編集してください
• migrate-commit-migrations-to-git — drizzle/ の SQL と drizzle/meta/ のスナップショットを両方コミットしてください。どちらも必要です

3. クエリの構築（HIGH）

• query-select-columns-not-star — db.select({ ... }) を使って、必要なカラムだけを取得してください
• query-avoid-n-plus-one-with-inarray — ループ内のクエリを inArray() に置き換えてください
• query-always-limit-listings — 一覧取得のクエリにはすべて .limit()（できればカーソルも）が必要です
• query-bind-parameters-not-concat — eq() または SQL テンプレートを使用し、値を文字列連結しないでください
• query-upsert-with-onconflict — 選択してから書き込むのではなく、.onConflictDoUpdate() でアトミックにアップサートしてください
• query-returning-instead-of-reselect — 挿入・更新・削除で .returning() を使うと、追加のラウンドトリップを省けます
• query-toSQL-and-explain — 負荷の高いパスで、生成された SQL と EXPLAIN QUERY PLAN を確認してください

4. リレーション（HIGH）

• rel-declare-relations-for-rqb — relations() の宣言により、db.query.* と with が使えるようになります
• rel-prefer-with-over-manual-joins — ネストしたデータの取得には with を使用してください。手動の結合では型情報が失われ、コードが増えます
• rel-partial-columns-in-with — with 内の columns: { ... } でペイロードを絞り、情報漏えいを防いでください
• rel-filter-with-where-inside-with — 関連行のフィルターは JS ではなく with.where に指定してください
• rel-leftjoin-for-flat-aggregates — 集計が必要な場合は、leftJoin と groupBy を使用してください

5. トランザクションとバッチ処理（MEDIUM-HIGH）

• tx-wrap-multi-statement-writes — 関連する書き込みを db.transaction() で囲み、アトミック性とスループットを確保してください
• tx-batch-for-libsql-roundtrips — libsql/Turso/D1 では db.batch() を使うと、N 回のラウンドトリップを 1 回にまとめられます
• tx-no-network-io-inside-transaction — トランザクション内で HTTP／FS／Stripe の呼び出しを await しないでください
• tx-handle-busy-with-retry — SQLITE_BUSY には、リトライ回数を制限して再試行してください。一時的なエラーの場合に限ります
• tx-single-writer-no-parallel-writes — 書き込みに Promise.all を使うと競合するため、順番に実行してください

6. プリペアドステートメントとホットパス（中〜高）

• perf-prepare-hot-paths — リクエストごとに実行されるクエリには、.prepare() と sql.placeholder() を使用します
• perf-bulk-insert-multi-row-values — N 回のループによる挿入の代わりに、1 回の values([...rows]) を使用します
• perf-avoid-count-star-on-large-tables — count(*) の代わりに、カウンター行またはキーベースのページネーションを使用します
• perf-keyset-not-offset-for-deep-pages — キーベースのページネーションでは、ページをまたいでもコストが一定に保たれます
• perf-covering-index-for-hot-queries — 射影する列をカバーして、プランナーが行の読み取りを省略できるようにします

7. 接続とドライバーの設定（中）

• conn-enable-wal — 並行読み取りと単一の書き込みには journal_mode = WAL を使用します
• conn-set-busy-timeout — busy_timeout = 5000 により、競合時に待機するようになります
• conn-foreign-keys-pragma — 接続ごとに foreign_keys = ON を設定します。デフォルトではオフです
• conn-singleton-client — モジュールスコープのシングルトンを使用し、リクエストごとにインスタンスを生成しないでください
• conn-pick-driver-deliberately — 同期、非同期、HTTP のいずれかを、デプロイ先に応じて選択します

8. 型推論（中）

• types-infer-select-insert — $inferSelect / $inferInsert で行の型を導出します
• types-narrow-json-with-dollartype — .$type<Shape>() を使用して、JSON 列の unknown を解消します
• types-getTableColumns-for-reuse — getTableColumns() とスプレッド構文を使って射影を共有します
• types-drizzle-zod-for-runtime-validation — createInsertSchema(table) でスキーマから Zod バリデーターを導出します
• types-bigint-mode-for-large-integers — Number.MAX_SAFE_INTEGER を超える ID には mode: 'bigint' を使用します

使用方法

references/_sections.md で該当するカテゴリの概要を読み、次に詳細な説明とコード例が記載された個別のルールファイルを読んでください。各ルールには誤った例と正しい例があるため、レビュー対象のコードには正しいパターンを適用します。

複雑な変更（スキーマの再設計、マイグレーション戦略、パフォーマンス改善）を行う場合は、判断する前に該当するカテゴリのルールをすべて読んでください。

• セクションの定義 — カテゴリ構成と影響レベル
• ルールのテンプレート — 新しいルールを追加するためのテンプレート

参照ファイル

ファイル	説明
references/_sections.md	カテゴリの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンと参照情報

関連スキル

• effect-ts — アプリケーションが Effect ベースの場合に使用します。Drizzle は Effect.tryPromise 経由で統合できます。
• nextjs-bundle-optimizer — Next.js アプリで SQLite をデータレイヤーとして使用する場合に役立ちます。
• better-auth — 認証テーブルで Drizzle SQLite とよく併用されます。テーブル生成については better-auth-scaffold を参照してください。