異なる種類のDBにプリザンターのデータを移行する手順
## 概要
[CodeDefiner](https://pleasanter.org/ja/manual/faq-codedefiner-about)を使用して異なる種類のDBにプリザンターのデータを移行する手順です。
下図で示す通り、プリザンターのサーバを新規構築する際、既に稼働している別のプリザンターのサーバからDBの全データを移行し、同じ状態のプリザンターを構築することが可能です。ID値が移行元DBと同一のものとなりますので、移行先DBにプリザンターのデータを事前に登録しておくことはできません。（移行先DBにデータが登録されていると、データの移行処理が一意制約違反エラーで失敗します。）
※同じ種類のDB間でデータ移行を行う場合は、本手順ではなく、バックアップ・リストア手順を実施してください。
・SQL Server：[異なる環境にプリザンターのデータベース(SQL Server)を移行する手順](migrate-to-other-environment-pleasanter-net5)を参照
・PostgreSQL：[FAQ：PostgreSQL データベース バックアップ・リストア手順](faq-postgresql-backup-restore)を参照
・MySQL：[FAQ：MySQL データベース バックアップ・リストア手順](faq-mysql-backup-restore)を参照
## 制限事項
1. 下表のとおり、移行可能なデータベースの種類に制限がございます。
|移行元|移行先|本手順の使用可否|備考|
|:--|:--|:--|:--|
|SQL Server|PostgreSQL|可| - |
|SQL Server|MySQL|可| バージョン1.4.12.0以前のプリザンターでは、移行できません |
|PostgreSQL|SQL Server|不可| - |
|PostgreSQL|MySQL|不可| - |
|MySQL|SQL Server|不可| - |
|MySQL|PostgreSQL|不可| - |
2. 格納可能な最大文字数の違い等、DB毎の仕様の違いにより、データ移行中にエラーが生じる可能性がございます。本手順を本番環境で実施いただく前にリハーサルを実施し、エラーデータの有無やリカバリ手順を確認した上で、本番環境の作業を実施してください。
3. 数百メガバイト単位の添付ファイル等の大容量データは、移行時処理中にプログラムの許容範囲オーバーでエラーとなる可能性がございます。
4. 数憶文字単位の大容量の文字列データは、移行時処理中にプログラムの許容範囲オーバーでエラーとなる可能性がございます。
## 前提条件
1. 本手順を進めていく中でパラメータファイルに記述するDB接続情報について、移行元DBの情報を[Migration.json](/ja/manual/Migration-json)に、移行先DBの情報を[Rds.json](/ja/manual/rds-json)に記載します。[Rds.json](/ja/manual/rds-json)は同じ設定をプリザンターの起動以降も使用します。[Migration.json](/ja/manual/Migration-json)に記載する移行元DBの情報は本手順の移行処理以外では使用しませんので、セキュリティの観点より移行完了後は"SourceConnectionString"をnullに更新してください。
## 事前準備
### 1. 移行元DBの確認
1. 移行元プリザンターが移行先プリザンターと同じバージョンになるように、必要に応じてバージョンアップします。本手順では、移行元DBと移行先DBのテーブル定義を一致させる必要があるため、両者が同一バージョンになるように調整してください。
※移行元プリザンターのバージョンを先行させてしまうと、定義不足によりデータ移行ができなくなりますので、ご遠慮ください。
2. 移行元DBの接続情報はこの後の手順で[Migration.json](/ja/manual/Migration-json)に記載します。必要に応じて移行元DBの[Rds.json](/ja/manual/rds-json)および[Service.json](/ja/manual/service-json)の内容をご確認ください。
3. 移行元DBが移行先のプリザンターから見て外部のサーバにある場合は、移行元DBに外部からの接続を許可する設定が必要です。必要に応じて設定してください。
### 2. プリザンターのセットアップ（前半部）
セットアップマニュアルの手順を途中まで実施します。
### 2-a. Windowsにインストールする場合
・[インストーラでプリザンターをWindowsにインストールする](getting-started-installer-pleasanter-windows)
・[プリザンターをWindowsにインストールする](getting-started-pleasanter-windows)
上記いずれかの手順でプリザンターを新規セットアップする場合、以下セットアップ手順（途中まで）を行います。
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの先頭から順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ 事前準備
□ （インストーラの場合）インストーラのインストール
□ プリザンターのセットアップ
※「CodeDefinerの実行」「IISのセットアップ」「プリザンターの動作確認」は実施しないでください。
</details>
### 2-b. インストーラでLinuxにインストールする場合
・[インストーラでプリザンターを Ubuntu にインストールする](getting-started-installer-pleasanter-ubuntu)
・[インストーラでプリザンターを AlmaLinux にインストールする](getting-started-installer-pleasanter-almalinux)
・[インストーラでプリザンターを Red Hat Enterprise Linux 8 にインストールする](getting-started-installer-pleasanter-rhel-8)
・[インストーラでプリザンターを Red Hat Enterprise Linux 9 にインストールする](getting-started-installer-pleasanter-rhel9)
上記いずれかの手順でプリザンターを新規セットアップする場合、以下セットアップ手順（途中まで）を行います。
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの先頭から順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ .NETのセットアップ
□ データベースのセットアップ
□ インストーラのインストール
□ プリザンターのセットアップの「インストーラの実行」
※「プリザンターの起動確認」以降は実施しないでください。
</details>
### 2-c. インストーラを使用せずLinuxにインストールする場合
・[プリザンターを Ubuntu にインストールする](getting-started-pleasanter-ubuntu)
・[プリザンターを AlmaLinux にインストールする](getting-started-pleasanter-almalinux)
・[プリザンターを Red Hat Enterprise Linux 8 にインストールする](getting-started-pleasanter-rhel-8)
・[プリザンターを Red Hat Enterprise Linux 9 にインストールする](getting-started-pleasanter-rhel)
上記いずれかの手順でプリザンターを新規セットアップする場合、以下セットアップ手順（途中まで）を行います。
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの先頭から順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ .NETのセットアップ
□ データベースのセットアップ
□ プリザンターのセットアップの「アプリケーションの準備」と「データベースの構成」
※「CodeDefinerの実行」以降は実施しないでください。
</details>
### 2-d. Dockerを使用する場合
・[Dockerイメージを使用しパラメータを既定値から変更して起動する](change-parameters-at-docker-image)
・[Dockerイメージを使用しDBにMySQLを指定して起動する](setup-by-docker-image-and-mysql)
上記いずれかの手順でプリザンターを新規セットアップする場合、以下セットアップ手順（途中まで）を行います。
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの先頭から順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ ファイル配置
※「コンテナイメージのビルド」以降は実施しないでください。
</details>
## DB移行の流れ
1. [Migration.json](/ja/manual/Migration-json)の変更
2. CodeDefinerをmigrateモードで実行
3. [Migration.json](/ja/manual/Migration-json)の変更
4. プリザンターのセットアップ（後半部）
5. （移行がエラーで中止した場合）エラーログの確認
## 1. [Migration.json](/ja/manual/Migration-json)の変更
移行元DBの情報等を記載します。
[Migration.json](/ja/manual/Migration-json)のマニュアルを確認の上、バージョンに沿った内容で記載してください。
**Dockerでプリザンターを起動する場合**
[Migration.json](/ja/manual/Migration-json)を含むパラメータファイルの変更後、以下コマンドを実行し、コンテナイメージをビルドします。
```
docker compose build
```
## 2. CodeDefinerをmigrateモードで実行
以下フローチャート結果に応じて、引数 /l および /z の引数の設定有無を確認してください。
**〈フローチャート〉**
1. 質問：プリザンターのインストーラを実行しましたか？（※）
当てはまる場合は、「2-a. 引数 /l および /z を指定しないコマンド」を実行してください。
2. 質問：インストーラなし、かつ、バージョンver.1.4.6以降ですか？
当てはまる場合は、「2-b. 引数 /l および /z を指定するコマンド」を実行してください。
3. それ以外の場合は、「2-a. 引数 /l および /z を指定しないコマンド」を実行してください。
※Dockerを使用する場合は「インストーラなし」と判断してください。
### 2-a. 引数 /l および /z を指定しないコマンド
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
#### Windowsの場合
コマンドプロンプトで以下コマンドを実行します。
```
cd {Implem.CodeDefinerのパス}
dotnet Implem.CodeDefiner.dll migrate
```
#### Linuxの場合
ターミナルで以下コマンドを実行します。
```
cd {Implem.CodeDefinerのパス}
sudo -u {Linuxユーザ名} /usr/local/bin/dotnet Implem.CodeDefiner.dll migrate
```
#### Dockerの場合
docker compose runを実行します。
```
docker compose run --rm codedefiner mingate
```
</details>
### 2-b. 引数 /l および /z を指定するコマンド
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
#### 引数 /l および /z について
以下コマンドは日本語環境をセットアップする例です。
|引数|設定例|説明|
|:--|:--|:--|
|/l|ja|Service.jsonのDefaultLanguageの値を書き換えます(※1)|
|/z|Asia/Tokyo|Service.jsonのTimeZoneDefaultの値を書き換えます(※1) |
※1：/l に指定する言語、および、/zに指定するタイムゾーンについては、以下マニュアルページを参照ください。
[FAQ：プリザンターでサポートしている言語とタイムゾーンのパラメータの設定値を知りたい](https://pleasanter.org/manual/faq-supported-language)
#### Windowsの場合
コマンドプロンプトで以下コマンドを実行します。
```
cd {Implem.CodeDefinerのパス}
dotnet Implem.CodeDefiner.dll migrate /l "ja" /z "Tokyo Standard Time"
```
#### Linuxの場合
ターミナルで以下コマンドを実行します。
```
cd {Implem.CodeDefinerのパス}
sudo -u {Linuxユーザ名} /usr/local/bin/dotnet Implem.CodeDefiner.dll migrate /l "ja" /z "Asia/Tokyo"
```
#### Dockerの場合
docker compose runを実行します。
```
docker compose run --rm codedefiner mingate /l "ja" /z "Asia/Tokyo"
```
</details>
### 開始時メッセージ
開始時に以下メッセージが表示されます。
「y」キー、「Enter」キーの順序で押下し、処理を先に進めてください。
``` text
Type "y" (yes) if the license is correct, otherwise type "n" (no).
|
```
### 移行処理の流れ
処理は2ステップ実行されます。
1. 移行先DBに、Implem.Pleasanterデータベースおよびデータのない空のテーブルを作成する処理
2. 移行元DBから移行先へデータを移行する処理
※注意：データ量およびデータサイズによっては、上記2. の移行処理が終了するまで時間を要する場合があります。
### 移行が終了すると、画面上のメッセージの末尾に以下が表示されます。
``` text
<SUCCESS> Starter.MigrateDatabase: The migration is complete.
<SUCCESS> Starter.Main: All of the processes have been completed
```
メッセージの表示後、以下手順を実施してください。
**・3. [Migration.json](/ja/manual/Migration-json)の変更**
**・4. プリザンターのセットアップ（後半部）**
### 移行中にエラーが発生すると、画面上のメッセージの末尾に以下が表示されます。
・バージョン1.4.13.0以降かつ[Migration.json](/ja/manual/Migration-json)の"AbortWhenException" = trueの場合
``` text
<ERROR>システムのエラーメッセージ
～システムのエラーメッセージの終端
Abort. Press any key to close.
```
・バージョン1.4.13.0以降かつ[Migration.json](/ja/manual/Migration-json)の"AbortWhenException" = falseの場合
``` text
<ERROR> Starter.MigrateDatabase: The migration process was completed, but some data encountered errors. See {ファイルパス}.
<ERROR> Starter.Main: There were {<ERROR>の件数} errors. Please check the log file ({ファイルパス}).
```
・バージョン1.4.12.0以前の場合
``` text
<ERROR> Starter.Main: There were {<ERROR>の件数} errors. Please check the log file ({ファイルパス}).
```
メッセージの表示後、以下手順を実施してください。
**・3. [Migration.json](/ja/manual/Migration-json)の変更**
**・5. （移行がエラーで中止した場合）エラーログの確認**
※「4. プリザンターのセットアップ（後半部）」は移行先データベースでプリザンターを起動する手順のため、エラーのリカバリが完了するまで実施しないでください。
## 3. [Migration.json](/ja/manual/Migration-json)の変更
[Migration.json](/ja/manual/Migration-json)の「SourceConnectionString」には移行元DBの接続情報が記載されています。[Migration.json](/ja/manual/Migration-json)は、前述の「2. CodeDefinerをmigrateモードで実行」におけるコマンド実行以外では使用しませんので、実行後すみやかにnullに変更してください。
```
"SourceConnectionString": null,
```
## 4. プリザンターのセットアップ（後半部）
事前準備「2. プリザンターのセットアップ（前半部）」以降の、セットアップ残手順を最後まで実施します。
### 4-a. Windowsにインストールする場合
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの最後まで順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ IISのセットアップ
□ プリザンターの起動確認
※「CodeDefinerの実行」は実施しないでください。
</details>
### 4-b. インストーラでLinuxにインストールする場合
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの最後まで順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ プリザンターのセットアップの「プリザンターの起動確認」「Pleasanterサービス用スクリプトの作成」「サービスとして登録・サービスの起動」
□ リバースプロキシ(nginx)のセットアップ
□ プリザンターの動作確認
</details>
### 4-c. インストーラを使用せずLinuxにインストールする場合
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの最後まで順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ プリザンターのセットアップの「プリザンターの起動確認」「Pleasanterサービス用スクリプトの作成」「サービスとして登録・サービスの起動」
□ リバースプロキシ(nginx)のセットアップ
□ プリザンターの動作確認
※「CodeDefinerの実行」は実施しないでください。
</details>
### 4-d. Dockerを使用する場合
<details>
<summary>（こちらをクリックすると詳細が開閉します） </summary>
各マニュアルの最後まで順序通りに、以下チェックリストの手順を実施します。
**〈セットアップ手順チェックリスト〉**
□ プリザンター起動
※「CodeDefinerの実行」は実施しないでください。
</details>
## 5. （移行がエラーで中止した場合）エラーログの確認
「2. CodeDefinerをmigrateモードで実行」の後、CodeDefiner標準ログと、エラーデータ一覧ログの2種類、ログファイルが作成されます。
・ログファイルの格納先：{Implem.CodeDefinerのパス}/logs
1. CodeDefiner標準ログファイル：「Implem.CodeDefiner_{年月日}_{時分秒}.log」
2. エラーデータ一覧ログファイル：「Implem.CodeDefiner_{年月日}_{時分秒}._Migratelog」（バージョン1.4.13.0以降の場合に作成されます）
### CodeDefiner標準ログファイル
CodeDefinerの実行時に表示されたメッセージと同一のログが記録されます。
バージョン1.4.12.0以前の場合は、CodeDefiner標準ログファイルの内容からエラーが発生したテーブルを判断してください。
### エラーデータ一覧ログファイル
バージョン1.4.13.0以降の場合に作成されます。
テーブル単位のエラー情報、または、データ単位のエラー情報が記録されます。
**テーブル単位のエラー**
発生原因：主に接続エラーです。外部的な原因や、移行元DBのデータ量が大きくプログラム内で保持しきれなかった場合等に発生します。
・例
``` text
[ERROR] Table:"Binaries" System.Data.SqlClient.SqlException caught.
```
・Table：原因のテーブル名
・処理中にエラーを検知したテーブルの情報のみ出力します。
・エラー発生後、該当テーブル内のデータの移行がスキップされた可能性があります。
※必ず移行前後のテーブル（**_historyと_deletedを含む**）を比較し、状況を確認してください。
**データ単位のエラー**
発生原因：該当データのINSERT用SQL処理中のエラーです。作業ミスによる一意制約違反や、データサイズが大きすぎる場合等に発生します。
・例
```
[ERROR] Table:"Binaries" Data:"BinaryId"=999, "TenantId"=999, "ReferenceId"=999, "Guid"=ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ, "Ver"=1, "BinaryType"=Attachments, "Title"=Attachment.zip, "Body"=, "Bin"=System.Byte[], "Thumbnail"=, "Icon"=, "FileName"=Attachment.zip, "Extension"=.zip, "Size"=999, "ContentType"=application/x-zip-compressed, "BinarySettings"=, "Comments"=, "Creator"=999, "Updator"=999, "CreatedTime"=2025/01/01 12:00:00.000, "UpdatedTime"=2025/01/01 12:00:00.000
```
・Table：原因のテーブル名
・Data：原因のデータ内容
・INSERT用SQL処理でエラーを検知したデータの情報のみ出力します。
※必ず移行前後のテーブル（**_historyと_deletedを含む**）を比較し、状況を確認してください。
**リカバリ手順**
1. ログ内容からエラーが検知されたテーブルを把握
2. 該当テーブル（**_historyと_deletedを含む**）の移行前後のDB内容を比較
3. 移行されなかったデータの確認
4. リカバリ作業の実施。詳細は、後述のFAQを参照してください。
## FAQ
### Q1. 移行対象外のDBの組み合わせを[Migration.json](/ja/manual/Migration-json)および[Rds.json](/ja/manual/rds-json)に記載することはできないのでしょうか？
バージョン1.4.13.0以降、パラメータをチェックするようになったため、指定可能な内容以外を記述した場合はCodeDefinerの起動エラーとなり、DB移行ができません。
Migration.json
・Dbmsは "SQLServer" のみ指定可能です。
・Providerは "Local" のみ指定可能です。
Rds.json
・Dbmsは "PostgreSQL"、"MySQL" のいずれかのみ指定可能です。
・Providerは "Local" のみ指定可能です。
バージョン1.4.12.0以前の場合、SQL ServerからPostgreSQLへ移行する組み合わせ以外は想定されていません。万が一各パラメータファイルの接続情報に対象外のDBの情報を記述して実行した場合、システムが想定していないエラーの原因になりますので、ご遠慮ください。
### Q2. DBへの接続エラーとみられるエラーを検知しました。設定に問題があるのでしょうか？
以下の原因が考えられます。
1. 移行先DBに関する[Rds.json](/ja/manual/rds-json)のミス
2. 移行先DBの設定ミス（外部参照設定やファイアウォール等）
3. 移行元DBに関する[Migration.json](/ja/manual/Migration-json)のミス
4. 移行元DBの設定ミス（外部参照設定やファイアウォール等）
上記1. および2. は、CodeDefinerの処理開始直後に検知されます。
上記3. および4. は、移行先DBの設定に問題がない場合、Implem.Pleasanterサービス作成処理の終了後、移行処理の開始時に検知されます。
移行前後のどちらのDBへの接続でエラーになったか、上記の基準で判断の上、設定を見直してください。
### Q3. 移行先DBへのImplem.Pleasanterサービス作成処理までは正常に実行されましたが、データ移行処理の最初に接続エラーで終了しました。移行元DBの接続情報を修正して再度移行処理を行う際、移行先DBに作成されたImplem.Pleasanterは削除が必要ですか？
削除は不要です。
「2. CodeDefinerをmigrateモードで実行」と同じコマンドを再実行してください。前回作成された空のImplem.Pleasanterサービスをそのまま使用し、移行します。
「Type "y" (yes) if the license is correct, otherwise type "n" (no).」の確認メッセージが表示された際も、同様に「y」「Enter」キーを押下してください。
### Q4. 移行に失敗したデータの修復方法を教えてください。（移行元DBで原因データを修正し、全移行処理をやり直す場合）
エラーデータの件数が多い場合に有効です。
1. 移行前後のDB内容を比較し（_historyと_deletedを含む）、移行されなかったデータを確認
2. 移行されなかったデータについて、移行前DBの各カラム内容を確認
3. CodeDefiner標準ログに出力されたメッセージや、移行先DBの列定義と上記2. の内容を比較して、前回INSERT処理のエラー原因を判断
4. 移行前DBにおいて、移行エラーになったデータの原因箇所をすべて修正
※データベースクライアントを使用しUPDATE文を実行する方法、または、プリザンターを起動して修正する方法の2通りがある。文章形式のデータはUPDATE文で修正して問題ないケースが多いが、JSON形式やバイナリファイルはプリザンター上で修正することが望ましい。
5.移行先DBにデータベースクライアントを使用して接続し、DROP DATABASE文でImplem.Pleasanterサービスを削除
6. 本マニュアルの移行手順を再実施
### Q5. 移行に失敗したデータの修復方法を教えてください。（移行後DBを維持したまま、移行に失敗したデータをひとつずつ登録する場合）
エラーデータの件数が少ない場合に有効です。
1. 移行前後のDB内容を比較し（_historyと_deletedを含む）、移行されなかったデータを確認
2. 移行されなかったデータについて、移行前DBの各カラム内容を確認
3. CodeDefiner標準ログに出力されたメッセージや、移行先DBの列定義と上記2. の内容を比較して、前回INSERT処理のエラー原因を判断
4. INSERT文を記述。その際、上記3. で確認したエラー原因の値を修正
5. 移行先DBにデータベースクライアントを使用して接続し、上記4. で記述したINSERT文を実行
6. 移行が必要なすべてのデータについて2. ～5.を実施
### Q6. MySQLへの移行処理中に以下エラーメッセージが表示されました。「max_allowed_packet」の数値は変更できますか？
**「MySqlConnector.MySqlException (0x80004005): Error submitting 100MB packet; ensure 'max_allowed_packet' is greater than 100MB.」**
（※100MBの部分は環境により異なります。）
MySQLサーバの「max_allowed_packet」の数値を大きく設定することで、エラーが解消される可能性がございます。
・参考：[MySQL :: MySQL 8.4 Reference Manual :: B.3.2.8 Packet Too Large](https://dev.mysql.com/doc/refman/8.4/en/packet-too-large.html)
「max_allowed_packet」が記述されているMySQL設定ファイルの配備先は環境によって異なります。
MySQL設定ファイルの修正後は、MySQLのサービス再起動を実施してください。
### Q7. ログのエラーデータ一覧に表示されていない内容があるようです。ログファイルに問題がありますか？
ログファイル出力の仕様により、1024文字を超えるデータの超過分やJSON形式のデータは、ログファイルに出力されません。移行元データの正確な内容は、データベースクライアントソフトや、データベースクライアントのコマンドを使用して確認してください。
## 対応バージョン
|対応バージョン|内容|
|:--|:--|
| - |プリザンターのDBをSQL ServerからPostgreSQLへ移行する機能の初期公開|
|1.4.13.0 以降|プリザンターのDBをSQL ServerからMySQLに移行する機能の追加|
## 関連項目
<div id="ManualList"><ul><li><a href="/ja/manual/Migration-json">パラメータ設定：Migration.json</a><span>2025/02/12 up</span></li>
<li><a href="/ja/manual/rds-json">パラメータ設定：Rds.json</a><span>2024/11/07 up</span></li>
<li><a href="/ja/manual/service-json">パラメータ設定：Service.json</a><span>2024/12/12 up</span></li></ul></article></div><input id="SearchTextHidden" type="hidden" value="" />
