
Auditing a live production database cluster requires two non-negotiable engineering guarantees: never mutating the observed server state silently and measuring the actual resource ceiling enforced by the runtime environment, whether bare-metal Linux, a cgroup-bounded Kubernetes pod, or a modern Windows Server host.
Released on November 16, 2026 (36 commits across 148 files, 19,565 lines of zero-dependency pure Perl), MySQLTuner v2.9.4 delivers major upgrades in production read-only safety, high-availability lag diagnostics, cgroup v2/v1 container accuracy, and strict air-gapped portability.
| Diagnostic Coverage Metric | v2.9.4 Total | Delta vs v2.9.3 | Category |
|---|---|---|---|
| Total Indicators | 1,125 |
+33 |
Overall coverage |
| Efficiency Checks | 165 |
+4 |
Ratios & log checks |
| Risk Detections | 322 |
+10 |
Security, HA & OS |
| Information Points | 582 |
+10 |
Topology & telemetry |
| Recommendations | 56 |
+9 |
Tuning & remediation |
1. Zero-Mutation Production Safety, InnoDB Math & Connected Auditors
On mission-critical OLTP servers, an audit script must never execute silent configuration writes to accelerate its own catalog queries, nor emit invalid SET GLOBAL statements.
A. Removal of Silent SET GLOBAL Mutation and Safe Auto-Fix Filtering
- Read-only
check_metadata_perf(#1022): Removed the silentSET GLOBAL innodb_stats_on_metadatamutation during schema inspection. When enabled (ON), MySQLTuner now reports the overhead and pushes a strictly advisorySET innodb_stats_on_metadata = OFFrecommendation into@adjvars. - Safe
SET GLOBALfiltering (#1027, #78): Automated remediation statements now strictly exclude read-only parameters, static variables requiring a restart, and dot-notation keys, while properly quoting SQL values. - Strict
--featureallowlist (#78): Passing--feature <name>now validates the argument against permitted diagnostic subroutines and fails explicitly when given an invalid input (Unknown or disallowed feature: $feature).
B. Exact innodb_page_size Math, BIGINT UNSIGNED Fix & BASE TABLE Precision
- Page-size-aware buffer pool math (#1026): InnoDB buffer pool memory calculations now scale directly from
innodb_page_size(4 KiBto64 KiB), removing sizing skew on non-16K instances. BIGINT UNSIGNED AUTO_INCREMENTfalse positive resolved (#1007): Primary keys backed byBIGINT UNSIGNEDno longer trigger spurious auto-increment exhaustion warnings.- Schema & Performance Schema query precision (#1029, #1030, #1034, #1037, #78):
- Scoped SQL modeling column and foreign key checks strictly to
TABLE_TYPE = 'BASE TABLE', escapedLIKE '%\_id'wildcards, deduplicated composite primary key counts, and eliminated a duplicate foreign key mismatch query. - Replaced a bitwise
|operator with logical||inquery_cache_typeevaluation. - Added result caching for Performance Schema and Galera GCache memory queries, preloaded virtual column tables, fixed
object_namein PFS index wait queries along witherror_logseverity ordering, guarded--dumpdircolumn scans, and enforced trailing newlines on CSV dumps.
C. Wiring All 4 Specialized Auditors into the Core Pipeline (#1038)
The four deep diagnostic auditors introduced in the 2.9.x cycle are now fully wired into the execution flow:
1. audit_pfs_stage_profiling (Performance Schema stage execution bottlenecks);
2. audit_innodb_ahi (Adaptive Hash Index efficiency and rw-latch partitioning);
3. audit_tls_ciphers_protocols (TLS protocol versions and weak cipher detection);
4. audit_table_definition_cache (metadata dictionary pressure and eviction rate).
2. High Availability: NULL Replication Lag & Galera %mystat Telemetry
When a replication thread stalls, MySQL and MariaDB often report Seconds_Behind_Source = NULL. Any parser that coerces NULL to 0 hides a broken replica behind a green status check.
A. Explicit IO / SQL Thread Health and Unknown Lag Checks (#78)
MySQLTuner v2.9.4 explicitly differentiates 0 seconds of lag from NULL/unknown lag and audits both replication threads independently:
[!!] Replication lag analysis: IO thread is stopped or unhealthy ($replica_io_running). Check network or source availability.
[!!] Replication lag analysis: SQL thread is stopped or unhealthy ($replica_sql_running). Check replication errors.
[!!] Replication lag analysis: Replication lag is NULL/unknown. Check replica thread status.
[!!] This replication replica has unknown lag ($seconds_behind_replica).
Additionally, SHOW REPLICA HOSTS parsing now accurately handles tab-separated output produced by batch clients.
B. Galera wsrep Context & %mystat Integration (#1033)
Galera Cluster and Percona XtraDB Cluster diagnostics now read status counters directly from %mystat, resolve wsrep cluster context cleanly, and fix index type resolution in metadata checks.
3. Cgroup v2/v1 Container Telemetry, Linux Sysctl Precision & Windows CIM
Running MySQLTuner inside a Docker container or Kubernetes pod while reading host /proc/meminfo leads to dangerous sizing advice: sizing an InnoDB Buffer Pool for 256 GiB of hypervisor RAM inside an 8 GiB pod triggers immediate OOMKill events.
A. Cgroup v2/v1 Memory Probes & Quiet Container Execution (#78)
- Native cgroup v2 & v1 memory/swap limits: MySQLTuner probes
/sys/fs/cgroup/memory.maxandmemory.swap.max(cgroup v2) first, falling back tomemory.limit_in_bytesandmemory.memsw.limit_in_bytes(cgroup v1) both locally and over remote transports. - Hermetic environment overrides: Supports
MYSQLTUNER_PROC_MEMINFOandMYSQLTUNER_CGROUP_DIRoverrides for isolated testing without modifying host files. - Container probe suppression & cloud/journal log detection: Suppresses irrelevant host hardware, network,
lsblk, and sysctl noise inside containers (Skipping host network, process, filesystem, and kernel probes in container mode.), while adding dedicated checks for cloud and systemd journal logs (Log from cloud $myvar{'log_error'} exists,Log journal $myvar{'log_error'} exists).
B. Linux Sysctl, Disk & Process Memory Accuracy (#1024, #1031, #1032, #78)
fs.nr_open&sunrpcTCP slot threshold: Correctsfs.nr_opensysctl calculation and warns when RPC initial TCP slot entries are undersized (Initial TCP slot entries is < 100, please consider having a value greater than 100).- Process accounting &
--noprocessenforcement: Strictly respects--noprocessand excludesmariadbdandgarbdfrom non-database process RAM totals. - System & filesystem guards: Anchors mountpoint regexes, guards against zero-size disks and non-numeric sysctl outputs, closes the exact file handle, adds a
logical_cpu_coresfallback, and returns full command output frominfocmd_tabwhile deduplicating redundantSHOWqueries.
C. Modern Windows Telemetry via PowerShell CIM (#992, #1025, #1028)
With wmic.exe deprecated and removed on modern Windows 11 and Windows Server builds, v2.9.4 transitions CPU and memory discovery to PowerShell Get-CimInstance (Win32_Processor, Win32_ComputerSystem) with automatic wmic fallback, scales FreeVirtualMemory accurately to bytes with zero-swap safety, and guards getpwuid calls on Windows in setup_environment.
4. Zero-CPAN Core JSON::PP, --list-indicators Contract & Hardened MCP / SSH
A. 100% Core JSON::PP Serialization & Air-Gapped --comparefile (#78, #1046)
All JSON output and historical --comparefile diffing (including aligned comparison keys) now rely exclusively on Perl Core JSON::PP, removing non-core CPAN JSON from the compliance whitelist (check_compliance.pl):
* If JSON::PP is absent on a stripped distribution, MySQLTuner fails explicitly (JSON::PP module required for comparison analysis.).
* Combining --agent-json with --outputfile now produces clean JSON without console pollution.
B. Offline --list-indicators Export Contract (#1046)
CI pipelines and AI orchestrators can inspect the complete catalog of 1,125 indicators, %CLI_METADATA options, and --feature subroutines as canonical JSON without connecting to a database:
perl mysqltuner.pl --list-indicators > mysqltuner_catalog_v294.json
C. Hardened SSH Transport, Updater Verification, HTML/CSV Escaping & Fail-Closed MCP
- SSH & credential escaping (#1023, #78): Escapes shell and SQL metacharacters in
select_oneand credential/SSH/container/defaults arguments; enables standalone--ssh-host; passes credentials tosshpassviaSSHPASSenv var (avoiding process-table exposure); preservesdebian.cnfprecedence; and skips local file checks on remote targets. - Staged updater safety (#1035, #78): Preserves
--nocoloron--outputfile, verifies downloaded file size, and validates staged updates viaperl -cbefore replacing the script. - Sanitized outputs & POSIX exit-code hygiene (#78): Escapes HTML
<script>blocks, properly escapes CSV quotes, isolatesmysqldumpandfragmented_tablesexports, and replacesexit(256)— which silently wrapped modulo 256 to exit code0on POSIX! — withexit(1)on fatal database connection failures. - Fail-Closed MCP Server & 9 AI Skills (#78, #1010):
build/mcp_server.pynow fails closed on database query errors, enforcestarget_ram_percentage, performs locked atomic cache writes, and tightens SQL sanitization..agent/skills/grows to 9 specialized skills withisolated-test-guardandwindows-powershell-metrics. - Supply-chain security (#1016): Remediates Dependabot advisories across
fast-uri,brace-expansion, andjs-yaml.
5. 2026 Engine Matrix (MySQL 26.10 & MariaDB 13.0), 238 Test Suites & CI Governance
A. Authoritative is_mariadb Gating for MySQL 26.10 (#75, #78)
With MySQL adopting calendar-style short-term versioning (26.10), naive numeric checks such as version >= 10 risked misclassifying MySQL 26.10 as MariaDB 10.x+. MySQLTuner v2.9.4 enforces authoritative is_mariadb gating across version-dependent branches and synchronizes build/ci_matrix.json with endoflife.date:
| Database Engine | Supported LTS Cycles | Short-Term (STS) |
Legacy Supported |
|---|---|---|---|
| MySQL | 8.4 LTS, 9.7 LTS |
26.10 |
8.0 |
| MariaDB | 10.11 LTS, 11.4 LTS, 11.8 LTS, 12.3 LTS |
13.0 |
— |
B. 238 Automated Test Suites, doc-lint CI Gate & 5-Language Parity
- Expanded from 153 to 238 test files: Verification now spans 189 Perl
.tsuites and 49 Python.pysuites, with hermeticchrootandTemporaryDirectoryisolation (#1010,#78) preventing working-tree mutation during execution, alongside lab harness validation (parallel_test.sh,test_envs.sh). doc-lintCI parity & SHA-256 invariance (#1039, #1044, #1042): Eliminates phantom CLI flags, enforces automated parity across%CLI_METADATA, embedded POD, andUSAGE.md, and verifies release artifact invariants.- GPLv3 alignment & 5-language README sync (#1041, #1045, #1048): Resolves license boilerplate to GPLv3, adds the community Vietnamese translation (
README.vi.md), and automates synchronization acrossEN,FR,IT,RU, andVI.
6. Upgrading to MySQLTuner v2.9.4
Upgrade directly with zero external runtime dependencies:
wget http://mysqltuner.pl/ -O mysqltuner.pl
chmod +x mysqltuner.pl
./mysqltuner.pl
Common v2.9.4 production, container, and AI pipeline commands:
# 1. Export the full 1,125-indicator catalog offline in canonical JSON
perl mysqltuner.pl --list-indicators > indicators_v294.json
# 2. Audit a Docker/Podman container with cgroup v2/v1 memory telemetry
perl mysqltuner.pl --container mysql_prod_01
# 3. Generate an AI-ready JSON remediation plan with SQL rollback statements
perl mysqltuner.pl --agent-json --outputfile=audit_v294.json
# 4. Run via the synchronized official Docker image
docker pull jmrenouard/mysqltuner:latest
- Official GitHub Release & SHA256SUMS: github.com/major/MySQLTuner-perl/releases/tag/v2.9.4
- LightPath DBRE & CIS Audit Services: Need a 10-day deep diagnostic of your MySQL, MariaDB, or PostgreSQL fleet with verified SQL rollback scripts and FinOps optimization? Visit lightpath.fr.