community.mysql.mysql_query – Run MySQL queries

Note

This plugin is part of the community.mysql collection (version 2.3.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.

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

New in version 0.1.0: of community.mysql

Synopsis

Runs arbitrary MySQL queries.
Pay attention, the module does not support check mode! All queries will be executed in autocommit mode.
To run SQL queries from a file, use community.mysql.mysql_db module.

Requirements

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

PyMySQL (Python 2.7 and Python 3.X), or
MySQLdb (Python 2.x)

Parameters

Parameter	Choices/Defaults	Comments
ca_cert path		The path to a Certificate Authority (CA) certificate. This option, if used, must specify the same certificate as used by the server. aliases: ssl_ca
check_hostname boolean added in 1.1.0 of community.mysql	Choices: no yes	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.
client_cert path		The path to a client public key certificate. aliases: ssl_cert
client_key path		The path to the client private key. aliases: ssl_key
config_file path	Default: "~/.my.cnf"	Specify a config file from which user and password are to be read.
connect_timeout integer	Default: 30	The connection timeout when connecting to the MySQL server.
login_db string		Name of database to connect to and run queries against.
login_host string	Default: "localhost"	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.
login_password string		The password used to authenticate with.
login_port integer	Default: 3306	Port of the MySQL server. Requires login_host be defined as other than localhost if login_port is used.
login_unix_socket string		The path to a Unix domain socket for local connections.
login_user string		The username used to authenticate with.
named_args dictionary		Dictionary of key-value arguments to pass to the query. Mutually exclusive with positional_args.
positional_args list / elements=string		List of values to be passed as positional arguments to the query. Mutually exclusive with named_args.
query raw / required		SQL query to run. Multiple queries can be passed using YAML list syntax. Must be a string or YAML list containing strings.
single_transaction boolean	Choices: no ← yes	Where passed queries run in a single transaction (`yes`) or commit them one-by-one (`no`).

Notes

Note

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 PyMySQL or MySQLdb library installed on the target machine for the Python interpreter Ansible uses, for example, if it is Python 3, you must install the library for Python 3. You can also change the interpreter. For more information, see https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html.
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 '127.0.0.1' 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 https://pypi.org/project/mysqlclient/ how to install it.

Examples

- name: Simple select query to acme db
  community.mysql.mysql_query:
    login_db: acme
    query: SELECT * FROM orders

- name: Select query to db acme with positional arguments
  community.mysql.mysql_query:
    login_db: acme
    query: SELECT * FROM acme WHERE id = %s AND story = %s
    positional_args:
    - 1
    - test

- name: Select query to test_db with named_args
  community.mysql.mysql_query:
    login_db: test_db
    query: SELECT * FROM test WHERE id = %(id_val)s AND story = %(story_val)s
    named_args:
      id_val: 1
      story_val: test

- name: Run several insert queries against db test_db in single transaction
  community.mysql.mysql_query:
    login_db: test_db
    query:
    - INSERT INTO articles (id, story) VALUES (2, 'my_long_story')
    - INSERT INTO prices (id, price) VALUES (123, '100.00')
    single_transaction: yes

Return Values

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

Key	Returned	Description
executed_queries list / elements=string	always	List of executed queries. Sample: ['SELECT * FROM bar', 'UPDATE bar SET id = 1 WHERE id = 2']
query_result list / elements=string	changed	List of lists (sublist for each query) containing dictionaries in column:value form representing returned rows. Sample: [[{'Column': 'Value1'}, {'Column': 'Value2'}], [{'ID': 1}, {'ID': 2}]]
rowcount list / elements=string	changed	Number of affected rows for each subquery. Sample: [5, 1]

Authors

Andrew Klychkov (@Andersson007)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/mysql/mysql_query_module.html

Docs

Docs4dev

Title here