MYSQL on Pigsty v5.0

Module: MYSQL

Mon, 01 Jan 0001 00:00:00 +0000

MySQL is one of the world’s most popular open-source relational databases. Pigsty’s MYSQL module deploys a fixed, native MySQL 8.4 LTS platform on managed nodes: either a standalone instance or a three-node single-primary InnoDB Cluster built on Group Replication, with TLS, backups, monitoring, and lifecycle handled for you.

Current status: Pilot module

MYSQL is a supplementary pilot module. It aims to be a simple, inexpensive, good-enough MySQL cluster — not a peer of the PGSQL module. The core capabilities (deployment and convergence, HA failover, daily backups, monitoring and alerting) have been tested systematically; destructive procedures such as complete-outage recovery and physical restore are deliberately kept manual, with runbooks provided in Administration.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

The MYSQL module is driven by the inventory: you declare the desired cluster, and mysql.yml converges the live state to match. This page covers topology planning and every configuration block; see Parameters for the full reference.

Before You Deploy

Target nodes are NODE-managed, with the shared CA installed at /etc/pki/ca.crt (managed by the node_ca role; the MySQL role only issues leaf certificates);
Package repositories include the mysql module: node_repo_modules: node,infra,mysql, or a local repo cached with repo_extra_packages: [mysql];
The platform is in the support matrix: x86_64 on EL 8/9/10, Debian 12/13, Ubuntu 22/24; or aarch64 on EL 9/10;
The three platform passwords (mysql_root_password, mysql_monitor_password, mysql_cluster_password) are set to production values — preflight rejects CHANGE_ME placeholders.

Identity

Each cluster is an inventory group with two required identity parameters:

Parameters

Mon, 01 Jan 0001 00:00:00 +0000

The MYSQL deployment role deliberately exposes only 11 parameters; the removal role adds 2 protected operations parameters. Software versions, ports, directories, charset, TLS paths, and timer schedules are fixed by the role; memory sizing is derived from node specs. To adjust server behavior, use mysql_parameters.

Quick Reference

Parameter	Level	Default	Description
`mysql_cluster`	Cluster	required	Cluster name and identity
`mysql_seq`	Instance	required	`1` for standalone; sequential `1..3` for HA
`mysql_root_password`	Cluster	`DBUser.Root`	Local root password
`mysql_monitor_password`	Cluster	`DBUser.Monitor`	Exporter identity password
`mysql_cluster_password`	Cluster	`DBUser.Cluster`	AdminAPI/Router/backup identity password
`mysql_databases`	Cluster	`[]`	Additive database declarations
`mysql_users`	Cluster	`[]`	Additive user and grant declarations
`mysql_parameters`	Cluster/Instance	`{}`	`[mysqld]` option overrides
`mysql_backup_enabled`	Cluster	`true`	Daily full-backup timer
`mysql_backup_repo`	Cluster	see below	Local backup path and retention
`mysql_exporter_enabled`	Cluster	`true`	Exporter and monitoring target

The removal parameters are used by mysql-rm.yml:

Administration

Mon, 01 Jan 0001 00:00:00 +0000

This page covers day-to-day operations for the MYSQL module. The governing principle: declare state in the inventory, converge with the playbook. Most anomalies — a dropped member, drifted AdminAPI state — heal with a single ./mysql.yml -l <cluster> rerun. Only three destructive scenarios (member replacement, physical restore, complete-outage recovery) require the manual runbooks below.

Quick Reference

Operation	Command
Deploy / converge a cluster	`./mysql.yml -l <cluster>`
Preflight without changes	`./mysql.yml -l <cluster> --check`
Local root session	`mysql --defaults-extra-file=/etc/mysql/pigsty/root.cnf`
Inspect MGR topology	`SELECT MEMBER_HOST,MEMBER_STATE,MEMBER_ROLE FROM performance_schema.replication_group_members;`
AdminAPI status	`dba.getCluster().status()` in `mysqlsh`
Trigger a backup	`systemctl start mysql-backup` (in HA, only the primary runs it)
Retire a secondary	`./mysql-rm.yml -l <IP> -e mysql_safeguard=false -e mysql_rm_confirm=<instance>`
Retire a whole cluster	`./mysql-rm.yml -l <cluster> -e mysql_safeguard=false -e mysql_rm_confirm=<cluster>`

Status Checks

Run the commands in this page on a cluster member as root: the client configs and secrets under /etc/mysql/pigsty/ are readable by root only. Examples use EL unit names — on Debian/Ubuntu the MySQL service unit is mysql, not mysqld.

Playbook

Mon, 01 Jan 0001 00:00:00 +0000

The MYSQL module ships two playbooks: mysql.yml deploys and converges, while mysql-rm.yml performs protected member retirement and cluster teardown. Re-running the former converges toward declared state; the latter is a separate lifecycle operation whose target, backups, and exact confirmation value must be checked again before every real run.

`mysql.yml`

Runs the full check → install → bootstrap → access → provision → backup → monitor convergence on the selected clusters:

Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

The MYSQL module plugs into Pigsty’s observability stack: metrics flow through mysqld_exporter into VictoriaMetrics, error logs flow through Journald/Vector into VictoriaLogs, Grafana ships 5 dashboards, and vmalert loads 68 recording rules plus 27 alert rules.

Collection Architecture

Each MySQL node runs one mysqld_exporter (port 9104) using the least-privilege monitor account (dbuser_monitor@'127.0.0.1'). Deployment writes a file-based service-discovery target on the Infra node:

/infra/targets/mysql/<instance>.yml     # e.g. my-test-1.yml

The VictoriaMetrics mysql scrape job consumes this directory. mysql_exporter_enabled: false converges the target to an empty list; only mysql-rm.yml deletes target files.

Metrics

Mon, 01 Jan 0001 00:00:00 +0000

MYSQL metrics come from mysqld_exporter (raw metrics, mysql_ prefix) and vmalert recording rules (mysql:ins:* / mysql:cls:*). Dashboards and alerts are built on the derived metrics; this page is their dictionary.

Common Labels

Every metric carries job=mysql and the identity labels cls / ins / ip / topology (standalone or innodb_cluster). Instance-level derived metrics keep all identity labels; cluster-level metrics aggregate to cls + topology.

Availability

Metric	Meaning
`mysql:ins:exporter_up`	Scrape success (transport health)
`mysql:ins:up`	MySQL connection probe success (database health)
`mysql:ins:uptime`	Instance uptime in seconds
`mysql:cls:instances`	Declared instance count
`mysql:cls:up`	Online instance count
`mysql:cls:health`	Cluster health: 2 healthy / 1 degraded-writable / 0 critical

For HA clusters, mysql:cls:health combines quorum, single-primary, and full-membership status; for standalones it is 2 × mysql:cls:up.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

How mature is the MYSQL module?

It is a pilot module aiming for a simple, inexpensive, good-enough MySQL cluster. The four core capabilities — deployment and convergence, HA failover, daily backups, monitoring and alerting — have been tested systematically, including fault injection and complete-outage drills. Destructive recovery flows are deliberately manual, with runbooks provided. It does not aim for PGSQL-module completeness: no PITR, no VIP/DNS access layer, no automatic scaling. Validate and rehearse recovery against your own requirements before serious production use.