これはデータベースのバージョン管理と database-as-code (GitOps) を扱うシリーズ記事です。
- データベースバージョン管理
- データベースバージョン管理、State ベースか Migration ベースか？
- Database as Code — 良いところ、悪いところ、見たくないところ
- Database as Code のランドスケープ
- データベースバージョン管理のベストプラクティス (本記事)
データベースバージョン管理とは、データベーススキーマと関連データの変更を時系列で管理・追跡する運用です。なぜベストプラクティスが大切なのか。リスクの低減、コラボレーションの向上、データの監査可能性の担保のためです。
GitOps と組み合わせたスクリプト派でも、GUI ベースのツール派でも、肝心なのは信頼でき、再現可能で、監査可能なプロセスを確立することです。本ガイドでは両方のアプローチを念頭に、ベストプラクティスを順に紹介します。
1. State ベースより Migration ベースを選ぶ
Migration ベースか State ベースか — まず最初に決めるべき大きな選択です。
- Migration ベース: ステップごとの変更を明示的に書く (例:
add_user_table.sql)。Flyway、Liquibase などスクリプトベースのワークフローでも、Bytebase のような GUI ツールでも相性が良い。 - State ベース: 望ましい最終状態を定義し、ツールが差分を計算する。代表例は SQL Server の DACPAC。
詳しくは データベースバージョン管理、State ベースか Migration ベースか？ を参照してください。
2. すべての成果物をバージョン管理する
スクリプトベースのアプローチを採るなら、テーブル、プロシージャ、ビュー、シードデータをすべて SQL ファイルとしてバージョン管理にチェックインしましょう。権限やロール、リソースの定義も忘れずに。
GUI ベースのツールでは、データベース関連のチケットをすべてそのツールの UI または API 経由で作成する必要があります (Jira や Linear など別のチケットシステムからトリガーしても構いません)。決して直接データベースに変更を入れないでください。検知できない問題を引き起こします。
3. アトミックなコミットを徹底する
1 マイグレーション = 1 つの論理的な変更。各変更はそれぞれ専用のマイグレーションファイルやチケットで追跡しましょう (例: テーブルの追加、カラムの変更)。デバッグ、レビュー、ロールバック、監査がシンプルになります。
4. テストと検証を自動化する
GUI ベースなら、Bytebase のようなツールが設定可能な SQL レビューと、影響行数を見積もるドライランプレビューを提供します。
スクリプトベースなら、CI/CD ツール (GitHub Actions、GitLab CI など) を使って、SQL Lint、構文チェック、命名規約チェックを行うデータベーステストツールを統合できます。
5. すべての変更にドキュメントを残す
スクリプトベースでは、各ファイルの先頭にコメントを追加し、Jira/GitHub/GitLab の Issue にリンクしましょう。GUI ベースでは詳細なコメントを書きます。コンプライアンスとナレッジ共有の両面で役立ちます。
6. 承認を強制する
スクリプトベースでは、GitHub/GitLab/Azure DevOps のプルリクエストでコードレビューを強制できます。
Bytebase のような GUI ツールは、リスクに応じて自動でマッチする承認フローを提供します。操作内容、対象データベースに応じてリスクレベルをカスタマイズし、承認戦略を指定できます。
7. 明確なステージング戦略を持つ
スクリプトベースではトランクベース開発を採用し、データベース変更はフィーチャーブランチで作業して PR でマージしましょう。
GUI ベースでは、Bytebase が環境ベースのマルチステージワークフローを提供します。dev → staging → production と段階的に変更を進められます。
8. ロールバックを計画する
スクリプトベースでは、各マイグレーションに対応する xxxx_down.sql を用意するか、後方互換な SQL を維持しましょう。
Bytebase のような GUI ツールには、ワンクリックロールバックが組み込まれています。
9. 機微なデータを保護する
スクリプトベースではシークレットをハードコードせず、環境変数や HashiCorp Vault、AWS Secrets Manager などのシークレット管理ツールを使いましょう。GUI ベースでは、ツール固有のシークレット注入機能やマネージドクレデンシャルストアを活用してください。
10. すべての変更を記録・監査する
スクリプトベースでは、スキーマバージョンを確認し、失敗したマイグレーションをアラートにします。Bytebase のような GUI ツールでは、各マイグレーションごとの変更履歴と監査ログがそのまま備わっています。
まとめ
| ベストプラクティス | スクリプトベース | GUI ベース |
|---|---|---|
| State ベースより Migration ベースを選ぶ | SQL ファイルでステップごとの変更を定義する (例: Flyway、Liquibase、Bytebase) | Bytebase でマイグレーションを管理する |
| すべての成果物をバージョン管理する | データベースオブジェクト (テーブル、プロシージャ、ビュー、権限) をすべて SQL ファイルとしてチェックインする | すべての変更をツールの UI または API 経由で作成し、システムを迂回しない |
| アトミックなコミットを徹底する | 1 つの論理変更につき 1 つのマイグレーションファイル | 1 つの論理変更につき 1 つのチケット |
| テストと検証を自動化する | CI/CD パイプラインで SQL Lint や構文チェックを統合する | Bytebase が SQL レビューとドライランを内蔵 |
| すべての変更にドキュメントを残す | マイグレーションファイルにコメントを追加し、Issue トラッカーへリンクする | ツールの UI 上で詳細なコメントを書く |
| 承認を強制する | Git プラットフォームのプルリクエストレビューを使う | Bytebase でリスクベースの承認ワークフローを設定する |
| 明確なステージング戦略を持つ | フィーチャーブランチを使ったトランクベース開発 | 環境ベースのマルチステージワークフロー (dev → staging → prod) を活用 |
| ロールバックを計画する | 対応する down マイグレーションや後方互換な変更を用意する | Bytebase がワンクリックロールバックを内蔵 |
| 機微なデータを保護する | 環境変数やシークレット管理ツールを使う | ツール固有のシークレット注入やマネージドクレデンシャルストアを活用する |
| すべての変更を記録・監査する | スキーマバージョンを監視し、失敗したマイグレーションをアラートにする | Bytebase が変更履歴と監査ログを内蔵 |
GitOps と組み合わせたスクリプトでマイグレーションを管理しても、UI をクリックして進めても、データベース変更管理の鍵は一貫性です。
GUI ツールはオンボーディングを早め、人為ミスを減らし、ガードレールが組み込まれていることが多いです。
スクリプトベースのワークフローは、柔軟性、透明性、Git ネイティブな操作を提供します。
ベストプラクティスは何か。チームのスキルセット、ツール、成熟度に合った道を 1 つ選ぶこと。そのうえで、すべての変更がバージョン管理され、テストされ、レビューされ、追跡可能であることを徹底しましょう。
そして忘れずに、金曜にプッシュしないこと。