community.mysql.mysql_db – Add or remove MySQL databases from a remote host

Note

This plugin is part of the community.mysql collection (version 2.3.1).

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.

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)
  • mysqldump (command line binary)

Parameters

Parameter Choices/Defaults Comments
ca_cert
path
The path to a Certificate Authority (CA) certificate. This option, if used, must specify the same certificate as used by the server.

aliases: ssl_ca
check_hostname
boolean
added in 1.1.0 of community.mysql
    Choices:
  • no
  • yes
Whether to validate the server host name when an SSL connection is required. Corresponds to MySQL CLIs --ssl switch.
Setting this to false disables hostname verification. Use with caution.
Requires pymysql >= 0.7.11.
This option has no effect on MySQLdb.
check_implicit_admin
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
Check if mysql allows login as root/nopassword before trying supplied credentials.
If success, passed login_user/login_password will be ignored.
client_cert
path
The path to a client public key certificate.

aliases: ssl_cert
client_key
path
The path to the client private key.

aliases: ssl_key
collation
string
Default:
""
Collation mode (sorting). This only applies to new table/databases and does not update existing ones, this is a limitation of MySQL.
config_file
path
Default:
"~/.my.cnf"
Specify a config file from which user and password are to be read.
config_overrides_defaults
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
If yes, connection parameters from config_file will override the default values of login_host and login_port parameters.
Used when stat is present or absent, ignored otherwise.
It needs Python 3.5+ as the default interpreter on a target host.
connect_timeout
integer
Default:
30
The connection timeout when connecting to the MySQL server.
dump_extra_args
string
added in 0.1.0 of community.mysql
Provide additional arguments for mysqldump. Used when state=dump only, ignored otherwise.
encoding
string
Default:
""
Encoding mode to use, examples include utf8 or latin1_swedish_ci, at creation of database, dump or importation of sql script.
force
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
Continue dump or import even if we get an SQL error.
Used only when state is dump or import.
hex_blob
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
Dump binary columns using hexadecimal notation.
ignore_tables
list / elements=string
Default:
[]
A list of table names that will be ignored in the dump of the form database_name.table_name.
login_host
string
Default:
"localhost"
Host running the database.
In some cases for local connections the login_unix_socket=/path/to/mysqld/socket, that is usually /var/run/mysqld/mysqld.sock, needs to be used instead of login_host=localhost.
login_password
string
The password used to authenticate with.
login_port
integer
Default:
3306
Port of the MySQL server. Requires login_host be defined as other than localhost if login_port is used.
login_unix_socket
string
The path to a Unix domain socket for local connections.
login_user
string
The username used to authenticate with.
master_data
integer
added in 0.1.0 of community.mysql
    Choices:
  • 0
  • 1
  • 2
Default:
0
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.
0 to not include master data.
1 to generate a 'CHANGE MASTER TO' statement required on the slave to start the replication process.
2 to generate a commented 'CHANGE MASTER TO'.
Can be used when state=dump.
name
list / elements=string / required
Name of the database to add or remove.
name=all may only be provided if state is dump or import.
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).

aliases: db
quick
boolean
    Choices:
  • no
  • yes
Option used for dumping large tables.
restrict_config_file
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
Read only passed config_file.
When state is dump or import, by default the module passes config_file parameter using --defaults-extra-file command-line argument to mysql/mysqldump utilities under the hood that read named option file in addition to usual option files.
If this behavior is undesirable, use yes to read only named option file.
single_transaction
boolean
    Choices:
  • no
  • yes
Execute the dump in a single transaction.
skip_lock_tables
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
Skip locking tables for read. Used when state=dump, ignored otherwise.
state
string
    Choices:
  • absent
  • dump
  • import
  • present
The database state.
target
path
Location, on the remote host, of the dump file to read from or write to.
Uncompressed SQL files (.sql) as well as bzip2 (.bz2), gzip (.gz) and xz (Added in 2.0) compressed files are supported.
unsafe_login_password
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
If no, the module will safely use a shell-escaped version of the login_password value.
It makes sense to use yes only if there are special symbols in the value and errors Access denied occur.
Used only when state is import or dump and login_password is passed, ignored otherwise.
use_shell
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no
  • yes
Used to prevent Broken pipe errors when the imported target file is compressed.
If yes, the module will internally execute commands via a shell.
Used when state=import, ignored otherwise.

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 PyMySQL or MySQLdb library installed on the target machine for the Python interpreter Ansible uses, for example, if it is Python 3, you must install the library for Python 3. You can also change the interpreter. For more information, see https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html.
  • Both login_password and login_user are 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.

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

- name: Create a new database with name 'bobdata'
  community.mysql.mysql_db:
    name: bobdata
    state: present

- 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: yes

- 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: yes
    login_user: bob
    login_password: 123456
    name: bobdata
    state: present

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
db
string
always
Database names in string format delimited by white space.

Sample:
foo bar
db_list
list / elements=string
always
List of database names.

Sample:
['foo', 'bar']
executed_commands
list / elements=string
added in 0.1.0 of community.mysql
if executed
List of commands which tried to run.

Sample:
['CREATE DATABASE acme']


Authors

  • Ansible Core Team

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/mysql/mysql_db_module.html