community.mysql.mysql_db 模块 – 从远程主机添加或删除 MySQL 或 MariaDB 数据库

注意

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

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

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

要在 Playbook 中使用它，请指定：community.mysql.mysql_db。

概要

  • 从远程主机添加或删除 MySQL 或 MariaDB 数据库。

要求

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

  • PyMySQL (Python 2.7 和 Python 3.x)

  • mysql (命令行二进制文件)

  • mysqldump (命令行二进制文件)

参数

参数

注释

ca_cert

别名：ssl_ca

路径

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

chdir

路径

在 community.mysql 3.4.0 中添加

更改当前工作目录。

例如，当 state=import 并且转储文件包含相对路径时，这可能很有用。

check_hostname

布尔值

在 community.mysql 1.1.0 中添加

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

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

需要 pymysql >= 0.7.11。

选项

  • false

  • true

check_implicit_admin

布尔值

在 community.mysql 0.1.0 中添加

在尝试提供的凭据之前，检查 mysql 是否允许以 root/nopassword 身份登录。

如果成功，则将忽略传递的 login_user/login_password。

选项

  • false ← (默认)

  • true

client_cert

别名：ssl_cert

路径

客户端公钥证书的路径。

client_key

别名：ssl_key

路径

客户端私钥的路径。

collation

字符串

排序模式（排序）。这仅适用于新的表/数据库，并且不会更新现有的表/数据库，这是 MySQL 的一个限制。

默认： ""

config_file

路径

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

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

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

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

默认： "~/.my.cnf"

config_overrides_defaults

布尔值

在 community.mysql 0.1.0 中添加

如果 yes，则 config_file 中的连接参数将覆盖 login_host 和 login_port 参数的默认值。

当 stat 为 present 或 absent 时使用，否则忽略。

它需要在目标主机上使用 Python 3.5+ 作为默认解释器。

选项

  • false ← (默认)

  • true

connect_timeout

整数

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

默认： 30

dump_extra_args

字符串

在 community.mysql 0.1.0 中添加

为 mysqldump 提供额外的参数。仅当 state=dump 时使用，否则忽略。

encoding

字符串

要使用的编码模式，示例包括 utf8 或 latin1_swedish_ci，在创建数据库、转储或导入 SQL 脚本时。

默认： ""

force

布尔值

在 community.mysql 0.1.0 中添加

即使出现 SQL 错误，也继续转储或导入。

仅当 state 为 dump 或 import 时使用。

选项

  • false ← (默认)

  • true

hex_blob

布尔值

在 community.mysql 0.1.0 中添加

使用十六进制表示法转储二进制列。

选项

  • false ← (默认)

  • true

ignore_tables

list / elements=string

一个表名列表，这些表名在转储时将被忽略，格式为 database_name.table_name。

默认值: []

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

字符串

用于身份验证的用户名。

master_data

整数

在 community.mysql 0.1.0 中添加

用于转储主复制服务器的选项，以生成一个可用于将另一个服务器设置为主服务器的从服务器的转储文件。

0 表示不包含主数据。

1 表示生成从服务器启动复制过程所需的 ‘CHANGE MASTER TO’ 语句。

2 表示生成注释掉的 ‘CHANGE MASTER TO’。

可在 state=dump 时使用。

选项

  • 0 ← (默认)

  • 1

  • 2

name

别名: db

list / elements=string / required

要添加或删除的数据库的名称。

仅当 state 为 dump 或 import 时，才可以提供 name=all。

数据库列表通过 state=dump、state=present 和 state=absent 提供。

如果 name=all，则其工作方式类似于 mysqldump 的 --all-databases 选项 (在 2.0 中添加)。

pipefail

布尔值

在 community.mysql 3.4.0 中添加

当 state=dump 并且使用压缩时，使用 bash 而不是 sh 并添加 -o pipefail 来捕获 mysql_dump 命令的错误。

默认值为 no，以防止在没有 bash 作为默认解释器的系统上出现问题。

默认值将在 community.mysql 4.0.0 中更改为 yes。

选项

  • false ← (默认)

  • true

quick

布尔值

用于转储大型表的选项。

选项

  • false

  • true ← (默认)

restrict_config_file

布尔值

在 community.mysql 0.1.0 中添加

仅读取传递的 config_file。

当 state 为 dump 或 import 时，默认情况下，模块使用 --defaults-extra-file 命令行参数将 config_file 参数传递给底层 mysql/mysqldump 实用程序，这些实用程序会读取指定的选项文件以及通常的选项文件。

如果不需要此行为，请使用 yes 仅读取指定的选项文件。

选项

  • false ← (默认)

  • true

single_transaction

布尔值

在单个事务中执行转储。

选项

  • false ← (默认)

  • true

skip_lock_tables

布尔值

在 community.mysql 0.1.0 中添加

跳过锁定表以进行读取。当 state=dump 时使用，否则忽略。

选项

  • false ← (默认)

  • true

state

字符串

数据库状态。

选项

  • "absent"

  • "dump"

  • "import"

  • "present" ← (默认)

target

路径

转储文件在远程主机上的位置，用于从中读取或写入。

