sqlalchemy-alembic-expert-best-practices-code-review

SQLAlchemy & Alembic のエキスパート向けベストプラクティス

シンプルで、実用的で、明確な方針に基づいています。本番品質の SQLAlchemy および Alembic コードを書くうえで重要なことだけを扱います。

適用するタイミング

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

• スキーマ変更のための Alembic マイグレーションを作成するとき
• SQLAlchemy モデルを作成または変更するとき
• Alembic を使ってインデックス、制約、または外部キーを追加するとき
• データベースマイグレーションコードの安全性を確認するとき
• 既存のデータベーススキーマをリファクタリングするとき
• クエリパターンやデータベースパフォーマンスを最適化するとき

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

優先度	カテゴリ	影響度	プレフィックス
1	インデックス管理	CRITICAL-HIGH	only-concurrent-indexes、verify-query-patterns-are-indexed
2	制約の安全性	HIGH	unique-constraint、split-foreign-key、change-column-type
3	最適化	MEDIUM	split-check-constraint、limit-non-unique-index
4	インデックスの効率性	LOW	ensure-index-not-covered

クイックリファレンス

• only-concurrent-indexes - インデックス操作では常に postgresql_concurrently=True を自動コミットブロックと併用します
• verify-query-patterns-are-indexed - SQLAlchemy クエリに適切なインデックスが定義されていることを確認します
• unique-constraint - 一意制約の作成を、並行インデックスの作成と制約の追加のステップに分けます
• split-foreign-key - 外部キーをまず NOT VALID で追加し、その後、別途検証します
• change-column-type - テーブルロックを避けるため、複数ステップでカラムの型を変更します
• split-check-constraint - チェック制約をまず NOT VALID で追加し、その後、別途検証します
• limit-non-unique-index - 効率性のため、非一意インデックスのカラム数を最大3つに制限します
• ensure-index-not-covered - 複合インデックスですでにカバーされている冗長なインデックスを防ぎます

使用方法

詳しい説明とコード例については、個々のルールファイルを読んでください。

rules/only-concurrent-indexes.md
rules/verify-query-patterns-are-indexed.md
rules/unique-constraint.md
rules/split-foreign-key.md
rules/change-column-type.md
rules/split-check-constraint.md
rules/limit-non-unique-index.md
rules/ensure-index-not-covered.md

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 影響度とその説明
• 説明付きの不適切な SQLAlchemy/Alembic の例
• ベストプラクティスに基づく適切な実装
• 安全なマイグレーションのための追加情報