mysql

#MySQL

####Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with mysql
   • What mysql affects
   • Setup requirements
   • Beginning with mysql
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

##Overview

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 extends Pupppet to allow management of MySQL resources, such as databases, users, and grants.

##Backwards Compatibility

This module has just undergone a very large rewrite. As a result it will no longer work with the previous classes and configuration as before. We've attempted to handle backwards compatibility automatically by adding a attempt_compatibility_mode parameter to the main mysql class. If you set this to true it will attempt to map your previous parameters into the new mysql::server class.

###WARNING

This may fail. It may eat your MySQL server. PLEASE test it before running it live. Even if it's just a no-op and a manual comparision. Please be careful!

##Setup

###What MySQL affects

• MySQL package.
• MySQL configuration files.
• MySQL service.

###Beginning with MySQL

If you just want a server installing with the default options you can run include '::mysql::server'. If you need to customize options, such as the root password or /etc/my.cnf settings then you can also include mysql::server and pass in an override hash as seen below:

class { '::mysql::server':
  root_password    => 'strongpassword',
  override_options => { 'mysqld' => { 'max_connections' => '1024' } }
}

##Usage

All interaction for the server is done via mysql::server. To install the client you use mysql::client, and to install bindings you can use mysql::bindings.

###Overrides

The hash structure for overrides in mysql::server is as follows:

$override_options = {
  'section' => {
    'item'             => 'thing',
  }
}

For items that you would traditionally represent as:

You can just make an entry like thing => true in the hash. MySQL doesn't care if thing is alone or set to a value, it'll happily accept both.

###Custom configuration

To add custom mysql configuration you can drop additional files into /etc/mysql/conf.d/ in order to override settings or add additional ones (if you choose not to use override_options in mysql::server). This location is hardcoded into the my.cnf template file.

##Reference

###Classes

####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).

####Private classes

• mysql::server::install: Installs packages.
• mysql::server::config: Configures MYSQL.
• mysql::server::service: Manages service.
• mysql::server::root_password: Sets MySQL root password.
• mysql::server::providers: Creates users, grants, and databases.
• mysql::bindings::java: Installs Java bindings.
• mysql::bindings::perl: Installs Perl bindings.
• mysql::bindings::python: Installs Python bindings.
• mysql::bindings::ruby: Installs Ruby bindings.
• mysql::client::install: Installs MySQL client.

###Parameters

####mysql::server

#####root_password

What is the MySQL root password. Puppet will attempt to set it to this and update /root/.my.cnf.

#####old_root_password

What was the previous root password (REQUIRED if you wish to change the root password via Puppet.)

#####override_options

This is the hash of override options to pass into MySQL. It can be visualized like a hash of the my.cnf file, so that entries look like:

$override_options = {
  'section' => {
    'item'             => 'thing',
  }
}

For items that you would traditionally represent as:

You can just make an entry like thing => true in the hash. MySQL doesn't care if thing is alone or set to a value, it'll happily accept both.

#####config_file

The location of the MySQL configuration file.

#####manage_config_file

Should we manage the MySQL configuration file.

#####purge_conf_dir

Should we purge the conf.d directory?

#####restart

Should the service be restarted when things change?

#####root_group

What is the group used for root?

#####package_ensure

What to set the package to. Can be present, absent, or version.

#####package_name

What is the name of the mysql server package to install.

#####remove_default_accounts

Boolean to decide if we should automatically include mysql::server::account_security.

#####service_enabled

Boolean to decide if the service should be enabled.

#####service_manage

Boolean to decide if the service should be managed.

#####service_name

What is the name of the mysql server service.

#####service_provider

Which provider to use to manage the service.

#####users

Optional hash of users to create, which are passed to mysql_user. Example:

$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. Example:

$grants = {
  'someuser@localhost/somedb.*' => {
    ensure     => 'present',
    options    => ['GRANT'],
    privileges => ['SELECT', 'INSERT', 'UPDATE', 'DELETE'],
    table      => 'somedb.*',
    user       => 'someuser@localhost',
  },
}

#####databases

Optional hash of databases to create, which are passed to mysql_database. Example:

$databases = {
  'somedb' => {
    ensure  => 'present',
    charset => 'utf8',
  },
}

#####service_provider

####mysql::server::backup

#####backupuser

MySQL user to create for backing up.

#####backuppassword

MySQL user password for backups.

#####backupdir

Directory to backup into.

#####backupcompress

Boolean to determine if backups should be compressed.

