atlas-best-practices

Atlas のベストプラクティス

Atlas は宣言型とバージョン管理型のスキーマワークフローに対応しています。このファイルは最小限に保ち、現在のタスクに必要なリファレンスファイルだけを読み込んでください。

ワークフローの選択

• 目的のスキーマ状態を信頼できる情報源とする場合は、宣言型ワークフローを使用してください。
• 監査や段階的なデプロイのためにマイグレーションファイルが必要な場合は、バージョン管理型ワークフローを使用してください。
• 既存のデータベースを導入する場合は、ベースラインワークフローを使用してください。

デフォルトの実行フロー

1. atlas.hcl で対象の env を確認します。
2. dev が設定され、本番環境から分離されていることを確認します。
3. まず計画を立て、その後に lint、テスト、検証を行ってから適用します。
4. 本番環境への変更は、CI/CD または承認済みのデプロイワークフローを通じて実行します。

クイックコマンド

# Declarative
atlas schema apply --env local

# Versioned
atlas migrate diff add_change --env local
atlas migrate lint --env local --latest 1
atlas migrate apply --env local

# Integrity
atlas migrate validate --env local
atlas migrate status --env local

リファレンスマップ

• core-workflows.md 環境設定、コードとしてのスキーマのパターン、宣言型ワークフローとバージョン管理型ワークフローの使い分け、ベースライン設定、ORM プロバイダーの読み込みに使用します。
• safety-and-quality.md lint アナライザー、トランザクションモード、スキーマテスト、実行前チェック、CI のパターンに使用します。
• atlas-v1-1-features.md セキュリティ・アズ・コード、宣言型データ、新しいドライバーやプラットフォームへの対応、Slack 連携、スキーマエクスポーター、MySQL TLS など、2026-02-03 にリリースされた Atlas v1.1 の機能を確認する際に使用します。
• cli-agent-gaps.md 計画ワークフロー、マイグレーションディレクトリのメンテナンスコマンド、URL/TLS に関する落とし穴、機能の利用可否、バージョンポリシーの制約など、エージェントが見落としやすい Atlas CLI の機能やエッジケースを確認する際に使用します。

ガードレール

• ソースファイルに認証情報を含めないでください。Atlas のデータソースと入力変数を優先してください。
• 破壊的なマイグレーションやデータに依存するマイグレーションでは、明示的なレビューを必須にしてください。
• 対応していないドライバー、dev URL の欠落、不明な環境名がある場合は、明確にエラーとして失敗させてください。