Installing plugins in the MariaDB Docker Library Container
MariaDB plugins are software components that may be added to the core software without the need to rebuild the MariaDB Server. Plugins can be storage engines, additional security requirements, special log information about the server and others. MariaDB has a large number of built-in plugins which are permanently installed (listed in
SHOW PLUGINS query). Plugins can be loaded at start-up, during initialization, or loaded dynamically when the server is running.
In this blog we are going to see how to list available plugins in the MariaDB container as well as the methods of installing plugins in a container. At the end we are going to create a Dockerfile in order to build a custom image with a plugin not installed in the container image.
MariaDB Foundation maintains the official docker library images of MariaDB Server on dockerhub. You will see that most of the commands reference those images.
Initial startup of the MariaDB container
On first startup of the MariaDB container, the server needs to be configured with a database user that can connect to it. By default, this user is called
root and the server will not start if one of:
MARIADB_RANDOM_ROOT_PASSWORD environment variables is not set.
There are also additional variables that allow the creation of a second user and also granting it rights on only one database. These are:
MARIADB_USERspecifying the name of the user
MARIADB_PASSWORDthe password to be used for the
MARIADB_DATABASEThe database that
MARIADB_USERwill have access to. The database will be created as well.
We recommend you make use of these variables and do not rely on simply using the
root user for all access. In this blog post, whenever we need to start-up the server, we’ll be using these environment variables. You can read more about other available variables in the official dockerhub docs, search for “environment variables”.
For further information please take a look into MariaDB Container cheat sheet.
Available plugins in the MariaDB container
MariaDB Server package comes already with some available plugins and these are present by default in the mariadb container. In the container, the plugin files (ending in .so) are located in the directory
/usr/lib/mysql/plugin. The server system variable plugin_dir is by default set to the same folder and it controls where the server looks for plugins.
We can list the available plugins by listing the directory within the container:
$ docker run --rm mariadb:latest ls -C /usr/lib/mysql/plugin auth_ed25519.so ha_blackhole.so query_cache_info.so auth_pam.so ha_federated.so query_response_time.so auth_pam_tool_dir ha_federatedx.so server_audit.so auth_pam_v1.so ha_sphinx.so simple_password_check.so disks.so handlersocket.so sql_errlog.so file_key_management.so locales.so type_mysql_json.so ha_archive.so metadata_lock_info.so wsrep_info.so
--rm flag to make sure no container is left on the system once we’re done executing the
Enabling a plugin in the MariaDB container
In order for MariaDB plugins to be used, the server must have them installed (more specifically loaded within the server) and then enabled. There are built-in plugins that are enabled by default and can not be uninstalled. Other plugins need to be installed within the server. Simply having the
.so file present in the plugin directory is not enough. There are multiple possible ways to install and enable plugins. We’ll explore four different ways to achieve this.
- Enabling a plugin with a command line option
- Enabling a plugin with a configuration file option
- Enabling a plugin in
- Build a new image containing a plugin using Dockerfile (for plugins that do not come installed in the container by default)
1. Enabling a plugin with a command line option
You can pass command line options to the docker entrypoint script, which eventually starts the
mariadbd binary (the Server). To load a plugin, we can use the option plugin-load-add. We use this method for one of our available plugins that are not installed by default:
$ docker run -d \ --env MARIADB_USER=anel \ --env MARIADB_PASSWORD='$coMp"|lex99password' \ --env MARIADB_DATABASE=web_users \ --env MARIADB_RANDOM_ROOT_PASSWORD=1 \ --name mariadb-server \ mariadb:latest --plugin-load-add=simple_password_check
We can check for the presence of
simple_password_check by connecting with
mariadb client to the container and running running
SHOW PLUGINS SONAME LIKE 'simple_password%'.
$ docker exec mariadb-server mariadb -u anel -p'$coMp"|lex99password' -e "SHOW PLUGINS SONAME LIKE 'simple_password%'\G" *************************** 1. row *************************** Name: simple_password_check Status: ACTIVE Type: PASSWORD VALIDATION Library: simple_password_check.so License: GPL
And here we see that the plugin is present and ACTIVE.
Before we jump into the next option, let’s stop the container and remove the reference to its name.
$ docker stop mariadb-server && docker rm mariadb-server
2. Enabling a plugin using an extra config file
Instead of passing in command line parameters to
mariadbd, which can quickly get out of hand, a better approach is to have the plugin specified in a config file. As an example, let’s install the FederatedX plugin. First let’s create a config directory and a config file to instruct the server to install the plugin.
$ mkdir my_container_config/ $ printf "[mariadb]\nplugin-load-add=ha_federatedx\n" > my_container_config/my_container.conf
We can pass this file to the container as a volume, in the special
/etc/mysql/conf.d directory. Files in this directory are read and appended to the default server configuration, on server startup.
$ docker run -d \ --env MARIADB_USER=anel \ --env MARIADB_PASSWORD='$coMp"|lex99password' \ --env MARIADB_DATABASE=web_users \ --env MARIADB_RANDOM_ROOT_PASSWORD=1 \ --volume $PWD/my_container_config:/etc/mysql/conf.d:z \ --name mariadb-server \ mariadb:latest
We can check for the presence of
ha_federatedx like we did for
$ docker exec mariadb-server mariadb -u anel -p'$coMp"|lex99password' -e "SHOW PLUGINS SONAME LIKE 'ha_federatedx%'\G" *************************** 1. row *************************** Name: FEDERATED Status: NOT INSTALLED Type: STORAGE ENGINE Library: ha_federatedx.so License: GPL
And again, remember to cleanup.
$ docker stop mariadb-server && docker rm mariadb-server
3. Enabling a plugin during first database initialization
Another container startup hook that we can use is the
/docker-entrypoint-initdb.d folder. This folder contains SQL scripts that are run when the container is initially created. They can be used to set up a custom database schema. We will be using it to install the
disks plugin by running
INSTALL SONAME. First, let’s create the database init folder and the sql script.
$ mkdir my_initdb/ $ printf 'INSTALL SONAME "disks";\n' > my_initdb/disks.sql
On startup with pass this directory as the /docker-entrypoint-init.d volume.
$ docker run -d \ --env MARIADB_USER=anel \ --env MARIADB_PASSWORD='$coMp"|lex99password' \ --env MARIADB_DATABASE=web_users \ --env MARIADB_RANDOM_ROOT_PASSWORD=1 \ --volume $PWD/my_initdb:/docker-entrypoint-initdb.d:z \ --name mariadb-server \ mariadb:latest
Note: Usually one is passing a /var/lib/mysql volume as well. This will only have an effect if there is no database already initialized.
$ docker exec -it mariadb-server mariadb -u anel -p'$coMp"|lex99password' -e "SHOW PLUGINS SONAME LIKE 'disks%'\G" *************************** 1. row *************************** Name: DISKS Status: ACTIVE Type: INFORMATION SCHEMA Library: disks.so License: GPL
4. Build a new image containing an additional plugin using a Dockerfile
Some plugins are not installed in the container by default because they contain additional dependencies. An example of this is the CONNECT storage engine. Instead we need to install it from the package
We use the layer approach of container images to create a new container image based on mariadb, in this case, using a Dockerfile.
Example of a Dockerfile
FROM mariadb:latest LABEL maintainer="firstname.lastname@example.org" RUN apt-get -y update && \ apt-get install mariadb-plugin-connect -y && \ rm -rf /var/lib/apt/lists/*
In order to build the image from Dockerfile run:
$ docker build -t mariadb_connect . -f my_connect_plugin.dockerfile
We can see from the generated image,
mariadb_connect, that the CONNECT storage engine is configured to load by a configuration file. This was installed from the
$ docker run --rm mariadb_connect cat /etc/mysql/mariadb.conf.d/connect.cnf [mariadb] plugin-load-add=ha_connect.so
Once built, we can use the
mariadb_connect image like the original
mariadb container image.
For more information see Creating a custom Docker image.
Conclusion and future work
In this blog we learned how to startup MariaDB in a container and various ways how to install plugins within the Docker Library MariaDB Container. We showed how to use configuration files and volumes in your container instances.
In the next blog we are going to use the image built from Dockerfile in order to do some work with the CONNECT Storage Engine. I have compiled a cheat sheet that covers the most frequent commands we’ll be using over the course of these tutorials.
As always, feedback is welcome! If you come across any problems when running any of these commands let us know in comments. You are welcome to chat about it on Zulip too! Any bugs you find should be reported in JIRA, in the MDEV project.