DEBOPS.MARIADB(5)

NAME
debops.mariadb - Manage MariaDB database client

SYNOPSIS

debops run service/mariadb [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

MariaDB <https://en.wikipedia.org/wiki/Mariadb> is a popular relational SQL database that was forked from MySQL server. Ansible roles debops.mariadb and debops.mariadb_server allow you to manage a MariaDB server and / or access it remotely from other hosts.

debops.mariadb role is the "client" part - it installs mariadb-client Debian package, and uses Ansible delegation to configure users and databases in local or remote MariaDB servers. You can use debops.mariadb_server role to manage the MariaDB server itself.

GETTING STARTED

debops.mariadb role is only the "client" part. To have working a MariaDB/MySQL installation, you also need to setup debops.mariadb_server role somewhere. It can be either on the same host, or on a separate host. See the debops.mariadb_server documentation to learn how to install the database server itself.

  Server configuration

The role supports different modes of operation, depending on the presence of a MariaDB or MySQL server installed locally or not, or presence of a tunneled connection to a remote server.

  Local database server

If the database server is installed locally, it will be automatically detected and used by the debops.mariadb role without any additional configuration. Also, if a remote server was used previously, and a local one was installed, it will automatically override the remote configuration. You might need to recreate the databases and user accounts in that case.

  Remote database server

If your MariaDB server is configured on a remote host and you don't have a local installation, debops.mariadb will detect that and won't manage the databases/user accounts without a server specified. To point it to a server, you need to set a variable in the inventory:

mariadb__server: 'db.example.org'

This needs to be a FQDN address or an IP address of a host with MariaDB server installed. This host will be accessed by Ansible using task delegation, so it needs to be accessible and managed by Ansible. Currently only 1 server at a time is supported by the role.

If debops.pki role is used to configure a PKI environment, with default domain PKI realm enabled, role will configure the provided private keys and X.509 certificates to enable SSL connections to the database by default. Support for client-side X.509 authentication will depend on a given user having access to the PKI private keys - see the documentation of debops.pki role for more details.

If the PKI environment is not configured or disabled, connections to the database server will be performed in cleartext, so you might want to consider securing them by configuring server on a separate internal network, or accessing it over a VPN connection. You can use debops.subnetwork, debops.tinc and debops.dnsmasq Ansible roles to set up a VPN internal network to secure communication between hosts.

  Remote database server over a SSL tunnel

If local MariaDB installation is not detected, but port 3306 is active and awaiting connections, debops.mariadb role assumes that MariaDB server is accessible over a VPN connection. In this case you need to specify the remote host in inventory for Ansible to delegate its tasks:

mariadb__server: 'db.example.org'

User accounts will automatically be configured with localhost as the "host" part of the account.

If you want to use tunneled connection to a MariaDB server, you can use debops.stunnel Ansible role to configure a SSL tunnel, although it might be more complex than using a VPN network.

  Example inventory

To enable MariaDB client support on a host, you need to add that host to [debops_service_mariadb] Ansible group:

[debops_service_mariadb]
hostname

When MariaDB server is properly configured, or installed locally, you can create user accounts and databases using inventory variables:

mariadb__databases:
  - name: 'application_production'
mariadb__users:
  - name: 'application'
    owner: 'application'

Above set of variables will create local system UNIX account application if it doesn't already exist, with a supplementary UNIX group of the same name, grant all privileges to application.* and application\_%.* databases, create a ~/.my.cnf configuration file with database credentials and finally, create a database application_production on the database server.

  Example playbook

Here's an example Ansible playbook that uses the debops.mariadb role:

---
- name: Manage MariaDB client
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_mariadb' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::mariadb' ]
      keyring__dependent_apt_keys:
        - '{{ mariadb__keyring__dependent_apt_keys }}'
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::mariadb' ]
      python__dependent_packages3:
        - '{{ mariadb__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ mariadb__python__dependent_packages2 }}'
    - role: mariadb
      tags: [ 'role::mariadb', 'skip::mariadb' ]

  Usage as a role dependency

debops.mariadb role can be used by another Ansible role as a dependency. The easiest way to do so is to have a separate set of variables for an user account, group, home directory, and MariaDB user. debops.mariadb will the create MariaDB user account, as wall as local UNIX account with a ~/.my.cnf configuration file as needed.

