Safely Enable a MariaDB Plugin with mysql_plugin

You will prepare a MariaDB plugin configuration, inspect the paths that mysql_plugin will use, and understand the controlled point at which it writes the plugin registry. The command is installed here as MariaDB 10.11.14 from the mariadb-client package. Allow about 15 minutes for an already-installed plugin, plus a maintenance window if you need to stop the database server.

This guide uses mysql_plugin, which is now a symlink to mariadb-plugin. You need a shell, a plugin library already installed in the server's plugin directory, and administrator access to the MariaDB data directory. The examples use names such as myplugins and plugin1 as placeholders. Do not enable them until they describe a real library on your host.

1. Confirm the installed command

Start with read-only checks. No elevated privileges are needed for these commands:

$ command -v mysql_plugin
/usr/bin/mysql_plugin
$ readlink -f /usr/bin/mysql_plugin
/usr/bin/mariadb-plugin
$ mysql_plugin --version
mysql_plugin  Ver 1.0.0 Distrib 10.11.14-MariaDB

The command's synopsis is mysql_plugin [options] <plugin> ENABLE|DISABLE. The action word is not case-sensitive, and the two positional arguments may be placed in either order. The plugin value names a plugin library base name, not an individual component.

2. Inspect the plugin files and defaults

For a library called myplugins, the default configuration file is myplugins.ini in the server plugin directory. The first line names the library without its platform suffix. Later lines name the components managed by this file. A line whose first character is # is a comment.

# /path/to/plugin-dir/myplugins.ini
myplugins
plugin1
plugin2

Do not add .so to the first line. On Linux the corresponding library is normally named myplugins.so. The exact directory and component names are installation-specific, so verify them from the package or plugin documentation before editing the file.

When the configuration is in the normal option-file setup, ask the command to print the recognised defaults without changing anything:

$ mysql_plugin --print-defaults
# output is host-specific; values are shown only when configured

This option reports only basedir, datadir and plugin-dir values found in the option file. Relative names passed with --plugin-ini are resolved from the current directory, which is an easy source of mistakes.

3. Make the server state safe to change

Check the service state using your system's service manager. On a systemd host, this is read-only:

$ systemctl is-active mariadb
active
$ sudo systemctl stop mariadb
$ systemctl is-active mariadb
inactive

The sudo commands require elevated privileges. If the service has another name, use that name instead. Do not run the plugin operation while the first check still says active; the bootstrap operation can fail or interfere with the running server.

4. Enable the configured components

Run the operation as the account that can read the data directory and start the server in bootstrap mode. If that is root on your installation, use sudo:

$ sudo mysql_plugin --plugin-dir=/path/to/plugin-dir myplugins ENABLE
mysql_plugin: enabling plugins from myplugins.ini

The exact verbose messages depend on the installation. A successful command returns to the shell without an error. If your configuration file is elsewhere, give its path explicitly:

$ sudo mysql_plugin --plugin-dir=/path/to/plugin-dir \
    --plugin-ini=/path/to/myplugins.ini myplugins ENABLE

Use --datadir=/path/to/data or --basedir=/path/to/server when the command cannot discover the server installation from its option files. The option-file [mysqld] group is consulted for basedir, datadir and plugin-dir; other values in that group are ignored by this utility.

5. Start MariaDB and verify the result

Start the service again through its normal manager:

$ sudo systemctl start mariadb
$ systemctl is-active mariadb
active

Then verify the plugin from a MariaDB client session. Replace the placeholder component name with one that is actually listed in the ini file:

$ mariadb -NBe "SELECT name, dl, status FROM information_schema.plugins WHERE name = 'plugin1';"
plugin1	myplugins.so	ACTIVE

The result format and status are produced by the server, not by mysql_plugin. If no row appears, check the library name, component name and server error log. A row with a non-active status needs investigation before an application relies on the plugin.

6. Undo a mistaken registry change

Disabling a plugin is the reverse operation, but it has the same stop-server requirement and may break features that use it. Schedule the change, stop MariaDB, run DISABLE with the same plugin and configuration file, then start and verify:

$ sudo systemctl stop mariadb
$ sudo mysql_plugin --plugin-dir=/path/to/plugin-dir myplugins DISABLE
$ sudo systemctl start mariadb

If the server does not start after a change, stop retrying the application. Read the MariaDB service log, restore the last known-good plugin configuration, and use the opposite registry action only when the library and data directory are correct. Keep a copy of the ini file and record the old service state before maintenance so recovery is deliberate rather than improvised.