#移行管理

#はじめに

移行管理プラグインは、アプリケーション設定をある環境（例：Staging）から別の環境（例：PROD）へ移行するために使用します。

主な違い：

• 移行管理： 特定のアプリケーション設定、データテーブル構造、または一部のデータの移行に重点を置いています。
• バックアップマネージャー： 全量データのバックアップと復元に重点を置いています。

#インストール

バックアップ管理 プラグインに依存しています。事前にインストールおよび有効化されていることをご確認ください。

#フローと仕組み

メインデータベースのデータテーブルおよびデータを、移行ルールに基づいてあるアプリケーションから別のアプリケーションへ移行します。外部データベースやサブアプリケーションのデータは移行されませんのでご注意ください。

#移行ルール

#組み込みルール

以下の 5 種類の移行ルールに対応しています：

• スキーマのみ： データテーブルの構造のみを同期し、データの挿入や更新は行いません。
• 上書き（クリアして再挿入）： 既存のテーブルレコードをクリアし、新しいデータを挿入します。
• 挿入または更新（Upsert）： 主キーに基づいて判断し、レコードが存在すれば更新、存在しなければ挿入します。
• 重複を無視して挿入： 新しいレコードを挿入しますが、主キーが競合する場合は無視します（既存レコードは更新されません）。
• スキップ： そのテーブルに対して何も処理を行いません。

補足：

• 上書き、挿入または更新、重複を無視して挿入でも、テーブル構造の変更は同期されます。
• 自動増分 ID を主キーとするテーブル、または主キーがないテーブルでは「挿入または更新」と「重複を無視して挿入」はサポートされません。

#詳細設計

#設定画面

移行ルールの設定

独立ルールの有効化

独立ルールおよび、その独立ルールで処理するデータテーブルの選択

#移行ファイル

#新規移行の作成

#移行の実行

#環境変数の検出

アプリケーション環境変数の検出（環境変数 について）

.env 内の DB_UNDERSCORED、USE_DB_SCHEMA_IN_SUBAPP、DB_TABLE_PREFIX、DB_SCHEMA、COLLECTION_MANAGER_SCHEMA が一致しない場合、移行を続行できないことを示すポップアップが表示されます。

動的に設定された環境変数またはシークレットが不足している場合、ポップアップが表示され、新たに追加が必要な環境変数やシークレットをここで入力してから続行するよう促されます。

#プラグインの検出

アプリケーションのプラグイン検出を行い、現在の環境にプラグインが不足している場合はポップアップが表示されます。この場合、移行を続行することも可能です。

#移行ログとストレージ

移行の実行後、サーバー上に実行ログファイルが保存され、オンラインで確認またはダウンロードできます。

実行ログファイルをオンラインで確認する際に、データ構造の移行時に実行された SQL もダウンロードできます。

「プロセス」ボタンをクリックすると、完了した移行の実行過程を確認できます。

#storage ディレクトリについて

移行管理は主にデータベースレコードを処理します。storage ディレクトリ内の一部のデータ（ログ、バックアップ履歴、リクエストログなど）は自動的には移行されません。

• 新しい環境でこれらのファイルを保持する必要がある場合は、storage ディレクトリ内の関連フォルダを手動でコピーしてください。

#ロールバック

移行を実行する前に、システムが自動的にバックアップを作成します。

#ロールバックの原則

1. サービスの停止： ロールバックを開始する前にアプリケーションを停止し、新しいデータの書き込みを防止します。
2. バージョンの一致： NocoBase のコアバージョン（Docker イメージ）はバックアップファイルが生成された時点のバージョンと一致している必要があります。
3. 新規環境での復元： 現在のデータベースやストレージが破損している場合、イメージバージョンの復元だけでは不十分な可能性があります。最も安全な方法は、正しいコアイメージを使用して新しいアプリケーションインスタンス（新しいデータベースとストレージ）でバックアップを復元することです。

#ロールバックフロー

#シーン A：移行タスクの実行が失敗した場合

移行タスクの実行でエラーが発生しただけでコアバージョンが変更されていない場合は、バックアップマネージャー を使用して、移行前に自動作成されたバックアップを直接復元してください。

#シーン B：システムの破損またはコアアップグレードの失敗

アップグレードや移行によりシステムが稼働できなくなった場合、安定した状態にロールバックする必要があります：

1. アプリケーションの停止： 現在のコンテナサービスを停止します。
2. 新規環境の準備： 新しい空のデータベースと空のストレージ環境を準備します。
3. ターゲットバージョンのデプロイ： Docker イメージタグをバックアップが生成された時点のバージョンに戻します。
4. バックアップの復元： このクリーンな環境で バックアップマネージャー を使用して復元を実行します。
5. トラフィックの切り替え： ゲートウェイ/ロードバランサーを更新し、復元済みの新しいインスタンスにトラフィックを向けます。

#コマンドライン

#yarn nocobase migration generate

Usage: nocobase migration generate [options]

Options:
  --title [title]    migration title
  --ruleId <ruleId>  migration rule id

例

yarn nocobase migration generate --ruleId=1

#yarn nocobase migration run

Usage: nocobase migration run [options] <filePath>

Arguments:
  filePath           migration file path

Options:
  --skip-backup      skip backup
  --var [var]        variable (default: [])
  --secret [secret]  secret (default: [])

例

yarn nocobase migration run /your/path/migration_1775658568158.nbdata \
  && --var A=a --var B=b \
  && --secret C=c --secret D=d

#ベストプラクティス

#推奨デプロイフロー（ブルーグリーン切り替え）

ゼロダウンタイムまたは極めて短いダウンタイムを実現し、最高の安全性を確保するために、デュアル環境切り替え方式を推奨します：

1. 準備段階（Staging）： Staging 環境で移行ファイルを作成します。
2. 安全なバックアップ（PROD-A）： 現在の本番環境（PROD-A）のフルバックアップを作成します。
3. 並行デプロイ（PROD-B）： ターゲットコアバージョンを使用して、新しい空のデータベースの本番インスタンス（PROD-B）をデプロイします。
4. 復元と移行：
   • PROD-A のバックアップを PROD-B に復元します。
   • PROD-B で Staging からの移行ファイルを実行します。
5. 検証： PROD-A がまだサービスを提供している間に、PROD-B を徹底的にテストします。
6. トラフィックの切り替え： Nginx/ゲートウェイを更新し、PROD-A から PROD-B にトラフィックを切り替えます。
   • 問題が発生した場合、即座に PROD-A に切り戻すことができます。

#データの一貫性とメンテナンス停止

現在、NocoBase はゼロダウンタイムでの移行をサポートしていません。バックアップや移行中のデータ不整合を回避するために：

• ゲートウェイ/エントリの停止： バックアップや移行を開始する前に、ユーザーアクセスを停止することを強く推奨します。Nginx またはゲートウェイで 503 メンテナンスページを設定し、システムがメンテナンス中であることをユーザーに通知するとともに、新しいデータの書き込みを防止できます。
• 手動データ同期： 移行中にユーザーが旧バージョンでデータを生成し続けた場合、そのデータは後から手動で同期する必要があります。