Database creation is best left for the application role, since then you can use the state change to perform other actions, like importing or initializing the database. See the next section for details.

Example usage as a role dependency:

dependencies:
  - role: debops.mariadb
    mariadb__dependent_users:
      - user: '{{ application__database_user }}'
        database: '{{ application__database_name }}'
        owner: '{{ application__user }}'
        group: '{{ application__group }}'
        home: '{{ application__home }}'
        system: True
        priv_aux: False

Password to the database user account can either be retrieved directly from the secret/ directory by the application role using debops.secret role, or set by the application role and provided as:

mariadb__dependent_users:
  - user: '{{ application__database_user }}'
    password: '{{ application__database_password }}'

In that case it's best to use debops.secret role to store the password securely in a separate directory.

  Local Ansible facts, custom tasks

Role creates a set of local Ansible facts which can be used by other roles to create database management tasks that work both with local and remote MariaDB servers. These facts are:

•   ansible_local.mariadb.client

•   ansible_local.mariadb.delegate_to

•   ansible_local.mariadb.host

•   ansible_local.mariadb.port

•   ansible_local.mariadb.server

    These variables can be used in Ansible tasks to provide correct values pointing to the correct MariaDB server. An example set of tasks to create user account and database:

    - name: Create database user
      mysql_user:
        name: '{{ application__database_user }}'
        host: '{{ ansible_local.mariadb.host }}'
        password: '{{ application__database_password }}'
        priv: '{{ application__database_name }}.*:ALL'
        state: 'present'
      delegate_to: '{{ ansible_local.mariadb.delegate_to }}'
    - name: Create application database
      mysql_db:
        name: '{{ application__database_name }}'
        state: 'present'
      delegate_to: '{{ ansible_local.mariadb.delegate_to }}'
      register: application__register_database

DEFAULT VARIABLE DETAILS

Some of debops.mariadb default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  mariadb__databases

List of databases that should be present or absent on a given MariaDB server. Each database is defined as a YAML dict with the following keys:

database or name
    Name of the database, required. Should be composed from alphanumeric characters and underscore (_) only. Max length: 16 for MySQL databases, 80 for MariaDB databases.

state
    Optional. If value is present, database will be created; if absent, database will be removed.

source
    Optional. Path to a file with SQL dump on the Ansible Controller, which will be copied to the remote host at the target location, imported into database (only if it was recently created), and removed afterwards. The role does not check if the file exists before copying it, so make sure that it's present in the location that you specify beforehand.

target
    Optional. Path to a file on the remote host which will be imported to the database after it has been created (only once). The role does not check if the file exists before trying to import it. You can use the source parameter to specify a file on the Ansible Controller to copy to the target location before import.

target_delete
    Optional. If present and False, it will prevent deletion of target file on remote host.

encoding
    Optional. Encoding mode to use, examples include utf8 or latin1_swedish_ci.

collation
    Optional. Collation mode (sorting). This only applies to new table/databases and does not update existing ones, this is a limitation of MySQL.

  Examples

Create databases, remove some of the existing ones:

mariadb__databases:
  - name: 'database1'
  - name: 'database2'
  - name: 'old_database'
    state: 'absent'

Create a database and import its contents from a file already present on remote host:

mariadb__databases:
  - name: 'fancy_db'
    target: '/tmp/dbcontents.sql.gz'

Create a database and import its contents from a file on the Ansible Controller:

mariadb__databases:
  - name: 'new_database'
    source: '/tmp/database-contents.sql.gz'
    target: '/tmp/dbcontents.sql.gz'

  mariadb__users

List of user accounts that should be present or absent on a given MariaDB server. Each user account is defined as a dict with a set of keys and values.

  User account parameters

user or name
    Required. The "username" part of the user account on the MariaDB server. If name is specified, it will be used to determine the database name for granting default privileges, if database is not specified.

host
    Optional. The "hostname" part of the user account on the MariaDB server. If not specified, it will be generated automatically by the role (this is usually what you want). It specifies the hostname or IP address of the host that is allowed to connect to the database.

password
    Optional. If specified, the role will set it as the password for the MariaDB account. If not present, a random password will be generated automatically and stored in the secret/ directory on the Ansible Controller. Refer to the debops.secret role for more details.

state
    Optional. If present, the account will be created on the database server. If absent, account will be removed from the database server.

  Database privileges