#####backuprotate

How many days to keep backups for.

#####delete_before_dump

Boolean to determine if you should cleanup before backing up or after.

#####backupdatabases

Array of databases to specifically backup.

#####file_per_database

Should a seperate file be used per database.

#####ensure

Present or absent, allows you to remove the backup scripts.

#####time

An array of two elements to set the time to backup. Allows ['23', '5'] or ['3', '45'] for HH:MM times.

####mysql::server::monitor

#####mysql_monitor_username

The username to create for MySQL monitoring.

#####mysql_monitor_password

The password to create for MySQL monitoring.

#####mysql_monitor_hostname

The hostname to allow to access the MySQL monitoring user.

####mysql::bindings

#####java_enable

Boolean to decide if the Java bindings should be installed.

#####perl_enable

Boolean to decide if the Perl bindings should be installed.

#####php_enable

Boolean to decide if the PHP bindings should be installed.

#####python_enable

Boolean to decide if the Python bindings should be installed.

#####ruby_enable

Boolean to decide if the Ruby bindings should be installed.

#####java_package_ensure

What to set the package to. Can be present, absent, or version.

#####java_package_name

The name of the package to install.

#####java_package_provider

What provider should be used to install the package.

#####perl_package_ensure

What to set the package to. Can be present, absent, or version.

#####perl_package_name

The name of the package to install.

#####perl_package_provider

What provider should be used to install the package.

#####python_package_ensure

What to set the package to. Can be present, absent, or version.

#####python_package_name

The name of the package to install.

#####python_package_provider

What provider should be used to install the package.

#####ruby_package_ensure

What to set the package to. Can be present, absent, or version.

#####ruby_package_name

The name of the package to install.

#####ruby_package_provider

What provider should be used to install the package.

####mysql::client

#####bindings_enable

Boolean to automatically install all bindings.

#####package_ensure

What to set the package to. Can be present, absent, or version.

#####package_name

What is the name of the mysql client package to install.

###Defines

####mysql::db

Creates a database with a user and assign some privileges.

    mysql::db { 'mydb':
      user     => 'myuser',
      password => 'mypass',
      host     => 'localhost',
      grant    => ['SELECT', 'UPDATE'],
    }

###Providers

####mysql_database

mysql_database can be used to create and manage databases within MySQL:

mysql_database { 'information_schema':
  ensure  => 'present',
  charset => 'utf8',
  collate => 'utf8_swedish_ci',
}
mysql_database { 'mysql':
  ensure  => 'present',
  charset => 'latin1',
  collate => 'latin1_swedish_ci',
}

####mysql_user

mysql_user can be used to create and manage 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',
}

####mysql_grant

mysql_grant can be used to create 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',
}

##Limitations

This module has been tested on:

• RedHat Enterprise Linux 5/6
• Debian 6/7
• CentOS 5/6
• Ubuntu 12.04

Testing on other platforms has been light and cannot be guaranteed.

#Development

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.

You can read the complete module contribution guide on the Puppet Labs wiki.

Authors

This module is based on work by David Schmitt. The following contributor have contributed patches to this module (beyond Puppet Labs):

• Larry Ludwig
• Christian G. Warden
• Daniel Black
• Justin Ellison
• Lowe Schmidt
• Matthias Pigulla
• William Van Hevelingen
• Michael Arnold
• Chris Weyl

2013-11-13 - Version 2.1.0

Summary:

The most important changes in 2.1.0 are improvements to the my.cnf creation, as well as providers. Setting options to = true strips them to be just the key name itself, which is required for some options.

The provider updates fix a number of bugs, from lowercase privileges to deprecation warnings.

Last, the new hiera integration functionality should make it easier to externalize all your grantts, users, and, databases. Another great set of community submissions helped to make this release.

Features:

• Some options can not take a argument. Gets rid of the '= true' when an option is set to true.
• Easier hiera integration: Add hash parameters to mysql::server to allow specifying grants, users, and databases.

Fixes:

• Fix an issue with lowercase privileges in mysql_grant{} causing them to be reapplied needlessly.
• Changed defaults-file to defaults-extra-file in providers.
• Ensure /root/.my.cnf is 0600 and root owned.
• database_user deprecation warning was incorrect.
• Add anchor pattern for client.pp
• Documentation improvements.
• Various test fixes.

2013-10-21 - Version 2.0.1

Summary:

This is a bugfix release to handle an issue where unsorted mysql_grant{} privileges could cause Puppet to incorrectly reapply the permissions on each run.

