community.mysql.mysql_variables module – Manage MySQL global variables


This module is part of the community.mysql collection (version 3.7.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.mysql. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.mysql.mysql_variables.


  • Query / Set MySQL variables.


The below requirements are needed on the host that executes this module.

  • mysqlclient (Python 3.5+) or

  • PyMySQL (Python 2.7 and Python 3.x) or

  • MySQLdb (Python 2.x)





aliases: ssl_ca


The path to a Certificate Authority (CA) certificate. This option, if used, must specify the same certificate as used by the server.



added in community.mysql 1.1.0

Whether to validate the server host name when an SSL connection is required. Corresponds to MySQL CLIs --ssl switch.

Setting this to false disables hostname verification. Use with caution.

Requires pymysql >= 0.7.11.

This option has no effect on MySQLdb.


  • false

  • true


aliases: ssl_cert


The path to a client public key certificate.


aliases: ssl_key


The path to the client private key.



Specify a config file from which user and password are to be read.

The default config file, ~/.my.cnf, if it exists, will be read, even if config_file is not specified.

The default config file, ~/.my.cnf, if it exists, must contain a [client] section as a MySQL connector requirement.

To prevent the default config file from being read, set config_file to be an empty string.

Default: "~/.my.cnf"



The connection timeout when connecting to the MySQL server.

Default: 30



Host running the database.

In some cases for local connections the login_unix_socket=/path/to/mysqld/socket, that is usually /var/run/mysqld/mysqld.sock, needs to be used instead of login_host=localhost.

Default: "localhost"



The password used to authenticate with.



Port of the MySQL server. Requires login_host be defined as other than localhost if login_port is used.

Default: 3306



The path to a Unix domain socket for local connections.

Use this parameter to avoid the Please explicitly state intended protocol error.



The username used to authenticate with.



added in community.mysql 0.1.0

global assigns value to a global system variable which will be changed at runtime but won’t persist across server restarts.

persist assigns value to a global system variable and persists it to the mysqld-auto.cnf option file in the data directory (the variable will survive service restarts).

persist_only persists value to the mysqld-auto.cnf option file in the data directory but without setting the global variable runtime value (the value will be changed after the next service restart).

Supported by MySQL 8.0 or later.

For more information see


  • "global" ← (default)

  • "persist"

  • "persist_only"



If set, then sets variable value to this.


string / required

Variable name to operate.



  • Does not support check_mode.

  • Requires the PyMySQL (Python 2.7 and Python 3.X) or MySQL-python (Python 2.X) package installed on the remote host. The Python package may be installed with apt-get install python-pymysql (Ubuntu; see ansible.builtin.apt) or yum install python2-PyMySQL (RHEL/CentOS/Fedora; see ansible.builtin.yum). You can also use dnf install python2-PyMySQL for newer versions of Fedora; see ansible.builtin.dnf.

  • Be sure you have mysqlclient, PyMySQL, or MySQLdb library installed on the target machine for the Python interpreter Ansible discovers. For example if ansible discovers and uses Python 3, you need to install the Python 3 version of PyMySQL or mysqlclient. If ansible discovers and uses Python 2, you need to install the Python 2 version of either PyMySQL or MySQL-python.

  • If you have trouble, it may help to force Ansible to use the Python interpreter you need by specifying ansible_python_interpreter. For more information, see

  • Both login_password and login_user are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of ‘root’ with no password.

  • If there are problems with local connections, using login_unix_socket=/path/to/mysqld/socket instead of login_host=localhost might help. As an example, the default MariaDB installation of version 10.4 and later uses the unix_socket authentication plugin by default that without using login_unix_socket=/var/run/mysqld/mysqld.sock (the default path) causes the error ``Host ‘’ is not allowed to connect to this MariaDB server``.

  • Alternatively, you can use the mysqlclient library instead of MySQL-python (MySQLdb) which supports both Python 2.X and Python >=3.5. See how to install it.

  • If credentials from the config file (for example, /root/.my.cnf) are not needed to connect to a database server, but the file exists and does not contain a [client] section, before any other valid directives, it will be read and this will cause the connection to fail, to prevent this set it to an empty string, (for example config_file: '').

  • To avoid the Please explicitly state intended protocol error, use the login_unix_socket argument, for example, login_unix_socket: /run/mysqld/mysqld.sock.

  • Alternatively, to avoid using login_unix_socket argument on each invocation you can specify the socket path using the `socket` option in your MySQL config file (usually ~/.my.cnf) on the destination host, for example socket=/var/lib/mysql/mysql.sock.

See Also

See also


Gather information about MySQL servers.

MySQL SET command reference

Complete reference of the MySQL SET command documentation.


# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument
- name: Check for sync_binlog setting
    variable: sync_binlog
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Set read_only variable to 1 persistently
    variable: read_only
    value: 1
    mode: persist

Return Values

Common return values are documented here, the following are the fields unique to this module:




list / elements=string

added in community.mysql 0.1.0

List of executed queries which modified DB’s state.

Returned: if executed

Sample: ["SET GLOBAL `read_only` = 1"]


  • Balazs Pocze (@banyek)