mysql module¶

The mysql module: comprehensive MySQL management.

Fact side: MysqlDatabases (the server's databases and their default character set/collation), MysqlUsers (the user@host accounts and their mysql.user attributes), MysqlUserGrants (one account's grants keyed by database.table, including granted roles), MysqlBinaryLogs (the binary-log file list and sizes), MysqlColumns (one table's column definitions), MysqlConnections (the active client connections from the processlist, without the query text), MysqlEngines (the storage engines and their capabilities), MysqlIndexes (a database's index definitions), MysqlPlugins (the installed plugins and their status), MysqlReplication (the replica channels from SHOW REPLICA STATUS), MysqlStatus (the SHOW GLOBAL STATUS runtime counters), MysqlTables (one database's table metadata and sizes) and MysqlVariables (the SHOW GLOBAL VARIABLES configuration). MysqlDatabases, MysqlUsers and MysqlUserGrants are ports of the mysql facts; every other fact is reemote-original and closes a visibility gap that set leaves open.

Operation side: mysql.database and mysql.user manage databases and accounts (both create/drop AND idempotently alter existing ones); mysql.privileges grants/revokes privileges; mysql.sql executes arbitrary SQL; mysql.dump and mysql.load write/read host-side mysqldump files; mysql.variable tunes global system variables via SET GLOBAL / SET PERSIST; mysql.table and mysql.index manage schema objects; mysql.role manages roles and their memberships; mysql.plugin installs/uninstalls server plugins; mysql.kill terminates a connection or its running query; mysql.optimize runs table maintenance (OPTIMIZE/ANALYZE/CHECK/ REPAIR); and mysql.replica starts/stops/resets replication. All operations talk to the server through the mysql CLI on the target host, targeting MySQL 8.0.22+ syntax (SHOW REPLICA STATUS, START REPLICA).

Credentials decision (developer-approved, the postgresql precedent): The mysql_password connection parameter and user's password option are deliberately dropped. reemote renders raw shell strings into the plan/apply log, so no operation accepts a password. Authenticate with sudo + the unix_socket/auth_socket plugin (sudo=True as root) or a host-side ~/.my.cnf; the optional mysql_defaults_file connection argument renders --defaults-extra-file for a host-side option file holding the credentials. mysql.user takes an auth_plugin option (e.g. auth_socket) instead of a password.

Every fact and operation accepts the connection keyword arguments mysql_user/mysql_host/mysql_port/mysql_database/ mysql_defaults_file (the mysql_* module arguments minus the password, plus the defaults-file escape hatch).

MysqlBinaryLog ¶

Attributes:

Name	Type	Description
`name`		The binary-log file name, e.g. `binlog.000001`.
`size`		The file size in bytes.
`encrypted`		Whether the file is encrypted (MySQL 8.0.14+ reports the `Encrypted` column); None on older servers.

MysqlBinaryLogs ¶

The server's binary-log files and their sizes.

Commands:

mysql -Be 'SHOW BINARY LOGS' || true

Returns:

list[MysqlBinaryLog]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_binary_logs.py.

MysqlColumn ¶

Attributes:

Name	Type	Description
`name`		The column name.
`type`		The full column type, e.g. `varchar(255)` or `int unsigned` (`COLUMN_TYPE`).
`nullable`		Whether the column accepts NULL.
`default`		The default value as text; None when the column has no default (or defaults to NULL).
`key`		The index role: `PRI`, `UNI`, `MUL` or empty.
`extra`		Extra attributes, e.g. `auto_increment` or `DEFAULT_GENERATED`; empty when none.
`comment`		The column comment; empty when none.
`position`		The 1-based ordinal position in the table.

MysqlColumns ¶

One table's column definitions, in ordinal order.

Commands:

mysql -Be "SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_KEY, EXTRA, COLUMN_COMMENT, ORDINAL_POSITION FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = '<database>' AND TABLE_NAME = '<table>' ORDER BY ORDINAL_POSITION"

Returns:

list[MysqlColumn]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_columns.py.

MysqlConnection ¶

Attributes:

Name	Type	Description
`id`		The connection (thread) ID, the operand for `mysql.kill`.
`user`		The authenticated user; None for background threads.
`host`		The client's `host:port`; None for background threads.
`database`		The default database; None when none is selected.
`command`		The thread command, e.g. `Query`, `Sleep`, `Binlog Dump GTID`.
`time`		Seconds the thread has been in its current state.
`state`		The thread state text, e.g. `Sending data`; None when the thread reports no state.

MysqlConnections ¶

The server's client connections, without the query text.

Commands:

mysql -Be 'SELECT ID, USER, HOST, DB, COMMAND, TIME, STATE FROM information_schema.PROCESSLIST'

Returns:

list[MysqlConnection]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_connections.py.

MysqlDatabase ¶

Attributes:

Name	Type	Description
`character_set`		The database's default character set, e.g. `utf8mb4`; None when the server reports none.
`collation_name`		The database's default collation, e.g. `utf8mb4_0900_ai_ci`; None when the server reports none.

MysqlDatabases ¶

The server's databases, keyed by database name.

Commands:

mysql -Be 'SELECT * FROM information_schema.SCHEMATA'

Returns:

dict[str, MysqlDatabase]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_databases.py.

MysqlEngine ¶

Attributes:

Name	Type	Description
`name`		The engine name, e.g. `InnoDB`, `MyISAM`.
`support`		The support level: `DEFAULT`, `YES`, `NO` or `DISABLED`.
`comment`		The engine description.
`transactions`		Whether the engine supports transactions.
`xa`		Whether the engine supports XA transactions.
`savepoints`		Whether the engine supports savepoints.

MysqlEngines ¶

The server's storage engines and their capabilities.

Commands:

mysql -Be 'SELECT ENGINE, SUPPORT, COMMENT, TRANSACTIONS, XA, SAVEPOINTS FROM information_schema.ENGINES'

Returns:

list[MysqlEngine]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_engines.py.

MysqlIndex ¶

Attributes:

Name	Type	Description
`name`		The index name, e.g. `PRIMARY` or `idx_email`.
`table`		The table the index belongs to (unqualified).
`columns`		The indexed column names in key order.
`unique`		Whether the index is UNIQUE (`PRIMARY` included).
`index_type`		The index method, e.g. `BTREE`, `HASH`, `FULLTEXT`, `SPATIAL`.

MysqlIndexes ¶

A database's index definitions, one entry per index.

Commands:

mysql -Be "SELECT TABLE_NAME, INDEX_NAME, NON_UNIQUE, SEQ_IN_INDEX, COLUMN_NAME, INDEX_TYPE FROM information_schema.STATISTICS WHERE TABLE_SCHEMA = '<database>' ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX"

Returns:

list[MysqlIndex]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_indexes.py.

MysqlPlugin ¶

Attributes:

Name	Type	Description
`name`		The plugin name, e.g. `validate_password`.
`status`		The plugin status: `ACTIVE`, `INACTIVE`, `DISABLED` or `DELETED`.
`type`		The plugin type, e.g. `AUTHENTICATION`, `STORAGE ENGINE`, `AUDIT`, `REPLICATION`.
`library`		The shared-library file name the plugin was loaded from; None for built-in plugins.
`license`		The plugin license, e.g. `GPL`; None when unreported.

MysqlPlugins ¶

The server's installed plugins and their status.

Commands:

mysql -Be 'SELECT PLUGIN_NAME, PLUGIN_STATUS, PLUGIN_TYPE, PLUGIN_LIBRARY, PLUGIN_LICENSE FROM information_schema.PLUGINS'

Returns:

list[MysqlPlugin]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_plugins.py.

MysqlReplicaStatus ¶

Attributes:

Name	Type	Description
`channel`		The replication channel name; empty for the default (unnamed) channel.
`source_host`		The replication source's host.
`source_port`		The replication source's port.
`source_user`		The replication user the IO thread authenticates as (a user name, never a credential).
`io_running`		The IO thread state: `Yes`, `No` or `Connecting`.
`sql_running`		The applier thread state: `Yes` or `No`.
`seconds_behind_source`		The replication lag in seconds; None when the applier is stopped or the lag is unknown.
`last_error`		The last replication error text; empty when none.

MysqlReplication ¶

The server's replica channels and their replication state.

Commands:

mysql -Be 'SHOW REPLICA STATUS'

Returns:

list[MysqlReplicaStatus]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_replication.py.

MysqlStatus ¶

The server's global runtime status counters, keyed by counter name.

Commands:

mysql -Be 'SHOW GLOBAL STATUS'

Returns:

dict[str, str]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_status.py.

MysqlTable ¶

Attributes:

Name	Type	Description
`name`		The table name (unqualified).
`engine`		The storage engine, e.g. `InnoDB`; None for views.
`rows`		The row-count estimate (InnoDB statistics, not an exact count); 0 when unreported.
`data_length`		The data size in bytes.
`index_length`		The index size in bytes.
`collation`		The table collation, e.g. `utf8mb4_0900_ai_ci`; None for views.
`comment`		The table comment; empty when none.

MysqlTables ¶

One database's tables and their metadata, in name order.

Commands:

mysql -Be "SELECT TABLE_NAME, ENGINE, TABLE_ROWS, DATA_LENGTH, INDEX_LENGTH, TABLE_COLLATION, TABLE_COMMENT FROM information_schema.TABLES WHERE TABLE_SCHEMA = '<database>' ORDER BY TABLE_NAME"

Returns:

list[MysqlTable]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_tables.py.

MysqlUser ¶

Attributes:

Name	Type	Description
`privileges`		The sorted global privileges parsed from the `*_priv` columns (which are removed from the entry).
`plugin`		The authentication plugin, e.g. `caching_sha2_password` or `auth_socket`; None when the server reports none.
`authentication_string`		The password hash as stored (never a plaintext password); None when empty.
`ssl_type`		The REQUIRE level: `ANY` (SSL), `X509`, `SPECIFIED`; None when no TLS is required.
`ssl_cipher`		The required TLS cipher; None when unset.
`x509_issuer`		The required certificate issuer; None when unset.
`x509_subject`		The required certificate subject; None when unset.
`max_questions`		The MAX_QUERIES_PER_HOUR limit; 0 means unlimited.
`max_updates`		The MAX_UPDATES_PER_HOUR limit; 0 means unlimited.
`max_connections`		The MAX_CONNECTIONS_PER_HOUR limit; 0 means unlimited.
`max_user_connections`		The MAX_USER_CONNECTIONS limit; 0 means unlimited.
`password_expired`		Whether the password is expired.
`is_role`		Whether the account is a role rather than a user.
`account_locked`		Whether the account is locked (MySQL 5.7+).
`default_role`		The account's default role (MariaDB); None when unset.
`max_statement_time`		The statement timeout (MariaDB); None when unreported.
`Password`		The legacy password hash column (MariaDB / MySQL 5.6); None when empty.

MysqlUserGrants ¶

One account's grants, keyed by database.table target.

Commands:

mysql -Be 'SHOW GRANTS FOR "<user>"@"<hostname>"' || true

Returns:

dict[str, list[str]]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_user_grants.py.

MysqlUsers ¶

The server's accounts, keyed by user@host.

Commands:

mysql -Be 'SELECT * FROM mysql.user'

Returns:

dict[str, MysqlUser]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_users.py.

MysqlVariables ¶

The server's global system variables, keyed by variable name.

Commands:

mysql -Be 'SHOW GLOBAL VARIABLES'

Returns:

dict[str, str]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/mysql/mysql_mysql_variables.py.

database `async` ¶

database(
    ctx: OpContext,
    database: str,
    present: bool = True,
    collate: str | None = None,
    charset: str | None = None,
    user: str | None = None,
    user_hostname: str = "localhost",
    user_privileges: str | list[str] = "ALL",
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, alter or remove a MySQL database.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`database`	`str`	Name of the database to manage.	required
`present`	`bool`	Whether the database should exist. Defaults to True.	`True`
`collate`	`str \| None`	Default collation; altered on an existing database when it differs. Defaults to None.	`None`
`charset`	`str \| None`	Default character set; altered on an existing database when it differs. Defaults to None.	`None`
`user`	`str \| None`	MySQL user to grant privileges on this database to. Defaults to None.	`None`
`user_hostname`	`str`	Hostname part of the user to grant to. Defaults to "localhost".	`'localhost'`
`user_privileges`	`str \| list[str]`	Privileges to grant to any specified user. Defaults to "ALL".	`'ALL'`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file (credentials never come from the operation). Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL database commands.

Raises:

CommandNotFoundError, HostConnectionError, OperationError

Examples:

Examples can be found in examples/modules/mysql/mysql_database.py.

dump `async` ¶

dump(
    ctx: OpContext,
    dest: str,
    database: str | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Dump a MySQL database into a host-side .sql file.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`dest`	`str`	Path on the target host to dump the SQL to.	required
`database`	`str \| None`	Name of the database to dump. Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The mysqldump command, always (the operation is stateless).

Raises:

None

Examples:

Examples can be found in examples/modules/mysql/mysql_dump.py.

index `async` ¶

index(
    ctx: OpContext,
    database: str,
    table: str,
    index: str,
    columns: list[str] | None = None,
    unique: bool = False,
    index_type: str = "BTREE",
    present: bool = True,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Create or drop an index on a MySQL table.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`database`	`str`	Database holding the table.	required
`table`	`str`	Table to index.	required
`index`	`str`	Name of the index to manage.	required
`columns`	`list[str] \| None`	Column names or parenthesized expressions to index, in key order; required when present is True. Defaults to None.	`None`
`unique`	`bool`	Create a UNIQUE index. Defaults to False.	`False`
`index_type`	`str`	Index method: BTREE, HASH, FULLTEXT or SPATIAL. Defaults to "BTREE".	`'BTREE'`
`present`	`bool`	Whether the index should exist. Defaults to True.	`True`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL index commands.

Raises:

CommandNotFoundError, HostConnectionError, OperationError, ValueError

Examples:

Examples can be found in examples/modules/mysql/mysql_index.py.

kill `async` ¶

kill(
    ctx: OpContext,
    process_id: int,
    query_only: bool = False,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Terminate a MySQL connection or its running query.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`process_id`	`int`	The connection (thread) ID to kill, as reported by MysqlConnections.	required
`query_only`	`bool`	Abort only the running statement (KILL QUERY), keeping the connection open. Defaults to False.	`False`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The KILL command, always (the operation is stateless).

Raises:

None

Examples:

Examples can be found in examples/modules/mysql/mysql_kill.py.

load `async` ¶

load(
    ctx: OpContext,
    src: str,
    database: str | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Load a host-side .sql file into a MySQL database.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`str`	Path on the target host to read the SQL from.	required
`database`	`str \| None`	Name of the database to import into. Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The load command, always (the operation is stateless).

Raises:

None

Examples:

Examples can be found in examples/modules/mysql/mysql_load.py.

optimize `async` ¶

optimize(
    ctx: OpContext,
    database: str,
    tables: list[str],
    action: str = "optimize",
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Run maintenance on MySQL tables (OPTIMIZE/ANALYZE/CHECK/REPAIR).

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`database`	`str`	Database holding the tables.	required
`tables`	`list[str]`	Table names to maintain, in one statement.	required
`action`	`str`	Maintenance verb: optimize, analyze, check or repair. Defaults to "optimize".	`'optimize'`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The maintenance command, always (the operation is stateless).

Raises:

ValueError

Examples:

Examples can be found in examples/modules/mysql/mysql_optimize.py.

plugin `async` ¶

plugin(
    ctx: OpContext,
    plugin: str,
    present: bool = True,
    soname: str | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Install or uninstall a MySQL server plugin.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`plugin`	`str`	Name of the plugin to manage, e.g. `validate_password`.	required
`present`	`bool`	Whether the plugin should be installed. Defaults to True.	`True`
`soname`	`str \| None`	Shared-library file name the plugin loads from, e.g. `validate_password.so`; required when present is True. Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL plugin commands.

Raises:

CommandNotFoundError, HostConnectionError, OperationError, ValueError

Examples:

Examples can be found in examples/modules/mysql/mysql_plugin.py.

privileges `async` ¶

privileges(
    ctx: OpContext,
    user: str,
    privileges: str | list[str] | set[str],
    user_hostname: str = "localhost",
    database: str = "*",
    table: str = "*",
    flush: bool = True,
    with_grant_option: bool = False,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add or remove MySQL privileges for a user on a target.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`user`	`str`	Name of the user to manage privileges for.	required
`privileges`	`str \| list[str] \| set[str]`	The exact privileges the user should have on the target; anything else currently granted on it is revoked.	required
`user_hostname`	`str`	Hostname part of the user. Defaults to "localhost".	`'localhost'`
`database`	`str`	Database to scope the privileges to; all databases when "". Defaults to "".	`'*'`
`table`	`str`	Table to scope the privileges to; all tables when "" (a named table requires a named database). Defaults to "".	`'*'`
`flush`	`bool`	Follow any change with FLUSH PRIVILEGES. Defaults to True.	`True`
`with_grant_option`	`bool`	Include GRANT OPTION in the desired privileges. Defaults to False.	`False`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL privilege commands.

Raises:

HostConnectionError, OperationError

Examples:

Examples can be found in examples/modules/mysql/mysql_privileges.py.

replica `async` ¶

replica(
    ctx: OpContext,
    running: bool = True,
    reset: bool = False,
    channel: str | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Start, stop or reset MySQL replication on a replica channel.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`running`	`bool`	Whether the replica threads should be running. Defaults to True.	`True`
`reset`	`bool`	Stop replication and discard ALL channel configuration (RESET REPLICA ALL), always yielded; overrides running and channel. Defaults to False.	`False`
`channel`	`str \| None`	The replication channel to address; the default (unnamed) channel when None. Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL replication commands.

Raises:

CommandNotFoundError, HostConnectionError, OperationError

Examples:

Examples can be found in examples/modules/mysql/mysql_replica.py.

role `async` ¶

role(
    ctx: OpContext,
    role: str,
    present: bool = True,
    role_hostname: str = "%",
    members: list[str] | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Create or drop a MySQL role and manage its memberships.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`role`	`str`	Name of the role to manage (MySQL 8.0+).	required
`present`	`bool`	Whether the role should exist; dropping a role revokes all its memberships server-side. Defaults to True.	`True`
`role_hostname`	`str`	Hostname part of the role account. Defaults to "%".	`'%'`
`members`	`list[str] \| None`	Accounts the role should be granted to, each as `user@host`; memberships are only added, never revoked (list every member the role should keep). Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL role commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/mysql/mysql_role.py.

sql `async` ¶

sql(
    ctx: OpContext,
    sql: str,
    database: str | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Execute arbitrary SQL against MySQL.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`sql`	`str`	SQL command(s) to execute.	required
`database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The SQL command, always (the operation is stateless).

Raises:

None

Examples:

Examples can be found in examples/modules/mysql/mysql_sql.py.

table `async` ¶

table(
    ctx: OpContext,
    database: str,
    table: str,
    present: bool = True,
    columns: list[str] | None = None,
    engine: str | None = None,
    charset: str | None = None,
    collate: str | None = None,
    comment: str | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Create or drop a MySQL table.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`database`	`str`	Database to create the table in.	required
`table`	`str`	Name of the table to manage.	required
`present`	`bool`	Whether the table should exist. Defaults to True.	`True`
`columns`	`list[str] \| None`	Column (and constraint) definitions as SQL text, e.g. `id INT PRIMARY KEY AUTO_INCREMENT`; required when present is True. Defaults to None.	`None`
`engine`	`str \| None`	Storage engine, e.g. InnoDB; creation-only. Defaults to None.	`None`
`charset`	`str \| None`	Default character set; creation-only. Defaults to None.	`None`
`collate`	`str \| None`	Default collation; creation-only. Defaults to None.	`None`
`comment`	`str \| None`	Table comment; creation-only. Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL table commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/mysql/mysql_table.py.

user `async` ¶

user(
    ctx: OpContext,
    user: str,
    present: bool = True,
    user_hostname: str = "localhost",
    auth_plugin: str | None = None,
    privileges: str | list[str] | None = None,
    require: str | None = None,
    require_cipher: str | None = None,
    require_issuer: str | None = None,
    require_subject: str | None = None,
    max_connections: int | None = None,
    max_queries_per_hour: int | None = None,
    max_updates_per_hour: int | None = None,
    max_connections_per_hour: int | None = None,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, alter or remove a MySQL user account.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`user`	`str`	Name of the user to manage.	required
`present`	`bool`	Whether the user should exist. Defaults to True.	`True`
`user_hostname`	`str`	Hostname part of the account; changing it addresses a different user@host account. Defaults to "localhost".	`'localhost'`
`auth_plugin`	`str \| None`	Authentication plugin, e.g. `auth_socket`; applied at creation and altered on an existing account when it differs. Replaces the password option (the credentials decision). Defaults to None.	`None`
`privileges`	`str \| list[str] \| None`	Global privileges the user should have, delegated to the mysql.privileges core. Defaults to None.	`None`
`require`	`str \| None`	TLS requirement: "SSL" or "X509". Defaults to None.	`None`
`require_cipher`	`str \| None`	Required TLS cipher (X509 only). Defaults to None.	`None`
`require_issuer`	`str \| None`	Required certificate issuer (X509 only). Defaults to None.	`None`
`require_subject`	`str \| None`	Required certificate subject (X509 only). Defaults to None.	`None`
`max_connections`	`int \| None`	MAX_USER_CONNECTIONS limit. Defaults to None.	`None`
`max_queries_per_hour`	`int \| None`	MAX_QUERIES_PER_HOUR limit. Defaults to None.	`None`
`max_updates_per_hour`	`int \| None`	MAX_UPDATES_PER_HOUR limit. Defaults to None.	`None`
`max_connections_per_hour`	`int \| None`	MAX_CONNECTIONS_PER_HOUR limit. Defaults to None.	`None`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL user commands.

Raises:

CommandNotFoundError, HostConnectionError, OperationError

Examples:

Examples can be found in examples/modules/mysql/mysql_user.py.

variable `async` ¶

variable(
    ctx: OpContext,
    variable: str,
    value: str | int | None = None,
    present: bool = True,
    persist: bool = False,
    mysql_user: str | None = None,
    mysql_host: str | None = None,
    mysql_port: int | None = None,
    mysql_database: str | None = None,
    mysql_defaults_file: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Set or reset a MySQL global system variable.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`variable`	`str`	The system variable name, e.g. `max_connections`.	required
`value`	`str \| int \| None`	The desired value in the server's own text rendering; required when present is True. Defaults to None.	`None`
`present`	`bool`	Set the value when True; remove the persisted override (RESET PERSIST) when False. Defaults to True.	`True`
`persist`	`bool`	Use SET PERSIST (MySQL 8.0+), which applies at runtime AND survives restarts via mysqld-auto.cnf, instead of the runtime-only SET GLOBAL. Defaults to False.	`False`
`mysql_user`	`str \| None`	User to connect as. Defaults to None.	`None`
`mysql_host`	`str \| None`	Server host to connect to. Defaults to None.	`None`
`mysql_port`	`int \| None`	Server port to connect to. Defaults to None.	`None`
`mysql_database`	`str \| None`	Database to open the connection with. Defaults to None.	`None`
`mysql_defaults_file`	`str \| None`	Host-side option file rendered as --defaults-extra-file. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated MySQL variable commands.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/mysql/mysql_variable.py.

mysql module¶

MysqlBinaryLog ¶

MysqlBinaryLogs ¶

MysqlColumn ¶

MysqlColumns ¶

MysqlConnection ¶

MysqlConnections ¶

MysqlDatabase ¶

MysqlDatabases ¶

MysqlEngine ¶

MysqlEngines ¶

MysqlIndex ¶

MysqlIndexes ¶

MysqlPlugin ¶

MysqlPlugins ¶

MysqlReplicaStatus ¶

MysqlReplication ¶

MysqlStatus ¶

MysqlTable ¶

MysqlTables ¶

MysqlUser ¶

MysqlUserGrants ¶

MysqlUsers ¶

MysqlVariables ¶

database async ¶

dump async ¶

index async ¶

kill async ¶

load async ¶

optimize async ¶

plugin async ¶

privileges async ¶

replica async ¶

role async ¶

sql async ¶

table async ¶

user async ¶

variable async ¶

database `async` ¶

dump `async` ¶

index `async` ¶

kill `async` ¶

load `async` ¶

optimize `async` ¶

plugin `async` ¶

privileges `async` ¶

replica `async` ¶

role `async` ¶

sql `async` ¶

table `async` ¶

user `async` ¶

variable `async` ¶