database-patterns

データベースのパターン

データベースのマイグレーション、スキーマ設計、バージョン管理に関する包括的なパターンです。各カテゴリには個別のルールファイルがあり、必要に応じて rules/ から読み込まれます。

クイックリファレンス

カテゴリ	ルール数	影響度	使用する場面
Alembic マイグレーション	2	CRITICAL	データのマイグレーション、ブランチ管理
スキーマ設計	3	HIGH	正規化、インデックス戦略、NoSQL パターン
バージョン管理	2	HIGH	変更履歴、スキーマドリフトの検出
ダウンタイムなしのマイグレーション	2	CRITICAL	拡張・縮小、pgroll、ロールバックの監視

| データベースの選定 | 1 | HIGH | 適切なデータベースの選定、PostgreSQL と MongoDB の比較、コスト分析 |

5 カテゴリで合計 10 個のルール

このスキルは Alembic と PostgreSQL を補完するものであり、それらのドキュメントに取って代わるものではありません。まず references/ork-delta.md を読んでください。ここには、上流のドキュメントにはないバージョンの下限、修正点、プロジェクト内の規約が記載されています。以下の表の内容はすべて、意図的に削除されています。

上流ドキュメントの対象範囲（再掲しないこと）

これらのトピックはベンダーのドキュメントで扱われています。ここで改めて説明するのではなく、参照元から取得してください。

トピック	一次情報
Alembic の自動生成、非同期 env.py テンプレート、revision／upgrade／downgrade／history CLI	https://alembic.sqlalchemy.org/en/latest/autogenerate.html（非同期テンプレートに対する当プロジェクト固有の修正は references/ork-delta.md に記載されています）
マイグレーションブランチ、マージリビジョン、タプル形式の down_revision、ブランチラベル	https://alembic.sqlalchemy.org/en/latest/branches.html
複数データベース用の env.py、バッチ処理によるバックフィルのレシピ、マイグレーションフック、環境に応じたマイグレーション	https://alembic.sqlalchemy.org/en/latest/cookbook.html
ロールバックとデータ整合性のテストハーネス	references/migration-testing.md
JSONB 演算子、インデックス作成、ストレージのトレードオフ	https://www.postgresql.org/docs/current/datatype-json.html（正規形とプロジェクト内の非正規化方針については rules/schema-normalization.md に記載されています）
インデックス種別と構文の完全なリファレンス（B-tree、GIN、部分インデックス、カバリングインデックス、CREATE INDEX CONCURRENTLY、REINDEX）	https://www.postgresql.org/docs/current/sql-createindex.html（実際に適用するプロジェクト内の対象範囲は rules/schema-indexing.md に記載されています）
マイグレーション中の lock_timeout、statement_timeout、アドバイザリロック	https://www.postgresql.org/docs/current/runtime-config-client.html および rules/versioning-drift.md
列挙型の変更	https://www.postgresql.org/docs/current/datatype-enum.html
テーブルパーティショニング	https://www.postgresql.org/docs/current/ddl-partitioning.html
トリガー関数	https://www.postgresql.org/docs/current/plpgsql-trigger.html
外部キーのカスケード動作	https://www.postgresql.org/docs/current/ddl-constraints.html
時系列テーブルと監査証跡テーブル、CDC 変更ログ、ストアドプロシージャとビューのバージョン管理	https://www.postgresql.org/docs/18/sql-createtable.html（これらが行履歴を提供すると決めつける前に references/ork-delta.md を読んでください）
HNSW とベクトルインデックスのチューニング（m、ef_construction、hnsw.ef_search）	https://github.com/pgvector/pgvector
デプロイ前、バックアップ、スキーマレビューに関する一般的なチェックリスト	https://alembic.sqlalchemy.org/en/latest/tutorial.html
非同期 SQLAlchemy セッション、FastAPI の接続、接続プールのチューニング	ork:python-backend スキル

クイックスタート

# Alembic: Auto-generate migration from model changes
# alembic revision --autogenerate -m "add user preferences"

def upgrade() -> None:
    op.add_column('users', sa.Column('org_id', UUID(as_uuid=True), nullable=True))
    op.execute("UPDATE users SET org_id = 'default-org-uuid' WHERE org_id IS NULL")

def downgrade() -> None:
    op.drop_column('users', 'org_id')