Fixes:

• Mysql_grant now sorts privileges in the type and provider for comparision.
• Comment and test tweak for PE3.1.

2013-10-14 - Version 2.0.0

Summary:

(Previously detailed in the changelog for 2.0.0-rc1)

This module has been completely refactored and works significantly different. The changes are broad and touch almost every piece of the module.

See the README.md for full details of all changes and syntax. Please remain on 1.0.0 if you don't have time to fully test this in dev.

• mysql::server, mysql::client, and mysql::bindings are the primary interface classes.
• mysql::server takes an options_override parameter to set my.cnf options, with the hash format: { 'section' => { 'thing' => 'value' }}
• mysql attempts backwards compatibility by forwarding all parameters to mysql::server.

2013-10-09 - Version 2.0.0-rc5

Summary:

Hopefully the final rc! Further fixes to mysql_grant (stripping out the cleverness so we match a much wider range of input.)

Fixes:

• Make mysql_grant accept '.'@'.' in terms of input for user@host.

2013-10-09 - Version 2.0.0-rc4

Summary:

Bugfixes to mysql_grant and mysql_user form the bulk of this rc, as well as ensuring that values in the override_options hash that contain a value of '' are created as just "key" in the conf rather than "key =" or "key = false".

Fixes:

• Improve mysql_grant to work with IPv6 addresses (both long and short).
• Ensure @host users work as well as user@host users.
• Updated my.cnf template to support items with no values.

2013-10-07 - Version 2.0.0-rc3

Summary:

Fix mysql::server::monitor's use of mysql_user{}.

Fixes:

• Fix myql::server::monitor's use of mysql_user{} to grant the proper permissions. Add specs as well. (Thanks to treydock!)

2013-10-03 - Version 2.0.0-rc2

Summary:

Bugfixes

Fixes:

• Fix a duplicate parameter in mysql::server

2013-10-03 - Version 2.0.0-rc1

Summary:

This module has been completely refactored and works significantly different. The changes are broad and touch almost every piece of the module.

See the README.md for full details of all changes and syntax. Please remain on 1.0.0 if you don't have time to fully test this in dev.

• mysql::server, mysql::client, and mysql::bindings are the primary interface classes.
• mysql::server takes an options_override parameter to set my.cnf options, with the hash format: { 'section' => { 'thing' => 'value' }}
• mysql attempts backwards compatibility by forwarding all parameters to mysql::server.

2013-09-23 - Version 1.0.0

Summary:

This release introduces a number of new type/providers, to eventually replace the database_ ones. The module has been converted to call the new providers rather than the previous ones as they have a number of fixes, additional options, and work with puppet resource.

This 1.0.0 release precedes a large refactoring that will be released almost immediately after as 2.0.0.

Features:

• Added mysql_grant, mysql_database, and mysql_user.
• Add mysql::bindings class and refactor all other bindings to be contained underneath mysql::bindings:: namespace.
• Added support to back up specified databases only with 'mysqlbackup' parameter.
• Add option to mysql::backup to set the backup script to perform a mysqldump on each database to its own file

Bugfixes:

• Update my.cnf.pass.erb to allow custom socket support
• Add environment variable for .my.cnf in mysql::db.
• Add HOME environment variable for .my.cnf to mysqladmin command when (re)setting root password

2013-07-15 - Version 0.9.0 Features:

• Add mysql::backup::backuprotate parameter
• Add mysql::backup::delete_before_dump parameter
• Add max_user_connections attribute to database_user type

Bugfixes:

• Add client package dependency for mysql::db
• Remove duplicate expire_logs_days and max_binlog_size settings
• Make root's .my.cnf file path dynamic
• Update pidfile path for Suse variants
• Fixes for lint

2013-07-05 - Version 0.8.1 Bugfixes:

• Fix a typo in the Fedora 19 support.

2013-07-01 - Version 0.8.0 Features:

• mysql::perl class to install perl-DBD-mysql.
• minor improvements to the providers to improve reliability
• Install the MariaDB packages on Fedora 19 instead of MySQL.
• Add new mysql class parameters:
• max_connections: The maximum number of allowed connections.
• manage_config_file: Opt out of puppetized control of my.cnf.
• ft_min_word_len: Fine tune the full text search.
• ft_max_word_len: Fine tune the full text search.
• Add new mysql class performance tuning parameters:
• key_buffer
• thread_stack
• thread_cache_size
• myisam-recover
• query_cache_limit
• query_cache_size
• max_connections
• tmp_table_size
• table_open_cache
• long_query_time
• Add new mysql class replication parameters:
• server_id
• sql_log_bin
• log_bin
• max_binlog_size
• binlog_do_db
• expire_logs_days
• log_bin_trust_function_creators
• replicate_ignore_table
• replicate_wild_do_table
• replicate_wild_ignore_table
• expire_logs_days
• max_binlog_size

