community.mysql.mysql_replication 模块 – 管理 MySQL 或 MariaDB 复制

注意

此模块是 community.mysql 集合 (版本 3.11.0) 的一部分。

如果您使用的是 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.mysql。要使用此模块，您需要其他要求，有关详细信息，请参见 需求。

要在 playbook 中使用它，请指定：community.mysql.mysql_replication。

概要

  • 管理 MySQL 或 MariaDB 服务器复制、副本、主服务器状态，获取和更改主服务器主机。

需求

执行此模块的主机需要以下需求。

  • PyMySQL (Python 2.7 和 Python 3.x)

参数

参数

注释

ca_cert

别名：ssl_ca

路径

证书颁发机构 (CA) 证书的路径。如果使用此选项，则必须指定与服务器使用的证书相同的证书。

channel

字符串

在 community.mysql 0.1.0 中添加

复制通道的名称。

从 MySQL 5.7 开始支持多源复制。

与 *connection_name* 互斥。

更多信息请参见 https://dev.mysqlserver.cn/doc/refman/8.0/en/replication-multi-source.html。

check_hostname

布尔值

在 community.mysql 1.1.0 中添加

当需要 SSL 连接时是否验证服务器主机名。对应于 MySQL CLI 的 --ssl 开关。

将其设置为 false 将禁用主机名验证。谨慎使用。

需要 pymysql >= 0.7.11。

选项

  • false

  • true

client_cert

别名：ssl_cert

路径

客户端公钥证书的路径。

client_key

别名：ssl_key

路径

客户端私钥的路径。

config_file

路径

指定一个配置文件，从中读取用户名和密码。

如果存在，则即使未指定 *config_file*，也会读取默认配置文件 ~/.my.cnf。

如果存在，则默认配置文件 ~/.my.cnf 必须包含一个 [client] 部分，这是 MySQL 连接器的要求。

要防止读取默认配置文件，请将 *config_file* 设置为空字符串。

默认值： "~/.my.cnf"

connect_timeout

整数

连接到 MySQL 服务器时的连接超时。

默认值： 30

connection_name

字符串

在 community.mysql 0.1.0 中添加

主连接的名称。

从 MariaDB 10.0.1 开始支持。

与 *channel* 互斥。

更多信息请参见 https://mariadb.com/kb/en/library/multi-source-replication/。

fail_on_error

布尔值

在 community.mysql 0.1.0 中添加

调用 mysql 时发生错误则失败。

选项

  • false ← (默认)

  • true

login_host

字符串

运行数据库的主机。

在某些情况下，对于本地连接，需要使用 *login_unix_socket=/path/to/mysqld/socket*（通常为 /var/run/mysqld/mysqld.sock），而不是 *login_host=localhost*。

默认值： "localhost"

login_password

字符串

用于身份验证的密码。

login_port

整数

MySQL 服务器的端口。如果使用 login_port，则需要将 *login_host* 定义为 localhost 以外的值。

默认值： 3306

login_unix_socket

字符串

本地连接的 Unix 域套接字的路径。

使用此参数可避免 Please explicitly state intended protocol 错误。

login_user

字符串

用于身份验证的用户名。

mode

字符串

模块操作模式。可以是 changeprimary (CHANGE MASTER TO) - 从 community.mysql 3.10.0 开始也适用于 MySQL 8.0.23 及更高版本，changereplication (CHANGE REPLICATION SOURCE TO) - 仅在 MySQL 8.0.23 及更高版本中受支持，getprimary (SHOW MASTER STATUS)，getreplica (SHOW REPLICA STATUS)，startreplica (START REPLICA)，stopreplica (STOP REPLICA)，resetprimary (RESET MASTER) - 从 community.mysql 0.1.0 开始支持，resetreplica (RESET REPLICA)，resetreplicaall (RESET REPLICA ALL)。

选项

  • "changeprimary"

  • "changereplication"

  • "getprimary"

  • "getreplica" ← (默认)

  • "startreplica"

  • "stopreplica"

  • "resetprimary"

  • "resetreplica"

  • "resetreplicaall"

primary_auto_position

别名：master_auto_position

布尔值

主机是否使用基于 GTID 的复制。

与 MASTER_AUTO_POSITION mysql 变量相同。

选项

  • false ← (默认)

  • true

primary_connect_retry

别名：master_connect_retry

整数

与 MASTER_CONNECT_RETRY mysql 变量相同。

primary_delay

别名: master_delay

整数

在 community.mysql 0.1.0 中添加

落后于主服务器状态的时间（以秒为单位）。

与MySQL变量MASTER_DELAY相同。

从MySQL 5.6开始可用。

更多信息请参见 https://dev.mysqlserver.cn/doc/refman/8.0/en/replication-delayed.html.

primary_host

别名: master_host

字符串

与MySQL变量MASTER_HOST相同。

primary_log_file

别名: master_log_file

字符串

与MySQL变量MASTER_LOG_FILE相同。

primary_log_pos

别名: master_log_pos

整数

与MySQL变量MASTER_LOG_POS相同。

primary_password

别名: master_password

字符串

与MySQL变量MASTER_PASSWORD相同。

primary_port

别名: master_port

整数

与MySQL变量MASTER_PORT相同。

primary_ssl

别名: master_ssl

布尔值

与MySQL变量MASTER_SSL相同。

设置为yes时，只有在能够建立加密连接的情况下，连接尝试才会成功。

