dev/provisioning/modules/mysql/README.md
changeset 28 b0b56e0f8c7f
child 146 dc4d1cdc47e0
equal deleted inserted replaced
27:a2342f26c9de 28:b0b56e0f8c7f
       
     1 # mysql
       
     2 
       
     3 #### Table of Contents
       
     4 
       
     5 1. [Module Description - What the module does and why it is useful](#module-description)
       
     6 2. [Backwards compatibility information](#backwards-compatibility)
       
     7 3. [Setup - The basics of getting started with mysql](#setup)
       
     8     * [Beginning with mysql](#beginning-with-mysql)
       
     9 4. [Usage - Configuration options and additional functionality](#usage)
       
    10     * [Customizing Server Options](#customizing-server-options)
       
    11     * [Creating a Database](#creating-a-database)
       
    12     * [Custom Configuration](#custom-configuration)
       
    13 5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
       
    14 6. [Limitations - OS compatibility, etc.](#limitations)
       
    15 7. [Development - Guide for contributing to the module](#development)
       
    16 
       
    17 ## Module Description
       
    18 
       
    19 The MySQL module installs, configures, and manages the MySQL service.
       
    20 
       
    21 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.
       
    22 
       
    23 ## Setup
       
    24 
       
    25 ### Beginning with MySQL
       
    26 
       
    27 If you want a server installed with the default options you can run
       
    28 `include '::mysql::server'`. 
       
    29 
       
    30 If you need to customize options, such as the root
       
    31 password or `/etc/my.cnf` settings, then you must also pass in an override hash:
       
    32 
       
    33 ~~~
       
    34 class { '::mysql::server':
       
    35   root_password           => 'strongpassword',
       
    36   remove_default_accounts => true,
       
    37   override_options        => $override_options
       
    38 }
       
    39 ~~~
       
    40 
       
    41 See [**Customizing Server Options**](#customizing-server-options) below for examples of the hash structure for $override_options`.
       
    42 
       
    43 ## Usage
       
    44 
       
    45 All interaction for the server is done via `mysql::server`. To install the client, use `mysql::client`. To install bindings, use `mysql::bindings`.
       
    46 
       
    47 ### Customizing Server Options
       
    48 
       
    49 The hash structure for overrides in `mysql::server` can be structured like a hash in the my.cnf file, so:
       
    50 
       
    51 ~~~
       
    52 $override_options = {
       
    53   'section' => {
       
    54     'item' => 'thing',
       
    55   }
       
    56 }
       
    57 ~~~
       
    58 
       
    59 For items that you would traditionally represent as
       
    60 
       
    61 ~~~
       
    62 [section]
       
    63 thing = X
       
    64 ~~~
       
    65 
       
    66 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. 
       
    67 
       
    68 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`.
       
    69 
       
    70 If an option needs multiple instances, you can pass an array. For example,
       
    71 
       
    72 ~~~
       
    73 $override_options = {
       
    74   'mysqld' => {
       
    75     'replicate-do-db' => ['base1', 'base2'],
       
    76   }
       
    77 }
       
    78 ~~~
       
    79 
       
    80 produces
       
    81 
       
    82 ~~~
       
    83 [mysqld]
       
    84 replicate-do-db = base1
       
    85 replicate-do-db = base2
       
    86 ~~~
       
    87 
       
    88 ### Creating a database
       
    89 
       
    90 To use `mysql::db` to create a database with a user and assign some privileges:
       
    91 
       
    92 ~~~
       
    93 mysql::db { 'mydb':
       
    94   user     => 'myuser',
       
    95   password => 'mypass',
       
    96   host     => 'localhost',
       
    97   grant    => ['SELECT', 'UPDATE'],
       
    98 }
       
    99 ~~~
       
   100 
       
   101 Or to use a different resource name with exported resources:
       
   102 
       
   103 ~~~
       
   104  @@mysql::db { "mydb_${fqdn}":
       
   105   user     => 'myuser',
       
   106   password => 'mypass',
       
   107   dbname   => 'mydb',
       
   108   host     => ${fqdn},
       
   109   grant    => ['SELECT', 'UPDATE'],
       
   110   tag      => $domain,
       
   111 }
       
   112 ~~~
       
   113 
       
   114 Then you can collect it on the remote DB server:
       
   115 
       
   116 ~~~
       
   117 Mysql::Db <<| tag == $domain |>>
       
   118 ~~~
       
   119 
       
   120 If you set the sql param to a file when creating a database, the file gets imported into the new database.
       
   121 
       
   122 For large sql files, you should raise the $import_timeout parameter, set by default to 300 seconds.
       
   123 
       
   124 ~~~
       
   125 mysql::db { 'mydb':
       
   126   user     => 'myuser',
       
   127   password => 'mypass',
       
   128   host     => 'localhost',
       
   129   grant    => ['SELECT', 'UPDATE'],
       
   130   sql      => '/path/to/sqlfile',
       
   131   import_timeout => 900,
       
   132 }
       
   133 ~~~
       
   134 
       
   135 ### Custom Configuration
       
   136 
       
   137 To add custom MySQL configuration, drop additional files into
       
   138 `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.
       
   139 
       
   140 ### Working with an existing server
       
   141 
       
   142 You can use the MySQL module to instantiate databases and
       
   143 users on an existing MySQL server. For this to work, you need an
       
   144 appropriate `.my.cnf` in `root`'s home directory containing the remote
       
   145 server address and credentials. For example:
       
   146 
       
   147     [client]
       
   148     user=root
       
   149     host=localhost
       
   150     password=secret
       
   151 
       
   152 When working with a remote server, do *not* use the
       
   153 `mysql::server` class in your Puppet manifests.
       
   154 
       
   155 ## Reference
       
   156 
       
   157 ### Classes
       
   158 
       
   159 #### Public classes
       
   160 
       
   161 * [`mysql::server`](#mysqlserver): Installs and configures MySQL.
       
   162 * [`mysql::server::monitor`](#mysqlservermonitor): Sets up a monitoring user.
       
   163 * [`mysql::server::mysqltuner`](#mysqlservermysqltuner): Installs MySQL tuner script.
       
   164 * [`mysql::server::backup`](#mysqlserverbackup): Sets up MySQL backups via cron.
       
   165 * [`mysql::bindings`](#mysqlbindings): Installs various MySQL language bindings.
       
   166 * [`mysql::client`](#mysqlclient): Installs MySQL client (for non-servers).
       
   167 
       
   168 #### Private classes
       
   169 
       
   170 * `mysql::server::install`: Installs packages.
       
   171 * `mysql::server::config`: Configures MYSQL.
       
   172 * `mysql::server::service`: Manages service.
       
   173 * `mysql::server::account_security`: Deletes default MySQL accounts.
       
   174 * `mysql::server::root_password`: Sets MySQL root password.
       
   175 * `mysql::server::providers`: Creates users, grants, and databases.
       
   176 * `mysql::bindings::client_dev`: Installs MySQL client development package.
       
   177 * `mysql::bindings::daemon_dev`: Installs MySQL daemon development package.
       
   178 * `mysql::bindings::java`: Installs Java bindings.
       
   179 * `mysql::bindings::perl`: Installs Perl bindings.
       
   180 * `mysql::bindings::php`: Installs PHP bindings.
       
   181 * `mysql::bindings::python`: Installs Python bindings.
       
   182 * `mysql::bindings::ruby`: Installs Ruby bindings.
       
   183 * `mysql::client::install`:  Installs MySQL client.
       
   184 * `mysql::backup::mysqldump`: Implements mysqldump backups.
       
   185 * `mysql::backup::mysqlbackup`: Implements backups with Oracle MySQL Enterprise Backup.
       
   186 * `mysql::backup::xtrabackup`: Implements backups with XtraBackup from Percona.
       
   187 
       
   188 ### Parameters
       
   189 
       
   190 #### mysql::server
       
   191 
       
   192 ##### `create_root_user`
       
   193 
       
   194 Specify whether root user should be created. Valid values are 'true', 'false'. Defaults to 'true'.
       
   195 
       
   196 This is useful for a cluster setup with Galera. The root user has to
       
   197 be created only once. `create_root_user` can be set to 'true' on one node while
       
   198 it is set to 'false' on the remaining nodes.
       
   199 
       
   200 #####  `create_root_my_cnf`
       
   201 
       
   202 If set to 'true', creates `/root/.my.cnf`. Valid values are 'true', 'false'. Defaults to 'true'.
       
   203 
       
   204 `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.
       
   205 
       
   206 #####  `root_password`
       
   207 
       
   208 The MySQL root password. Puppet attempts to set the root password and update `/root/.my.cnf` with it.
       
   209 
       
   210 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.
       
   211 
       
   212 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. 
       
   213 
       
   214 ##### `old_root_password`
       
   215 
       
   216 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.
       
   217 
       
   218 ##### `override_options`
       
   219 
       
   220 The hash of override options to pass into MySQL. Structured like a hash in the my.cnf file:
       
   221 
       
   222 ~~~
       
   223 $override_options = {
       
   224   'section' => {
       
   225     'item'             => 'thing',
       
   226   }
       
   227 }
       
   228 ~~~
       
   229 
       
   230 See [**Customizing Server Options**](#customizing-server-options) above for usage details.
       
   231 
       
   232 ##### `config_file`
       
   233 
       
   234 The location, as a path, of the MySQL configuration file.
       
   235 
       
   236 ##### `manage_config_file`
       
   237 
       
   238 Whether the MySQL configuration file should be managed. Valid values are 'true', 'false'. Defaults to 'true'.
       
   239 
       
   240 ##### `includedir`
       
   241 The location, as a path, of !includedir for custom configuration overrides.
       
   242 
       
   243 ##### `install_options`
       
   244 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.
       
   245 
       
   246 ##### `purge_conf_dir`
       
   247 
       
   248 Whether the `includedir` directory should be purged. Valid values are 'true', 'false'. Defaults to 'false'.
       
   249 
       
   250 ##### `restart`
       
   251 
       
   252 Whether the service should be restarted when things change. Valid values are 'true', 'false'. Defaults to 'false'.
       
   253 
       
   254 ##### `root_group`
       
   255 
       
   256 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).
       
   257 
       
   258 ##### `mysql_group`
       
   259 
       
   260 The name of the group of the MySQL daemon user. 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).
       
   261 
       
   262 ##### `package_ensure`
       
   263 
       
   264 Whether the package exists or should be a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Defaults to 'present'.
       
   265 
       
   266 ##### `package_manage`
       
   267 
       
   268 Whether to manage the MySQL server package. Defaults to true.
       
   269 
       
   270 ##### `package_name`
       
   271 
       
   272 The name of the MySQL server package to install.
       
   273 
       
   274 ##### `remove_default_accounts`
       
   275 
       
   276 Specify whether to automatically include `mysql::server::account_security`. Valid values are 'true', 'false'. Defaults to 'false'.
       
   277 
       
   278 ##### `service_enabled`
       
   279 
       
   280 Specify whether the service should be enabled. Valid values are 'true', 'false'. Defaults to 'true'.
       
   281 
       
   282 ##### `service_manage`
       
   283 
       
   284 Specify whether the service should be managed. Valid values are 'true', 'false'. Defaults to 'true'.
       
   285 
       
   286 ##### `service_name`
       
   287 
       
   288 The name of the MySQL server service. Defaults are OS dependent, defined in params.pp.
       
   289 
       
   290 ##### `service_provider`
       
   291 
       
   292 The provider to use to manage the service. For Ubuntu, defaults to 'upstart'; otherwise, default is undefined.
       
   293 
       
   294 ##### `users`
       
   295 
       
   296 Optional hash of users to create, which are passed to [mysql_user](#mysql_user). 
       
   297 
       
   298 ~~~
       
   299 users => {
       
   300   'someuser@localhost' => {
       
   301     ensure                   => 'present',
       
   302     max_connections_per_hour => '0',
       
   303     max_queries_per_hour     => '0',
       
   304     max_updates_per_hour     => '0',
       
   305     max_user_connections     => '0',
       
   306     password_hash            => '*F3A2A51A9B0F2BE2468926B4132313728C250DBF',
       
   307   },
       
   308 }
       
   309 ~~~
       
   310 
       
   311 ##### `grants`
       
   312 
       
   313 Optional hash of grants, which are passed to [mysql_grant](#mysql_grant). 
       
   314 
       
   315 ~~~
       
   316 grants => {
       
   317   'someuser@localhost/somedb.*' => {
       
   318     ensure     => 'present',
       
   319     options    => ['GRANT'],
       
   320     privileges => ['SELECT', 'INSERT', 'UPDATE', 'DELETE'],
       
   321     table      => 'somedb.*',
       
   322     user       => 'someuser@localhost',
       
   323   },
       
   324 }
       
   325 ~~~
       
   326 
       
   327 ##### `databases`
       
   328 
       
   329 Optional hash of databases to create, which are passed to [mysql_database](#mysql_database).
       
   330 
       
   331 ~~~
       
   332 databases   => {
       
   333   'somedb'  => {
       
   334     ensure  => 'present',
       
   335     charset => 'utf8',
       
   336   },
       
   337 }
       
   338 ~~~
       
   339 
       
   340 #### mysql::server::backup
       
   341 
       
   342 ##### `backupuser`
       
   343 
       
   344 MySQL user to create for backups.
       
   345 
       
   346 ##### `backuppassword`
       
   347 
       
   348 MySQL user password for backups.
       
   349 
       
   350 ##### `backupdir`
       
   351 
       
   352 Directory in which to store backups.
       
   353 
       
   354 ##### `backupdirmode`
       
   355 
       
   356 Permissions applied to the backup directory. This parameter is passed directly
       
   357 to the `file` resource.
       
   358 
       
   359 ##### `backupdirowner`
       
   360 
       
   361 Owner for the backup directory. This parameter is passed directly to the `file`
       
   362 resource.
       
   363 
       
   364 ##### `backupdirgroup`
       
   365 
       
   366 Group owner for the backup directory. This parameter is passed directly to the
       
   367 `file` resource.
       
   368 
       
   369 ##### `backupcompress`
       
   370 
       
   371 Whether backups should be compressed. Valid values are 'true', 'false'. Defaults to 'true'.
       
   372 
       
   373 ##### `backuprotate`
       
   374 
       
   375 How many days to keep backups. Valid value is an integer. Defaults to '30'.
       
   376 
       
   377 ##### `delete_before_dump`
       
   378 
       
   379 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'.
       
   380 
       
   381 ##### `backupdatabases`
       
   382 
       
   383 Specify an array of databases to back up.
       
   384 
       
   385 ##### `file_per_database`
       
   386 
       
   387 Whether a separate file be used per database. Valid values are 'true', 'false'. Defaults to 'false'.
       
   388 
       
   389 ##### `include_routines`
       
   390 
       
   391 Whether or not to include routines for each database when doing a `file_per_database` backup. Defaults to `false`.
       
   392 
       
   393 ##### `include_triggers`
       
   394 
       
   395 Whether or not to include triggers for each database when doing a `file_per_database` backup. Defaults to `false`.
       
   396 
       
   397 ##### `ensure`
       
   398 
       
   399 Allows you to remove the backup scripts. Valid values are 'present', 'absent'. Defaults to 'present'.
       
   400 
       
   401 ##### `execpath`
       
   402 
       
   403 Allows you to set a custom PATH should your MySQL installation be non-standard places. Defaults to `/usr/bin:/usr/sbin:/bin:/sbin`.
       
   404 
       
   405 ##### `time`
       
   406 
       
   407 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.
       
   408 
       
   409 ##### `postscript`
       
   410 
       
   411 A script that is executed 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.
       
   412 
       
   413 ##### `prescript`
       
   414 
       
   415 A script that is executed before the backup begins.
       
   416 
       
   417 ##### `provider`
       
   418 
       
   419 Sets the server backup implementation. Valid values are:
       
   420 
       
   421 * `mysqldump`: Implements backups with mysqldump. Backup type: Logical. This is the default value.
       
   422 * `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.
       
   423 * `xtrabackup`: Implements backups with XtraBackup from Percona. Backup type: Physical.
       
   424 
       
   425 #### mysql::server::monitor
       
   426 
       
   427 ##### `mysql_monitor_username`
       
   428 
       
   429 The username to create for MySQL monitoring.
       
   430 
       
   431 ##### `mysql_monitor_password`
       
   432 
       
   433 The password to create for MySQL monitoring.
       
   434 
       
   435 ##### `mysql_monitor_hostname`
       
   436 
       
   437 The hostname from which the monitoring user requests are allowed access. 
       
   438 
       
   439 #### mysql::server::mysqltuner
       
   440 
       
   441 **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.
       
   442 
       
   443 ##### `ensure`
       
   444 
       
   445 Ensures that the resource exists. Valid values are `present`, `absent`. Defaults to `present`.
       
   446 
       
   447 ##### `version`
       
   448 
       
   449 The version to install from the major/MySQLTuner-perl github repository. Must be a valid tag. Defaults to 'v1.3.0'.
       
   450 
       
   451 ##### `source`
       
   452 
       
   453 Parameter to optionally specify the source. If not specified, defaults to `https://github.com/major/MySQLTuner-perl/raw/${version}/mysqltuner.pl`
       
   454 
       
   455 #### mysql::bindings
       
   456 
       
   457 ##### `client_dev`
       
   458 
       
   459 Specify whether `::mysql::bindings::client_dev` should be included. Valid values are true', 'false'. Defaults to 'false'.
       
   460 
       
   461 ##### `daemon_dev`
       
   462 
       
   463 Specify whether `::mysql::bindings::daemon_dev` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
       
   464 
       
   465 ##### `java_enable`
       
   466 
       
   467 Specify whether `::mysql::bindings::java` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
       
   468 
       
   469 #####  `perl_enable`
       
   470 
       
   471 Specify whether `mysql::bindings::perl` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
       
   472 
       
   473 ##### `php_enable`
       
   474 
       
   475 Specify whether `mysql::bindings::php` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
       
   476 
       
   477 ##### `python_enable`
       
   478 
       
   479 Specify whether `mysql::bindings::python` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
       
   480 
       
   481 ##### `ruby_enable`
       
   482 
       
   483 Specify whether `mysql::bindings::ruby` should be included. Valid values are 'true', 'false'. Defaults to 'false'.
       
   484 
       
   485 ##### `install_options`
       
   486 
       
   487 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).
       
   488 
       
   489 ##### `client_dev_package_ensure`
       
   490 
       
   491 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`.
       
   492  
       
   493 ##### `client_dev_package_name`
       
   494 
       
   495 The name of the client_dev package to install. Only applies if `client_dev => true`.
       
   496  
       
   497 ##### `client_dev_package_provider`
       
   498 
       
   499 The provider to use to install the client_dev package. Only applies if `client_dev => true`.
       
   500 
       
   501 ##### `daemon_dev_package_ensure`
       
   502 
       
   503 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`.
       
   504 
       
   505 ##### `daemon_dev_package_name`
       
   506 
       
   507 The name of the daemon_dev package to install. Only applies if `daemon_dev => true`.
       
   508 
       
   509 ##### `daemon_dev_package_provider`
       
   510 
       
   511 The provider to use to install the daemon_dev package. Only applies if `daemon_dev => true`.
       
   512 
       
   513 ##### `java_package_ensure`
       
   514 
       
   515 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`.
       
   516 
       
   517 ##### `java_package_name`
       
   518 
       
   519 The name of the Java package to install. Only applies if `java_enable => true`.
       
   520 
       
   521 ##### `java_package_provider`
       
   522 
       
   523 The provider to use to install the Java package. Only applies if `java_enable => true`.
       
   524 
       
   525 ##### `perl_package_ensure`
       
   526 
       
   527 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`.
       
   528 
       
   529 ##### `perl_package_name`
       
   530 
       
   531 The name of the Perl package to install. Only applies if `perl_enable => true`.
       
   532 
       
   533 ##### `perl_package_provider`
       
   534 
       
   535 The provider to use to install the Perl package. Only applies if `perl_enable => true`.
       
   536 
       
   537 ##### `php_package_ensure`
       
   538 
       
   539 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`.
       
   540  
       
   541 ##### `php_package_name`
       
   542 
       
   543 The name of the PHP package to install. Only applies if `php_enable => true`.
       
   544 
       
   545 ##### `python_package_ensure`
       
   546 
       
   547 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`.
       
   548 
       
   549 ##### `python_package_name`
       
   550 
       
   551 The name of the Python package to install. Only applies if `python_enable => true`.
       
   552 
       
   553 ##### `python_package_provider`
       
   554 
       
   555 The provider to use to install the PHP package. Only applies if `python_enable => true`.
       
   556 
       
   557 ##### `ruby_package_ensure`
       
   558 
       
   559 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`.
       
   560 
       
   561 ##### `ruby_package_name`
       
   562 
       
   563 The name of the Ruby package to install. Only applies if `ruby_enable => true`.
       
   564 
       
   565 ##### `ruby_package_provider`
       
   566 
       
   567 What provider should be used to install the package.
       
   568 
       
   569 #### mysql::client
       
   570 
       
   571 ##### `bindings_enable`
       
   572 
       
   573 Whether to automatically install all bindings. Valid values are 'true', 'false'. Default to 'false'.
       
   574 
       
   575 ##### `install_options`
       
   576 Array of install options for managed package resources. You must pass the appropriate options for the package manager.
       
   577 
       
   578 ##### `package_ensure`
       
   579 
       
   580 Whether the MySQL package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'.
       
   581 
       
   582 ##### `package_manage`
       
   583 
       
   584 Whether to manage the MySQL client package. Defaults to true.
       
   585 
       
   586 ##### `package_name`
       
   587 
       
   588 The name of the MySQL client package to install.
       
   589 
       
   590 ### Defines
       
   591 
       
   592 #### mysql::db
       
   593 
       
   594 ~~~
       
   595 mysql_database { 'information_schema':
       
   596   ensure  => 'present',
       
   597   charset => 'utf8',
       
   598   collate => 'utf8_swedish_ci',
       
   599 }
       
   600 mysql_database { 'mysql':
       
   601   ensure  => 'present',
       
   602   charset => 'latin1',
       
   603   collate => 'latin1_swedish_ci',
       
   604 }
       
   605 ~~~
       
   606 
       
   607 ##### `user`
       
   608 
       
   609 The user for the database you're creating.
       
   610  
       
   611 ##### `password`
       
   612 
       
   613 The password for $user for the database you're creating.
       
   614 
       
   615 ##### `dbname`
       
   616 
       
   617 The name of the database to create. Defaults to $name.
       
   618  
       
   619 ##### `charset`
       
   620 
       
   621 The character set for the database. Defaults to 'utf8'.
       
   622 
       
   623 ##### `collate`
       
   624 
       
   625 The collation for the database. Defaults to 'utf8_general_ci'.
       
   626  
       
   627 ##### `host`
       
   628 
       
   629 The host to use as part of user@host for grants. Defaults to 'localhost'.
       
   630 
       
   631 ##### `grant`
       
   632 
       
   633 The privileges to be granted for user@host on the database. Defaults to 'ALL'.
       
   634 
       
   635 ##### `sql`
       
   636 
       
   637 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.
       
   638 
       
   639 ##### `enforce_sql`
       
   640 
       
   641 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'.
       
   642  
       
   643 ##### `ensure`
       
   644 
       
   645 Specify whether to create the database. Valid values are 'present', 'absent'. Defaults to 'present'. 
       
   646 
       
   647 ##### `import_timeout`
       
   648 
       
   649 Timeout, in seconds, for loading the sqlfiles. Defaults to '300'.
       
   650 
       
   651 ### Types
       
   652 
       
   653 #### mysql_database
       
   654 
       
   655 `mysql_database` creates and manages databases within MySQL.
       
   656 
       
   657 ##### `ensure`
       
   658 
       
   659 Whether the resource is present. Valid values are 'present', 'absent'. Defaults to 'present'.
       
   660 
       
   661 ##### `name`
       
   662 
       
   663 The name of the MySQL database to manage.
       
   664 
       
   665 ##### `charset`
       
   666 
       
   667 The CHARACTER SET setting for the database. Defaults to ':utf8'.
       
   668 
       
   669 ##### `collate`
       
   670 
       
   671 The COLLATE setting for the database. Defaults to ':utf8_general_ci'. 
       
   672 
       
   673 #### mysql_user
       
   674 
       
   675 Creates and manages user grants within MySQL.
       
   676 
       
   677 ~~~
       
   678 mysql_user { 'root@127.0.0.1':
       
   679   ensure                   => 'present',
       
   680   max_connections_per_hour => '0',
       
   681   max_queries_per_hour     => '0',
       
   682   max_updates_per_hour     => '0',
       
   683   max_user_connections     => '0',
       
   684 }
       
   685 ~~~
       
   686 
       
   687 You can also specify an authentication plugin.
       
   688 
       
   689 ~~~
       
   690 mysql_user{ 'myuser'@'localhost':
       
   691   ensure                   => 'present',
       
   692   plugin                   => 'unix_socket',
       
   693 }
       
   694 ~~~
       
   695 
       
   696 ##### `name`
       
   697 
       
   698 The name of the user, as 'username@hostname' or username@hostname.
       
   699 
       
   700 ##### `password_hash`
       
   701 
       
   702 The user's password hash of the user. Use mysql_password() for creating such a hash.
       
   703 
       
   704 ##### `max_user_connections`
       
   705 
       
   706 Maximum concurrent connections for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
       
   707 
       
   708 ##### `max_connections_per_hour`
       
   709 
       
   710 Maximum connections per hour for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
       
   711 
       
   712 ##### `max_queries_per_hour`
       
   713 
       
   714 Maximum queries per hour for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
       
   715 
       
   716 ##### `max_updates_per_hour`
       
   717 
       
   718 Maximum updates per hour for the user. Must be an integer value. A value of '0' specifies no (or global) limit.
       
   719 
       
   720 
       
   721 #### mysql_grant
       
   722 
       
   723 `mysql_grant` creates grant permissions to access databases within
       
   724 MySQL. To create grant permissions to access databases with MySQL, use it you must create the title of the resource as shown below,
       
   725 following the pattern of `username@hostname/database.table`:
       
   726 
       
   727 ~~~
       
   728 mysql_grant { 'root@localhost/*.*':
       
   729   ensure     => 'present',
       
   730   options    => ['GRANT'],
       
   731   privileges => ['ALL'],
       
   732   table      => '*.*',
       
   733   user       => 'root@localhost',
       
   734 }
       
   735 ~~~
       
   736 
       
   737 It is possible to specify privileges down to the column level:
       
   738 
       
   739 ~~~
       
   740 mysql_grant { 'root@localhost/mysql.user':
       
   741   ensure     => 'present',
       
   742   privileges => ['SELECT (Host, User)'],
       
   743   table      => 'mysql.user',
       
   744   user       => 'root@localhost',
       
   745 }
       
   746 ~~~
       
   747 
       
   748 ##### `ensure`
       
   749 
       
   750 Whether the resource is present. Valid values are 'present', 'absent'. Defaults to 'present'.
       
   751 
       
   752 ##### `name`
       
   753 
       
   754 Name to describe the grant. Must in a 'user/table' format. 
       
   755 
       
   756 ##### `privileges`
       
   757 
       
   758 Privileges to grant the user.
       
   759 
       
   760 ##### `table`
       
   761 
       
   762 The table to which privileges are applied.
       
   763 
       
   764 ##### `user`
       
   765 
       
   766 User to whom privileges are granted.
       
   767 
       
   768 ##### `options`
       
   769 
       
   770 MySQL options to grant. Optional.
       
   771 
       
   772 #### mysql_plugin
       
   773 
       
   774 `mysql_plugin` can be used to load plugins into the MySQL Server.
       
   775 
       
   776 ~~~
       
   777 mysql_plugin { 'auth_socket':
       
   778   ensure     => 'present',
       
   779   soname     => 'auth_socket.so',
       
   780 }
       
   781 ~~~
       
   782 
       
   783 ##### `ensure`
       
   784 
       
   785 Whether the resource is present. Valid values are 'present', 'absent'. Defaults to 'present'.
       
   786 
       
   787 ##### `name`
       
   788 
       
   789 The name of the MySQL plugin to manage.
       
   790 
       
   791 #####  `soname`
       
   792 
       
   793 The library file name.
       
   794 
       
   795 ### Facts
       
   796 
       
   797 #### `mysql_version`
       
   798 
       
   799 Determines the MySQL version by parsing the output from `mysql --version`
       
   800 
       
   801 #### `mysql_server_id`
       
   802 
       
   803 Generates a unique id, based on the node's MAC address, which can be used as
       
   804 `server_id`. This fact will *always* return `0` on nodes that have only
       
   805 loopback interfaces. Because those nodes aren't connected to the outside world, this shouldn't cause any conflicts.
       
   806 
       
   807 ## Limitations
       
   808 
       
   809 This module has been tested on:
       
   810 
       
   811 * RedHat Enterprise Linux 5, 6, 7
       
   812 * Debian 6, 7
       
   813 * CentOS 5, 6, 7
       
   814 * Ubuntu 10.04, 12.04, 14.04
       
   815 * Scientific Linux 5, 6
       
   816 * SLES 11
       
   817 
       
   818 Testing on other platforms has been minimal and cannot be guaranteed.
       
   819 
       
   820 ## Development
       
   821 
       
   822 Puppet Labs modules on the Puppet Forge are open projects, and community
       
   823 contributions are essential for keeping them great. We can't access the
       
   824 huge number of platforms and myriad of hardware, software, and deployment
       
   825 configurations that Puppet is intended to serve.
       
   826 
       
   827 We want to keep it as easy as possible to contribute changes so that our
       
   828 modules work in your environment. There are a few guidelines that we need
       
   829 contributors to follow so that we can have a chance of keeping on top of things.
       
   830 
       
   831 Check out our the complete [module contribution guide](https://docs.puppetlabs.com/forge/contributing.html).
       
   832 
       
   833 ### Authors
       
   834 
       
   835 This module is based on work by David Schmitt. The following contributors have contributed to this module (beyond Puppet Labs):
       
   836 
       
   837 * Larry Ludwig
       
   838 * Christian G. Warden
       
   839 * Daniel Black
       
   840 * Justin Ellison
       
   841 * Lowe Schmidt
       
   842 * Matthias Pigulla
       
   843 * William Van Hevelingen
       
   844 * Michael Arnold
       
   845 * Chris Weyl
       
   846 * Daniƫl van Eeden
       
   847