community.mysql.mysql_db module – Add or remove MySQL databases from a remote host
Note
This module is part of the community.mysql collection (version 3.7.2).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.mysql.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.mysql.mysql_db.
Synopsis
Add or remove MySQL databases from a remote host.
Requirements
The below requirements are needed on the host that executes this module.
MySQLdb (Python 2.x)
PyMySQL (Python 2.7 and Python 3.x) or
mysql (command line binary)
mysqlclient (Python 3.5+) or
mysqldump (command line binary)
Parameters
Parameter |
Comments |
|---|---|
The path to a Certificate Authority (CA) certificate. This option, if used, must specify the same certificate as used by the server. |
|
Changes the current working directory. Can be useful, for example, when state=import and a dump file contains relative paths. |
|
Whether to validate the server host name when an SSL connection is required. Corresponds to MySQL CLIs Setting this to Requires pymysql >= 0.7.11. This option has no effect on MySQLdb. Choices:
|
|
Check if mysql allows login as root/nopassword before trying supplied credentials. If success, passed login_user/login_password will be ignored. Choices:
|
|
The path to a client public key certificate. |
|
The path to the client private key. |
|
Collation mode (sorting). This only applies to new table/databases and does not update existing ones, this is a limitation of MySQL. Default: |
|
Specify a config file from which user and password are to be read. The default config file, The default config file, To prevent the default config file from being read, set config_file to be an empty string. Default: |
|
If Used when stat is It needs Python 3.5+ as the default interpreter on a target host. Choices:
|
|
The connection timeout when connecting to the MySQL server. Default: |
|
Provide additional arguments for mysqldump. Used when state=dump only, ignored otherwise. |
|
Encoding mode to use, examples include Default: |
|
Continue dump or import even if we get an SQL error. Used only when state is Choices:
|
|
Dump binary columns using hexadecimal notation. Choices:
|
|
A list of table names that will be ignored in the dump of the form database_name.table_name. Default: |
|
Host running the database. In some cases for local connections the login_unix_socket=/path/to/mysqld/socket, that is usually Default: |
|
The password used to authenticate with. |
|
Port of the MySQL server. Requires login_host be defined as other than localhost if login_port is used. Default: |
|
The path to a Unix domain socket for local connections. Use this parameter to avoid the |
|
The username used to authenticate with. |
|
Option to dump a master replication server to produce a dump file that can be used to set up another server as a slave of the master.
Can be used when state=dump. Choices:
|
|
Name of the database to add or remove. name=all may only be provided if state is List of databases is provided with state=dump, state=present and state=absent. If name=all it works like –all-databases option for mysqldump (Added in 2.0). |
|
Use The default is The default will change to Choices:
|
|
Option used for dumping large tables. Choices:
|
|
Read only passed config_file. When state is If this behavior is undesirable, use Choices:
|
|
Execute the dump in a single transaction. Choices:
|
|
Skip locking tables for read. Used when state=dump, ignored otherwise. Choices:
|
|
The database state. Choices:
|
|
Location, on the remote host, of the dump file to read from or write to. Uncompressed SQL files ( |
|
If It makes sense to use Used only when state is Choices:
|
|
Used to prevent If Used when state=import, ignored otherwise. Choices:
|
Notes
Note
Supports
check_mode.Requires the mysql and mysqldump binaries on the remote host.
This module is not idempotent when state is
import, and will import the dump file each time if run more than once.Requires the PyMySQL (Python 2.7 and Python 3.X) or MySQL-python (Python 2.X) package installed on the remote host. The Python package may be installed with apt-get install python-pymysql (Ubuntu; see ansible.builtin.apt) or yum install python2-PyMySQL (RHEL/CentOS/Fedora; see ansible.builtin.yum). You can also use dnf install python2-PyMySQL for newer versions of Fedora; see ansible.builtin.dnf.
Be sure you have mysqlclient, PyMySQL, or MySQLdb library installed on the target machine for the Python interpreter Ansible discovers. For example if ansible discovers and uses Python 3, you need to install the Python 3 version of PyMySQL or mysqlclient. If ansible discovers and uses Python 2, you need to install the Python 2 version of either PyMySQL or MySQL-python.
If you have trouble, it may help to force Ansible to use the Python interpreter you need by specifying
ansible_python_interpreter. For more information, see https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html.Both
login_passwordandlogin_userare required when you are passing credentials. If none are present, the module will attempt to read the credentials from~/.my.cnf, and finally fall back to using the MySQL default login of ‘root’ with no password.If there are problems with local connections, using login_unix_socket=/path/to/mysqld/socket instead of login_host=localhost might help. As an example, the default MariaDB installation of version 10.4 and later uses the unix_socket authentication plugin by default that without using login_unix_socket=/var/run/mysqld/mysqld.sock (the default path) causes the error ``Host ‘127.0.0.1’ is not allowed to connect to this MariaDB server``.
Alternatively, you can use the mysqlclient library instead of MySQL-python (MySQLdb) which supports both Python 2.X and Python >=3.5. See https://pypi.org/project/mysqlclient/ how to install it.
If credentials from the config file (for example,
/root/.my.cnf) are not needed to connect to a database server, but the file exists and does not contain a[client]section, before any other valid directives, it will be read and this will cause the connection to fail, to prevent this set it to an empty string, (for exampleconfig_file: '').To avoid the
Please explicitly state intended protocolerror, use the login_unix_socket argument, for example,login_unix_socket: /run/mysqld/mysqld.sock.Alternatively, to avoid using login_unix_socket argument on each invocation you can specify the socket path using the `socket` option in your MySQL config file (usually
~/.my.cnf) on the destination host, for examplesocket=/var/lib/mysql/mysql.sock.
See Also
See also
- community.mysql.mysql_info
The official documentation on the community.mysql.mysql_info module.
- community.mysql.mysql_variables
The official documentation on the community.mysql.mysql_variables module.
- community.mysql.mysql_user
The official documentation on the community.mysql.mysql_user module.
- community.mysql.mysql_replication
The official documentation on the community.mysql.mysql_replication module.
- MySQL command-line client reference
Complete reference of the MySQL command-line client documentation.
- mysqldump reference
Complete reference of the ``mysqldump`` client utility documentation.
- CREATE DATABASE reference
Complete reference of the CREATE DATABASE command documentation.
- DROP DATABASE reference
Complete reference of the DROP DATABASE command documentation.
Examples
# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument
- name: Create a new database with name 'bobdata'
community.mysql.mysql_db:
name: bobdata
state: present
login_unix_socket: /run/mysqld/mysqld.sock
- name: Create new databases with names 'foo' and 'bar'
community.mysql.mysql_db:
name:
- foo
- bar
state: present
# Copy database dump file to remote host and restore it to database 'my_db'
- name: Copy database dump file
copy:
src: dump.sql.bz2
dest: /tmp
- name: Restore database
community.mysql.mysql_db:
name: my_db
state: import
target: /tmp/dump.sql.bz2
- name: Restore database ignoring errors
community.mysql.mysql_db:
name: my_db
state: import
target: /tmp/dump.sql.bz2
force: true
- name: Dump multiple databases
community.mysql.mysql_db:
state: dump
name: db_1,db_2
target: /tmp/dump.sql
- name: Dump multiple databases
community.mysql.mysql_db:
state: dump
name:
- db_1
- db_2
target: /tmp/dump.sql
- name: Dump all databases to hostname.sql
community.mysql.mysql_db:
state: dump
name: all
target: /tmp/dump.sql
- name: Dump all databases to hostname.sql including master data
community.mysql.mysql_db:
state: dump
name: all
target: /tmp/dump.sql
master_data: 1
# Import of sql script with encoding option
- name: >
Import dump.sql with specific latin1 encoding,
similar to mysql -u <username> --default-character-set=latin1 -p <password> < dump.sql
community.mysql.mysql_db:
state: import
name: all
encoding: latin1
target: /tmp/dump.sql
# Dump of database with encoding option
- name: >
Dump of Databse with specific latin1 encoding,
similar to mysqldump -u <username> --default-character-set=latin1 -p <password> <database>
community.mysql.mysql_db:
state: dump
name: db_1
encoding: latin1
target: /tmp/dump.sql
- name: Delete database with name 'bobdata'
community.mysql.mysql_db:
name: bobdata
state: absent
- name: Make sure there is neither a database with name 'foo', nor one with name 'bar'
community.mysql.mysql_db:
name:
- foo
- bar
state: absent
# Dump database with argument not directly supported by this module
# using dump_extra_args parameter
- name: Dump databases without including triggers
community.mysql.mysql_db:
state: dump
name: foo
target: /tmp/dump.sql
dump_extra_args: --skip-triggers
- name: Try to create database as root/nopassword first. If not allowed, pass the credentials
community.mysql.mysql_db:
check_implicit_admin: true
login_user: bob
login_password: 123456
name: bobdata
state: present
- name: Dump a database with compression and catch errors from mysqldump with bash pipefail
community.mysql.mysql_db:
state: dump
name: foo
target: /tmp/dump.sql.gz
pipefail: true
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Database names in string format delimited by white space. Returned: always Sample: |
|
List of database names. Returned: always Sample: |
|
List of commands which tried to run. Returned: if executed Sample: |