Claude Codeでデータベーススキーマとクエリを設計する実践ガイド（2026年）

Claude Codeは本当にDBを設計し、クエリを書けるのか？

はい、しかもうまくこなします。スキーマ設計とクエリ作成は、まさにClaude Codeのようなエージェント型ツールが得意とする種類の作業だからです。 Claude Codeは単なるオートコンプリート的な提案ではありません。あなたのファイルやリポジトリ全体を読み、ターミナルでコマンド（psql、mongosh、テストの実行）を走らせ、その出力を読み、自分で修正しながら反復できます。データベースにおいては、この「コンテキストを読む → DDL/クエリを生成する → 実行する → 結果を読む → 調整する」というループこそ、Claude Codeが最も力を発揮する場面です。

本記事では、最もよく使われる2つのシステム、PostgreSQL（リレーショナル）とMongoDB（ドキュメント）に焦点を当てます。同じアプローチが両方に通用します。まだ始めたばかりで、そもそもClaude Codeが何なのか分からないという方は、まずClaude Codeとは何か、何に使うのかを読んでから、ここに戻ってきてください。

最初に正直な注意点を1つ。AIはデータベース作業が速い一方で、自動的に安全なわけではありません。存在しないカラム名をでっち上げたり、金額に不適切なデータ型を選んだり、元に戻す手段のないマイグレーションを生成したりすることがあります。だからこそ本記事全体は2つの原則の上に成り立っています。本番環境には読み取り専用アクセスのみを与えることと、Claudeに必ず自分の作業を検証する手段を与えることです。接続 → スキーマ設計 → クエリ作成 → インデックスとパフォーマンス → マイグレーション、という一連のループをたどっていきましょう。

セットアップ：Claude Codeをデータベースに接続する

Claudeに何かを頼む前に、まずデータを実際に「見せる」必要があります。安全なものから柔軟なものまで、方法は3つあります。

方法1 - MCPサーバー（推奨、読み取り専用）

MCP（Model Context Protocol）は、Claude Codeがデータベースを含む外部ツールに接続する標準的な方法です。Claude CodeのMCPドキュメントには、「私たちのPostgreSQLデータベースに基づいて」データを問い合わせるという直接的な例が示されています（Claude Code MCPドキュメント、Anthropic、2026）。HTTP版のMCPサーバーを追加するコマンドは次のとおりです。

claude mcp add --transport http postgres-db https://your-mcp-endpoint

安全面で決定的に重要な点。リファレンス実装のPostgres MCPサーバーは「スキーマ検査付きの読み取り専用データベースアクセス」と説明されています。つまり構造の読み取りと検査だけを行い、書き込みはしません（modelcontextprotocol/servers、2026。このサーバーはその後servers-archivedリポジトリへ移動しました）。AIをDBに近づけるとき、これこそが望ましい形です。コンテキストを理解するためにスキーマを読むことはできても、勝手にテーブルを削除することはできません。MCPが初めての方は、MCPとは何か、外部ツールをClaude Codeに接続する方法をご覧ください。

方法2 - psql / mongosh CLI

さらにシンプルな方法として、ターミナル経由でClaudeにコマンドを実行させるだけでも構いません。すでにpsqlやmongoshを設定済みなら、Claudeはそれらを直接呼び出せます。これは柔軟ですが（書き込みコマンドも実行できてしまう）、まさにその理由でリスクも高くなります。開発用/ローカルのDBだけに向け、書き込み権限のある本番接続文字列には決して向けないでください。

方法3 - @でスキーマファイルを渡す

実際のDBに接続する準備がまだできていないなら、@構文を使ってschema.sqlファイルやテーブルの説明をClaudeに渡すだけでも構いません。

Read @db/schema.sql and summarize the tables, primary keys, and relationships.
Then list 3 design risks you see.

ステップ1 - Claude Codeでスキーマを設計する

最もよくある間違いは、Claudeを開いていきなり「users テーブルを作って」と打ち込むことです。そうすると、AIが当てずっぽうで推測した汎用的なスキーマが返ってきます。正しいやり方はワークロード優先です。まず負荷の種類を決め、それからAIにテーブルを作らせます。

まずワークロードを分類する

