MySQLTuner-perl: a Perl audit script for MySQL, MariaDB and Percona servers
MySQLTuner is a script written in Perl that will assist you with your MySQL configuration and make recommendations for increased performance and stability.
At a glance
- What is it?
- MySQLTuner reads your server's configuration and status variables and prints tuning suggestions. It is a diagnostic starting point, not an automated tuner, and the README is explicit about which environments it has been tested against.
- Who is it for?
- MySQLTuner suits engineers who inherit a MySQL, MariaDB or Percona server and need a fast read on configuration and status variables before changing anything. It is the wrong tool if you expect it to apply fixes: it only prints suggestions, and the README describes MySQL Replication as partial support with no test environment.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 8 days ago.
- What is it written in?
- Mainly Perl, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 30, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What MySQLTuner-perl actually does for a MySQL server
MySQLTuner is a single Perl script that connects to a running database server, reads its current configuration variables and status counters, and prints a short report with suggestions. The README describes it as a way to "review a MySQL installation quickly and make adjustments to increase performance and stability." That phrasing matters. The script does not change anything on the server. It reports, and the operator decides.
The audience is narrow but common: the person who has just taken over a database they did not configure, or who wants a second opinion before raising a buffer size. It is aimed at MySQL, MariaDB and Percona Server, and the README lists Galera Cluster, TokuDB, the Performance Schema, Linux OS metrics, InnoDB, MyISAM and Aria among the configurations it handles. The current release line advertises around 900 indicators, KPIs and recommendations, including a Weighted Health Score, capacity planning output and an SSL/TLS audit.
That breadth is also the first thing to be sceptical about. A script that emits hundreds of suggestions across three forks of MySQL will produce advice that is generic in places, and advice that is wrong for an unusual workload. The report is a checklist to read, not a verdict to obey.
How the script collects data and builds its recommendations
The mechanism is straightforward. mysqltuner.pl connects to the server as a MySQL client, queries the variables and status counters the server exposes, and compares them against thresholds and rules embedded in the script. The README points to INTERNALS.md for the indicator descriptions, which is where the actual thresholds live. Nothing is sampled over time by default, so the numbers reflect the state of the server at the moment of the run, not a trend.
The newer features follow the same pattern. Cloud autodiscovery works by inspecting @@version_comment and provider-specific variables to work out whether the server is AWS RDS or Aurora, GCP Cloud SQL, Azure Flexible or Managed, or DigitalOcean. Infrastructure-aware tuning looks at whether storage is SSD or NVMe versus HDD, and whether the CPU is ARM64 or x86_64, then adjusts recommendations such as innodb settings accordingly. The Weighted Health Score combines performance, security and resilience into a 0 to 100 figure, weighted 40, 30 and 30 points respectively.
Two consequences follow. First, a single snapshot taken during a quiet period will understate memory pressure and connection counts, so the score can look better than the server deserves. Second, because the rules are static, a recommendation to raise a buffer is based on the server's own reported memory and the script's assumptions about what else is running on the host, not on a measurement of actual contention.
Installing MySQLTuner and running a first audit
The project ships as a Perl script, so the practical requirement is a Perl interpreter and a MySQL client library. The repository's Makefile exposes an installdep_debian target described as installing dependencies on Debian, which is the closest thing to a packaged install path. Otherwise the README points at the GitHub releases page for tags and the Docker Hub repository jmrenouard/mysqltuner for images.
The most direct way to start is the Docker image, because the repository's Dockerfile already fixes the arguments the maintainers use. Its ENTRYPOINT is the runnable command line:
ENTRYPOINT [ "perl", "/mysqltuner.pl", "--passwordfile", "/basic_passwords.txt",\
"--nosysstat", "--defaults-file", "/defaults.cnf", "--cvefile", "/vulnerabilities.txt", \
"--dumpdir", "/results", "--outputfile", \
"/results/mysqltuner.txt", \
"--reportfile", "/results/mysqltuner.html" ]Read that entrypoint as a list of the flags the project relies on. It supplies credentials through --passwordfile, skips system statistics with --nosysstat, points --defaults-file at an empty /defaults.cnf, feeds a CVE list with --cvefile, and writes into --dumpdir /results. The image is built from an Ubuntu base and installs perl, mysql-client, libjson-perl and libtext-template-perl, so nothing beyond Docker is needed on the host.
Interactive HTML reports are a v2.9.0 and later feature, and the README links live examples for MariaDB 11.4, MySQL 8.4 and Percona 8.0. After the run, read the report top to bottom rather than jumping to the recommendations. The variables section tells you what the server currently believes about itself, and several suggestions only make sense in light of those values.
Where MySQLTuner-perl gives you a wrong or partial answer
The compatibility table in the README is the honest part of the project. MySQL, Percona Server, MariaDB, Galera replication and Percona XtraDB Cluster are listed as full support. MySQL Replication is listed as partial support with no test environment, which means replication-specific findings are the least verified part of the output.
Windows support is described as partial. The README says Windows is supported at this time and that the script has been run successfully across WSL2, and it links the Microsoft WSL documentation. That is a different claim from native Windows support, and anyone running the script directly on Windows should treat the output as unverified.
The README also carries a heading for unsupported environments with the note that help is wanted. Anything in that category is a place where the script may run and still produce misleading advice.
The deeper limitation is the one that applies everywhere. MySQLTuner reads configuration and counters; it does not read your query patterns, your schema, or your application's access distribution. A recommendation to enlarge the InnoDB buffer pool is derived from the server's reported memory and the script's rules, not from a measurement of buffer pool hit rate under your real traffic. If your workload is bursty, or if the server shares a host with other processes, the snapshot the script takes can point you in the wrong direction. Treat every suggestion as a hypothesis to test, and where the script recommends a change, confirm the current value in the report before touching the configuration file.
MySQLTuner-perl versus Percona Toolkit and MySQL Shell
The nearest alternative in the same problem space is Percona Toolkit, a collection of command line tools rather than one script. pt-variable-advisor reads server variables and flags settings it considers risky, which overlaps with part of what MySQLTuner does. The difference is scope and shape: Percona Toolkit is a set of focused utilities you compose, while MySQLTuner is one script that produces one consolidated report with a health score and capacity projections. If you want a single pass over an unfamiliar server, MySQLTuner gets you there faster. If you want to script a specific check into a pipeline, a single-purpose tool is easier to reason about.
MySQL Shell, the newer client from Oracle, takes a different route again: it is an interactive and scriptable shell with JavaScript and Python modes, and its diagnostic utilities are oriented around the server's own instrumentation rather than a fixed rule set. For MySQL 8.x estates, that integration is tighter. MySQLTuner's advantage is that the same script covers MySQL, MariaDB and Percona, and that it runs as plain Perl with no server-side component.
The honest comparison is that MySQLTuner trades depth for breadth. It will tell you something useful about almost any MySQL-family server in one command. It will not tell you as much about any single one of them as a tool built specifically for that fork.
Maintenance, licence and what an upgrade costs
The repository is not archived, and the last push was on 2026-09-21. Releases have been frequent: v2.9.0 on 2026-07-05, v2.9.1 on 2026-07-29 and v2.9.2 on 2026-08-19. The Changelog and CURRENT_VERSION.txt in the repository root are the places to confirm what a given release changed.
Upgrades are cheap in the sense that matters most: the script is a single file, mysqltuner.pl, so deploying a new version means replacing that file. The cost is in the output. Because the recommendation rules change between releases, a report generated by v2.9.2 is not directly comparable to one generated by an earlier version, and a suggestion that disappeared may have been removed as wrong rather than fixed. If you archive reports, record the script version alongside them.
The licence is GPL-3.0, per the repository and the badge in the README. That is a copyleft licence. Running the script against your own database is not distribution, but if you embed it in a product you ship, or modify and redistribute it, the GPL-3.0 obligations apply. The README also mentions paid support channels from LightPath and Releem, which is separate from the licence question. None of this is legal advice; check with your own counsel if you plan to redistribute.
Editorial conclusion
MySQLTuner suits engineers who inherit a MySQL, MariaDB or Percona server and need a fast read on configuration and status variables before changing anything. It is the wrong tool if you expect it to apply fixes: it only prints suggestions, and the README describes MySQL Replication as partial support with no test environment. Before trusting a run, confirm the script's version matches the release you intended, check that the account you use has the privileges the run needs, and compare the output against the supported-version files the repository keeps for MySQL and MariaDB.
Frequently asked questions
Is MariaDB replacing MySQL?
The README does not take a position on that. It lists MySQL, Percona Server and MariaDB as separate fully supported targets, with version support documented in mysql_support.md and mariadb_support.md.
Is MariaDB slower than MySQL?
The README makes no performance comparison between the two. It supports both as full-support targets and documents supported versions for each in separate files.
Can MySQL be used on Linux?
The README lists Linux OS metrics among the configurations MySQLTuner handles, and the project's Dockerfile is built from an Ubuntu base image. The compatibility section treats Linux as a supported environment for the server the script audits.
How can I benchmark MySQL performance?
MySQLTuner does not benchmark. The README describes it as reading current configuration variables and status data and presenting them with suggestions, and its predictive capacity planning works from memory headroom and disk growth rather than a synthetic load.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/major-mysqltuner-perl)