MySQLバージョンアップグレード後のKopanoデータベース移行エラーを修正する

MySQLまたはMariaDBのバージョンアップグレード直後にKopanoのデータベース移行エラーが発生する場合、通常はアプリケーションとデータベースの間で、以前は暗黙的だった何らかの事柄（スキーマの状態、サーバーのデフォルト設定、SQLの動作、認証、あるいはアップグレードパス自体など）について合意が得られなくなったことを意味しますkopano-server。重要なのは、単に一度起動させることではなく、スキーマが整合し、データベースアップグレードエラーなしでKopanoが起動し、ユーザーがストアを開くことができ、再起動後もメールフローが正常に機能する状態に到達することです。

このガイドでは、証拠を重視します。各段階には成功の兆候と、同じ解決策を試み続けるのをやめて方向転換すべきポイントが含まれています。Kopanoの公開管理者向けドキュメントは、現在のMySQLおよびMariaDBのリリースよりも古いため、すべての最新のデータベースバージョンがすべての過去のKopanoビルドでサポートされているとは限りません。決定的な証拠として、正確なKopanoパッケージバージョン、データベースベンダー、およびサーバーエラーを使用してください。

必要な結果から始めましょう

設定を変更する前に、「修正済み」の意味を明確に定義してください。正常な復旧には通常、以下の兆候がすべて見られます。

• kopano-serverサービス再起動後も起動し、動作を継続する。
• Kopanoのログには、データベーススキーマのアップグレードやSQL実行の失敗に関するエラーは報告されなくなりました。
• 設定されたKopanoアカウントは、データベースの読み書きが可能です。
• 新規に作成された空のスキーマではなく、既存のストアとユーザーが表示されます。
• 郵便物の発送と配達は通常通り再開されます。
• 2回目の再起動でも、同様に良好な結果が得られた。

最初の項目しか達成できなかった場合は、テストを続けてください。sql_modeたとえば、変更後に一時的に動作を開始したとしても、基となるスキーマが正しいことを証明するものではありません。

1. Kopanoライターを停止し、復元可能なデータベースバックアップを取得します。

Kopano のアップグレードに関するドキュメントでは、アップグレード作業の前にデータベースと構成ファイルをバックアップし、データベースを使用するサービスを停止することを推奨しています。ドキュメントでは特に、および、さらに実行中のオプションのコンポーネントを停止するように指示していますkopano-spooler。Kopano kopano-serverCoreのアップグレードに関するドキュメントを参照してください。

sudo systemctl stop kopano-spooler
sudo systemctl stop kopano-server

mysqldump -u root -p --single-transaction kopano > /root/kopano-before-fix.sql
ls -lh /root/kopano-before-fix.sql

大規模なインストールの場合、/etc/kopano/添付ファイルの保存場所も保存し、既存のデータベースバックアップポリシーに従ってください。添付ファイルがMySQL以外の場所に保存されている場合、SQLダンプだけではKopanoの完全なバックアップにはなりません。

スキーマやサーバー設定を変更する前に、データベースに書き込みを行うKopanoサービスを停止し、最新のダンプファイルが存在することを確認してください。

成功シグナル：別のデータベースインスタンスに復元可能なバックアップがあり、外部添付ファイルの保存場所がわかっている場合。ダンプ自体が失敗した場合、アプローチを変更してください。 Kopanoスキーマ移行を試みる前に、データベースの破損、権限、ディスク容量、または接続性を修正してください。

2. 正確なデータベースバージョンと変更されたデフォルト値を記録する

MySQLのメジャーアップグレードでは、既存のテーブルを変更せずにサーバーのデフォルト設定を変更できます。たとえば、MySQL 8.0では、デフォルトのサーバー文字セットが にutf8mb4、デフォルトの照合順序が にutf8mb4_0900_ai_ci変更されました。また、その他のデフォルト設定も変更され、古い動作が削除または非推奨になりました。Oracleは、これらの変更点について「MySQL 8.0の変更点」で説明しています。

パッケージのアップグレードによって何が起こったかを推測するのではなく、実際のサーバーの状態を把握してください。

mysql -u root -p

SELECT VERSION();
SHOW VARIABLES LIKE 'sql_mode';
SHOW VARIABLES LIKE 'character_set_server';
SHOW VARIABLES LIKE 'collation_server';

Kopanoが現在認識しているデータベースのバージョンとデフォルト値を記録してください。これらの値は、データベースのアップグレード後にのみ発生した障害の原因を特定するのに役立ちます。

