--- a/modules/mysql/README.md	Fri Dec 20 15:36:56 2019 +0000
+++ b/modules/mysql/README.md	Sat Dec 21 14:11:43 2019 -0500
@@ -1,115 +1,116 @@
-#MySQL
+# mysql
 
-####Table of Contents
+#### Table of Contents
 
-1. [Overview](#overview)
-2. [Module Description - What the module does and why it is useful](#module-description)
-3. [Backwards compatibility information](#backwards-compatibility)
-3. [Setup - The basics of getting started with mysql](#setup)
+1. [Module Description - What the module does and why it is useful](#module-description)
+2. [Setup - The basics of getting started with mysql](#setup)
     * [Beginning with mysql](#beginning-with-mysql)
-4. [Usage - Configuration options and additional functionality](#usage)
-    * [Customizing Server Options](#customizing-server-options)
-    * [Creating a Database](#creating-a-database)
-    * [Custom Configuration](#custom-configuration)
-5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
+3. [Usage - Configuration options and additional functionality](#usage)
+    * [Customize server options](#customize-server-options)
+    * [Create a database](#create-a-database)
+    * [Customize configuration](#customize-configuration)
+    * [Work with an existing server](#work-with-an-existing-server)
+    * [Specify passwords](#specify-passwords)
+    * [Install Percona server on CentOS](#install-percona-server-on-centos)
+    * [Install MariaDB on Ubuntu](#install-mariadb-on-ubuntu)
+    * [Install Plugins](#install-plugins)
+4. [Reference - An under-the-hood peek at what the module is doing and how](REFERENCE.md)
 5. [Limitations - OS compatibility, etc.](#limitations)
 6. [Development - Guide for contributing to the module](#development)
 
-##Overview
+## Module Description
 
 The mysql module installs, configures, and manages the MySQL service.
 
-##Module Description
-
-The mysql module manages both the installation and configuration of MySQL, as well as extending Puppet to allow management of MySQL resources, such as databases, users, and grants.
+This module manages both the installation and configuration of MySQL, as well as extending Puppet to allow management of MySQL resources, such as databases, users, and grants.
 
-##Setup
+## Setup
 
-###What MySQL affects
+### Beginning with mysql
 
-* MySQL package
-* MySQL configuration files
-* MySQL service
+To install a server with the default options:
 
-###Beginning with MySQL
+`include '::mysql::server'`.
 
-If you want a server installed with the default options you can run
-`include '::mysql::server'`. 
+To customize options, such as the root password or `/etc/my.cnf` settings, you must also pass in an override hash:
 
-If you need to customize options, such as the root
-password or `/etc/my.cnf` settings, then you must also pass in an override hash:
-
-~~~
+```puppet
 class { '::mysql::server':
   root_password           => 'strongpassword',
   remove_default_accounts => true,
+  restart                 => true,
   override_options        => $override_options
 }
-~~~
+```
 
-See [**Customizing Server Options**](#customizing-server-options) below for examples of the hash structure for $override_options`.
+Nota bene: Configuration changes will only be applied to the running
+MySQL server if you pass true as restart to mysql::server.
 
-##Usage
+See [**Customize Server Options**](#customize-server-options) below for examples of the hash structure for $override_options.
+
+## Usage
 
 All interaction for the server is done via `mysql::server`. To install the client, use `mysql::client`. To install bindings, use `mysql::bindings`.
 
-###Customizing Server Options
+### Customize server options
 
-The hash structure for overrides in `mysql::server` can be structured like a hash in the my.cnf file, so:
+To define server options, structure a hash structure of overrides in `mysql::server`. This hash resembles a hash in the my.cnf file:
 
-~~~
+```puppet
 $override_options = {
   'section' => {
     'item' => 'thing',
   }
 }
-~~~
+```
 
-For items that you would traditionally represent as
+For options that you would traditionally represent in this format:
 
-~~~
+```
 [section]
 thing = X
-~~~
+```
 
-you can make an entry like `thing => true`, `thing => value`, or `thing => "` in the hash. Alternatively, you can pass an array, as `thing => ['value', 'value2']`, or list each `thing => value` separately on separate lines. 
+Entries can be created as `thing => true`, `thing => value`, or `thing => ""` in the hash. Alternatively, you can pass an array as `thing => ['value', 'value2']` or list each `thing => value` separately on individual lines.
 
-MySQL doesn't care if 'thing' is alone or set to a value; it happily accepts both. To keep an option out of the my.cnf file --- e.g., when using `override_options` to revert to a default value --- you can pass `thing => undef`.
+You can pass a variable in the hash without setting a value for it; the variable would then use MySQL's default settings. To exclude an option from the `my.cnf` file --- for example, when using `override_options` to revert to a default value --- pass `thing => undef`.
 
-If an option needs multiple instances, you can pass an array. For example,
+If an option needs multiple instances, pass an array. For example,
 
-~~~
+```puppet
 $override_options = {
   'mysqld' => {
     'replicate-do-db' => ['base1', 'base2'],
   }
 }
-~~~
+```
 
 produces
 
-~~~
-[mysql]
+```puppet
+[mysqld]
 replicate-do-db = base1
 replicate-do-db = base2
-~~~
+```
 
-### Creating a database
+To implement version specific parameters, specify the version, such as [mysqld-5.5]. This allows one config for different versions of MySQL.
 
-To use `mysql::db` to create a database with a user and assign some privileges:
+### Create a database
 
-~~~
+To create a database with a user and some assigned privileges:
+
+```puppet
 mysql::db { 'mydb':
   user     => 'myuser',
   password => 'mypass',
   host     => 'localhost',
   grant    => ['SELECT', 'UPDATE'],
 }
-~~~
+```
 
-Or to use a different resource name with exported resources:
+To use a different resource name with exported resources:
 
-~~~
+```puppet
  @@mysql::db { "mydb_${fqdn}":
   user     => 'myuser',
   password => 'mypass',
@@ -118,49 +119,293 @@
   grant    => ['SELECT', 'UPDATE'],
   tag      => $domain,
 }
-~~~
+```
 
 Then you can collect it on the remote DB server:
 
-~~~
+```puppet
 Mysql::Db <<| tag == $domain |>>
-~~~
+```
+
+If you set the sql parameter to a file when creating a database, the file is imported into the new database.
 
-If you set the sql param to a file when creating a database, the file gets imported into the new database.
+For large sql files, increase the `import_timeout` parameter, which defaults to 300 seconds.
 
-For large sql files, you should raise the $import_timeout parameter, set by default to 300 seconds.
+If you have installed the mysql client in a non standard bin/sbin path you can set this with `mysql_exec_path` .
 
-~~~
+```puppet
 mysql::db { 'mydb':
   user     => 'myuser',
   password => 'mypass',
   host     => 'localhost',
   grant    => ['SELECT', 'UPDATE'],
-  sql      => '/path/to/sqlfile',
+  sql      => '/path/to/sqlfile.gz',
+  import_cat_cmd => 'zcat',
   import_timeout => 900,
+  mysql_exec_path => '/opt/rh/rh-myql57/root/bin'
 }
-~~~
+```
+
+### Customize configuration
+
+To add custom MySQL configuration, place additional files into `includedir`. This allows you to override settings or add additional ones, which is helpful if you don't use `override_options` in `mysql::server`. The `includedir` location is by default set to `/etc/mysql/conf.d`.
+
+### Work with an existing server
+
+To instantiate databases and users on an existing MySQL server, you need a `.my.cnf` file in `root`'s home directory. This file must specify the remote server address and credentials. For example:
+
+```puppet
+[client]
+user=root
+host=localhost
+password=secret
+```
+
+This module uses the `mysqld_version` fact to discover the server version being used.  By default, this is set to the output of `mysqld -V`.  If you're working with a remote MySQL server, you may need to set a custom fact for `mysqld_version` to ensure correct behaviour.
+
+When working with a remote server, do *not* use the `mysql::server` class in your Puppet manifests.
+
+### Specify passwords
+
+In addition to passing passwords as plain text, you can input them as hashes. For example:
+
+```puppet
+mysql::db { 'mydb':
+  user     => 'myuser',
+  password => '*6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4',
+  host     => 'localhost',
+  grant    => ['SELECT', 'UPDATE'],
+}
+```
+
+If required, the password can also be an empty string to allow connections without an password.
+
+### Install Percona server on CentOS
+
+This example shows how to do a minimal installation of a Percona server on a
+CentOS system. This sets up the Percona server, client, and bindings (including Perl and Python bindings). You can customize this usage and update the version as needed.
+
+This usage has been tested on Puppet 4.4, 5.5 and 6.3.0 / CentOS 7 / Percona Server 5.7.
+
+**Note:** The installation of the yum repository is not part of this package
+and is here only to show a full example of how you can install.
+
+```puppet
+yumrepo { 'percona':
+  descr    => 'CentOS $releasever - Percona',
+  baseurl  => 'http://repo.percona.com/percona/yum/release/$releasever/RPMS/$basearch',
+  gpgkey   => 'https://repo.percona.com/yum/PERCONA-PACKAGING-KEY',
+  enabled  => 1,
+  gpgcheck => 1,
+}
 
-###Custom Configuration
+class {'mysql::server':
+  package_name     => 'Percona-Server-server-57',
+  service_name     => 'mysql',
+  config_file      => '/etc/my.cnf',
+  includedir       => '/etc/my.cnf.d',
+  root_password    => 'PutYourOwnPwdHere',
+  override_options => {
+    mysqld => {
+      log-error => '/var/log/mysqld.log',
+      pid-file  => '/var/run/mysqld/mysqld.pid',
+    },
+    mysqld_safe => {
+      log-error => '/var/log/mysqld.log',
+    },
+  }
+}
+
+# Note: Installing Percona-Server-server-57 also installs Percona-Server-client-57.
+# This shows how to install the Percona MySQL client on its own
+class {'mysql::client':
+  package_name   => 'Percona-Server-client-57'
+}
+
+# These packages are normally installed along with Percona-Server-server-57
+# If you needed to install the bindings, however, you could do so with this code
+class { 'mysql::bindings':
+  client_dev_package_name   => 'Percona-Server-shared-57',
+  client_dev                => true,
+  daemon_dev_package_name   => 'Percona-Server-devel-57',
+  daemon_dev                => true,
+  perl_enable               => true,
+  perl_package_name         => 'perl-DBD-MySQL',
+  python_enable             => true,
+  python_package_name       => 'MySQL-python',
+}
 
-To add custom MySQL configuration, drop additional files into
-`includedir`. Dropping files into `includedir` allows you to override settings or add additional ones, which is helpful if you choose not to use `override_options` in `mysql::server`. The `includedir` location is by default set to /etc/mysql/conf.d.
+# Dependencies definition
+Yumrepo['percona']->
+Class['mysql::server']
+
+Yumrepo['percona']->
+Class['mysql::client']
+
+Yumrepo['percona']->
+Class['mysql::bindings']
+```
+
+### Install MariaDB on Ubuntu
+
+#### Optional: Install the MariaDB official repo
+
+In this example, we'll use the latest stable (currently 10.1) from the official MariaDB repository, not the one from the distro repository. You could instead use the package from the Ubuntu repository. Make sure you use the repository corresponding to the version you want.
 
-##Reference
+**Note:** `sfo1.mirrors.digitalocean.com` is one of many mirrors available. You can use any official mirror.
+
+```puppet
+include apt
+
+apt::source { 'mariadb':
+  location => 'http://sfo1.mirrors.digitalocean.com/mariadb/repo/10.1/ubuntu',
+  release  => $::lsbdistcodename,
+  repos    => 'main',
+  key      => {
+    id     => '199369E5404BD5FC7D2FE43BCBCB082A1BB943DB',
+    server => 'hkp://keyserver.ubuntu.com:80',
+  },
+  include => {
+    src   => false,
+    deb   => true,
+  },
+}
+```
 
-###Classes
+#### Install the MariaDB server
+
+This example shows MariaDB server installation on Ubuntu Trusty. Adjust the version and the parameters of `my.cnf` as needed. All parameters of the `my.cnf` can be defined using the `override_options` parameter.
+
+The folders `/var/log/mysql` and `/var/run/mysqld` are created automatically, but if you are using other custom folders, they should exist as prerequisites for this code.
+
+All the values set here are an example of a working minimal configuration.
+
+Specify the version of the package you want with the `package_ensure` parameter.
+
+```puppet
+class {'::mysql::server':
+  package_name     => 'mariadb-server',
+  package_ensure   => '10.1.14+maria-1~trusty',
+  service_name     => 'mysql',
+  root_password    => 'AVeryStrongPasswordUShouldEncrypt!',
+  override_options => {
+    mysqld => {
+      'log-error' => '/var/log/mysql/mariadb.log',
+      'pid-file'  => '/var/run/mysqld/mysqld.pid',
+    },
+    mysqld_safe => {
+      'log-error' => '/var/log/mysql/mariadb.log',
+    },
+  }
+}
+
+# Dependency management. Only use that part if you are installing the repository
+# as shown in the Preliminary step of this example.
+Apt::Source['mariadb'] ~>
+Class['apt::update'] ->
+Class['::mysql::server']
+
+```
+
+#### Install the MariaDB client
+
+This example shows how to install the MariaDB client and all of the bindings at once. You can do this installation separately from the server installation.
+
+Specify the version of the package you want with the `package_ensure` parameter.
+
+```puppet
+class {'::mysql::client':
+  package_name    => 'mariadb-client',
+  package_ensure  => '10.1.14+maria-1~trusty',
+  bindings_enable => true,
+}
+
+# Dependency management. Only use that part if you are installing the repository as shown in the Preliminary step of this example.
+Apt::Source['mariadb'] ~>
+Class['apt::update'] ->
+Class['::mysql::client']
+```
+
+### Install MySQL Community server on CentOS
+
+You can install MySQL Community Server on CentOS using the mysql module and Hiera. This example was tested with the following versions:
+
+* MySQL Community Server 5.6
+* Centos 7.3
+* Puppet 3.8.7 using Hiera
+* puppetlabs-mysql module v3.9.0
+
+In Puppet:
 
-####Public classes
-* `mysql::server`: Installs and configures MySQL.
-* `mysql::server::account_security`: Deletes default MySQL accounts.
-* `mysql::server::monitor`: Sets up a monitoring user.
-* `mysql::server::mysqltuner`: Installs MySQL tuner script.
-* `mysql::server::backup`: Sets up MySQL backups via cron.
-* `mysql::bindings`: Installs various MySQL language bindings.
-* `mysql::client`: Installs MySQL client (for non-servers).
+```puppet
+include ::mysql::server
+
+create_resources(yumrepo, hiera('yumrepo', {}))
+
+Yumrepo['repo.mysql.com'] -> Anchor['mysql::server::start']
+Yumrepo['repo.mysql.com'] -> Package['mysql_client']
+
+create_resources(mysql::db, hiera('mysql::server::db', {}))
+```
+
+In Hiera:
+
+```yaml
+---
+
+# Centos 7.3
+yumrepo:
+  'repo.mysql.com':
+    baseurl: "http://repo.mysql.com/yum/mysql-5.6-community/el/%{::operatingsystemmajrelease}/$basearch/"
+    descr: 'repo.mysql.com'
+    enabled: 1
+    gpgcheck: true
+    gpgkey: 'http://repo.mysql.com/RPM-GPG-KEY-mysql'
 
-####Private classes
+mysql::client::package_name: "mysql-community-client" # required for proper MySQL installation
+mysql::server::package_name: "mysql-community-server" # required for proper MySQL installation
+mysql::server::package_ensure: 'installed' # do not specify version here, unfortunately yum fails with error that package is already installed
+mysql::server::root_password: "change_me_i_am_insecure"
+mysql::server::manage_config_file: true
+mysql::server::service_name: 'mysqld' # required for puppet module
+mysql::server::override_options:
+  'mysqld':
+    'bind-address': '127.0.0.1'
+    'log-error': '/var/log/mysqld.log' # required for proper MySQL installation
+  'mysqld_safe':
+    'log-error': '/var/log/mysqld.log'  # required for proper MySQL installation
+
+# create database + account with access, passwords are not encrypted
+mysql::server::db:
+  "dev":
+    user: "dev"
+    password: "devpass"
+    host: "127.0.0.1"
+    grant:
+      - "ALL"
+
+```
+
+### Install Plugins
+
+Plugins can be installed by using the `mysql_plugin` defined type. See `examples/mysql_plugin.pp` for futher examples.
+## Reference
+
+### Classes
+
+#### Public classes
+
+* [`mysql::server`](#mysqlserver): Installs and configures MySQL.
+* [`mysql::server::monitor`](#mysqlservermonitor): Sets up a monitoring user.
+* [`mysql::server::mysqltuner`](#mysqlservermysqltuner): Installs MySQL tuner script.
+* [`mysql::server::backup`](#mysqlserverbackup): Sets up MySQL backups via cron.
+* [`mysql::bindings`](#mysqlbindings): Installs various MySQL language bindings.
+* [`mysql::client`](#mysqlclient): Installs MySQL client (for non-servers).
+
+#### Private classes
+
 * `mysql::server::install`: Installs packages.
+* `mysql::server::installdb`: Implements setup of mysqld data directory (e.g. /var/lib/mysql)
 * `mysql::server::config`: Configures MYSQL.
 * `mysql::server::service`: Manages service.
 * `mysql::server::account_security`: Deletes default MySQL accounts.
@@ -176,623 +421,114 @@
 * `mysql::client::install`:  Installs MySQL client.
 * `mysql::backup::mysqldump`: Implements mysqldump backups.
 * `mysql::backup::mysqlbackup`: Implements backups with Oracle MySQL Enterprise Backup.
-* `mysql::backup::xtrabackup`: Implements backups with XtraBackup from Percona.
+* `mysql::backup::xtrabackup`: Implements backups with XtraBackup from Percona or Mariabackup.
 
-###Parameters
+### Parameters
+
+#### mysql::server
 
-####mysql::server
+##### `create_root_user`
+
+Whether root user should be created.
 
-#####`create_root_user`
+Valid values are `true`, `false`.
 
-Specify whether root user should be created. Valid values are 'true', 'false'. Defaults to 'true'.
+Defaults to `true`.
 
-This is useful for a cluster setup with Galera. The root user has to
-be created only once. `create_root_user` can be set to 'true' on one node while
-it is set to 'false' on the remaining nodes.
+This is useful for a cluster setup with Galera. The root user has to be created only once. You can set this parameter true on one node and set it to false on the remaining nodes.
 
-#####`create_root_my_cnf`
+#####  `create_root_my_cnf`
+
+Whether to create `/root/.my.cnf`.
 
-If set to 'true', creates `/root/.my.cnf`. Valid values are 'true', 'false'. Defaults to 'true'.
+Valid values are `true`, `false`.
+
+Defaults to `true`.
 
-`create_root_my_cnf` allows creation of `/root/.my.cnf` independently of `create_root_user`. This can be used for a cluster setup with Galera where you want `/root/.my.cnf` to exist on all nodes.
+`create_root_my_cnf` allows creation of `/root/.my.cnf` independently of `create_root_user`. You can use this for a cluster setup with Galera where you want `/root/.my.cnf` to exist on all nodes.
 
-#####`root_password`
+#####  `root_password`
 
 The MySQL root password. Puppet attempts to set the root password and update `/root/.my.cnf` with it.
 
-This is required if `create_root_user` or `create_root_my_cnf` are 'true'. If `root_password` is 'UNSET', then `create_root_user` and `create_root_my_cnf` are assumed to be false --- that is, the MySQL root user and `/root/.my.cnf` are not created.
-
-#####`old_root_password`
-
-The previous root password. Required if you want to change the root password via Puppet.
-
-#####`override_options`
-
-The hash of override options to pass into MySQL. Structured like a hash in the my.cnf file:
-
-~~~
-$override_options = {
-  'section' => {
-    'item'             => 'thing',
-  }
-}
-~~~
+This is required if `create_root_user` or `create_root_my_cnf` are true. If `root_password` is 'UNSET', then `create_root_user` and `create_root_my_cnf` are assumed to be false --- that is, the MySQL root user and `/root/.my.cnf` are not created.
 
-See [**Customizing Server Options**](#customizing-server-options) above for usage details.
-
-#####`config_file`
-
-The location, as a path, of the MySQL configuration file.
-
-#####`manage_config_file`
-
-Whether the MySQL configuration file should be managed. Valid values are 'true', 'false'. Defaults to 'true'.
-
-#####`includedir`
-The location, as a path, of !includedir for custom configuration overrides.
-
-#####`install_options`
-Pass [install_options](https://docs.puppetlabs.com/references/latest/type.html#package-attribute-install_options) array to managed package resources. You must pass the appropriate options for the specified package manager.
-
-#####`purge_conf_dir`
+Password changes are supported; however, the old password must be set in `/root/.my.cnf`. Effectively, Puppet uses the old password, configured in `/root/my.cnf`, to set the new password in MySQL, and then updates `/root/.my.cnf` with the new password.
 
-Whether the `includedir` directory should be purged. Valid values are 'true', 'false'. Defaults to 'false'.
-
-#####`restart`
-
-Whether the service should be restarted when things change. Valid values are 'true', 'false'. Defaults to 'false'.
-
-#####`root_group`
-
-The name of the group used for root. Can be a group name or a group ID. See more about the [`group` file attribute](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-group).
-
-#####`package_ensure`
-
-Whether the package exists or should be a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Defaults to 'present'.
-
-#####`package_manage`
-
-Whether to manage the mysql server package. Defaults to true.
+##### `old_root_password`
 
-#####`package_name`
-
-The name of the MySQL server package to install.
-
-#####`remove_default_accounts`
-
-Specify whether to automatically include `mysql::server::account_security`. Valid values are 'true', 'false'. Defaults to 'false'.
-
-#####`service_enabled`
-
-Specify whether the service should be enabled. Valid values are 'true', 'false'. Defaults to 'true'.
-
-#####`service_manage`
-
-Specify whether the service should be managed. Valid values are 'true', 'false'. Defaults to 'true'.
-
-#####`service_name`
-
-The name of the MySQL server service. Defaults are OS dependent, defined in params.pp.
+This parameter no longer does anything. It exists only for backwards compatibility. See the `root_password` parameter above for details on changing the root password.
 
-#####`service_provider`
-
-The provider to use to manage the service. For Ubuntu, defaults to 'upstart'; otherwise, default is undefined.
-
-#####`users`
-
-Optional hash of users to create, which are passed to [mysql_user](#mysql_user). 
+#####  `create_root_login_file`
 
-~~~
-users => {
-  'someuser@localhost' => {
-    ensure                   => 'present',
-    max_connections_per_hour => '0',
-    max_queries_per_hour     => '0',
-    max_updates_per_hour     => '0',
-    max_user_connections     => '0',
-    password_hash            => '*F3A2A51A9B0F2BE2468926B4132313728C250DBF',
-  },
-}
-~~~
-
-#####`grants`
-
-Optional hash of grants, which are passed to [mysql_grant](#mysql_grant). 
-
-~~~
-grants => {
-  'someuser@localhost/somedb.*' => {
-    ensure     => 'present',
-    options    => ['GRANT'],
-    privileges => ['SELECT', 'INSERT', 'UPDATE', 'DELETE'],
-    table      => 'somedb.*',
-    user       => 'someuser@localhost',
-  },
-}
-~~~
+Whether to create `/root/.mylogin.cnf` when using mysql 5.6.6+.
 
-#####`databases`
-
-Optional hash of databases to create, which are passed to [mysql_database](#mysql_database).
-
-~~~
-databases   => {
-  'somedb'  => {
-    ensure  => 'present',
-    charset => 'utf8',
-  },
-}
-~~~
-
-####mysql::server::backup
-
-#####`backupuser`
+Valid values are `true`, `false`.
 
-MySQL user to create for backups.
-
-#####`backuppassword`
-
-MySQL user password for backups.
-
-#####`backupdir`
-
-Directory in which to store backups.
-
-#####`backupdirmode`
-
-Permissions applied to the backup directory. This parameter is passed directly
-to the `file` resource.
-
-#####`backupdirowner`
-
-Owner for the backup directory. This parameter is passed directly to the `file`
-resource.
+Defaults to `false`.
 
-#####`backupdirgroup`
-
-Group owner for the backup directory. This parameter is passed directly to the
-`file` resource.
-
-#####`backupcompress`
-
-Whether backups should be compressed. Valid values are 'true', 'false'. Defaults to 'true'.
-
-#####`backuprotate`
-
-How many days to keep backups. Valid value is an integer. Defaults to '30'.
-
-#####`delete_before_dump`
-
-Whether to delete old .sql files before backing up. Setting to 'true' deletes old files before backing up, while setting to 'false' deletes them after backup. Valid values are 'true', 'false'. Defaults to 'false'.
+`create_root_login_file` will put a copy of your existing `.mylogin.cnf` in the  `/root/.mylogin.cnf` location.
 
-#####`backupdatabases`
-
-Specify an array of databases to back up.
-
-#####`file_per_database`
-
-Whether a separate file be used per database. Valid values are 'true', 'false'. Defaults to 'false'.
-
-#####`ensure`
-
-Allows you to remove the backup scripts. Valid values are 'present', 'absent'. Defaults to 'present'.
-
-#####`execpath`
-
-Allows you to set a custom PATH should your MySQL installation be non-standard places. Defaults to `/usr/bin:/usr/sbin:/bin:/sbin`.
-
-#####`time`
+When set to 'true', this option also requires the `login_file` option.
 
-An array of two elements to set the backup time. Allows ['23', '5'] (i.e., 23:05) or ['3', '45'] (i.e., 03:45) for HH:MM times.
-
-#####`postscript`
-
-A script that is executed at when the backup is finished. This could be used to (r)sync the backup to a central store. This script can be either a single line that is directly executed or a number of lines supplied as an array. It could also be one or more externally managed (executable) files.
-
-#####`provider`
-
-Sets the server backup implementation. Valid values are:
-
-* `mysqldump`: Implements backups with mysqldump. Backup type: Logical. This is the default value.
-* `mysqlbackup`: Implements backups with MySQL Enterprise Backup from Oracle. Backup type: Physical. To use this type of backup, you'll need the `meb` package, which is available in RPM and TAR formats from Oracle. For Ubuntu, you can use [meb-deb](https://github.com/dveeden/meb-deb) to create a package from an official tarball.
-* `xtrabackup`: Implements backups with XtraBackup from Percona. Backup type: Physical.
-
-####mysql::server::monitor
-
-#####`mysql_monitor_username`
+The `login_file` option is required when set to true.
 
-The username to create for MySQL monitoring.
-
-#####`mysql_monitor_password`
-
-The password to create for MySQL monitoring.
-
-#####`mysql_monitor_hostname`
-
-The hostname from which the monitoring user requests are allowed access. 
-
-####mysql::server::mysqltuner
-
-**Note**: If you're using this class on a non-network-connected system, you must download the mysqltuner.pl script and have it hosted somewhere accessible via `http(s)://`, `puppet://`, `ftp://`, or a fully qualified file path.
-
-##### `ensure`
-
-Ensures that the resource exists. Valid values are `present`, `absent`. Defaults to `present`.
-
-##### `version`
+#### `login_file`
 
-The version to install from the major/MySQLTuner-perl github repository. Must be a valid tag. Defaults to 'v1.3.0'.
-
-##### `source`
-
-Parameter to optionally specify the source. If not specified, defaults to `https://github.com/major/MySQLTuner-perl/raw/${version}/mysqltuner.pl`
-
-####mysql::bindings
-
-##### `client_dev`
-
-Specify whether `::mysql::bindings::client_dev` should be included. Valid values are true', 'false'. Defaults to 'false'.
-
-##### `daemon_dev`
-
-Specify whether `::mysql::bindings::daemon_dev` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
-
-##### `java_enable`
+Whether to put the `/root/.mylogin.cnf` in place.
 
-Specify whether `::mysql::bindings::java` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
-
-##### `perl_enable`
-
-Specify whether `mysql::bindings::perl` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
-
-##### `php_enable`
-
-Specify whether `mysql::bindings::php` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
-
-##### `python_enable`
-
-Specify whether `mysql::bindings::python` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
-
-##### `ruby_enable`
-
-Specify whether `mysql::bindings::ruby` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
-
-##### `install_options`
+You need to create the `.mylogin.cnf` file with `mysql_config_editor`, this tool comes with mysql 5.6.6+.
 
-Pass `install_options` array to managed package resources. You must pass the [appropriate options](https://docs.puppetlabs.com/references/latest/type.html#package-attribute-install_options) for the package manager(s).
-
-##### `client_dev_package_ensure`
-
-Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `client_dev => true`.
- 
-##### `client_dev_package_name`
-
-The name of the client_dev package to install. Only applies if `client_dev => true`.
- 
-##### `client_dev_package_provider`
-
-The provider to use to install the client_dev package. Only applies if `client_dev => true`.
-
-##### `daemon_dev_package_ensure`
-
-Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `daemon_dev => true`.
+The created .mylogin.cnf needs to be put under files in your module, see example below on how to use this.
 
-##### `daemon_dev_package_name`
-
-The name of the daemon_dev package to install. Only applies if `daemon_dev => true`.
-
-##### `daemon_dev_package_provider`
-
-The provider to use to install the daemon_dev package. Only applies if `daemon_dev => true`.
-
-#####`java_package_ensure`
+When the `/root/.mylogin.cnf` exists the environment variable `MYSQL_TEST_LOGIN_FILE` will be set.
 
-Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `java_enable => true`.
-
-#####`java_package_name`
-
-The name of the Java package to install. Only applies if `java_enable => true`.
-
-#####`java_package_provider`
-
-The provider to use to install the Java package. Only applies if `java_enable => true`.
+This is required if `create_root_user` and `create_root_login_file` are true. If `root_password` is 'UNSET', then `create_root_user` and `create_root_login_file` are assumed to be false --- that is, the MySQL root user and `/root/.mylogin.cnf` are not created.
 
-#####`perl_package_ensure`
-
-Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `perl_enable => true`.
-
-#####`perl_package_name`
-
-The name of the Perl package to install. Only applies if `perl_enable => true`.
-
-#####`perl_package_provider`
-
-The provider to use to install the Perl package. Only applies if `perl_enable => true`.
-
-##### `php_package_ensure`
-
-Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `php_enable => true`.
- 
-##### `php_package_name`
-
-The name of the PHP package to install. Only applies if `php_enable => true`.
-
-#####`python_package_ensure`
-
-Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `python_enable => true`.
-
-#####`python_package_name`
-
-The name of the Python package to install. Only applies if `python_enable => true`.
-
-#####`python_package_provider`
-
-The provider to use to install the PHP package. Only applies if `python_enable => true`.
-
-#####`ruby_package_ensure`
-
-Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `ruby_enable => true`.
-
-#####`ruby_package_name`
-
-The name of the Ruby package to install. Only applies if `ruby_enable => true`.
-
-#####`ruby_package_provider`
-
-What provider should be used to install the package.
-
-####mysql::client
-
-#####`bindings_enable`
-
-Whether to automatically install all bindings. Valid values are 'true', 'false'. Default to 'false'.
-
-#####`install_options`
-Array of install options for managed package resources. You must pass the appropriate options for the package manager.
-
-#####`package_ensure`
-
-Whether the MySQL package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'.
-
-#####`package_manage`
-
-Whether to manage the mysql client package. Defaults to true.
-
-#####`package_name`
-
-The name of the MySQL client package to install.
-
-###Defined Types
-
-####mysql::db
+```puppet
+class { '::mysql::server':
+root_password          => 'password',
+create_root_my_cnf     => false,
+create_root_login_file => true,
+login_file             => "puppet:///modules/${module_name}/mylogin.cnf",
+}
+```
 
-~~~
-mysql_database { 'information_schema':
-  ensure  => 'present',
-  charset => 'utf8',
-  collate => 'utf8_swedish_ci',
-}
-mysql_database { 'mysql':
-  ensure  => 'present',
-  charset => 'latin1',
-  collate => 'latin1_swedish_ci',
-}
-~~~
-
-##### `user`
-
-The user for the database you're creating.
- 
-##### `password`
+##### `override_options`
 
-The password for $user for the database you're creating.
-
-##### `dbname`
-
-The name of the database to create. Defaults to $name.
- 
-##### `charset`
-
-The character set for the database. Defaults to 'utf8'.
-
-##### `collate`
-
-The collation for the database. Defaults to 'utf8_general_ci'.
- 
-##### `host`
-
-The host to use as part of user@host for grants. Defaults to 'localhost'.
-
-##### `grant`
+Specifies override options to pass into MySQL. Structured like a hash in the my.cnf file:
 
-The privileges to be granted for user@host on the database. Defaults to 'ALL'.
-
-##### `sql`
-
-The path to the sqlfile you want to execute. This can be single file specified as string, or it can be an array of strings. Defaults to undef.
-
-##### `enforce_sql`
-
-Specify whether executing the sqlfiles should happen on every run. If set to 'false', sqlfiles only run once. Valid values are 'true', 'false'. Defaults to 'false'.
- 
-##### `ensure`
-
-Specify whether to create the database. Valid values are 'present', 'absent'. Defaults to 'present'. 
-
-##### `import_timeout`
-
-Timeout, in seconds, for loading the sqlfiles. Defaults to '300'.
-
-
-###Types
-
-####mysql_database
-
-`mysql_database` creates and manages databases within MySQL.
-
-##### `ensure`
-
-Whether the resource is present. Valid values are 'present', 'absent'. Defaults to 'present'.
-
-##### `name`
-
-The name of the MySQL database to manage.
-
-##### `charset`
-
-The CHARACTER SET setting for the database. Defaults to ':utf8'.
-
-##### `collate`
+```puppet
+class { 'mysql::server':
+  root_password => 'password'
+}
 
-The COLLATE setting for the database. Defaults to ':utf8_general_ci'. 
-
-####mysql_user
-
-Creates and manages user grants within MySQL.
-
-~~~
-mysql_user { 'root@127.0.0.1':
-  ensure                   => 'present',
-  max_connections_per_hour => '0',
-  max_queries_per_hour     => '0',
-  max_updates_per_hour     => '0',
-  max_user_connections     => '0',
-}
-~~~
-
-You can also specify an authentication plugin.
-
-~~~
-mysql_user{ 'myuser'@'localhost':
-  ensure                   => 'present',
-  plugin                   => 'unix_socket',
-}
-~~~
-
-##### `name`
-
-The name of the user, as 'username@hostname' or username@hostname.
-
-##### `password_hash`
-
-The user's password hash of the user. Use mysql_password() for creating such a hash.
-
-##### `max_user_connections`
-
-Maximum concurrent connections for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
-
-##### `max_connections_per_hour`
-
-Maximum connections per hour for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
-
-##### `max_queries_per_hour`
-
-Maximum queries per hour for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
-
-##### `max_updates_per_hour`
-
-Maximum updates per hour for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
-
-
-####mysql_grant
-
-`mysql_grant` creates grant permissions to access databases within
-MySQL. To use it you must create the title of the resource as shown below,
-following the pattern of `username@hostname/database.table`:
-
-~~~
-mysql_grant { 'root@localhost/*.*':
-  ensure     => 'present',
-  options    => ['GRANT'],
-  privileges => ['ALL'],
-  table      => '*.*',
-  user       => 'root@localhost',
-}
-~~~
-
-It is possible to specify privileges down to the column level:
-
-~~~
-mysql_grant { 'root@localhost/mysql.user':
-  ensure     => 'present',
-  privileges => ['SELECT (Host, User)'],
-  table      => 'mysql.user',
-  user       => 'root@localhost',
+mysql_plugin { 'auth_pam':
+  ensure => present,
+  soname => 'auth_pam.so',
 }
-~~~
-
-##### `ensure`
-
-Whether the resource is present. Valid values are 'present', 'absent'. Defaults to 'present'.
-
-##### `name`
 
-Name to describe the grant. Must in a 'user/table' format. 
-
-##### `privileges`
+```
 
-Privileges to grant the user.
-
-##### `table`
-
-The table to which privileges are applied.
+### Tasks
 
-##### `user`
-
-User to whom privileges are granted.
-
-##### `options`
-
-MySQL options to grant. Optional.
+The MySQL module has an example task that allows a user to execute arbitary SQL against a database. Please refer to to the [PE documentation](https://puppet.com/docs/pe/2017.3/orchestrator/running_tasks.html) or [Bolt documentation](https://puppet.com/docs/bolt/latest/bolt.html) on how to execute a task.
 
-####mysql_plugin
-
-`mysql_plugin` can be used to load plugins into the MySQL Server.
+## Limitations
 
-~~~
-mysql_plugin { 'auth_socket':
-  ensure     => 'present',
-  soname     => 'auth_socket.so',
-}
-~~~
+For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-mysql/blob/master/metadata.json)
 
-##### `ensure`
-
-Whether the resource is present. Valid values are 'present', 'absent'. Defaults to 'present'.
-
-##### `name`
-
-The name of the MySQL plugin to manage.
+**Note:** The mysqlbackup.sh does not work and is not supported on MySQL 5.7 and greater.
 
-##### `soname`
-
-The library file name.
+## Development
 
-##Limitations
-
-This module has been tested on:
+We are experimenting with a new tool for running acceptance tests. Its name is [puppet_litmus](https://github.com/puppetlabs/puppet_litmus) this replaces beaker as the test runner. To run the acceptance tests follow the instructions from this point [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).
 
-* RedHat Enterprise Linux 5, 6, 7
-* Debian 6, 7
-* CentOS 5, 6, 7
-* Ubuntu 10.04, 12.04, 14.04
-* Scientific Linux 5, 6
-* SLES 11
-
-Testing on other platforms has been minimal and cannot be guaranteed.
-
-#Development
+Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can't access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
 
-Puppet Labs modules on the Puppet Forge are open projects, and community
-contributions are essential for keeping them great. We can’t access the
-huge number of platforms and myriad of hardware, software, and deployment
-configurations that Puppet is intended to serve.
+We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
 
-We want to keep it as easy as possible to contribute changes so that our
-modules work in your environment. There are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of things.
-
-Check out our the complete [module contribution guide](https://docs.puppetlabs.com/forge/contributing.html).
+Check out our the complete [module contribution guide](https://puppet.com/docs/puppet/latest/contributing.html).
 
 ### Authors
 
@@ -808,4 +544,5 @@
 * Michael Arnold
 * Chris Weyl
 * Daniël van Eeden
-
+* Jan-Otto Kröpke
+* Timothy Sven Nelson