MySQLTuner v2.9.4: 1,125 Indicators, Cgroup v2 Container Telemetry, Zero-Mutation Production Safety, and Core JSON::PP Contract

MySQLTuner v2.9.4 Architecture - Zero-Mutation Engine, Cgroup v2 Containers and Core JSON::PP

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 silent SET GLOBAL innodb_stats_on_metadata mutation during schema inspection. When enabled (ON), MySQLTuner now reports the overhead and pushes a strictly advisory SET innodb_stats_on_metadata = OFF recommendation into @adjvars.
  • Safe SET GLOBAL filtering (#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 --feature allowlist (#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 KiB to 64 KiB), removing sizing skew on non-16K instances.
  • BIGINT UNSIGNED AUTO_INCREMENT false positive resolved (#1007): Primary keys backed by BIGINT UNSIGNED no 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', escaped LIKE '%\_id' wildcards, deduplicated composite primary key counts, and eliminated a duplicate foreign key mismatch query.
  • Replaced a bitwise | operator with logical || in query_cache_type evaluation.
  • Added result caching for Performance Schema and Galera GCache memory queries, preloaded virtual column tables, fixed object_name in PFS index wait queries along with error_log severity ordering, guarded --dumpdir column 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.max and memory.swap.max (cgroup v2) first, falling back to memory.limit_in_bytes and memory.memsw.limit_in_bytes (cgroup v1) both locally and over remote transports.
  • Hermetic environment overrides: Supports MYSQLTUNER_PROC_MEMINFO and MYSQLTUNER_CGROUP_DIR overrides 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 & sunrpc TCP slot threshold: Corrects fs.nr_open sysctl 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 & --noprocess enforcement: Strictly respects --noprocess and excludes mariadbd and garbd from 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_cores fallback, and returns full command output from infocmd_tab while deduplicating redundant SHOW queries.

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_one and credential/SSH/container/defaults arguments; enables standalone --ssh-host; passes credentials to sshpass via SSHPASS env var (avoiding process-table exposure); preserves debian.cnf precedence; and skips local file checks on remote targets.
  • Staged updater safety (#1035, #78): Preserves --nocolor on --outputfile, verifies downloaded file size, and validates staged updates via perl -c before replacing the script.
  • Sanitized outputs & POSIX exit-code hygiene (#78): Escapes HTML <script> blocks, properly escapes CSV quotes, isolates mysqldump and fragmented_tables exports, and replaces exit(256) — which silently wrapped modulo 256 to exit code 0 on POSIX! — with exit(1) on fatal database connection failures.
  • Fail-Closed MCP Server & 9 AI Skills (#78, #1010): build/mcp_server.py now fails closed on database query errors, enforces target_ram_percentage, performs locked atomic cache writes, and tightens SQL sanitization. .agent/skills/ grows to 9 specialized skills with isolated-test-guard and windows-powershell-metrics.
  • Supply-chain security (#1016): Remediates Dependabot advisories across fast-uri, brace-expansion, and js-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 .t suites and 49 Python .py suites, with hermetic chroot and TemporaryDirectory isolation (#1010, #78) preventing working-tree mutation during execution, alongside lab harness validation (parallel_test.sh, test_envs.sh).
  • doc-lint CI parity & SHA-256 invariance (#1039, #1044, #1042): Eliminates phantom CLI flags, enforces automated parity across %CLI_METADATA, embedded POD, and USAGE.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 across EN, FR, IT, RU, and VI.

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

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.