厳密なSQLモードをすぐに無効にしないでください。厳密モードでのエラーは、修正が必要な無効なレガシーデータやSQLを明らかにする可能性があります。厳密モードをオフにすると、症状が隠蔽され、後で問題が発生するデータが残ってしまう可能性があります。まず、Kopanoのログから、エラーが発生したステートメントまたはデータベースエラーを正確に取得してください。

3. 最終的なサービス障害だけでなく、最初のSQLエラーも読み取ってください。

Systemd は終了したというメッセージのみを表示することがよくありますkopano-server。有用な行は通常、ジャーナルまたは Kopano ログのより前の部分にあります。以下から始めてください。

journalctl -u kopano-server -n 100 --no-pager

次に、障害を分類します。以下の表は、あらゆる設置状況に共通する単一の原因を示すものではなく、実用的なトリアージマップです。

Kopanoの変更履歴には、特定の操作を必要とするスキーマ変更が導入されたリリースがあることが記載されていますkopano-dbadm。また、古いMySQLテーブル定義やutf8mb4のアップグレードに関連する不具合など、過去のデータベースアップグレードの不具合も記録されています。Kopano Coreの変更履歴を参照して、ご使用のKopanoリリースに合ったメンテナンス作業を確認してください。

4. 既存のKopanoスキーマと新しいサーバーのデフォルト設定を比較する

既存のスキーマを確認してください。サーバーのデフォルト設定だけでは、Kopanoテーブルがいつ定義されたかはわかりません。

SHOW CREATE DATABASE kopano;
SHOW TABLE STATUS FROM kopano;

既存のKopanoデータベース定義とストレージエンジンを検査すると同時に、比較のために元の移行エラーを表示したままにしておきます。

データベースが元々古いバージョンのMySQLで作成されていた場合、新しく作成されたオブジェクトのデフォルトがutf8mb4になったとしても、テーブルには古い文字セットが残っている可能性があります。MySQLは、5.7から8.0へのアップグレードでは、既存のデータベースオブジェクトが新しいデフォルト文字セットに自動的に変換されないことを明示的に述べています。この点は重要です。新しい列やインデックスが、隣接するオブジェクトとは異なるデフォルト値で作成されると、移行が失敗する可能性があるからです。

Kopano自体は後のCoreリリースでutf8mb4のサポートを追加し、既存のデータベースを4バイトUnicodeに対応させるための特定のデータベースメンテナンス手順を文書化しましたkopano-dbadm usmp。MySQLがデフォルトでutf8mb4を使用するようになったからといって、このコマンドを実行しないでください。インストール済みのKopanoリリースのドキュメントまたはサーバー出力で指示されている場合にのみ実行してください。

5. MariaDBをアップグレードした場合は、まずMariaDB側のアップグレードを完了してください。

バックエンドがOracle MySQLではなくMariaDBの場合は、Kopanoを責める前に、データベースサーバー自身のアップグレード手順を完了させてください。MariaDBのドキュメントには、mariadb-upgradeシステムテーブルを更新し、メジャーバージョン変更後にテーブルをチェックするツールとして記載されています。ドキュメントでは、まずすべてのデータベースをバックアップすることを推奨しています。公式のmariadb-upgradeリファレンスを参照してください。

これは分岐コマンドであり、汎用コマンドではありません。Oracle mariadb-upgradeMySQLに対しては実行しないでください。逆に、両方ともクライアントプロトコルを受け入れるという理由だけで、MySQL 8.0の前提をMariaDBサーバーに適用しないでくださいmysql。

6. Kopanoデータベースアカウントに必要な権限がまだ付与されていることを確認します。

Kopano の管理者マニュアルには、サーバーには Kopano データベースに対するALTER、CREATE、CREATE ROUTINE、DELETE、DROP、INDEX、INSERT、LOCK TABLES、SELECTなどの権限が必要であると記載されていますUPDATE。データベース接続パラメータは、 の MySQL 関連設定で構成します/etc/kopano/server.cfg。KCコンポーネントの構成を参照してください。

MySQLのバージョン移行後、管理者はユーザーの再作成、認証プラグインの変更、データベースホストの移動、または権限の不完全な復元を行う場合があります。Kopanoが使用するホスト名とアカウントと同じものを使用してテストしてください。移行SQLが実行される前に認証が失敗した場合は、まずアカウントまたは権限の問題を修正してください。

7. エラーによって証明された状態のみを修復する

