ansible.mariadb.mariadb_perf_schema module – Manage MariaDB Performance Schema setup tables

Note

This module is part of the ansible.mariadb collection (version 6.0.2).

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 ansible.mariadb. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: ansible.mariadb.mariadb_perf_schema.

New in ansible.mariadb 5.1.0

Synopsis

• This module only supports MariaDB; all MySQL-related options will be removed in the next releases. Use the ansible.mysql collection for MySQL automation.

• Manage runtime Performance Schema configuration through setup tables.

• Supports instruments, consumers, actors, and objects.

• Reconciles only the rows requested in the task and leaves unrelated rows untouched.

• This module manages runtime state only. Restart-persistent Performance Schema configuration remains outside its scope.

Requirements

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

• PyMySQL (Python 2.7 and Python 3.x)

Parameters

Parameter	Comments
actors list / elements=dictionary	Actor rows to reconcile in performance_schema.setup_actors.
enabled boolean	Whether matching threads should be instrumented. Required when state=present. Choices: false true
history boolean	Whether history consumers should retain data for matching threads. Required when state=present. Choices: false true
host string / required	Account host pattern.
role string / required	Role pattern.
state string	Whether the actor row should exist. Choices: "absent" "present" ← (default)
user string / required	Account user pattern.
ca_cert aliases: ssl_ca path	The path to a Certificate Authority (CA) certificate. This option, if used, must specify the same certificate as used by the server.
check_hostname boolean added in ansible.mariadb 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. Choices: false true
client_cert aliases: ssl_cert path	The path to a client public key certificate.
client_key aliases: ssl_key path	The path to the client private key.
config_file path	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"
connect_timeout integer	The connection timeout when connecting to the MySQL server. Default: 30
consumers list / elements=dictionary	Consumer rows to reconcile in performance_schema.setup_consumers. Existing consumer rows are updated in place.
enabled boolean / required	Whether the consumer should be enabled. Choices: false true
name string / required	Consumer name.
instruments list / elements=dictionary	Instrument rows to reconcile in performance_schema.setup_instruments. Existing instrument rows are updated in place.
enabled boolean / required	Whether the instrument should be enabled. Choices: false true
name string / required	Instrument name or pattern from performance_schema.setup_instruments, for example statement/%.
timed boolean / required	Whether the instrument should be timed. Choices: false true
login_host string	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"
login_password string	The password used to authenticate with.
login_port integer	Port of the MySQL server. Requires login_host be defined as other than localhost if login_port is used. Default: 3306
login_unix_socket string	The path to a Unix domain socket for local connections. Use this parameter to avoid the Please explicitly state intended protocol error.
login_user string	The username used to authenticate with.
objects list / elements=dictionary	Object rows to reconcile in performance_schema.setup_objects.
enabled boolean	Whether the object should be instrumented. Required when state=present. Choices: false true
object_name string / required	Object name pattern.
object_schema string / required	Schema name pattern.
object_type string / required	Object type stored in Performance Schema.
state string	Whether the object row should exist. Choices: "absent" "present" ← (default)
timed boolean	Whether the object should be timed. Required when state=present. Choices: false true

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
idempotent	Support: full	When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. This assumes that the system controlled/queried by the module has not changed in a relevant way.

Notes

Note

• Compatible with MariaDB or MySQL when the requested Performance Schema sections are available on the server.

• The module requires Performance Schema to be enabled and the requested setup table columns to exist.

• Changes are runtime only and are not persisted across restart by this module.

• Requires the PyMySQL (Python 2.7 and Python 3.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 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. If ansible discovers and uses Python 2, you need to install the Python 2 version of PyMySQL.

• 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 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``.

• 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

ansible.mariadb.mariadb_query

Run MariaDB queries.

MySQL Performance Schema reference

Oracle MySQL Performance Schema documentation.

MariaDB Performance Schema overview

MariaDB Performance Schema documentation.

Examples

- name: Apply a standard monitoring baseline profile
  ansible.mariadb.mariadb_perf_schema:
    login_unix_socket: /run/mysqld/mysqld.sock
    instruments:
      - name: statement/sql/select
        enabled: true
        timed: true
      - name: stage/sql/Opening_tables
        enabled: true
        timed: true
      - name: wait/io/table/sql/handler
        enabled: true
        timed: true
    consumers:
      - name: events_statements_history
        enabled: true
      - name: events_waits_current
        enabled: true

- name: Enable statement instrumentation for one instrument
  ansible.mariadb.mariadb_perf_schema:
    login_unix_socket: /run/mysqld/mysqld.sock
    instruments:
      - name: statement/sql/insert
        enabled: true
        timed: true

- name: Enable one consumer and add one actor row
  ansible.mariadb.mariadb_perf_schema:
    login_unix_socket: /run/mysqld/mysqld.sock
    consumers:
      - name: events_waits_current
        enabled: true
    actors:
      - user: app
        host: '%'
        role: '%'
        enabled: true
        history: false

- name: Remove one object rule
  ansible.mariadb.mariadb_perf_schema:
    login_unix_socket: /run/mysqld/mysqld.sock
    objects:
      - object_type: TABLE
        object_schema: reporting
        object_name: slow_queries
        state: absent

Return Values

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

Key	Description
actors list / elements=dictionary	Normalized requested actor rows after module execution or prediction. Returned: when actors is provided Sample: [{"enabled": true, "history": false, "host": "%", "role": "%", "user": "app"}]
consumers list / elements=dictionary	Normalized requested consumer rows after module execution or prediction. Returned: when consumers is provided Sample: [{"enabled": true, "name": "events_waits_current"}]
instruments list / elements=dictionary	Normalized requested instrument rows after module execution or prediction. Returned: when instruments is provided Sample: [{"enabled": true, "name": "statement/sql/select", "timed": true}]
objects list / elements=dictionary	Normalized requested object rows after module execution or prediction. Returned: when objects is provided Sample: [{"enabled": true, "object_name": "slow_queries", "object_schema": "reporting", "object_type": "TABLE", "timed": false}]
queries list / elements=string	List of executed SQL statements or predicted SQL statements in check mode. Returned: when changed Sample: ["UPDATE performance_schema.setup_consumers SET ENABLED = 'YES' WHERE NAME = 'events_waits_current'"]

Authors

• Ron Gershburg (@ronger4)

Collection links

• Issue Tracker
• Repository (Sources)