Commit 21c703d3 authored by Alex Thomae's avatar Alex Thomae

Merge branch 'update-readme' into 'master'

Updates README.md

See merge request !3
parents 4f93e021 2ff1c66c
Pipeline #101454403 passed with stages
in 1 minute and 37 seconds
About
=====
# mariadb-backup
The mysql-backup Docker image will provide you a container to backup and restore a [MySQL](https://hub.docker.com/_/mysql/) or [MariaDB](https://hub.docker.com/_/mariadb/) database container.
[![Pipeline Status](https://gitlab.com/ix.ai/mariadb-backup/badges/master/pipeline.svg)](https://gitlab.com/ix.ai/mariadb-backup/)
[![Docker Stars](https://img.shields.io/docker/stars/ixdotai/mariadb-backup.svg)](https://hub.docker.com/r/ixdotai/mariadb-backup/)
[![Docker Pulls](https://img.shields.io/docker/pulls/ixdotai/mariadb-backup.svg)](https://hub.docker.com/r/ixdotai/mariadb-backup/)
[![Gitlab Project](https://img.shields.io/badge/GitLab-Project-554488.svg)](https://gitlab.com/ix.ai/mariadb-backup/)
The mariadb-backup Docker image will provide you a container to backup and restore a [MySQL](https://hub.docker.com/_/mysql/) or [MariaDB](https://hub.docker.com/_/mariadb/) database container.
The backup is made with [mydumper](http://centminmod.com/mydumper.html), a fast MySQL backup utility.
Usage
=====
## Usage
To backup a [MySQL](https://hub.docker.com/_/mysql/) or [MariaDB](https://hub.docker.com/_/mariadb/) database, you simply specify the credentials and the host. You can optionally specify the database as well.
Environment variables
=====================
* `DB_HOST` (mandatory, no default): The host to connect to
* `DB_PASS` (mandatory, no default): The password to use
* `DB_NAME` (optional, no default): If specified, only this database will be backed up
* `DB_PORT` (optional, default `3306`): The password for the SQL server
* `DB_USER` (optional, default `root`): The user to connect to the SQL server
## Environment variables
| **Variable** | **Default** | **Mandatory** | **Description** |
|:--------------|:-----------:|:-------------:|:-----------------------------------------------------|
| `DB_HOST` | - | *yes* | The host to connect to |
| `DB_PASS` | - | *yes* | The password for the SQL server |
| `DB_NAME` | - | *no* | If specified, only this database will be backed up |
| `DB_PORT` | `3306` | *no* | The port of the SQL server |
| `DB_USER` | `root` | *no* | The user to connect to the SQL server |
| `MODE` | `BACKUP` | *no* | One of `BACKUP` or `RESTORE` |
| `BASE_DIR` | `/backup` | *no* | Path of the base directory (aka working directory) |
| `RESTORE_DIR` | - | *no* | Name of a backup directory to restore |
| `BACKUP_UID` | `666` | *no* | UID of the backup |
| `BACKUP_GID` | `666` | *no* | GID of the backup |
| `UMASK` | `0022` | *no* | Umask which should be used to write the backup files |
| `OPTIONS` | `-c` / `-o` | *no* | Options passed to `mydumper` / `myloader` |
Please note the backup will be written to `/backup` by default, so you might want to mount that directory from your host.
Example Docker CLI client
-------------------------
## Example Docker CLI client
To __create a backup__ from a MySQL container via `docker` CLI client:
```bash
docker run --name my-backup -e DB_HOST=mariadb -e DB_PASS=amazing_pass -v /var/mysql_backups:/backup registry.gitlab.com/ix.ai/mariadb-backup
docker run --name my-backup -e DB_HOST=mariadb -e DB_PASS=amazing_pass -v /var/mysql_backups:/backup ixdotai/mariadb-backup:latest
```
The container will stop automatically as soon as the backup has finished.
......@@ -40,30 +49,47 @@ docker start my-backup
To __restore a backup__ into a MySQL container via `docker` CLI client:
```bash
docker run --name my-restore -e DB_HOST=mariadb -e DB_PASS=amazing_pass -v /var/mysql_backups:/backup registry.gitlab.com/ix.ai/mariadb-backup
docker run --name my-restore -e DB_HOST=mariadb -e DB_PASS=amazing_pass -v /var/mysql_backups:/backup ixdotai/mariadb-backup:latest
```
Configuration
=============
## Script example
The following example uses the image []() for MariaDB.
To back up multiple databases, all running in docker, all labeled with `mariadb-backup`:
```bash
#!/usr/bin/env bash
/bin/mkdir -p /mariadb-backup
/usr/bin/docker pull ixdotai/mariadb-backup:latest
for CONTAINER in $(/usr/bin/docker ps -f label=mariadb-backup --format='{{.Names}}'); do
DB_PASS=$(/usr/bin/docker inspect ${CONTAINER}|/usr/bin/jq -r '.[0]|.Config.Env[]|select(test("^MARIADB_ROOT_PASSWORD.*"))'|/bin/sed -n 's/^MARIADB_ROOT_PASSWORD=\(.*\)/\1/p')
DB_NAME=$(/usr/bin/docker inspect ${CONTAINER}|/usr/bin/jq -r '.[0]|.Config.Env[]|select(test("^MARIADB_DATABASE.*"))'|/bin/sed -n 's/^MARIADB_DATABASE=\(.*\)/\1/p')
DB_NET=$(/usr/bin/docker inspect ${CONTAINER}|/usr/bin/jq -r '.[0]|.NetworkSettings.Networks|to_entries[]|.key')
if [[ -n "${DB_PASS}" ]]; then
/usr/bin/docker run --rm --name ${CONTAINER}-backup -e DB_PASS=${DB_PASS} -e DB_HOST=${CONTAINER} -e DB_NAME=${DB_NAME} --network ${DB_NET} -v /mariadb-backup:/backup ixdotai/mariadb-backup:latest
fi
done
```
## Configuration
Mode
----
### Mode
By default the container backups the database.
However, you can change the mode of the container by setting the following environment variable:
* `MODE`: Sets the mode of the backup container while [`BACKUP`|`RESTORE`]
Base directory
--------------
### Base directory
By default the base directory `/backup` is used.
However, you can overwrite that by setting the following environment variable:
* `BASE_DIR`: Path of the base directory (aka working directory)
Restory directory
-----------------
### Restore directory
By default the container will automatically restore the latest backup found in `BASE_DIR`.
However, you can manually set the name of a backup directory underneath `BASE_DIR`:
......@@ -72,8 +98,7 @@ However, you can manually set the name of a backup directory underneath `BASE_DI
_This option is only required when the container runs in in `RESTORE` mode._
UID and GID
-----------
### UID and GID
By default the backup will be written with UID and GID `666`.
However, you can overwrite that by setting the following environment variables:
......@@ -81,23 +106,20 @@ However, you can overwrite that by setting the following environment variables:
* `BACKUP_UID`: UID of the backup
* `BACKUP_GID`: GID of the backup
umask
-----
### umask
By default a `umask` of `0022` will be used.
However, you can overwrite that by setting the following environment variable:
* `UMASK`: Umask which should be used to write the backup files
mydumper / myloader CLI options
-------------------------------
### mydumper / myloader CLI options
By default `mydumper` is invoked with the `-c` (compress backup) and `myloader` with the `-o` (overwrite tables) CLI option.
However, you can modify the CLI options by setting the following environment variable:
* `OPTIONS`: Options passed to `mydumper` (when `MODE` is `BACKUP`) or `myloader` (when `MODE` is `RESTORE`)
Credits
=======
## Credits
Special thanks to [confirm/docker-mysql-backup](https://github.com/confirm/docker-mysql-backup), which this project uses heavily.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment