using-relational-databases

リレーショナルデータベース

目的

このスキルでは、複数の言語におけるリレーショナルデータベースの選定と実装について説明します。トランザクションシステム、CRUD アプリケーション、構造化データの保存に適したデータベースエンジン、ORM／クエリビルダー、デプロイ戦略を選択します。

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• ユーザー認証、コンテンツ管理、e コマースアプリケーションを構築する
• CRUD 操作（作成、読み取り、更新、削除）を実装する
• リレーションを持つデータモデルを設計する（ユーザー → 投稿、注文 → 商品）
• 本番環境でスキーマを安全に移行する
• パフォーマンス向上のためにコネクションプーリングを設定する
• サーバーレスデータベースの選択肢（Neon、PlanetScale、Turso）を評価する
• フロントエンドのスキル（フォーム、テーブル、ダッシュボード、検索・フィルター）と統合する

次の場合はこのスキルを使用しないでください：

• 大規模な時系列データ（時系列データベースを使用してください）
• リアルタイム分析（カラム型データベースを使用してください）
• ドキュメント中心のワークロード（ドキュメントデータベースを使用してください）
• キー・バリューキャッシュ（Redis、Memcached を使用してください）

クイックリファレンス：データベースの選択

Database Selection Decision Tree
═══════════════════════════════════════════════════════════

PRIMARY CONCERN?
├─ MAXIMUM FLEXIBILITY & EXTENSIONS (JSON, arrays, vector search)
│  └─ PostgreSQL
│     ├─ Serverless → Neon (scale-to-zero, database branching)
│     └─ Traditional → Self-hosted, AWS RDS, Google Cloud SQL
│
├─ EMBEDDED / EDGE DEPLOYMENT (local-first, global latency)
│  └─ SQLite or Turso
│     ├─ Global distribution → Turso (libSQL, edge replicas)
│     └─ Local-only → SQLite (embedded, zero-config)
│
├─ LEGACY SYSTEM / MYSQL REQUIRED
│  └─ MySQL
│     ├─ Serverless → PlanetScale (non-blocking migrations)
│     └─ Traditional → Self-hosted, AWS RDS, Google Cloud SQL
│
└─ RAPID PROTOTYPING
   ├─ Python → SQLModel (FastAPI) or SQLAlchemy 2.0
   ├─ TypeScript → Prisma (best DX) or Drizzle (performance)
   ├─ Rust → SQLx (compile-time checks)
   └─ Go → sqlc (type-safe code generation)

クイックリファレンス：ORM とクエリビルダーの比較

ORM vs Query Builder Selection
═══════════════════════════════════════════════════════════

TEAM PRIORITIES?
├─ DEVELOPMENT SPEED / DEVELOPER EXPERIENCE
│  └─ ORM (abstracts SQL, handles relations automatically)
│     ├─ Python → SQLAlchemy 2.0, SQLModel
│     ├─ TypeScript → Prisma (migrations, type generation)
│     ├─ Rust → SeaORM (Active Record + Data Mapper)
│     └─ Go → GORM, Ent
│
├─ PERFORMANCE / QUERY CONTROL
│  └─ Query Builder (SQL-like, zero abstraction overhead)
│     ├─ Python → SQLAlchemy Core, asyncpg
│     ├─ TypeScript → Drizzle, Kysely
│     ├─ Rust → SQLx (compile-time query validation!)
│     └─ Go → sqlc (generates types from SQL)
│
├─ TYPE SAFETY / COMPILE-TIME GUARANTEES
│  ├─ Rust → SQLx (queries checked at build time)
│  ├─ Go → sqlc (generates types from SQL)
│  ├─ TypeScript → Prisma or Drizzle
│  └─ Python → SQLModel (Pydantic integration)
│
└─ COMPLEX QUERIES / JOINS
   ├─ SQL-first → Query builders or raw SQL
   └─ ORM-friendly → SeaORM, SQLAlchemy ORM

複数言語での実装

Python：SQLAlchemy 2.0 + SQLModel

推奨ライブラリ：

• SQLAlchemy 2.0 (/websites/sqlalchemy_en_21) - ORM + Core、7,090 件のスニペット
• SQLModel - FastAPI との統合、Pydantic による検証
• asyncpg - 高性能な非同期 PostgreSQL ドライバー

使用する場面：

• 柔軟性が求められる本番アプリケーション
• FastAPI／Starlette バックエンド
• async／await ワークフロー

クイックパターン：