支持未压缩的 SQL 文件 (.sql) 以及 bzip2 (.bz2)、gzip (.gz) 和 xz (在 2.0 中添加) 压缩文件。

unsafe_login_password

布尔值

在 community.mysql 0.1.0 中添加

如果 no，模块将安全地使用 login_password 值的经过 shell 转义的版本。

仅当该值中存在特殊符号并且发生 Access denied 错误时，才可以使用 yes。

仅当 state 为 import 或 dump 并且传递了 login_password 时使用，否则忽略。

选项

  • false ← (默认)

  • true

use_shell

布尔值

在 community.mysql 0.1.0 中添加

用于防止导入的 target 文件被压缩时出现 Broken pipe 错误。

如果 yes，模块将在内部通过 shell 执行命令。

当 state=import 时使用，否则忽略。

选项

  • false ← (默认)

  • true

属性

属性

支持

描述

check_mode

支持: 完全

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

注意事项

注意

  • 与 MariaDB 或 MySQL 兼容。

  • 远程主机上需要 mysql 和 mysqldump 二进制文件。

  • 当 state 为 import 时，此模块是非幂等的，并且如果多次运行，每次都会导入转储文件。

  • 远程主机上需要安装 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 服务器的信息。

community.mysql.mysql_variables

管理 MySQL 或 MariaDB 全局变量。

community.mysql.mysql_user

从 MySQL 或 MariaDB 数据库添加或删除用户。

community.mysql.mysql_replication

管理 MySQL 或 MariaDB 复制。

MySQL 命令行客户端参考

MySQL 命令行客户端文档的完整参考。

mysqldump 参考

``mysqldump`` 客户端实用程序文档的完整参考。

CREATE DATABASE 参考

CREATE DATABASE 命令文档的完整参考。

DROP DATABASE 参考

DROP DATABASE 命令文档的完整参考。

示例

# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument
- name: Create a new database with name 'bobdata'
  community.mysql.mysql_db:
    name: bobdata
    state: present
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Create new databases with names 'foo' and 'bar'
  community.mysql.mysql_db:
    name:
      - foo
      - bar
    state: present

# Copy database dump file to remote host and restore it to database 'my_db'
- name: Copy database dump file
  copy:
    src: dump.sql.bz2
    dest: /tmp

- name: Restore database
  community.mysql.mysql_db:
    name: my_db
    state: import
    target: /tmp/dump.sql.bz2

- name: Restore database ignoring errors
  community.mysql.mysql_db:
    name: my_db
    state: import
    target: /tmp/dump.sql.bz2
    force: true

- name: Dump multiple databases
  community.mysql.mysql_db:
    state: dump
    name: db_1,db_2
    target: /tmp/dump.sql

- name: Dump multiple databases
  community.mysql.mysql_db:
    state: dump
    name:
      - db_1
      - db_2
    target: /tmp/dump.sql

- name: Dump all databases to hostname.sql
  community.mysql.mysql_db:
    state: dump
    name: all
    target: /tmp/dump.sql

- name: Dump all databases to hostname.sql including master data
  community.mysql.mysql_db:
    state: dump
    name: all
    target: /tmp/dump.sql
    master_data: 1

# Import of sql script with encoding option
- name: >
    Import dump.sql with specific latin1 encoding,
    similar to mysql -u <username> --default-character-set=latin1 -p <password> < dump.sql
  community.mysql.mysql_db:
    state: import
    name: all
    encoding: latin1
    target: /tmp/dump.sql

# Dump of database with encoding option
- name: >
    Dump of Databse with specific latin1 encoding,
    similar to mysqldump -u <username> --default-character-set=latin1 -p <password> <database>
  community.mysql.mysql_db:
    state: dump
    name: db_1
    encoding: latin1
    target: /tmp/dump.sql

- name: Delete database with name 'bobdata'
  community.mysql.mysql_db:
    name: bobdata
    state: absent

- name: Make sure there is neither a database with name 'foo', nor one with name 'bar'
  community.mysql.mysql_db:
    name:
      - foo
      - bar
    state: absent

# Dump database with argument not directly supported by this module
# using dump_extra_args parameter
- name: Dump databases without including triggers
  community.mysql.mysql_db:
    state: dump
    name: foo
    target: /tmp/dump.sql
    dump_extra_args: --skip-triggers

- name: Try to create database as root/nopassword first. If not allowed, pass the credentials
  community.mysql.mysql_db:
    check_implicit_admin: true
    login_user: bob
    login_password: 123456
    name: bobdata
    state: present

- name: Dump a database with compression and catch errors from mysqldump with bash pipefail
  community.mysql.mysql_db:
    state: dump
    name: foo
    target: /tmp/dump.sql.gz
    pipefail: true

返回值

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

键

描述

db

字符串

以空格分隔的字符串格式的数据库名称。

返回: 始终

示例: "foo bar"

db_list

list / elements=string

数据库名称列表。

返回: 始终

示例: ["foo", "bar"]

executed_commands

list / elements=string

在 community.mysql 0.1.0 中添加

尝试运行的命令列表。

返回: 如果已执行

示例: ["CREATE DATABASE acme"]

作者

  • Ansible 核心团队