この時点で、具体的な障害クラスが1つあるはずです。それを説明できる最小限の変更を適用してください。

• Kopanoスキーマの部分的な更新：インストールされているバージョンで指定されているリリース固有のKopanoアップグレード手順またはkopano-dbadm指示に従ってください。次のステートメントを実行するためだけに、バージョンマーカーを削除したり、列を手動で追加したりしないでください。
• 文字セットまたは照合順序の不一致：まず、影響を受けるテーブルと列を特定してください。文字セットの変更はインデックスのサイズや比較動作に影響を与える可能性があるため、本番環境に手を加える前に、復元されたコピーに対して変換計画を立ててください。
• MariaDBのシステムテーブルの不一致：ドキュメントに記載されているMariaDBのアップグレード手順を完了してから、Kopanoを再試行してください。
• 権限または認証： Kopano DBアカウントを修正し、Kopanoホストからのログインを確認してください。
• サポートされていないバージョン組み合わせです。設定実験を中止してください。アップグレード前のデータベース環境に戻すか、ベンダーまたはパッケージソースがサポートするKopano/データベースの組み合わせに移行してください。

最後のケースは重要です。公開されているKopano Coreの管理者マニュアルは旧世代の製品に関するものであり、一方、最新のMySQLおよびMariaDBのリリースは継続的に変更されています。ご使用の組み合わせに関するサポート情報が見つからない場合でも、ドキュメントがないことを互換性がないと解釈すべきではありません。

8. Kopanoを起動し、プロセス状態だけでなく、より多くの項目を検証する

sudo systemctl start kopano-server
sudo systemctl start kopano-spooler

systemctl --no-pager --full status kopano-server
journalctl -u kopano-server -n 50 --no-pager

正常なサービス状態は必要条件ではありますが、十分条件ではありません。起動ログを確認し、ユーザーストアとメールフローを検証してください。

サービスが安定稼働したら、実際のアプリケーションの動作でテストしてください。既存のメールボックスを少なくとも1つ開き、古いフォルダーとメッセージが存在することを確認し、2つのローカルアカウント間でメッセージを送信し、送信メッセージを1つ送信して、受信メールが正常に配信されることを確認してください。IMAP、ActiveSync、アーカイブ、マルチサーバーコンポーネント、または外部添付ファイルストレージを使用している場合は、それらの機能もテストしてください。

アプローチを変えるべきタイミングはいつですか？

以下のいずれかの条件が発生した場合は、スキーマ変更の繰り返しを停止してください。

• SQLエラーは手動で変更を加えるたびに変化するため、スキーマが部分的にしか移行されていないことが示唆されます。
• 復元されたアップグレード前のデータベースは、古いデータベースバージョンでは正常に動作しますが、新しいバージョンでは常に失敗します。
• お使いのKopanoビルドが、インストールされているMySQLまたはMariaDBのメジャーバージョンをサポートしているかどうかを確認できません。
• テーブルチェックでは、通常のスキーマの不適合ではなく、破損が報告されます。
• 文字セットの変換には、テスト済みのロールバックなしに多数の大きなテーブルを変更する必要がある。

このような場合、より安全な方法は、以前のデータベース環境を再現し、正常に動作することが確認されているバックアップを復元し、クローン環境で段階的なアップグレードを計画することです。Oracleは、MySQL 8.0から5.7へのダウングレードはインプレースではサポートされていないと述べています。サポートされている代替手段は、アップグレード前に取得したバックアップを復元することです。MySQL 8.0のリリースノートを参照してください。

最終確認チェックリスト

• データベースのバックアップとKopanoの設定バックアップは保存されます。
• MySQLまたはMariaDBの正確なバージョンが記録されます。
• 最初の実際のSQLエラーが特定され、説明されました。
• 証拠がない限り、広範なSQLモードや文字セットの回避策は適用されなかった。
• 必要なKopanoスキーマのメンテナンスは、インストールされているKopanoのリリースと一致している必要があります。
• kopano-server2回目の再起動にも耐える。
• 既存のメールボックス、フォルダ、メッセージはすべてそのまま残っています。
• 受信、送信、およびローカル配送のテストはすべて成功しました。
• お客様の環境で使用されているオプションコンポーネントはテスト済みです。

データベース移行の問題は、スキーマ、データベースサーバー、およびKopanoのバージョンが再び一致した時点で解決されます。エラーメッセージが消えただけでは解決しません。修復に至った経緯を記録しておいてください。それは、次回のデータベースまたはKopanoのアップグレードに必要な情報でもあります。