from sqlmodel import SQLModel, Field, Session
class User(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    email: str = Field(unique=True, index=True)

参照： SQLAlchemy／SQLModel のパターン、非同期ワークフロー、コネクションプーリングの全容については、references/orms-python.md を参照してください。

TypeScript：Prisma と Drizzle の比較

推奨ライブラリ：

• Prisma 6.x (/prisma/prisma, スコア：96.4、ドキュメントスニペット 4,281 件) - 優れた開発者体験、マイグレーション
• Drizzle ORM (/drizzle-team/drizzle-orm-docs, スコア：95.4、スニペット 4,037 件) - パフォーマンス、SQL に近い構文

簡単な比較：

• Prisma：優れた開発者体験、自動生成される型、マイグレーションを内蔵
• Drizzle：最高のパフォーマンス、SQL に近い構文、オーバーヘッドなし

参照： Prisma と Drizzle の詳細な比較、Kysely、TypeORM のパターンについては、references/orms-typescript.md を参照してください。

Rust：SQLx（コンパイル時チェック）

推奨ライブラリ：

• SQLx 0.8 - コンパイル時のクエリ検証、非同期
• SeaORM 1.x - Active Record パターンを備えたフル ORM
• Diesel 2.3 - 成熟して安定（同期／非同期）

クイックパターン：

use sqlx::FromRow;
#[derive(FromRow)]
struct User { id: i32, email: String, name: String }
// Compile-time checked queries (verified at build time!)
let user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE email = $1")
    .bind("[email protected]").fetch_one(&pool).await?;

参照： SQLx マクロ、SeaORM、Diesel のパターン、コンパイル時の保証については、references/orms-rust.md を参照してください。

Go：sqlc（型安全なコード生成）

推奨ライブラリ：

• sqlc - SQL クエリから Go コードを生成
• GORM v2 - アソシエーション、フックを備えたフル ORM
• Ent - グラフベースの ORM、コードとしてのスキーマ
• pgx - 高性能な PostgreSQL ドライバー

クイックパターン：

-- queries.sql: SQL annotations generate type-safe Go code
-- name: CreateUser :one
INSERT INTO users (email, name) VALUES ($1, $2) RETURNING *;

user, err := queries.CreateUser(ctx, db.CreateUserParams{Email: "[email protected]"})

参照： sqlc のセットアップ、GORM、Ent、pgx のパターンについては、references/orms-go.md を参照してください。

コネクションプーリング

推奨プールサイズ：

• Web API（単一インスタンス）：10～20 接続
• サーバーレス（関数ごと）：1～2 接続 + pgBouncer
• バックグラウンドワーカー：5～10 接続

参照： 設定例、サイズ算出式、監視戦略については、references/connection-pooling.md を参照してください。

マイグレーション

重要な原則：

1. カラムの削除には複数フェーズのデプロイを使用します（本番環境で直接削除しないでください）
2. 書き込みのブロックを避けるため、CREATE INDEX CONCURRENTLY（PostgreSQL）を使用します
3. 本番環境に近いデータ量を使用して、ステージング環境でマイグレーションをテストします

ツール： Alembic（Python）、Prisma Migrate（TypeScript）、SQLx migrations（Rust）、golang-migrate（Go）

参照： 安全なマイグレーションパターン、複数フェーズのデプロイ、ロールバック戦略については、references/migrations-guide.md を参照してください。

サーバーレスデータベース

データベース	種類	主な特徴	最適な用途
Neon	PostgreSQL	データベースのブランチ作成、ゼロスケール	開発ワークフロー、プレビュー環境
PlanetScale	MySQL (Vitess)	ブロックなしのスキーマ変更	MySQL アプリ、ダウンタイムゼロのマイグレーション
Turso	SQLite (libSQL)	エッジデプロイ、低レイテンシ	エッジ関数、グローバル配信

参照： references/serverless-databases.md にセットアップ例、ブランチ作成ワークフロー、コスト比較があります。

フロントエンド連携

一般的な連携パターン：

• Forms スキル：フォーム送信 → API による検証 → データベース CRUD（INSERT/UPDATE）
• Tables スキル：ページネーション付きクエリ → API → ソート／フィルタリング機能付きテーブル表示
• Dashboards スキル：集計クエリ（COUNT、SUM）→ API → KPI カード
• Search-filter スキル：全文検索（PostgreSQL tsvector）→ ランク付けされた結果

実際に動作する例： examples/python-sqlalchemy/、examples/typescript-drizzle/、examples/rust-sqlx/

同梱リソース

リファレンスドキュメント

• references/postgresql-guide.md - PostgreSQL の機能（pgvector、PostGIS、TimescaleDB）
• references/mysql-guide.md - MySQL 固有のパターン、PlanetScale との連携
• references/sqlite-guide.md - SQLite のパターン、Turso のエッジデプロイ
• references/orms-python.md - SQLAlchemy 2.0、SQLModel、asyncpg
• references/orms-typescript.md - Prisma、Drizzle、Kysely の比較
• references/orms-rust.md - SQLx、SeaORM、Diesel
• references/orms-go.md - GORM、sqlc、Ent、pgx
• references/migrations-guide.md - 安全なスキーマ進化のパターン
• references/connection-pooling.md - プールサイズの設定とモニタリング
• references/serverless-databases.md - Neon、PlanetScale、Turso のデプロイ

実際に動作する例

• examples/python-sqlalchemy/ - SQLAlchemy 2.0 + FastAPI によるプーリング、マイグレーション
• examples/typescript-prisma/ - スキーマとマイグレーションを備えた Prisma + Next.js
• examples/typescript-drizzle/ - 型安全なクエリを備えた Drizzle + Hono
• examples/rust-sqlx/ - コンパイル時チェックを備えた SQLx + Axum
• examples/go-sqlc/ - 生成された型安全なコードを使用する sqlc + Gin

ユーティリティスクリプト

• scripts/validate_schema.py - データベーススキーマの構造と制約を検証
• scripts/generate_migration.py - 一般的な操作向けのマイグレーションテンプレートを生成

ベストプラクティス

セキュリティ：

• 常にパラメーター化クエリを使用します（SQL インジェクションを防止）
• パスワードは Argon2/bcrypt でハッシュ化します
• 接続文字列には環境変数を使用します
• 本番環境では SSL/TLS を有効にします

パフォーマンス：

• コネクションプーリングを使用します（Web API では 10～20）
• フィルターやソートに使用する列にインデックスを作成します
• 大規模な結果セットにはページネーションを実装します
• 遅いクエリには EXPLAIN ANALYZE を使用します

信頼性：

• マイグレーションはまずステージング環境でテストします
• 複数のステートメントを伴う操作にはトランザクションを使用します
• コネクションプールの枯渇を監視します
• データベースのバックアップを設定し、テストします

開発：

• スキーマとマイグレーションをバージョン管理します
• 機能開発にはデータベースのブランチ作成（Neon）を使用します
• 実際のデータベースを使った統合テストを記述します