存在した問題

MySQL Server がオフライン (メンテナンス) モードになり、クライアント接続が突然拒否され、一般的なエラー ER_SERVER_OFFLINE_MODE: “The server is currently in offline mode” が表示されることがあります。

たとえば管理者がシステム変数 offline_mode を設定したとか、グループ・レプリケーション・ノードの問題やクラウド・インスタンスのディスク容量の低下などによって、意図的あるいは自動的にこのモードが有効になります。

このエラーの根本原因を見つけるには、管理者がサーバーマシンに接続し、エラーログから可能性のある手がかりを探し出さなければなりません。また、例えばサーバーをオフラインモードにしたプラグインやコンポーネントが、このアクションに対して明確なログエントリーを追加していない場合、エラーログは役に立たない可能性もあります。ただただ、サーバーが突然使い勝手の悪いモードで動作しているということだけがわかり、なぜだろうと不思議に思うかもしれません。

私たちは、この問題の原因をもっとよく伝える必要があると認識しています。そこで、オフラインモードが設定された理由や変更を行ったユーザアカウントをサーバに添付する手段を追加しました。

この記事で紹介する改善は MySQL 9.0 から導入され、この仕組みはクライアントが使用する MySQL プロトコル（クラシックまたは X プロトコル）に関係なく機能します。これは MySQL Community Edition と Enterprise Edition、および HeatWave のいずれもで使えます。

解決法

この改良により、グローバルシステム変数の値が変更されたときにに、キー/バリュー属性をアタッチする汎用オプションが追加されました。

紹介する使用例では、システムをオフラインモードに設定するたびに “offline_mode” システム変数に “reason” 属性をアタッチするよう、MySQLコードをインストルメント化しました。この “reason” 属性は、システムをオフラインモードにした理由を説明するテキスト断片で、エラーメッセージを追加情報で充実させるために使うことができます。

これらの変更を受けて、オフラインモードが設定されるとシステムは3つのエラーから選択するようになりました。この選択条件は、”offline_mode” システム変数の “reason” 属性が存在するかどうか、そして “offline” 変数が変更されたときのユーザーとタイムスタンプのデータが存在するかに依存しています。

システム変数がSQL（SET GLOBAL offline_mode=’ON’）によって変更された場合は、”reason” 属性は付与されません。

 

簡単にまとめると、システムは以下の優先順で最も冗長なエラーを選択するようになりました：

  • ER_SERVER_OFFLINE_MODE_REASON
    (“reason” 属性が存在する場合),
    エラー例文:
    The server is currently in offline mode since 2024-03-18 07:47:36.000581, reason: (GR) autorejoin failed
  • ER_SERVER_OFFLINE_MODE_USER
    (“reason” は与えられていないが、ユーザ情報はある場合),
    エラー例文:
    The server is currently in offline mode since 2024-03-18 08:38:29.146141, set by user db_admin
  • ER_SERVER_OFFLINE_MODE
    (従来通り、コンテクスト情報が存在しない場合), example:
    The server is currently in offline mode

例

例1: グローバルシステム変数 “offline_mode” をONに設定することで発生する ER_SERVER_OFFLINE_MODE_USER エラー

例1

例2: コマンドラインパラメータで –offline_mode=ON をつけてサーバーを起動したことで発生する ER_SERVER_OFFLINE_MODE エラー

 

例2

例3: は、テストコンポーネントの関数を用いてグローバルシステム変数 “offline_mode” をONに設定し、その “reason” 属性に文字列値を設定して発生する ER_SERVER_OFFLINE_MODE_REASON エラー

例3

まとめ

サーバーがオフラインモードになった理由を知ることで、ユーザーは接続エラーのトラブルシューティングをより迅速に行え、サポートチームの負荷を軽減できます。

導入された解決法は、任意のシステム変数に任意の属性を追加する汎用的な仕組みであり、将来的には、例えば観測可能性のために使ったりもできます。この仕組みを独自の目的で使用することに興味のあるコンポーネント開発者は、こちらのドキュメントを参照してください。

この仕組みは、MySQL Community EditionおよびEnterprise Edition、そしてHeatWaveで利用可能です。

よりよい MySQL ライフを！