これがどんなアプリケーションなのかを自分に問い、Claudeにも伝えましょう。種類ごとに最適化すべきデータの形が異なるからです。

プランモードを使い、書く前に読ませる

プランモードをオンにして（Shift+Tabを押してモードを切り替えます）、要件を読み、不明な点があれば質問し、そのうえでDDLを生成するようClaudeに指示しましょう。これにより、誤った前提のままテーブル作成に突き進むのを防げます。

プロンプトの型：カラムではなく不変条件を述べる

カラムを列挙する代わりに、不変のビジネスルールを説明しましょう。そうすればAIが自分で適切な主キー、ユニーク制約、外部キーを設定してくれます。

Design a PostgreSQL schema for a small shop. Workload: OLTP.
Invariants:
- One email belongs to exactly one account (unique).
- An order must belong to an existing user (an orphan = a bug).
- Each order_items row records the price AT PURCHASE TIME, not the current price.
- Money must be exact, with no rounding error.
Ask me questions if anything is missing before writing the DDL.

リレーショナル・チェックリスト（Claudeが生成したDDLをレビューするために）

• エンティティは名詞で命名し、結合テーブルはそれが表す関係にちなんで命名します。
• 安定した識別子は主キーに、ユニークなビジネスルールはユニーク制約に入れます。
• 孤立データがバグになる場合は必ず外部キーを使います。
• 金額、数量、時刻には正確な型を使います。金額にfloatを使ってはいけません（numeric/decimalを使いましょう）。
• 多対多：専用の結合テーブルを作り、必要なメタデータ列を追加します。
• インデックスは、必要だと実証できた述語に対してのみ追加します（何でもかんでもインデックスを張らないこと）。

実例として、Claudeが生成した最小限のeコマース向けスキーマを示します（1行だけ私が修正しました。注記を参照）。

