community.mysql.mysql_replication (3.9.0) — module

Install collection

Install with ansible-galaxy collection install community.mysql:==3.9.0

Add to requirements.yml

  collections:
    - name: community.mysql
      version: 3.9.0

Description

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

Requirements

• mysqlclient (Python 3.5+) or
• PyMySQL (Python 2.7 and Python 3.x) or
• MySQLdb (Python 2.x)

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument
- name: Stop mysql replica thread
  community.mysql.mysql_replication:
    mode: stopreplica
    login_unix_socket: /run/mysqld/mysqld.sock

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Inputs

    
mode:
    choices:
    - changeprimary
    - getprimary
    - getreplica
    - startreplica
    - stopreplica
    - resetprimary
    - resetreplica
    - resetreplicaall
    default: getreplica
    description:
    - Module operating mode. Could be C(changeprimary) (CHANGE MASTER TO), C(getprimary)
      (SHOW MASTER STATUS), C(getreplica) (SHOW REPLICA STATUS), C(startreplica) (START
      REPLICA), C(stopreplica) (STOP REPLICA), C(resetprimary) (RESET MASTER) - supported
      since community.mysql 0.1.0, C(resetreplica) (RESET REPLICA), C(resetreplicaall)
      (RESET REPLICA ALL).
    type: str

ca_cert:
    aliases:
    - ssl_ca
    description:
    - The path to a Certificate Authority (CA) certificate. This option, if used, must
      specify the same certificate as used by the server.
    type: path

