community.mysql.mysql_replication – Manage MySQL replication¶
Note
This plugin is part of the community.mysql collection (version 1.4.0).
To install it use: ansible-galaxy collection install community.mysql
.
To use it in a playbook, specify: community.mysql.mysql_replication
.
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.
For more information see https://dev.mysql.com/doc/refman/8.0/en/replication-multi-source.html.
|
|
check_hostname
boolean
added in 1.1.0 of community.mysql
|
|
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 optoin 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 master connection.
Supported from MariaDB 10.0.1.
Mutually exclusive with channel.
For more information see https://mariadb.com/kb/en/library/multi-source-replication/.
|
|
fail_on_error
boolean
added in 0.1.0 of community.mysql
|
|
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.
|
|
master_auto_position
boolean
|
|
Whether the host uses GTID based replication or not.
|
master_connect_retry
integer
|
Same as mysql variable.
|
|
master_delay
integer
added in 0.1.0 of community.mysql
|
Time lag behind the master's state (in seconds).
Available from MySQL 5.6.
For more information see https://dev.mysql.com/doc/refman/8.0/en/replication-delayed.html.
|
|
master_host
string
|
Same as mysql variable.
|
|
master_log_file
string
|
Same as mysql variable.
|
|
master_log_pos
integer
|
Same as mysql variable.
|
|
master_password
string
|
Same as mysql variable.
|
|
master_port
integer
|
Same as mysql variable.
|
|
master_ssl
boolean
|
|
Same as the
MASTER_SSL mysql variable.When setting it to
yes , the connection attempt only succeeds if an encrypted connection can be established.For details, refer to MySQL encrypted replication documentation.
|
master_ssl_ca
string
|
Same as the
MASTER_SSL_CA mysql variable.For details, refer to MySQL encrypted replication documentation.
|
|
master_ssl_capath
string
|
Same as the
MASTER_SSL_CAPATH mysql variable.For details, refer to MySQL encrypted replication documentation.
|
|
master_ssl_cert
string
|
Same as the
MASTER_SSL_CERT mysql variable.For details, refer to MySQL encrypted replication documentation.
|
|
master_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.
For details, refer to MySQL encrypted replication documentation.
|
|
master_ssl_key
string
|
Same as the
MASTER_SSL_KEY mysql variable.For details, refer to MySQL encrypted replication documentation.
|
|
master_use_gtid
string
added in 0.1.0 of community.mysql
|
|
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 . |
master_user
string
|
Same as mysql variable.
|
|
mode
string
|
|
Module operating mode. Could be
changemaster (CHANGE MASTER TO), getmaster (SHOW MASTER STATUS), getreplica | getslave (SHOW REPLICA | SLAVE STATUS), startreplica | startslave (START REPLICA | SLAVE), stopreplica | stopslave (STOP REPLICA | SLAVE), resetmaster (RESET MASTER) - supported since community.mysql 0.1.0, resetreplica, resetslave (RESET REPLICA | SLAVE), resetreplicaall, resetslave (RESET REPLICA | SLAVE ALL). |
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
andlogin_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 master binlog file name and binlog position
community.mysql.mysql_replication:
mode: getmaster
- name: Change master to master server 192.0.2.1 and use binary log 'mysql-bin.000009' with position 4578
community.mysql.mysql_replication:
mode: changemaster
master_host: 192.0.2.1
master_log_file: mysql-bin.000009
master_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 master to use GTID current_pos
community.mysql.mysql_replication:
mode: changemaster
master_use_gtid: current_pos
- name: Change master to use replication delay 3600 seconds
community.mysql.mysql_replication:
mode: changemaster
master_host: 192.0.2.1
master_delay: 3600
- name: Start MariaDB replica with connection name master-1
community.mysql.mysql_replication:
mode: startreplica
connection_name: master-1
- name: Stop replication in channel master-1
community.mysql.mysql_replication:
mode: stopreplica
channel: master-1
- name: >
Run RESET MASTER command which will delete all existing binary log files
and reset the binary log index file on the master
community.mysql.mysql_replication:
mode: resetmaster
- name: Run start replica and fail the task on errors
community.mysql.mysql_replication:
mode: startreplica
connection_name: master-1
fail_on_error: yes
- name: Change master and fail on error (like when replica thread is running)
community.mysql.mysql_replication:
mode: changemaster
fail_on_error: yes
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Authors¶
Balazs Pocze (@banyek)
Andrew Klychkov (@Andersson007)