Bugfixes:

• No longer restart MySQL when /root/.my.cnf changes.
• Ensure mysql::config runs before any mysql::db defines.

2013-06-26 - Version 0.7.1 Bugfixes:

• Single-quote password for special characters
• Update travis testing for puppet 3.2.x and missing Bundler gems

2013-06-25 - Version 0.7.0 This is a maintenance release for community bugfixes and exposing configuration variables.

• Add new mysql class parameters:

• basedir: The base directory mysql uses
• bind_address: The IP mysql binds to
• client_package_name: The name of the mysql client package
• config_file: The location of the server config file
• config_template: The template to use to generate my.cnf
• datadir: The directory MySQL's datafiles are stored
• default_engine: The default engine to use for tables
• etc_root_password: Whether or not to add the mysql root password to /etc/my.cnf
• java_package_name: The name of the java package containing the java connector
• log_error: Where to log errors
• manage_service: Boolean dictating if mysql::server should manage the service
• max_allowed_packet: Maximum network packet size mysqld will accept
• old_root_password: Previous root user password
• php_package_name: The name of the phpmysql package to install
• pidfile: The location mysql will expect the pidfile to be
• port: The port mysql listens on
• purge_conf_dir: Value fed to recurse and purge parameters of the /etc/mysql/conf.d resource
• python_package_name: The name of the python mysql package to install
• restart: Whether to restart mysqld
• root_group: Use specified group for root-owned files
• root_password: The root MySQL password to use
• ruby_package_name: The name of the ruby mysql package to install
• ruby_package_provider: The installation suite to use when installing the ruby package
• server_package_name: The name of the server package to install
• service_name: The name of the service to start
• service_provider: The name of the service provider
• socket: The location of the MySQL server socket file
• ssl_ca: The location of the SSL CA Cert
• ssl_cert: The location of the SSL Certificate to use
• ssl_key: The SSL key to use
• ssl: Whether or not to enable ssl
• tmpdir: The directory MySQL's tmpfiles are stored

• Deprecate mysql::package_name parameter in favor of mysql::client_package_name
• Fix local variable template deprecation
• Fix dependency ordering in mysql::db
• Fix ANSI quoting in queries
• Fix travis support (but still messy)
• Fix typos

2013-01-11 - Version 0.6.1

• Fix providers when /root/.my.cnf is absent

2013-01-09 - Version 0.6.0

• Add mysql::server::config define for specific config directives
• Add mysql::php class for php support
• Add backupcompress parameter to mysql::backup
• Add restart parameter to mysql::config
• Add purge_conf_dir parameter to mysql::config
• Add manage_service parameter to mysql::server
• Add syslog logging support via the log_error parameter
• Add initial SuSE support
• Fix remove non-localhost root user when fqdn != hostname
• Fix dependency in mysql::server::monitor
• Fix .my.cnf path for root user and root password
• Fix ipv6 support for users
• Fix / update various spec tests
• Fix typos
• Fix lint warnings

2012-08-23 - Version 0.5.0

• Add puppetlabs/stdlib as requirement
• Add validation for mysql privs in provider
• Add pidfile parameter to mysql::config
• Add ensure parameter to mysql::db
• Add Amazon linux support
• Change bind_address parameter to be optional in my.cnf template
• Fix quoting root passwords

2012-07-24 - Version 0.4.0

• Fix various bugs regarding database names
• FreeBSD support
• Allow specifying the storage engine
• Add a backup class
• Add a security class to purge default accounts

2012-05-03 - Version 0.3.0

• #14218 Query the database for available privileges
• Add mysql::java class for java connector installation
• Use correct error log location on different distros
• Fix set_mysql_rootpw to properly depend on my.cnf

2012-04-11 - Version 0.2.0

2012-03-19 - William Van Hevelingen blkperl@cat.pdx.edu

