ansible.mysql.mysql_tablespace_info module – Gather MySQL tablespace information

Note

This module is part of the ansible.mysql collection (version 5.2.0).

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

To use it in a playbook, specify: ansible.mysql.mysql_tablespace_info.

New in ansible.mysql 5.2.0

Synopsis

  • Gather general tablespace metadata from MySQL servers.

  • This module returns the general-tablespace view using INFORMATION_SCHEMA.FILES together with the version-appropriate InnoDB metadata family.

  • On 5.7, the module uses INFORMATION_SCHEMA.INNODB_SYS_TABLESPACES, INFORMATION_SCHEMA.INNODB_SYS_DATAFILES, and INFORMATION_SCHEMA.INNODB_SYS_TABLES.

  • On 8.0 or later, the module uses INFORMATION_SCHEMA.INNODB_TABLESPACES, INFORMATION_SCHEMA.INNODB_DATAFILES, and INFORMATION_SCHEMA.INNODB_TABLES.

  • This module is read-only and always reports no change.

Requirements

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

  • PyMySQL (Python 2.7 and Python 3.x)

Parameters

Parameter

Comments

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

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

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.

name

string

Limit the collected information to a single tablespace name.

This matches the general tablespace name.

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 MySQL 5.7.6 or later.

  • This module reports metadata only. Key rotation remains outside scope because MySQL exposes it through ALTER INSTANCE ROTATE INNODB MASTER KEY.

  • Tablespace metadata queries may require the PROCESS privilege.

  • No external tools are required.

  • 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.mysql.mysql_tablespace

Manage MySQL InnoDB general tablespaces.

MySQL INFORMATION_SCHEMA FILES reference

Reference for INFORMATION_SCHEMA.FILES, used as the base MySQL metadata source.

Examples

# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument
- name: Gather MySQL tablespace information
  ansible.mysql.mysql_tablespace_info:
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Gather one MySQL tablespace by name
  ansible.mysql.mysql_tablespace_info:
    login_unix_socket: /run/mysqld/mysqld.sock
    name: app_data

Return Values

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

Key

Description

tablespaces

list / elements=dictionary

List of normalized MySQL tablespace metadata rows.

Rows expose the general-tablespace view returned by the server.

Returned: always

allocated_size

integer

Allocated size in bytes when available.

Returned: when available

Sample: 8388608

attached_tables

list / elements=string

Tables attached to the tablespace when the server exposes them.

Returned: success

Sample: ["app/orders", "app/order_items"]

autoextend_size

integer

Autoextend size in bytes.

Returned: when available

Sample: 8388608

datafile

string

Tablespace datafile path reported by the server.

Returned: when available

Sample: "./app_data.ibd"

encryption

string

Encryption state.

Returned: when available

Sample: "N"

extent_size

integer

Extent size in bytes.

Returned: when available

Sample: 1048576

file_size

integer

Current file size in bytes when available.

Returned: when available

Sample: 16777216

filesystem_block_size

integer

Filesystem block size in bytes when available.

Returned: when available

Sample: 4096

maximum_size

integer

Maximum size in bytes.

Returned: when available

Sample: 67108864

name

string

Tablespace name.

Returned: success

Sample: "app_data"

page_size

integer

InnoDB page size in bytes when available.

Returned: when available

Sample: 16384

space_id

integer

Internal InnoDB space identifier.

Returned: success

Sample: 17

state

string

Tablespace state.

Returned: when available

Sample: "active"

status

string

Tablespace status reported by the server.

Returned: when available

Sample: "NORMAL"

zip_page_size

integer

Compressed page size in bytes.

Returned: when available

Sample: 0

Authors

  • Ron Gershburg (@ronger4)