详情请参考 MySQL加密复制文档。

默认值为false。

选项

  • false

  • true

primary_ssl_ca

别名: master_ssl_ca

字符串

与MySQL变量MASTER_SSL_CA相同。

详情请参考 MySQL加密复制文档。

primary_ssl_capath

别名: master_ssl_capath

字符串

与MySQL变量MASTER_SSL_CAPATH相同。

详情请参考 MySQL加密复制文档。

primary_ssl_cert

别名: master_ssl_cert

字符串

与MySQL变量MASTER_SSL_CERT相同。

详情请参考 MySQL加密复制文档。

primary_ssl_cipher

别名: master_ssl_cipher

字符串

与MySQL变量MASTER_SSL_CIPHER相同。

指定副本对复制连接允许使用的一个或多个密码的冒号分隔列表。

详情请参考 MySQL加密复制文档。

primary_ssl_key

别名: master_ssl_key

字符串

与MySQL变量MASTER_SSL_KEY相同。

详情请参考 MySQL加密复制文档。

primary_ssl_verify_server_cert

布尔值

在community.mysql 3.5.0中添加

与MySQL变量相同。

选项

  • false ← (默认)

  • true

primary_use_gtid

别名: master_use_gtid

字符串

在 community.mysql 0.1.0 中添加

配置副本以使用MariaDB全局事务ID。

disabled 等同于 MASTER_USE_GTID=no 命令。

要查找有关可用值的信息，请参见 https://mariadb.com/kb/en/library/change-master-to/#master_use_gtid.

自MariaDB 10.0.2起可用。

选项

  • "current_pos"

  • "replica_pos"

  • "disabled"

primary_user

别名: master_user

字符串

与MySQL变量MASTER_USER相同。

relay_log_file

字符串

与MySQL变量相同。

relay_log_pos

整数

与MySQL变量相同。

属性

属性

支持

描述

check_mode

支持: 不支持

可以在check_mode下运行并返回更改状态预测，而无需修改目标。

备注

注意

  • 兼容MariaDB或MySQL。

  • 如果需要字符串类型参数的空值，请使用空字符串。

  • 需要在远程主机上安装PyMySQL（Python 2.7和Python 3.X）包。可以使用apt-get install python-pymysql（Ubuntu；参见ansible.builtin.apt）或yum install python2-PyMySQL（RHEL/CentOS/Fedora；参见ansible.builtin.yum）安装Python包。对于较新的Fedora版本，也可以使用dnf install python2-PyMySQL；参见ansible.builtin.dnf。

  • 确保在Ansible发现的Python解释器目标机器上安装了PyMySQL库。例如，如果Ansible发现并使用Python 3，则需要安装Python 3版本的PyMySQL。如果Ansible发现并使用Python 2，则需要安装Python 2版本的PyMySQL。

  • 如果遇到问题，可以通过指定ansible_python_interpreter来强制Ansible使用所需的Python解释器，这可能会有所帮助。更多信息，请参见 https://docs.ansible.org.cn/ansible/latest/reference_appendices/interpreter_discovery.html.

  • 当您传递凭据时，login_password和login_user都是必需的。如果没有，模块将尝试从~/.my.cnf读取凭据，最后回退到使用MySQL默认登录名“root”且没有密码。

  • 如果本地连接出现问题，使用login_unix_socket=/path/to/mysqld/socket而不是login_host=localhost可能会有所帮助。例如，10.4及更高版本的MariaDB默认安装使用unix_socket身份验证插件，如果不使用login_unix_socket=/var/run/mysqld/mysqld.sock（默认路径），则会导致错误“Host ‘127.0.0.1’ is not allowed to connect to this MariaDB server”。

  • 如果不需要来自配置文件（例如，/root/.my.cnf）的凭据来连接到数据库服务器，但文件存在且不包含[client]部分（在任何其他有效指令之前），它将被读取，这将导致连接失败，为避免这种情况，请将其设置为空字符串（例如config_file: ''）。

  • 要避免Please explicitly state intended protocol错误，请使用login_unix_socket参数，例如login_unix_socket: /run/mysqld/mysqld.sock。

  • 或者，为了避免在每次调用时都使用login_unix_socket参数，您可以使用目标主机上的MySQL配置文件（通常为~/.my.cnf）中的`socket`选项指定套接字路径，例如socket=/var/lib/mysql/mysql.sock。

另请参阅

另请参阅

community.mysql.mysql_info

收集有关MySQL或MariaDB服务器的信息。

MySQL复制参考

MySQL复制文档的完整参考。

MySQL加密复制参考。

设置MySQL复制以使用加密连接。

MariaDB复制参考

MariaDB复制文档的完整参考。

示例

# 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

- 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: Change replication source to replica server 192.0.2.1 and use binary log 'mysql-bin.000009' with position 4578
  community.mysql.mysql_replication:
    mode: changereplication
    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: true

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

返回值

常见的返回值已在此处记录此处，以下是此模块特有的字段

键

描述

queries

列表 / 元素=字符串

在 community.mysql 0.1.0 中添加

已执行的修改数据库状态的查询列表。

返回：始终

示例：["CHANGE MASTER TO MASTER_HOST='primary2.example.com',MASTER_PORT=3306"]

作者

  • Balazs Pocze (@banyek)

  • Andrew Klychkov (@Andersson007)

  • Dennis Urtubia (@dennisurtubia)

  • Laurent Indermühle (@laurent-indermuehle)