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

路径

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

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

如果存在默认配置文件 ~/.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 的复制。

与 MySQL 变量 MASTER_AUTO_POSITION 相同。

选项

  • false ← (默认)

  • true

primary_connect_retry

别名：master_connect_retry

整数

与 MySQL 变量 MASTER_CONNECT_RETRY 相同。

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*（默认路径），则会导致错误“主机‘127.0.0.1’不允许连接到此 MariaDB 服务器”。

  • 如果不需要来自配置文件（例如，/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)