• (#13203) Add ssl support (f7e0ea5)

2012-03-18 - Nan Liu nan@puppetlabs.com

• Travis ci before script needs success exit code. (0ea463b)

2012-03-18 - Nan Liu nan@puppetlabs.com

• Fix Puppet 2.6 compilation issues. (9ebbbc4)

2012-03-16 - Nan Liu nan@puppetlabs.com

• Add travis.ci for testing multiple puppet versions. (33c72ef)

2012-03-15 - William Van Hevelingen blkperl@cat.pdx.edu

• (#13163) Datadir should be configurable (f353fc6)

2012-03-16 - Nan Liu nan@puppetlabs.com

• Document create_resources dependency. (558a59c)

2012-03-16 - Nan Liu nan@puppetlabs.com

• Fix spec test issues related to error message. (eff79b5)

2012-03-16 - Nan Liu nan@puppetlabs.com

• Fix mysql service on Ubuntu. (72da2c5)

2012-03-16 - Dan Bode dan@puppetlabs.com

• Add more spec test coverage (55e399d)

2012-03-16 - Nan Liu nan@puppetlabs.com

• (#11963) Fix spec test due to path changes. (1700349)

2012-03-07 - François Charlier fcharlier@ploup.net

• Add a test to check path for 'mysqld-restart' (b14c7d1)

2012-03-07 - François Charlier fcharlier@ploup.net

• Fix path for 'mysqld-restart' (1a9ae6b)

2012-03-15 - Dan Bode dan@puppetlabs.com

• Add rspec-puppet tests for mysql::config (907331a)

2012-03-15 - Dan Bode dan@puppetlabs.com

• Moved class dependency between sever and config to server (da62ad6)

2012-03-14 - Dan Bode dan@puppetlabs.com

• Notify mysql restart from set_mysql_rootpw exec (0832a2c)

2012-03-15 - Nan Liu nan@puppetlabs.com

• Add documentation related to osfamily fact. (8265d28)

2012-03-14 - Dan Bode dan@puppetlabs.com

• Mention osfamily value in failure message (e472d3b)

2012-03-14 - Dan Bode dan@puppetlabs.com

• Fix bug when querying for all database users (015490c)

2012-02-09 - Nan Liu nan@puppetlabs.com

• Major refactor of mysql module. (b1f90fd)

2012-01-11 - Justin Ellison justin.ellison@buckle.com

• Ruby and Python's MySQL libraries are named differently on different distros. (1e926b4)

2012-01-11 - Justin Ellison justin.ellison@buckle.com

• Per @ghoneycutt, we should fail explicitly and explain why. (09af083)

2012-01-11 - Justin Ellison justin.ellison@buckle.com

• Removing duplicate declaration (7513d03)

2012-01-10 - Justin Ellison justin.ellison@buckle.com

• Use socket value from params class instead of hardcoding. (663e97c)

2012-01-10 - Justin Ellison justin.ellison@buckle.com

• Instead of hardcoding the config file target, pull it from mysql::params (031a47d)

2012-01-10 - Justin Ellison justin.ellison@buckle.com

• Moved $socket to within the case to toggle between distros. Added a $config_file variable to allow per-distro config file destinations. (360eacd)

2012-01-10 - Justin Ellison justin.ellison@buckle.com

• Pretty sure this is a bug, 99% of Linux distros out there won't ever hit the default. (3462e6b)

2012-02-09 - William Van Hevelingen blkperl@cat.pdx.edu

• Changed the README to use markdown (3b7dfeb)

2012-02-04 - Daniel Black grooverdan@users.sourceforge.net

• (#12412) mysqltuner.pl update (b809e6f)

2011-11-17 - Matthias Pigulla mp@webfactory.de

• (#11363) Add two missing privileges to grant: event_priv, trigger_priv (d15c9d1)

2011-12-20 - Jeff McCune jeff@puppetlabs.com

• (minor) Fixup typos in Modulefile metadata (a0ed6a1)

2011-12-19 - Carl Caum carl@carlcaum.com

• Only notify Exec to import sql if sql is given (0783c74)

2011-12-19 - Carl Caum carl@carlcaum.com

• (#11508) Only load sql_scripts on DB creation (e3b9fd9)

2011-12-13 - Justin Ellison justin.ellison@buckle.com

• Require not needed due to implicit dependencies (3058feb)

2011-12-13 - Justin Ellison justin.ellison@buckle.com

• Bug #11375: puppetlabs-mysql fails on CentOS/RHEL (a557b8d)

2011-06-03 - Dan Bode dan@puppetlabs.com - 0.0.1

• initial commit