データベース変更に関する JiHu ガイドライン

データベース変更に関する JiHu ガイドライン

データベースマイグレーション（PostgreSQL 向け）を含む JiHu コントリビューションには、2つの方法を検討できます：

1. 完全アップストリーム方式：コード変更をデータベースマイグレーションも含めて GitLab にアップストリームにコントリビューションする
2. マイグレーションのみアップストリーム方式：コード変更なしでデータベースマイグレーションのみをアップストリームにコントリビューションする（例：JiHu 独自機能の場合）

以下は（2）についてのガイドラインと背景説明です：関連するコード変更なしでデータベースマイグレーションのみをアップストリームにコントリビューションする方法。

コード変更も含めて完全にアップストリームにコントリビューションされる変更については、GitLab の通常のコントリビューションワークフローに従うため、以下は適用されません。

スキーマ変更

構造変更については、すべてのデータベースマイグレーションをアップストリームプロジェクトに送ることを選択しています。GitLab CE/EE と JiHu リリース間のアップグレードパスを容易にするため、GitLab と JiHu 間でデータベーススキーマをまったく同じに保つことを意図しています。

これは GitLab CE/EE に対してすでに適用しているパターンの拡張です：両エディションに対して1つのデータベーススキーマしかありません。

JiHu 固有のデータベースオブジェクト（カラム、テーブル、インデックスなど）には、PostgreSQL コメントでアノテーションを付与します。これにより、通常の GitLab 環境でのオブジェクトの関連性について把握しやすくなり（JiHu 固有のカラムは無視できるなど）、そのオブジェクトが存在する理由（GitLab でそれを使うコードがない場合でも）を明確にすることができます。 詳細については gitlab-org/database-team/team-tasks#192 をご参照ください。

以下のケースを区別します：

カラムの追加

JiHu コントリビューションは既存の GitLab テーブルにカラムを追加する場合があります。ただし、これらのカラムは GitLab コードベースでは使用されません。明確にするため、以下の措置を取ります：

1. カラムが JiHu 固有であることを示すために PostgreSQL コメントでアノテーションを付与する。
2. アノテーションに基づき、通常の GitLab 環境では ActiveRecord に JiHu 固有のカラムを公開しない。JiHu 環境ではこれがオフになる。
3. 追加されるカラムは nullable（NULL）またはデフォルト値のある not-null（NOT NULL DEFAULT x）のみ設定可能

テーブル/ビューの追加

JiHu コントリビューションで新しいテーブルを追加する場合、テーブルが JiHu 固有であることを示すために PostgreSQL コメントでアノテーションを付与します。通常の GitLab 環境では ActiveRecord モデルを通じてこれらのテーブルが使用されないようにする措置を取ります。

既存のテーブルに外部キーを追加することは問題ありません。ただし、既存の GitLab テーブルへの外部キーには、カスケード削除が引き続き機能するよう ON DELETE 句を付与する必要があります。これは GitLab と JiHu 間（およびその逆）のマイグレーションをサポートするために特に重要であり、残留データが ON DELETE 句なしではカスケード削除を壊してしまう可能性があります。

インデックスの追加

JiHu 固有テーブルへのインデックスは、追加の考慮なしに追加できます。

GitLab テーブル上の JiHu 固有カラムにインデックスを追加するには、GitLab でのサイズを削減するため、インデックスを部分インデックスに変換する必要があります。例：

CREATE INDEX user_details_phone ON user_details (phone_number) WHERE phone_number IS NOT NULL

既存の GitLab カラムへのインデックスの追加は、ケースバイケースでデータベースグループのレビューが必要です。

いずれの場合も、インデックスが JiHu 固有であることを示すために PostgreSQL コメントでアノテーションを付与します。

任意：GitLab.com でのオーバーヘッドを軽減するため、JiHu 固有のインデックスの作成を無視することも選択できます。

追加オブジェクト

トリガー、関数、拡張など他の種類のデータベースオブジェクトは、ケースバイケースでデータベースグループのレビューが必要です。

データマイグレーション

既存データを変更するマイグレーションも、アップストリームプロジェクトにマージされます。ただし、通常の GitLab 環境（特に GitLab.com）で JiHu 固有のデータマイグレーションが実行されないようにしたいと考えています。

JiHu 固有のデータマイグレーション（バックグラウンドマイグレーションを含む）は JiHu 環境のみを対象とすることが推奨され、標準のデータベースレビュープロセスを経る必要があります。

GitLab と JiHu 間の切り替え

GitLab と JiHu 間でまったく同じスキーマを使用することで、GitLab から JiHu への切り替えがシームレスになります。

ただし、JiHu から GitLab への切り替えのセマンティクスはまだ定義されていないことを認識しています。同じデータベーススキーマを使用するため GitLab に戻すことは技術的には可能ですが、その状況で既存の JiHu 固有データをどう扱うかはまだ決定していません。GitLab に戻った後は、JiHu 固有データを維持するコードがなくなります。これは、インストールが後で JiHu に戻される場合などに制約違反や不整合なデータを引き起こす可能性があります。

トレードオフ/議論

このパターンには以下の欠点があることを認識しています（緩和策も記載）：

代替案：JiHu 固有マイグレーション（未採用）

JiHu 固有マイグレーションを別途保持する代替アプローチを検討しました。

JiHu はアップストリームプロジェクトにマージされない JiHu 固有マイグレーションを可能にするメカニズムを実装したい場合があります。これにより、GitLab CE/EE と JiHu エディション間のさまざまなアップグレードパスをサポートする複雑さが増す代わりに、データベース変更においてより柔軟性と自律性が得られます。GitLab と JiHu のマイグレーション間で時間の経過とともにGit タイムラインのような競合が生じる可能性がある（issue #161 の例参照）ため、JiHu は GitLab からサポートされる各アップグレードパスに対して特定のスキーママイグレーションを提供する必要があります。

より迅速なターンアラウンド、低い複雑性、GitLab と JiHu 間のシームレスな切り替えを可能にするため、現時点ではこのオプションを採用しませんでした。

GitLab チームメンバーによるデータベースレビューの考慮事項

関連するコード変更なしにデータベースマイグレーションを含む変更をレビューすることは、データベースレビュアーとメンテナーにとって難しいことが証明されています。 GitLab レビュアーがより詳細にコンテキストを理解できるよう、データベースレビューを依頼する前に関連するコード変更の準備とレビューを完了するようにお願いしています。 関連するコード変更は、有用な背景情報とともにマージリクエストからリンクされる必要があります。

それ以外は、データベースレビュー用マージリクエストの準備方法に記載されている同じプロセスに従います。

フォークからデータベースマイグレーションを含むマージリクエストを送る

フォークからマージリクエストを作成する際のレビュー効率を高めるため、フォークプロジェクトで DANGER_GITLAB_API_TOKEN を設定することをお勧めします。これにより、レビューに役立つ情報の中から関連するレビュアーを提案する Danger を実行できるようになります。

質問は？

質問やサポートについてはデータベースグループにお問い合わせください。

ページのソースコードを見る - ページの編集 - please contribute.