MySQL 8.0 リファレンスマニュアル


MySQL 8.0 リファレンスマニュアル  /  ...  /  プラグインのインストールおよびアンインストール

5.6.1 プラグインのインストールおよびアンインストール

サーバープラグインは、使用する前にサーバーにロードする必要があります。 MySQL は、サーバーの起動時および実行時のプラグインのロードをサポートしています。 また、起動時にロードされたプラグインのアクティブ化状態を制御し、実行時にアンロードすることもできます。

プラグインがロードされている間は、セクション5.6.2「サーバープラグイン情報の取得」 で説明されているように、プラグインに関する情報を入手できます。

プラグインのインストール

サーバープラグインを使用する前に、次のいずれかの方法を使用してインストールする必要があります。 説明で、plugin_nameinnodbcsvvalidate_password などのプラグイン名を表します。

組込みプラグイン

組み込みプラグインは、サーバーによって自動的に認識されます。 デフォルトでは、サーバーは起動時にプラグインを有効にします。 一部の組み込みプラグインでは、これを --plugin_name[=activation_state]オプションで変更できます。

mysql.plugin システムテーブルに登録されているプラグイン

mysql.plugin システムテーブルは、プラグインのレジストリとして機能します (登録する必要のない組込みプラグイン以外)。 通常の起動シーケンスでは、サーバーはテーブルに登録されているプラグインをロードします。 デフォルトでは、mysql.plugin テーブルからロードされたプラグインの場合、サーバーはプラグインも有効にします。 これは、--plugin_name[=activation_state]オプションで変更できます。

サーバーが --skip-grant-tables オプションで起動された場合、mysql.plugin テーブルに登録されているプラグインはロードされず、使用できません。

コマンドラインオプションで指定されたプラグイン

プラグインライブラリファイルにあるプラグインは、サーバーの起動時に --plugin-load--plugin-load-add、または --early-plugin-load オプションを使用してロードできます。 通常、起動時にロードされたプラグインの場合、サーバーはプラグインも有効にします。 これは、--plugin_name[=activation_state]オプションで変更できます。

--plugin-load および --plugin-load-add オプションは、組み込みプラグインおよびストレージエンジンがサーバーの起動シーケンス中に初期化されたあとにプラグインをロードします。 --early-plugin-load オプションは、組み込みプラグインおよびストレージエンジンを初期化する前に使用可能である必要があるプラグインをロードするために使用されます。

各プラグインロードオプションの値は、name = plugin_library および plugin_library の値をセミコロンで区切ったリストです。 各 name はロードするプラグインの名前で、plugin_library はプラグインコードを含むライブラリファイルの名前です。 プラグイン名を前に付けずにプラグインライブラリを指定した場合、サーバーはライブラリ内のすべてのプラグインをロードします。 サーバーは、plugin_dir システム変数で指定されたディレクトリ内でプラグインライブラリファイルを検索します。

プラグインロードオプションでは、プラグインは mysql.plugin テーブルに登録されません。 その後の再起動では、--plugin-load--plugin-load-add または --early-plugin-load が再度指定された場合にのみ、サーバーはプラグインを再度ロードします。 つまり、このオプションを指定すると、単一サーバーの起動のために保持されるワンタイムプラグインのインストール操作が生成されます。

--plugin-load--plugin-load-add および --early-plugin-load を使用すると、--skip-grant-tables が指定されている場合でもプラグインをロードできます (これにより、サーバーは mysql.plugin テーブルを無視します)。--plugin-load--plugin-load-add および --early-plugin-load を使用すると、実行時にロードできないプラグインを起動時にロードすることもできます。

--plugin-load-add オプションは、--plugin-load オプションを補完します:

  • --plugin-load の各インスタンスは、起動時にロードするプラグインのセットをリセットしますが、--plugin-load-add は、現在のセットをリセットせずに、ロードするプラグインのセットにプラグインを追加します。 したがって、--plugin-load の複数のインスタンスが指定されている場合は、最後のインスタンスのみが有効になります。 --plugin-load-add の複数のインスタンスでは、それらはすべて有効になります。

  • 引数の形式は --plugin-load の場合と同じですが、--plugin-load-add の複数のインスタンスを使用して、多数のプラグインを単一の長いアンワイルディ --plugin-load 引数として指定しないようにできます。

  • --plugin-load-add--plugin-load がない場合でも指定できますが、--plugin-load がロードするプラグインのセットをリセットするため、--plugin-load より前に表示されていた --plugin-load-add のインスタンスは影響を受けません。