channel:
    description:
    - Name of replication channel.
    - Multi-source replication is supported from MySQL 5.7.
    - Mutually exclusive with I(connection_name).
    - For more information see U(https://dev.mysql.com/doc/refman/8.0/en/replication-multi-source.html).
    type: str
    version_added: 0.1.0
    version_added_collection: community.mysql

client_key:
    aliases:
    - ssl_key
    description:
    - The path to the client private key.
    type: path

login_host:
    default: localhost
    description:
    - Host running the database.
    - In some cases for local connections the I(login_unix_socket=/path/to/mysqld/socket),
      that is usually C(/var/run/mysqld/mysqld.sock), needs to be used instead of I(login_host=localhost).
    type: str

login_port:
    default: 3306
    description:
    - Port of the MySQL server. Requires I(login_host) be defined as other than localhost
      if login_port is used.
    type: int

login_user:
    description:
    - The username used to authenticate with.
    type: str

client_cert:
    aliases:
    - ssl_cert
    description:
    - The path to a client public key certificate.
    type: path

config_file:
    default: ~/.my.cnf
    description:
    - Specify a config file from which user and password are to be read.
    - The default config file, C(~/.my.cnf), if it exists, will be read, even if I(config_file)
      is not specified.
    - The default config file, C(~/.my.cnf), if it exists, must contain a C([client])
      section as a MySQL connector requirement.
    - To prevent the default config file from being read, set I(config_file) to be an
      empty string.
    type: path

primary_ssl:
    aliases:
    - master_ssl
    description:
    - Same as the C(MASTER_SSL) mysql variable.
    - When setting it to C(yes), the connection attempt only succeeds if an encrypted
      connection can be established.
    - For details, refer to L(MySQL encrypted replication documentation,https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted-connections.html).
    - The default is C(false).
    type: bool

primary_host:
    aliases:
    - master_host
    description:
    - Same as the C(MASTER_HOST) mysql variable.
    type: str

primary_port:
    aliases:
    - master_port
    description:
    - Same as the C(MASTER_PORT) mysql variable.
    type: int

primary_user:
    aliases:
    - master_user
    description:
    - Same as the C(MASTER_USER) mysql variable.
    type: str

fail_on_error:
    default: false
    description:
    - Fails on error when calling mysql.
    type: bool
    version_added: 0.1.0
    version_added_collection: community.mysql

primary_delay:
    aliases:
    - master_delay
    description:
    - Time lag behind the primary's state (in seconds).
    - Same as the C(MASTER_DELAY) mysql variable.
    - Available from MySQL 5.6.
    - For more information see U(https://dev.mysql.com/doc/refman/8.0/en/replication-delayed.html).
    type: int
    version_added: 0.1.0
    version_added_collection: community.mysql

relay_log_pos:
    description:
    - Same as mysql variable.
    type: int

check_hostname:
    description:
    - Whether to validate the server host name when an SSL connection is required. Corresponds
      to MySQL CLIs C(--ssl) switch.
    - Setting this to C(false) disables hostname verification. Use with caution.
    - Requires pymysql >= 0.7.11.
    - This option has no effect on MySQLdb.
    type: bool
    version_added: 1.1.0
    version_added_collection: community.mysql

login_password:
    description:
    - The password used to authenticate with.
    type: str

primary_ssl_ca:
    aliases:
    - master_ssl_ca
    description:
    - Same as the C(MASTER_SSL_CA) mysql variable.
    - For details, refer to L(MySQL encrypted replication documentation,https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted-connections.html).
    type: str

relay_log_file:
    description:
    - Same as mysql variable.
    type: str

connect_timeout:
    default: 30
    description:
    - The connection timeout when connecting to the MySQL server.
    type: int

connection_name:
    description:
    - Name of the primary connection.
    - Supported from MariaDB 10.0.1.
    - Mutually exclusive with I(channel).
    - For more information see U(https://mariadb.com/kb/en/library/multi-source-replication/).
    type: str
    version_added: 0.1.0
    version_added_collection: community.mysql

primary_log_pos:
    aliases:
    - master_log_pos
    description:
    - Same as the C(MASTER_LOG_POS) mysql variable.
    type: int

primary_ssl_key:
    aliases:
    - master_ssl_key
    description:
    - Same as the C(MASTER_SSL_KEY) mysql variable.
    - For details, refer to L(MySQL encrypted replication documentation,https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted-connections.html).
    type: str

primary_log_file:
    aliases:
    - master_log_file
    description:
    - Same as the C(MASTER_LOG_FILE) mysql variable.
    type: str

primary_password:
    aliases:
    - master_password
    description:
    - Same as the C(MASTER_PASSWORD) mysql variable.
    type: str

primary_ssl_cert:
    aliases:
    - master_ssl_cert
    description:
    - Same as the C(MASTER_SSL_CERT) mysql variable.
    - For details, refer to L(MySQL encrypted replication documentation,https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted-connections.html).
    type: str

primary_use_gtid:
    aliases:
    - master_use_gtid
    choices:
    - current_pos
    - replica_pos
    - disabled
    description:
    - Configures the replica to use the MariaDB Global Transaction ID.
    - C(disabled) equals MASTER_USE_GTID=no command.
    - To find information about available values see U(https://mariadb.com/kb/en/library/change-master-to/#master_use_gtid).
    - Available since MariaDB 10.0.2.
    type: str
    version_added: 0.1.0
    version_added_collection: community.mysql

login_unix_socket:
    description:
    - The path to a Unix domain socket for local connections.
    - Use this parameter to avoid the C(Please explicitly state intended protocol) error.
    type: str

primary_ssl_capath:
    aliases:
    - master_ssl_capath
    description:
    - Same as the C(MASTER_SSL_CAPATH) mysql variable.
    - For details, refer to L(MySQL encrypted replication documentation,https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted-connections.html).
    type: str

primary_ssl_cipher:
    aliases:
    - master_ssl_cipher
    description:
    - Same as the C(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 L(MySQL encrypted replication documentation,https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted-connections.html).
    type: str

primary_auto_position:
    aliases:
    - master_auto_position
    default: false
    description:
    - Whether the host uses GTID based replication or not.
    - Same as the C(MASTER_AUTO_POSITION) mysql variable.
    type: bool

primary_connect_retry:
    aliases:
    - master_connect_retry
    description:
    - Same as the C(MASTER_CONNECT_RETRY) mysql variable.
    type: int

primary_ssl_verify_server_cert:
    default: false
    description:
    - Same as mysql variable.
    type: bool
    version_added: 3.5.0
    version_added_collection: community.mysql

Outputs

queries:
  description: List of executed queries which modified DB's state.
  returned: always
  sample:
  - CHANGE MASTER TO MASTER_HOST='primary2.example.com',MASTER_PORT=3306
  type: list
  version_added: 0.1.0
  version_added_collection: community.mysql

See also

• community.mysql.mysql_info
• MySQL replication reference: Complete reference of the MySQL replication documentation. link
• MySQL encrypted replication reference.: Setting up MySQL replication to use encrypted connection. link
• MariaDB replication reference: Complete reference of the MariaDB replication documentation. link