Skip to content

Commit

Permalink
mariadb docs update (#2080)
Browse files Browse the repository at this point in the history 
* mariadb: using --port

As mentioned in #2708 docs documenting how to change the port,
particular for host networking was requested.

The example in "configuration without a cnf file section" was
already the default anyway (utf8), so this was just replaced.

Using MARIADB_ROOT_PASSWORD in the example to move away from
MySQL naming (still supported however).

Closes: #2078

* mariadb: added support for .sql.zst in /docker-entrypoint-initdb.d

This was added a while ago in MariaDB/mariadb-docker#376

* mariadb: add Mariabackup (and restore) mechanism

gosu mysql -> --user mysql suggestion thanks @yosifkit

Closes: #MariaDB/mariadb-docker/issues/390

* mariadb: add password reset documentation

Closes: #MariaDB/mariadb-docker/issues/365

* mariadb: installing plugins

* Update mariadb/content.md

Co-authored-by: yosifkit <[email protected]>

* Update mariadb/content.md

Formatting on INSTALL SONAME

Co-authored-by: Tianon Gravi <[email protected]>

* Update mariadb/content.md

Compressed backup simplier

Co-authored-by: Tianon Gravi <[email protected]>

* Update mariadb/content.md

better use of apt-get arguments

Co-authored-by: Tianon Gravi <[email protected]>

Co-authored-by: yosifkit <[email protected]>
Co-authored-by: Tianon Gravi <[email protected]>
  • Loading branch information
@grooverdan @yosifkit @tianon
3 people authored Nov 25, 2021
1 parent 58d272a commit 37666d4
Showing 1 changed file with 150 additions and 3 deletions.
153 changes: 150 additions & 3 deletions mariadb/content.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,10 @@ This will start a new container `some-%%REPO%%` where the MariaDB instance uses

### Configuration without a `cnf` file

Many configuration options can be passed as flags to `mysqld`. This will give you the flexibility to customize the container without needing a `cnf` file. For example, if you want to change the default encoding and collation for all tables to use UTF-8 (`utf8mb4`) just run the following:
Many configuration options can be passed as flags to `mysqld`. This will give you the flexibility to customize the container without needing a `cnf` file. For example, if you want to run on port 3808 just run the following:

```console
$ docker run --name some-%%REPO%% -e MYSQL_ROOT_PASSWORD=my-secret-pw -d %%IMAGE%%:latest --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
$ docker run --name some-%%REPO%% -e MARIADB_ROOT_PASSWORD=my-secret-pw -d %%IMAGE%%:latest --port 3808
```

If you would like to see a complete list of available options, just run:
Expand Down Expand Up @@ -145,7 +145,7 @@ Currently, this is only supported for `MARIADB_ROOT_PASSWORD`, `MARIADB_ROOT_HOS

# Initializing a fresh instance

When a container is started for the first time, a new database with the specified name will be created and initialized with the provided configuration variables. Furthermore, it will execute files with extensions `.sh`, `.sql`, `.sql.gz`, and `.sql.xz` that are found in `/docker-entrypoint-initdb.d`. Files will be executed in alphabetical order. `.sh` files without file execute permission are sourced rather than executed. You can easily populate your `%%IMAGE%%` services by [mounting a SQL dump into that directory](https://docs.docker.com/engine/tutorials/dockervolumes/#mount-a-host-file-as-a-data-volume) and provide [custom images](https://docs.docker.com/reference/builder/) with contributed data. SQL files will be imported by default to the database specified by the `MARIADB_DATABASE` / `MYSQL_DATABASE` variable.
When a container is started for the first time, a new database with the specified name will be created and initialized with the provided configuration variables. Furthermore, it will execute files with extensions `.sh`, `.sql`, `.sql.gz`, `.sql.xz` and `.sql.zst` that are found in `/docker-entrypoint-initdb.d`. Files will be executed in alphabetical order. `.sh` files without file execute permission are sourced rather than executed. You can easily populate your `%%IMAGE%%` services by [mounting a SQL dump into that directory](https://docs.docker.com/engine/tutorials/dockervolumes/#mount-a-host-file-as-a-data-volume) and provide [custom images](https://docs.docker.com/reference/builder/) with contributed data. SQL files will be imported by default to the database specified by the `MARIADB_DATABASE` / `MYSQL_DATABASE` variable.

# Caveats

Expand Down Expand Up @@ -190,3 +190,150 @@ For restoring data. You can use the `docker exec` command with the `-i` flag, si
```console
$ docker exec -i some-%%REPO%% sh -c 'exec mysql -uroot -p"$MARIADB_ROOT_PASSWORD"' < /some/path/on/your/host/all-databases.sql
```

## Creating backups with Mariabackup

To perform a backup using Mariabackup, an additional volume for the backup needs to be included when the container is started like this:

```console
$ docker run --name some-%%REPO%% -v /my/own/datadir:/var/lib/mysql -v /my/own/backupdir:/backup -e MARIADB_ROOT_PASSWORD=my-secret-pw -d %%IMAGE%%:latest
```

Mariabackup will run as the `mysql` user in the container, so the permissions on `/backup` will need to ensure that it can be written to by this user:

```console
$ docker exec some-%%REPO%% chown mysql: /backup
```

To perform the backup:

```console
$ docker exec --user mysql some-%%REPO%% mariabackup --backup --target-dir=/backup --user=root --password=my-secret-pw
```

If you wish to take a copy of the `/backup` you can do so without stopping the container or getting an inconsistent backup.

```console
$ docker exec --user mysql some-%%REPO%% tar --create --xz --file - /backup > backup.tar.xz
```

## Restore backups with Mariabackup

These steps restore the backup made with Mariabackup.

At some point before doing the restore, the backup needs to be prepared. Here `/my/own/backupdir` contains a previous backup. Perform the prepare like this:

```console
$ docker run --user mysql --rm -v /my/own/backupdir:/backup %%IMAGE%%:latest mariabackup --prepare --target-dir=/backup
```

Now that the image is prepared, start the container with both the data and the backup volumes and restore the backup:

```console
$ docker run --user mysql --rm -v /my/own/newdatadir:/var/lib/mysql -v /my/own/backupdir:/backup %%IMAGE%%:latest mariabackup --copy-back --target-dir=/backup
```

With `/my/own/newdatadir` containing the restored backup, start normally as this is an initialized data directory:

```console
$ docker run --name some-%%REPO%% -v /my/own/newdatadir:/var/lib/mysql -d %%IMAGE%%:latest
```

For further information on Mariabackup, see the [Mariabackup Knowledge Base](https://mariadb.com/kb/en/mariabackup-overview/).

## How to reset root and user passwords

If you have an existing data directory and wish to reset the root and user passwords, and to create a database on which the user can fully modify, perform the following steps.

First create a `passwordreset.sql` file:

```text
CREATE USER IF NOT EXISTS root@localhost IDENTIFIED BY 'thisismyrootpassword';
SET PASSWORD FOR root@localhost = PASSWORD('thisismyrootpassword');
GRANT ALL ON *.* TO root@localhost WITH GRANT OPTION;
CREATE USER IF NOT EXISTS root@'%' IDENTIFIED BY 'thisismyrootpassword';
SET PASSWORD FOR root@'%' = PASSWORD('thisismyrootpassword');
GRANT ALL ON *.* TO root@'%' WITH GRANT OPTION;
CREATE USER IF NOT EXISTS myuser@'%' IDENTIFIED BY 'thisismyuserpassword';
SET PASSWORD FOR myuser@'%' = PASSWORD('thisismyuserpassword');
CREATE DATABASE IF NOT EXISTS databasename;
GRANT ALL ON databasename.* TO myuser@'%';
```

Adjust `myuser`, `databasename` and passwords as needed.

Then:

```console
$ docker run --rm -v /my/own/datadir:/var/lib/mysql -v /my/own/passwordreset.sql:/passwordreset.sql:z %%IMAGE%%:latest --init-file=/passwordreset.sql
```

On restarting the MariaDB container on this `/my/own/datadir`, the `root` and `myuser` passwords will be reset.

## How to install MariaDB plugins

MariaDB has many plugins, most are not enabled by default, some are in the %%IMAGE%% container, others need to be installed from additional packages.

The following methods summarize the [MariaDB Blog article - Installing plugins in the MariaDB Docker Library Container](https://mariadb.org/installing-plugins-in-the-mariadb-docker-library-container/) on this topic.

### Which plugins does the container contain?

To see which plugins are available in the %%IMAGE%%:

```console
$ docker run --rm %%IMAGE%%:latest ls -C /usr/lib/mysql/plugin
```

### Enabling a plugin using flags

Using the `--plugin-load-add` flag with the plugin name (can be repeated), the plugins will be loaded and ready when the container is started:

For example enable the `simple\_password\_check` plugin:

```console
$ docker run --name some-%%REPO%% -e MARIADB_ROOT_PASSWORD=my-secret-pw --network=host -d %%IMAGE%%:latest --plugin-load-add=simple_password_check
```

### Enabling a plugin in the configuration files

`plugin-load-add` can be used as a configuration option to load plugins. The example below load the [FederatedX Storage Engine](https://mariadb.com/kb/en/federatedx-storage-engine/).

```console
$ printf "[mariadb]\nplugin-load-add=ha_federatedx\n" > /my/custom/federatedx.conf
$ docker run --name some-%%REPO%% -v /my/custom:/etc/mysql/conf.d -e MARIADB_ROOT_PASSWORD=my-secret-pw -d %%IMAGE%%:latest
```

### Install a plugin using SQL in /docker-entrypoint-initdb.d

[`INSTALL SONAME`](https://mariadb.com/kb/en/install-soname/) can be used to install a plugin as part of the database initialization.

Create the SQL file used in initialization:

```console
$ echo 'INSTALL SONAME "disks";' > my_initdb/disks.sql
```

In this case the `my\_initdb` is a `/docker-entrypoint-initdb.d` directory per "Initializing a fresh instance" section above.

### Identifing additional plugins in additional packages

A number of plugins are in separate packages to reduce their installation size. The package names of MariaDB created plugins can be determined using the following command:

```console
$ docker run --rm %%IMAGE%%:latest sh -c 'apt-get update -qq && apt-cache search mariadb-plugin'
```

### Creating a image with plugins from additional packages

A new image needs to be created when using additional packages. The %%IMAGE%% image can be used as a base however:

In the following the [CONNECT Storage Engine](https://mariadb.com/kb/en/connect/) is installed:

```dockerfile
FROM %%IMAGE%%:latest
RUN apt-get update && \
apt-get install mariadb-plugin-connect -y && \
rm -rf /var/lib/apt/lists/*
```

Installing plugins from packages creates a configuration file in the directory `/etc/mysql/mariadb.conf.d/` that loads the plugin on startup.

0 comments on commit 37666d4

Please sign in to comment.