たとえば、次のオプションがあります:

--plugin-load=x --plugin-load-add=y

次のオプションと同等です:

--plugin-load-add=x --plugin-load-add=y

また、次のオプションと同等です:

--plugin-load="x;y"

ただし、次のオプションの場合、

--plugin-load-add=y --plugin-load=x

上記は次のオプションと同等です。

--plugin-load=x
INSTALL PLUGIN ステートメントでインストールされるプラグイン

プラグインライブラリファイルにあるプラグインは、実行時に INSTALL PLUGIN ステートメントを使用してロードできます。 このステートメントはさらにプラグインを mysql.plugin テーブルに登録し、その後再起動してサーバーからロードします。 このため、INSTALL PLUGIN には、mysql.plugin テーブルに対する INSERT 権限が必要です。

プラグインライブラリファイルのベース名は、プラットフォームによって異なります。 一般的な接尾辞は、.so for Unix および Unix のようなシステム、.dll for Windows です。

例: --plugin-load-add オプションは、サーバーの起動時にプラグインをインストールします。 somepluglib.so という名前のプラグインライブラリファイルから myplugin という名前のプラグインをインストールするには、my.cnf ファイルで次の行を使用します:

[mysqld]
plugin-load-add=myplugin=somepluglib.so

この場合、プラグインは mysql.plugin に登録されません。 --plugin-load-add オプションを指定せずにサーバーを再起動すると、起動時にプラグインがロードされません。

一方、INSTALL PLUGIN ステートメントでは、サーバーは起動時にライブラリファイルからプラグインコードをロードします。

INSTALL PLUGIN myplugin SONAME 'somepluglib.so';

INSTALL PLUGIN では、permanent プラグインの登録も行われます: プラグインは、その後の再起動時にサーバーがロードするように、mysql.plugin テーブルにリストされます。

多くのプラグインは、サーバーの起動時または実行時のいずれかにロードできます。 ただし、プラグインがサーバーの起動時にロードおよび初期化する必要があるように設計されている場合は、INSTALL PLUGIN を使用して実行時にロードしようとするとエラーが発生します:

mysql> INSTALL PLUGIN myplugin SONAME 'somepluglib.so';
ERROR 1721 (HY000): Plugin 'myplugin' is marked as not dynamically
installable. You have to stop the server to install it.

この場合、--plugin-load--plugin-load-add または --early-plugin-load を使用する必要があります。

プラグインの名前が mysql.plugin テーブルで --plugin-load--plugin-load-add、または --early-plugin-load オプションと (INSTALL PLUGIN ステートメントの以前の結果として) の両方を使用して指定されている場合、サーバーは起動しますが、これらのメッセージはエラーログに書き込まれます:

[ERROR] Function 'plugin_name' already exists
[Warning] Couldn't load plugin named 'plugin_name'
with soname 'plugin_object_file'.

プラグインのアクティブ化状態の制御

プラグインの起動時にサーバーがプラグインについて知っている場合 (たとえば、プラグインに --plugin-load-add オプションを使用して名前が付けられているか、mysql.plugin テーブルに登録されているため)、サーバーはデフォルトでプラグインをロードして有効にします。 このようなプラグインのアクティブ化状態は、--plugin_name[=activation_state]起動オプションを使用して制御できます。ここで、plugin_name は、innodbcsvvalidate_password など、影響を受けるプラグインの名前です。 ほかのオプションと同じように、オプション名のダッシュとアンダースコアは交換可能です。 また、アクティブ化状態の値では大文字と小文字は区別されません。 たとえば、--my_plugin=ON--my-plugin=on は同等です。

  • --plugin_name=OFF

    プラグインを無効にするようサーバーに指示します。 これは、mysql_native_password などの特定の組込みプラグインでは不可能な場合があります。

  • --plugin_name[=ON]

    プラグインを有効にするようサーバーに指示します。 (値を付けずにオプションを --plugin_name と指定しても効果は同じです。) プラグインが初期化に失敗した場合、サーバーはプラグインを無効にして実行します。

  • --plugin_name=FORCE

    プラグインを有効にするようサーバーに指示しますが、プラグインの初期化が失敗した場合、サーバーは開始しません。 つまり、このオプションはプラグインを有効にしてサーバーを実行するか、何もしないかのいずれかを強制します。

  • --plugin_name=FORCE_PLUS_PERMANENT

    FORCE と似ていますが、さらにプラグインが実行時にアンロードされないようにします。 ユーザーが UNINSTALL PLUGIN を使用してこの操作を実行しようとすると、エラーが発生します。

