W3cubDocs

/Ansible

community.mysql.mysql_replication – Manage MySQL replication

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_replication.

Synopsis

  • Manages MySQL server replication, replica, primary status, get and change primary host.

Requirements

The below requirements are needed on the host that executes this module.

  • PyMySQL (Python 2.7 and Python 3.X), or
  • MySQLdb (Python 2.x)

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
channel
string
added in 0.1.0 of community.mysql
Name of replication channel.
Multi-source replication is supported from MySQL 5.7.
Mutually exclusive with connection_name.
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.
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
config_file
path
Default:
"~/.my.cnf"
Specify a config file from which user and password are to be read.
connect_timeout
integer
Default:
30
The connection timeout when connecting to the MySQL server.
connection_name
string
added in 0.1.0 of community.mysql
Name of the primary connection.
Supported from MariaDB 10.0.1.
Mutually exclusive with channel.
fail_on_error
boolean
added in 0.1.0 of community.mysql
    Choices:
  • no ←
  • yes
Fails on error when calling mysql.
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.
mode
string
    Choices:
  • changeprimary
  • changemaster
  • getprimary
  • getmaster
  • getreplica ←
  • getslave
  • startreplica
  • startslave
  • stopreplica
  • stopslave
  • resetprimary
  • resetmaster
  • resetreplica
  • resetslave
  • resetreplicaall
  • resetslaveall
Module operating mode. Could be changeprimary | changemaster (CHANGE PRIMARY | MASTER TO), getprimary | getmaster (SHOW PRIMARY | MASTER STATUS), getreplica | getslave (SHOW REPLICA | SLAVE STATUS), startreplica | startslave (START REPLICA | SLAVE), stopreplica | stopslave (STOP REPLICA | SLAVE), resetprimary | resetmaster (RESET PRIMARY | MASTER) - supported since community.mysql 0.1.0, resetreplica, resetslave (RESET REPLICA | SLAVE), resetreplicaall, resetslave (RESET REPLICA | SLAVE ALL).
primary_auto_position
boolean
    Choices:
  • no ←
  • yes
Whether the host uses GTID based replication or not.
Same as the MASTER_AUTO_POSITION mysql variable.

aliases: master_auto_position
primary_connect_retry
integer
Same as the MASTER_CONNECT_RETRY mysql variable.

aliases: master_connect_retry
primary_delay
integer
added in 0.1.0 of community.mysql
Time lag behind the primary's state (in seconds).
Same as the MASTER_DELAY mysql variable.
Available from MySQL 5.6.

aliases: master_delay
primary_host
string
Same as the MASTER_HOST mysql variable.

aliases: master_host
primary_log_file
string
Same as the MASTER_LOG_FILE mysql variable.

aliases: master_log_file
primary_log_pos
integer
Same as the MASTER_LOG_POS mysql variable.

aliases: master_log_pos
primary_password
string
Same as the MASTER_PASSWORD mysql variable.

aliases: master_password
primary_port
integer
Same as the MASTER_PORT mysql variable.

aliases: master_port
primary_ssl
boolean
    Choices:
  • no ←
  • yes
Same as the MASTER_SSL mysql variable.
When setting it to yes, the connection attempt only succeeds if an encrypted connection can be established.

aliases: master_ssl
primary_ssl_ca
string
Same as the MASTER_SSL_CA mysql variable.

aliases: master_ssl_ca
primary_ssl_capath
string
Same as the MASTER_SSL_CAPATH mysql variable.

aliases: master_ssl_capath
primary_ssl_cert
string
Same as the MASTER_SSL_CERT mysql variable.

aliases: master_ssl_cert
primary_ssl_cipher
string
Same as the MASTER_SSL_CIPHER mysql variable.
Specifies a colon-separated list of one or more ciphers permitted by the replica for the replication connection.

aliases: master_ssl_cipher
primary_ssl_key
string
Same as the MASTER_SSL_KEY mysql variable.

aliases: master_ssl_key
primary_use_gtid
string
added in 0.1.0 of community.mysql
    Choices:
  • current_pos
  • replica_pos
  • slave_pos
  • disabled
Configures the replica to use the MariaDB Global Transaction ID.
disabled equals MASTER_USE_GTID=no command.
To find information about available values see https://mariadb.com/kb/en/library/change-master-to/#master_use_gtid.
Available since MariaDB 10.0.2.
replica_pos has been introduced in MariaDB 10.5.1 and it is an alias for slave_pos.

aliases: master_use_gtid
primary_user
string
Same as the MASTER_USER mysql variable.

aliases: master_user
relay_log_file
string
Same as mysql variable.
relay_log_pos
integer
Same as mysql variable.

Notes

Note

  • If an empty value for the parameter of string type is needed, use an empty string.
  • 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.

MySQL replication reference

Complete reference of the MySQL replication documentation.

MySQL encrypted replication reference.

Setting up MySQL replication to use encrypted connection.

MariaDB replication reference

Complete reference of the MariaDB replication documentation.

Examples

- name: Stop mysql replica thread
  community.mysql.mysql_replication:
    mode: stopreplica

- name: Get primary binlog file name and binlog position
  community.mysql.mysql_replication:
    mode: getprimary

- name: Change primary to primary server 192.0.2.1 and use binary log 'mysql-bin.000009' with position 4578
  community.mysql.mysql_replication:
    mode: changeprimary
    primary_host: 192.0.2.1
    primary_log_file: mysql-bin.000009
    primary_log_pos: 4578

- name: Check replica status using port 3308
  community.mysql.mysql_replication:
    mode: getreplica
    login_host: ansible.example.com
    login_port: 3308

- name: On MariaDB change primary to use GTID current_pos
  community.mysql.mysql_replication:
    mode: changeprimary
    primary_use_gtid: current_pos

- name: Change primary to use replication delay 3600 seconds
  community.mysql.mysql_replication:
    mode: changeprimary
    primary_host: 192.0.2.1
    primary_delay: 3600

- name: Start MariaDB replica with connection name primary-1
  community.mysql.mysql_replication:
    mode: startreplica
    connection_name: primary-1

- name: Stop replication in channel primary-1
  community.mysql.mysql_replication:
    mode: stopreplica
    channel: primary-1

- name: >
    Run RESET MASTER command which will delete all existing binary log files
    and reset the binary log index file on the primary
  community.mysql.mysql_replication:
    mode: resetprimary

- name: Run start replica and fail the task on errors
  community.mysql.mysql_replication:
    mode: startreplica
    connection_name: primary-1
    fail_on_error: yes

- name: Change primary and fail on error (like when replica thread is running)
  community.mysql.mysql_replication:
    mode: changeprimary
    fail_on_error: yes

Return Values

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

Key Returned Description
queries
list / elements=string
added in 0.1.0 of community.mysql
 always
List of executed queries which modified DB's state.

Sample:
["CHANGE MASTER TO MASTER_HOST='primary2.example.com',MASTER_PORT=3306"]


Authors

  • Balazs Pocze (@banyek)
  • Andrew Klychkov (@Andersson007)

© 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_replication_module.html