ansible.mysql.mysql_tablespace module – Manage MySQL InnoDB general tablespaces

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.

New in ansible.mysql 5.2.0

Synopsis 

Create, update, rename, or drop MySQL InnoDB general tablespaces.
Supports general tablespace lifecycle operations on MySQL servers.
Key rotation is outside this module’s scope because MySQL exposes it through ALTER INSTANCE ROTATE INNODB MASTER KEY, not as a per-tablespace lifecycle action.

Requirements 

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

PyMySQL (Python 2.7 and Python 3.x)

Parameters 

Parameter	Comments
autoextend_size integer	Tablespace autoextend size in bytes. Supported on MySQL `8.0.23` and later. Can be set during create or alter.
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`
datafile string	Tablespace datafile path. Create-only. Required on MySQL versions earlier than `8.0.14`. Optional on MySQL `8.0.14` and later.
encryption string	Whether the general tablespace should be encrypted. Uses MySQL literal values `Y` or `N`. Supported on MySQL `8.0.13` and later. Can be set during create or alter. Does not rotate InnoDB master keys. Key rotation remains an instance-level operation exposed through `ALTER INSTANCE ROTATE INNODB MASTER KEY`.
file_block_size integer	File block size for the general tablespace. Create-only. Existing tablespaces are compared best-effort using available metadata. Deeper semantic validation is left to MySQL because valid values depend on `innodb_page_size` and compressed-page rules rather than a standalone whitelist.
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 / required	Name of the tablespace to manage.
rename_to string	Rename the tablespace to this new name. Alter-only. Supported on MySQL `8.0.3` and later. Cannot be used when `state` is `absent`.
state string	If `present`, create the tablespace when it does not exist. If `present`, alter mutable tablespace attributes when it already exists. If `absent`, drop the tablespace. Choices: `"absent"` `"present"` ← (default)

Attributes 

Attribute	Support	Description
check_mode	Support: full In check mode the module reads current tablespace state and reports the DDL it would run without executing it.	Can run in check_mode and return changed status prediction without modifying target.
idempotent	Support: full The module emits DDL only when the requested tablespace lifecycle state differs from the current server state.	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 only.
datafile and file_block_size are create-only options.
rename_to is an alter-only option.
Key rotation is outside this module’s scope because MySQL exposes it with ALTER INSTANCE ROTATE INNODB MASTER KEY.
Metadata reads used for idempotency and post-change verification may require the PROCESS privilege.
DROP TABLESPACE requires the tablespace to be empty.
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.

Examples 

# If you encounter the "Please explicitly state intended protocol" error,
# use the login_unix_socket argument
- name: Create a MySQL general tablespace
  ansible.mysql.mysql_tablespace:
    name: app_data
    datafile: ./app_data.ibd
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Create a MySQL general tablespace with file block and autoextend settings
  ansible.mysql.mysql_tablespace:
    name: analytics_data
    datafile: ./analytics_data.ibd
    file_block_size: 8192
    autoextend_size: 4194304

- name: Enable encryption on a MySQL tablespace
  ansible.mysql.mysql_tablespace:
    name: app_data
    encryption: Y

- name: Rename a MySQL tablespace
  ansible.mysql.mysql_tablespace:
    name: app_data
    rename_to: archive_data

- name: Drop an empty MySQL tablespace
  ansible.mysql.mysql_tablespace:
    name: archive_data
    state: absent

Return Values 

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

Key	Description
queries list / elements=string	List of executed queries. Returned: when changed Sample: ["CREATE TABLESPACE `app_data` ADD DATAFILE './app_data.ibd' ENGINE = InnoDB"]
tablespace dictionary	Normalized representation of the MySQL tablespace after module execution when server metadata is available. In create check mode, this is a predicted subset derived from requested values because no post-create server metadata exists yet. Returned: when `state` is `present`
attached_tables list / elements=string	Tables attached to the tablespace when the server exposes them. Returned: success Sample: `["app/orders"]`
autoextend_size integer	Autoextend size in bytes when available. Returned: success Sample: `4194304`
datafile string	Tablespace datafile path when available. Returned: success Sample: `"./app_data.ibd"`
encryption string	Encryption state when available. Returned: success Sample: `"N"`
name string	Tablespace name after module execution. Returned: success Sample: `"app_data"`
page_size integer	InnoDB page size in bytes when available. Returned: success Sample: `16384`
server_implementation string	Server implementation that produced the result. Returned: success Sample: `"mysql"`
zip_page_size integer	Compressed page size in bytes when available. Returned: success Sample: `8192`

Authors

Ron Gershburg (@ronger4)