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 命令行的 `--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 列表 / 元素=字符串	一个表名列表，在转储中将被忽略，格式为数据库名.表名。默认值： `[]`
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 列表 / 元素=字符串 / 必需	要添加或删除的数据库名称。只有当state为`dump`或`import`时，才能提供name=all。当state=dump、state=present和state=absent时，提供数据库列表。如果name=all，则其作用类似于mysqldump的 –all-databases 选项（在2.0中添加）。
pipefail 布尔值在 community.mysql 3.4.0 中添加	使用`bash`代替`sh`，并添加`-o pipefail`以在state=dump且使用压缩时捕获来自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

返回值 

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

键	描述
db 字符串	以空格分隔的字符串格式的数据库名称。返回：始终示例： `"foo bar"`
db_list 列表 / 元素=字符串	数据库名称列表。返回：始终示例： `["foo", "bar"]`
executed_commands 列表 / 元素=字符串在 community.mysql 0.1.0 中添加	尝试运行的命令列表。返回：如果已执行示例： `["CREATE DATABASE acme"]`

作者

Ansible核心团队

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

作者

资源链接