database
    Optional. If present, it specifies the database name and/or database prefix that a given user account will be able to access using default privileges. If not present, name will be used instead.

priv_default
    Optional. By default, the user accounts will get all privileges to databases with the same name. If this key is present and False, the users will not get default privileges.

priv_aux
    Optional. By default, the user accounts will get all privileges to the database prefixed with the name of the user account. If this key is present and False, the users will not get default prefix privileges.

priv
    Optional. String or list of privileges to grant to a given user account. See mysql_user documentation for information about how to specify the privileges.

append_privs
    Optional. If present and True, specified privileges will be appended to already existing privileges (default). If False, specified privileges will replace all current privileges for a given user account.

  User configuration file

owner
    Optional. It should specify a local UNIX account on the host managed by the debops.mariadb role (not on the host with the database, unless it's a local installation). If specified, the debops.mariadb role will create a local UNIX account if it doesn't exist with the specified name and create a ~/.my.cnf configuration file with the MariaDB account credentials and configuration pointing to the MariaDB server.

group
    Optional. Main local UNIX group of the created account. If not specified, a group named after the account will be created instead.

home
    Required if item.owner is specified. Specifies the home directory of given local UNIX account.

system
    Optional. If specified and True, the local UNIX group/user account which is going to be created will be a "system" account with UID/GID < 1000. If specified and False, local UNIX group/user account will be a "normal" account with UID/GID >= 1000. By default groups and accounts will be created as "system" accounts.

mode
    Optional. If specified, defines the permissions of the ~/.my.cnf configuration file. By default they are set to 0640.

creds_path
    Optional, string. Allows you to change the file path for the credentials file which defaults to ~/.my.cnf.

  Examples

Create a MariaDB user account with all privileges granted to the someuser.* and someuser\_%.* databases:

mariadb__users:
  - name: 'someuser'

Create a MariaDB user account with all privileges to somedatabase.* without auxiliary privileges:

mariadb__users:
  - name: 'someuser'
    database: 'somedatabase'
    priv_aux: False

Create a MariaDB user account and set up a local system account configured to use MariaDB:

mariadb__users:
  - name: 'someuser'
    owner: 'system-user'
    home: '/var/local/system-user'

Create a MariaDB user account without default privileges:

mariadb__users:
  - name: 'someuser'
    priv_default: False
    priv_aux: False

Create a MariaDB user account with custom additional privileges:

mariadb__users:
  - name: 'someuser'
    priv: [ 'otherdb.*:ALL' ]

  mariadb__options

The role uses /etc/mysql/conf.d/client.cnf configuration file to manage the MariaDB/MySQL system-wide client configuration. This configuration file is generated by a template that uses the mariadb__client_options variable to get the configuration data. The configuration itself is split among several variables located in defaults/main.yml file.

A minimal configuration is stored as a YAML dictionary. Keys of the dictionary as MariaDB configuration option names, and values of the dictionary are the configuration values. All values are automatically quoted in the generated configuration file.

Example configuration section:

mariadb__options:
  'query_cache_type': '0'
  'key_buffer': '16M'
  'skip_name_resolve':

The dictionary keys without values will be written in the configuration file with correct notation.

Alternative configuration notation is to use a YAML list, each element of a list being a YAML dictionary in the above format. An example:

mariadb__options:
  - 'query_cache_type': '0'
    'key_buffer': '16M'
  - 'skip_name_resolve':

Yet another alternative format can be used if you use certain keys in the YAML dictionary. The template checks for presence of the name or section keys, and if found, changes to a different format that uses YAML dictionary keys:

name
    Required for the main options. Name of the option to add.

section
    Required for the definition of a configuration section. Create new section of the configuration file, written in square brackets.

state
    Optional. Either present or absent. If not specified or present, a given section or option will be added in the configuration file; if absent, option or section won't be added.

comment
    Optional. Add a comment to a given option or section.

value
    Optional for main options. If specified, set a value of a given option.

options
    Optional. A YAML dictionary or list of YAML dictionaries with options to include in a given section, or multiple options specified together as a group. If it's specified, values of name and value are ignored.

    Examples:

    mariadb__options:
      - section: 'client'
        comment: 'Global MariaDB client options'
        options:
          - name: 'skip_name_resolve'
          - name: 'key_buffer'
            value: '16M'
          - name: 'query_cache_type'
            value: '0'
            state: 'present'

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others