プラグインアクティブ化状態は、INFORMATION_SCHEMA.PLUGINS テーブルの LOAD_OPTION カラムに表示されます。

CSVBLACKHOLE および ARCHIVE が組込みのプラガブルなストレージエンジンであり、サーバーが起動時にそれらをロードする必要があるとします。条件は次のとおりです: CSV の初期化が失敗した場合、サーバーの実行が許可され、BLACKHOLE の初期化が成功する必要があり、ARCHIVE を無効にする必要があります。 これを満たすには、オプションファイル内で次の行を使用します。

[mysqld]
csv=ON
blackhole=FORCE
archive=OFF

--enable-plugin_name オプションの形式は、--plugin_name=ON のシノニムです。 --disable-plugin_name および --skip-plugin_name のオプション形式は、--plugin_name=OFF のシノニムです。

プラグインが OFF で明示的に無効化されているか、ON で有効化されていても初期化に失敗したために暗黙的に無効化されている場合、プラグインを変更する必要があるサーバー操作の側面。 たとえば、プラグインがストレージエンジンを実装している場合、ストレージエンジンの既存のテーブルにアクセスできなくなり、ストレージエンジンの新しいテーブルを作成しようとすると、代わりに NO_ENGINE_SUBSTITUTION SQL モードが有効になってエラーが発生しないかぎり、デフォルトのストレージエンジンを使用するテーブルになります。

プラグインの無効化は、ほかのオプションの調整を要することもあります。 たとえば、--skip-innodb を使用して InnoDB を無効にするためにサーバーを起動する場合、起動時に他の innodb_xxx オプションも省略する必要がある可能性があります。 また、InnoDB はデフォルトのストレージエンジンであるため、--default_storage_engine で別の使用可能なストレージエンジンを指定しないかぎり起動できません。 --default_tmp_storage_engine も設定する必要があります。

プラグインのアンインストール

実行時に、UNINSTALL PLUGIN ステートメントはサーバーに認識されているプラグインを無効にしてアンインストールします。 このステートメントは、プラグインをアンロードし、mysql.plugin システムテーブルに登録されている場合はそこから削除します。 このため、UNINSTALL PLUGIN ステートメントには、mysql.plugin テーブルに対する DELETE 権限が必要です。 プラグインがテーブルに登録されなくなったため、サーバーはその後の再起動時にプラグインをロードしません。

UNINSTALL PLUGIN では、プラグインが INSTALL PLUGIN を使用して実行時にロードされたか、プラグインロードオプションを使用して起動時にロードされたかに関係なく、次の条件に従ってプラグインをアンロードできます:

  • サーバーに組み込まれているプラグインをアンロードできません。 これらは INFORMATION_SCHEMA.PLUGINS または SHOW PLUGINS からの出力で、ライブラリ名が NULL のプラグインとして識別できます。

  • 実行時にプラグインをアンロードしないようにする --plugin_name=FORCE_PLUS_PERMANENT を使用すると、サーバーが開始された目的のプラグインをアンロードできません。 これらは INFORMATION_SCHEMA.PLUGINS テーブルの LOAD_OPTION カラムから識別できます。

サーバーの起動時にプラグインロードオプションを使用して現在ロードされているプラグインをアンインストールするには、この手順を使用します。

  1. プラグインに関連するオプションおよびシステム変数を my.cnf ファイルから削除します。 プラグインシステム変数が mysqld-auto.cnf ファイルに永続化されていた場合は、削除するプラグインごとに RESET PERSIST var_name を使用して削除します。

  2. サーバーを再起動します。

  3. プラグインは通常、起動時にプラグインロードオプションを使用するか、実行時に INSTALL PLUGIN とともにインストールされますが、両方を使用することはできません。 ただし、ある時点で INSTALL PLUGIN も使用されている場合は、プラグインのオプションを my.cnf ファイルから削除するだけではアンインストールできない可能性があります。 INFORMATION_SCHEMA.PLUGINS または SHOW PLUGINS からの出力にプラグインがまだ表示される場合は、UNINSTALL PLUGIN を使用して mysql.plugin テーブルからプラグインを削除します。 その後、サーバーを再起動します。

プラグインおよびユーザー定義関数

プラグインをインストールすると、関連するユーザー定義関数 (UDF) も自動的にインストールされる場合があります。 その場合、アンインストール時にプラグインによってそれらの UDF も自動的にアンインストールされます。


関連キーワード:  plugin, サーバー, load, ロード, 起動, テーブル, インストール, 実行, PLUGIN, 変数