CREATE TABLE users (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 email text NOT NULL UNIQUE,
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE orders (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 user_id bigint NOT NULL REFERENCES users(id),
 status text NOT NULL DEFAULT 'pending',
 created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE order_items (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 order_id bigint NOT NULL REFERENCES orders(id),
 product_id bigint NOT NULL,
 quantity int NOT NULL CHECK (quantity > 0),
 unit_price numeric(12,2) NOT NULL -- NOT float: money must be exact
);

最初のとき、Claudeはunit_priceをreal（浮動小数点数）のままにしていました。私はそれをnumeric(12,2)に変えさせました。これはまさに、あなた自身が注意すべきバグの典型です。AIは必ずしもこれを覚えているとは限らないからです。

PostgreSQLかMongoDBか？アクセスパターンで選ぶ

好みで選ぶのではなく、データがどう読み書きされるかで選びましょう。手早い比較表です。

埋め込みか参照かで迷ったときの、MongoDBの黄金律です。

• 埋め込み（Embed）：子データが親と一緒に読み書きされ、かつサイズが有界な場合（例：注文の中の配送先住所）。
• 参照（Reference）：データが無制限に増える、多くの親から共有される、または独自のライフサイクルが必要な場合（例：バズった投稿へのコメント）。

ステップ2 - Claude Codeでクエリを書き、最適化する

ここがClaude Codeの真骨頂です。ほしい結果を平易な言葉で説明すると、クエリを書き、それを説明し、そして最適化してくれます。SQLではJOIN、サブクエリ、CTE、ウィンドウ関数を自在に扱います。MongoDBでは集計パイプライン（$match → $group → $lookup）を組み立てます。

実例として、月次売上レポートを見てみましょう。プロンプトはこちら。

Write a Postgres query for total revenue per month in 2026,
counting only orders with status = 'paid'. Use a CTE for readability,
with a short explanation.

Claudeの返答です。

WITH paid_items AS (
 SELECT o.created_at, oi.quantity * oi.unit_price AS line_total
 FROM orders o
 JOIN order_items oi ON oi.order_id = o.id
 WHERE o.status = 'paid'
 AND o.created_at >= '2026-01-01'
 AND o.created_at < '2027-01-01'
)
SELECT date_trunc('month', created_at) AS month,
 SUM(line_total) AS revenue
FROM paid_items
GROUP BY 1
ORDER BY 1;

実行結果（サンプルデータ）です。

 month | revenue
--------------------+-----------
 2026-01-01 00:00:00 | 154200.00
 2026-02-01 00:00:00 | 187650.50
 2026-03-01 00:00:00 | 203110.00

MongoDBでも同じ考え方がパイプラインになります。$matchでpaidの注文を絞り込み、$unwindで商品配列を展開し、$groupで月ごとに集計します。Claudeにこれを書かせ、各ステージを説明させましょう。クエリとその理解を同時に得られる最速の方法です。

重要な警告：Claudeが書いたクエリを実データに対して実行する前に、必ず読み直してください。WHEREが欠けたUPDATE/DELETEは（AIがうっかり生成することがあります）、テーブル全体を消し飛ばしかねません。読んで、理解して、それからEnterを押しましょう。

ステップ3 - EXPLAIN ANALYZEによるインデックスとパフォーマンス

クエリが正しく動くだけでは不十分で、速く動く必要があります。ClaudeにEXPLAIN ANALYZE（Postgres）や.explain()（Mongo）を実行させ、実行計画を読み、それから適切な場所に（やみくもにではなく）インデックスを提案させましょう。

Run EXPLAIN ANALYZE for the revenue query above.
If you see a Seq Scan on orders, suggest a suitable index and explain why.

大きなordersテーブルでは、statusとcreated_atで絞り込むため、最初の実行計画はしばしばSeq Scanを示します。適切なインデックスを追加しましょう。

CREATE INDEX idx_orders_status_created
 ON orders (status, created_at);

もう一度実行すると、計画はIndex Scanに切り替わり、クエリ時間が目に見えて短くなります。Claudeの助けがほしいのは、複合インデックスにおける列の順序を述語に合うように選ぶ場面です。ここは経験の浅い開発者がよく間違えるところです。

過剰なインデックス作成（Claude自身がやりがちです）を避けるインデックスの原則。インデックスは、外部キー、頻繁に絞り込み/並べ替えに使う列、ユニーク制約に対してのみ張りましょう。インデックスを1つ追加するたびに書き込みが遅くなり、ストレージも消費します。だから「念のため」でインデックスを張ってはいけません。Claudeに「速くするためにインデックスを追加して」と伝えると、やりすぎる傾向があります。実証できる述語のあるインデックスだけを提案するよう指示しましょう。

ステップ4 - Claude Codeで安全にマイグレーションする

稼働中のシステムでスキーマを変更するのは、数ある作業の中でも最も障害を起こしやすいものです。Claudeにマイグレーションを生成させるときの安全な手順です。

1. 必ずロールバックを含める。すべての「up」マイグレーションには対応する「down」が必要です。両方を書き、変更をどう元に戻すかを説明するようClaudeに指示しましょう。
2. まずコピーでテストする。マイグレーションは開発用DBか本番のスナップショットで実行し、本番に直接当てないこと。
3. 前後を比較する。実行の前後で行数を数え、いくつかのサンプルレコードを確認して、データが失われていないことを確かめます。
4. サブエージェントで差分をレビューする。サブエージェントに、独立したPRのようにマイグレーションをレビューさせ、安全策のない破壊的操作（DROP、データ型の変更）を探させましょう。

Anthropicのベストプラクティスは、この原則を一言でまとめています。「Claudeに自分の作業を検証する手段を与えよ」（Claude Codeベストプラクティス、Anthropic、2026）。データベースにおいて「検証」とは具体的なことを意味します。テストを実行し、EXPLAINを実行し、前後の行数を比較すること。AIの「終わりました」という言葉を鵜呑みにしないことです。

用意しておく価値のあるガードレール。パーミッションフックを使って、Claudeが勝手にmigrations/ディレクトリへ書き込むのを止めたり、破壊的なDDLコマンドをブロックしたりして、すべての変更を必ずあなたのレビューを通すようにしましょう。パーミッションを安全に締める方法については、Claude Codeでセキュリティ監査を実行するをご覧ください。

AIにデータベースを任せるときの本当の落とし穴（本番前に読んでください）

このセクションが最も重要で、しかもほとんどのドキュメントははっきり口にしません。AIはDB作業が速い一方で、本当に間違えるのは以下のポイントです。私はすべて実際に踏み抜きました。

• カラム名/テーブル名のでっち上げ。Claudeはスキーマを推測して、存在しないカラムを参照することがあります。クエリを書く前に、必ず実際のスキーマを（MCPまたは@schema.sqlで）読ませましょう。
• 金額に誤った型。価格にfloat/realを使いたがることが非常に多く、丸め誤差が積み重なる原因になります。numeric/decimalを必須にしましょう。
• 過剰なインデックス。あちこちにインデックスをばらまくと、読み取りをたいして速くしないまま書き込みが遅くなります。
• ロールバックのないマイグレーション。upは生成してもdownを忘れ、いざ元に戻したいときに立ち往生します。
• N+1やフルスキャンのクエリ。1つのJOINの代わりにレコードごとに問い合わせるループを書いたり、絞り込み条件を落としたりします。

妥協できない3つのルール。(1) 本番には読み取り専用アクセスのみを与える。AIには読ませても、決して書かせない。(2) すべてのスキーマ変更はPR + テストを通す。直接適用しない。(3) EXPLAIN + 行数比較で検証する。「終わった」を信用しない。この3つを守れば、DBにAIを使うのは十分に安全です。

ak-databasesスキル（AgentKit）でもっと速く

「ワークロード優先、不変条件を述べる、チェックリストを含める」というプロンプトを毎回書き直している自分に気づいたら、正直な近道があります。AgentKit Engineer Kit（ak-databasesスキルを含む）は、まさに本記事の骨格をパッケージ化したものです。ak-databasesスキルはOLTP/OLAPのスキーマ設計、Postgres/Mongoのクエリ作成、集計、インデックス、マイグレーションをカバーし、db_migrate.py、db_backup.py、db_performance_check.pyといったスクリプトも付いてきます。「〜のスキーマを設計して」と自然に打ち込むだけで、スキルが自ら起動するので、プロンプトの型を覚えておく必要はありません。

よくある質問（FAQ）

Claude Codeはデータベースに直接接続できますか？

はい、2つの方法があります。MCPサーバー（推奨、通常は読み取り専用）か、ターミナル経由でClaudeにpsql/mongoshコマンドを実行させる方法です。実際のDBにまだ接続したくない場合は、@構文でスキーマファイルを貼り付けられます。

Claude Codeは自分で本番環境にクエリを実行してしまいますか？

その能力を与えるべきではありません。本番には読み取り専用の接続のみを与え、すべての書き込み/DDL操作は開発用DBか、レビュー済みのPRの背後にとどめましょう。破壊的なコマンドをブロックするにはパーミッションフックを使います。

PostgreSQLとMongoDB、どちらを選ぶべきですか？

好みではなく、アクセスパターンで選びましょう。厳格な制約が必要なトランザクションや集計レポートにはPostgreSQL、ひとまとまりとして読み書きするネストデータにはMongoDBです。金額のトランザクションはほぼ常にPostgreSQLにすべきです。

Claude Codeはマイグレーションを書けますか？

はい。ただしロールバック手順（down）も書くよう指示し、まずコピーでテストし、実行の前後で行数を比較する必要があります。AIが生成したマイグレーションを本番にそのまま当ててはいけません。

AIにデータベースを任せて安全ですか？

3つのルールを守れば安全です。本番は読み取り専用、すべての変更はPR + テストを通す、そしてEXPLAIN ANALYZE + 行数比較で検証する。本当のリスクは、書き込み権限を与え、確認せずにAIを信用することから生じます。

Engineer Kitを買わなければいけませんか？

いいえ。本記事のワークフロー全体は、素のClaude Codeで動きます。ak-databasesスキルは、DB作業を日常的に、あるいはチームで行うときに、それをより速く、より一貫させるだけのものです。

まとめと次のステップ

4つのステップをおさらいします。DBに接続する（読み取り専用MCPが望ましい）→ ワークロードでスキーマを設計する → 検証しながらクエリを書いて最適化する → ロールバック付きでマイグレーションする。肝心なのは、AIにすべてを丸投げすることではなく、十分なコンテキストと、必ず自分の作業を検証する手段を与えることです。スキーマができたら、次の論理的なステップはDBをAPI層に組み込むことです。Claude CodeでバックエンドとAPIを構築するをご覧ください。そしてDB設計の部分を高速化したいなら、Engineer Kitのak-databasesスキルを試すのもよいでしょう。