mash-playbook/docs/services/mariadb.md

# MariaDB

[MariaDB](https://mariadb.org/) is a powerful, open source object-relational database system.

Some of the services installed by this playbook require a MariaDB database.

Enabling the MariaDB database service will automatically wire all other services which require such a database to use it.


## Configuration

To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:

```yaml
########################################################################
#                                                                      #
# mariadb                                                              #
#                                                                      #
########################################################################

mariadb_enabled: true

# Put a strong password below, generated with `pwgen -s 64 1` or in another way
mariadb_root_passsword: ''

########################################################################
#                                                                      #
# /mariadb                                                             #
#                                                                      #
########################################################################
```


## Getting a database terminal

You can use the `/mash/mariadb/bin/cli` tool to get interactive terminal access to the MariaDB server.

To see the available databases, run `SHOW DATABASES`.

To change to another existing database (for example `miniflux`), run `USE miniflux`.

You can then proceed to write queries. Example: `SELECT COUNT(*) FROM users;`

**Be careful**. Modifying the database directly (especially as services are running) is dangerous and may lead to irreversible database corruption.
When in doubt, consider [making a backup](#backing-up-mariadb).


## Upgrading MariaDB

The major MariaDB version you start with (e.g. `10.10` or `10.11`) will be kept until you manually upgrade it. The playbook will stick to this major version and only do minor version upgrades (e.g. `10.10.1` -> `10.10.3`).

This is because newer MariaDB versions cannot start with data generated by older MariaDB versions.

Upgrades must be performed manually.

This playbook can upgrade your existing MariaDB setup with the following command:

```sh
just run-tags upgrade-mariadb
```

**The old MariaDB data directory is backed up** automatically, by renaming it to `/mash/mariadb/data-auto-upgrade-backup`.
To rename to a different path, pass some extra flags to the command above, like this: `--extra-vars="mariadb_auto_upgrade_backup_data_path=/another/disk/mash-postgres-before-upgrade"`

The auto-upgrade-backup directory stays around forever, until you **manually decide to delete it**.

As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty MariaDB server is started, and then the dump is restored into the new server.
To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="mariadb_dump_dir=/directory/to/dump/here"`

To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage.
If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`.
Example: `--extra-vars="mariadb_dump_name=mash-postgres-dump.sql"`

**All databases, users, etc. on the MariaDB server are migrated**.


## Backing up MariaDB

A `/mash/mariadb/bin/dump-all` script will be installed, which can dump the database to a path of your choosing.