-- Schema: Normalization to 3NF with proper indexing
-- PG18: prefer uuidv7() (time-ordered, better B-tree locality) over gen_random_uuid() (random v4)
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT uuidv7(),
    customer_id UUID NOT NULL REFERENCES customers(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_orders_customer_id ON orders(customer_id);

Alembic マイグレーション

SQLAlchemy 2.0 の非同期アプリケーション向けの Alembic によるマイグレーション管理です。

ルール	ファイル	主なパターン
データマイグレーション	rules/alembic-data-migration.md	バッチバックフィル、2 段階の NOT NULL、ダウンタイムなし
ブランチ管理	rules/alembic-branching.md	機能ブランチ、マージマイグレーション、競合解決

自動生成の設定はアップストリームに準拠しています。Alembic の非同期 env.py テンプレートからの唯一の変更（in_greenlet() ガード）は、references/ork-delta.md に記載されています。

スキーマ設計

正規化、インデックス作成、制約パターンを含む SQL および NoSQL のスキーマ設計です。

ルール	ファイル	主なパターン
正規化	rules/schema-normalization.md	1NF～3NF、非正規化するタイミング、JSON と正規化の比較
インデックス作成	rules/schema-indexing.md	B-tree、GIN、HNSW、部分インデックス／カバリングインデックス
NoSQL パターン	rules/schema-nosql.md	埋め込みと参照の使い分け、ドキュメント設計、シャーディング

バージョン管理

環境全体にわたるデータベースのバージョン管理と変更管理です。

ルール	ファイル	主なパターン
変更履歴	rules/versioning-changelog.md	スキーマバージョンテーブル、セマンティックバージョニング、監査証跡
ドリフト検出	rules/versioning-drift.md	環境の同期、チェックサム検証、マイグレーションロック

ロールバックテストは references/migration-testing.md に記載されています。 データ損失を伴うダウングレードの docstring 規約は references/ork-delta.md に記載されています。

データベースの選択

適切なデータベースを選ぶための判断フレームワークです。デフォルトは PostgreSQL です。

ルール	ファイル	主なパターン
選択ガイド	rules/db-selection.md	PostgreSQL 優先、階層別マトリックス、アンチパターン

主な決定事項

決定事項	推奨事項	理由
非同期ダイアレクト	postgresql+asyncpg	SQLAlchemy 2.0 のネイティブな非同期サポート
NOT NULL カラム	2 段階方式：まず NULL 許容にし、その後変更	ロックを回避し、後方互換性を維持
大規模テーブルのインデックス	CREATE INDEX CONCURRENTLY	ダウンタイムなし、テーブルロックなし
正規化の目標	OLTP では 3NF	クエリ性能を維持しながら冗長性を削減
主キー戦略	分散環境では UUID、単一 DB では INT	コンテキストに適したキー生成
論理削除	deleted_at タイムスタンプカラム	監査証跡を保持し、復旧を可能にする
マイグレーションの粒度	1 ファイルにつき論理的な変更を 1 つ	ロールバックとデバッグが容易
本番環境へのデプロイ	SQL を生成してレビューしてから適用	本番環境では自動実行しない

アンチパターン（禁止）

# NEVER: Add NOT NULL without default or two-phase approach
op.add_column('users', sa.Column('org_id', UUID, nullable=False))  # LOCKS TABLE!

# NEVER: Use blocking index creation on large tables
op.create_index('idx_large', 'big_table', ['col'])  # Use CONCURRENTLY

# NEVER: Skip downgrade implementation
def downgrade():
    pass  # WRONG - implement proper rollback

# NEVER: Modify migration after deployment - create new migration instead

# NEVER: Run migrations automatically in production
# Use: alembic upgrade head --sql > review.sql

# NEVER: Run CONCURRENTLY inside transaction
op.execute("BEGIN; CREATE INDEX CONCURRENTLY ...; COMMIT;")  # FAILS

# NEVER: Delete migration history
command.stamp(alembic_config, "head")  # Loses history

# NEVER: Skip environments (Always: local -> CI -> staging -> production)

詳細ドキュメント

リソース	説明
references/ork-delta.md	修正点とプロジェクト内の規約です。最初にお読みください
references/migration-testing.md	アップグレード／ダウングレードのサイクルとデータ整合性テストハーネス
references/postgres-vs-mongodb.md	PostgreSQL 優先のデフォルト方針の根拠となる直接比較
references/db-migration-paths.md	データベースエンジン間のマイグレーションリスクマトリックス
references/cost-comparison.md	マネージドデータベースのコスト分析
references/storage-and-cms.md	オブジェクトストレージと CMS の選定
scripts/	マイグレーションテンプレート、モデル変更検出ツール

ダウンタイムなしのマイグレーション

拡張・縮小パターンとオンラインスキーマ変更を使用して、ダウンタイムなしで安全にデータベーススキーマを変更します。

ルール	ファイル	主なパターン
拡張・縮小	rules/migration-zero-downtime.md	拡張フェーズ、バックフィル、縮小フェーズ、pgroll による自動化
ロールバックと監視	rules/migration-rollback.md	pgroll によるロールバック、ロック監視、レプリケーション遅延、バックフィルの進捗

関連スキル

• sqlalchemy-2-async - SQLAlchemy の非同期セッションパターン
• ork:testing-integration - マイグレーションテストを含む統合テストパターン
• caching - データベースの性能を補完するキャッシュレイヤー設計
• ork:performance - 性能最適化パターン