ansible.mysql.mysql_partition module – Manage MySQL table partitions

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

New in ansible.mysql 5.2.0

Synopsis 

Add, drop, reorganize, truncate, or run maintenance operations on MySQL table partitions.
Supports RANGE, RANGE COLUMNS, LIST, LIST COLUMNS, HASH, and KEY partition types.
The module auto-detects the partition method of the target table and generates the appropriate SQL syntax.
The module is limited to MySQL and fails on MariaDB.

Requirements 

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

PyMySQL (Python 2.7 and Python 3.x)

Parameters 

Parameter	Comments
action string / required	Partition operation to perform. `add` adds a new partition. For RANGE and LIST types, `name` and `value` are required. For HASH and KEY types, `number` is required instead. `drop` removes partitions. Only valid for RANGE and LIST types. `reorganize` splits or merges partitions. Only valid for RANGE and LIST types. Requires `name` and `into`. `truncate` removes all rows from specified partitions without dropping them. `check`, `repair`, `analyze`, and `optimize` run maintenance operations on specified partitions. Choices: `"add"` `"drop"` `"reorganize"` `"truncate"` `"check"` `"repair"` `"analyze"` `"optimize"`
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`
into list / elements=dictionary	List of target partition definitions for reorganize. Each element is a dictionary with `into[].name` and `into[].value` keys. Required when `action=reorganize`.
name string / required	Name of the target partition.
value string / required	Partition boundary expression for the target partition, written as raw SQL.
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 list / elements=string	Partition name or names to operate on. For `action=add` on RANGE and LIST partition types, provide exactly one partition name. For `action=drop`, `action=truncate`, `action=check`, `action=repair`, `action=analyze`, and `action=optimize`, provide one or more partition names. For `action=reorganize`, specifies the source partitions to reorganize. For maintenance and truncate actions, a single-element list containing `ALL` targets every partition.
number integer	Number of partitions to add. Used only when `action=add` for HASH and KEY partition types.
schema string	Database (schema) containing the table. If omitted, the current default database from the connection is used.
table string / required	Name of the partitioned table to manage.
value string	Partition boundary expression, written as raw SQL. For RANGE partitions, this is the expression used in `VALUES LESS THAN`, for example `2024`, `MAXVALUE`, or `'2024-07-01'`. For LIST partitions, this is the expression used in `VALUES IN`, for example `7,8,9`. Required when `action=add` for RANGE and LIST partition types.

Attributes 

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
idempotent	Support: partial `action=add` for RANGE and LIST types is idempotent when the partition already exists. `action=drop` is idempotent when the partition does not exist. `action=reorganize` is idempotent when the target partition layout already matches `into`. Maintenance operations and truncate always report `changed=true`. `action=add` for HASH and KEY types always reports `changed=true`.	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

MariaDB is not supported. The module fails with an error on MariaDB servers.
DROP PARTITION is only supported for RANGE and LIST partition types. HASH and KEY partitions cannot be dropped individually.
REORGANIZE PARTITION with value definitions is only supported for RANGE and LIST types.
The value and into[].value parameters accept raw SQL expressions. They are validated against common SQL injection patterns but are not parameterized.
Each invocation runs a single ALTER TABLE ... PARTITION statement.
For action=add on HASH or KEY partitions, each call increases the partition count and is not idempotent.
Reducing HASH and KEY partition counts with COALESCE PARTITION is not currently supported.
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 

- name: Add a RANGE partition for the next year
  ansible.mysql.mysql_partition:
    table: events
    schema: mydb
    action: add
    name: p2025
    value: "2026"
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Add a LIST partition for new regions
  ansible.mysql.mysql_partition:
    table: sales
    schema: mydb
    action: add
    name: p_south
    value: "10, 11, 12"
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Add partitions to a HASH-partitioned table
  ansible.mysql.mysql_partition:
    table: sessions
    schema: mydb
    action: add
    number: 4
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Drop an old partition
  ansible.mysql.mysql_partition:
    table: events
    schema: mydb
    action: drop
    name:
      - p2020
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Reorganize a partition into two
  ansible.mysql.mysql_partition:
    table: events
    schema: mydb
    action: reorganize
    name:
      - p2024
    into:
      - name: p2024h1
        value: "2024"
      - name: p2024h2
        value: "2025"
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Truncate a partition
  ansible.mysql.mysql_partition:
    table: events
    schema: mydb
    action: truncate
    name:
      - p2020
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Analyze all partitions
  ansible.mysql.mysql_partition:
    table: events
    schema: mydb
    action: analyze
    name:
      - ALL
    login_unix_socket: /run/mysqld/mysqld.sock

- name: Monthly partition rotation
  block:
    - name: Add next month partition
      ansible.mysql.mysql_partition:
        table: events
        schema: mydb
        action: add
        name: p202502
        value: "'2025-03-01'"
        login_unix_socket: /run/mysqld/mysqld.sock

    - name: Drop oldest partition
      ansible.mysql.mysql_partition:
        table: events
        schema: mydb
        action: drop
        name:
          - p202401
        login_unix_socket: /run/mysqld/mysqld.sock

Return Values 

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

Key	Description
msg string	Human-readable description of the result. Returned: always Sample: `"Partition p2025 added."`
partition_info list / elements=dictionary	Partition metadata from `INFORMATION_SCHEMA.PARTITIONS` after the operation. Returned: success
PARTITION_DESCRIPTION string	Partition boundary or value list as reported by `INFORMATION_SCHEMA.PARTITIONS`. Returned: success Sample: `"2026"`
PARTITION_EXPRESSION string	Expression used by the table partition definition. Returned: success Sample: `"created_year"`
PARTITION_METHOD string	Partitioning method used by the table. Returned: success Sample: `"RANGE"`
PARTITION_NAME string	Name of the partition. Returned: success Sample: `"p2025"`
PARTITION_ORDINAL_POSITION integer	Position of the partition within the table definition. Returned: success Sample: `4`
TABLE_ROWS integer	Estimated number of rows stored in the partition. Returned: success Sample: `0`
queries list / elements=string	List of SQL queries executed (or that would be executed in check mode). Returned: always Sample: ["ALTER TABLE `mydb`.`events` ADD PARTITION (PARTITION `p2025` VALUES LESS THAN (2026))"]

Authors

Ron Gershburg (@rgershbu)

ansible.mysql.mysql_partition module – Manage MySQL table partitions

Synopsis 

Requirements 

Parameters 

Attributes 

Notes 

See Also 

Examples 

Return Values 

Authors

Collection links