# CDBTune: A Hands-On Guide to Tuning MySQL 5.6 with Reinforcement Learning

> CDBTune is a research-oriented Python project that trains a DDPG agent to tune MySQL knobs. This review covers its two-machine setup, the exact commands it requires, and the limitations that make it unsuitable for production.

**HustAIsGroup/CDBTune** — CDBTune

- Repository: https://github.com/HustAIsGroup/CDBTune
- Stars: 100 · Forks: 40
- Language: Python
- License: not declared
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/hustaisgroup-cdbtune

## What CDBTune Actually Does

CDBTune is a training harness for a deep reinforcement learning model that tunes MySQL configuration knobs. The repository, from HustAIsGroup, contains code for a DDPG agent (the file train.py and the tuner module) and a set of scripts that use sysbench to generate load and collect metrics. The README describes a workflow where one machine runs the training and the load generation, while a second machine runs the MySQL server being tuned. The user must manually set default values for each knob in knobs.py and hyperparameters in tuner_configs.py. The project is aimed at someone who wants to experiment with reinforcement learning for database tuning, not at an operator who wants a finished tool. The documentation is a step-by-step setup guide, not a description of the algorithm's internals, so you have to infer the data flow from the file names and commands.

## The Two-Machine Architecture and Data Flow

The README specifies two hosts: CDBTune1 (192.168.110.10) runs sysbench and the training script, and CDBTune2 (192.168.110.11) runs MySQL 5.6. The training machine contacts the database machine via the MySQL port 3306. The flow appears to be: the training script reads knob values, applies them to MySQL by editing my.cnf and restarting the service (implied by the config file replacement step), then runs sysbench workloads against the sbtest database, collects performance metrics, and feeds them to the DDPG model. The environment module contains configs.py where you add the MySQL instance details, and mysql.py which has TEMP_FILES and PROJECT_DIR variables you must edit to match your username. The server directory on CDBTune2 runs start_server.sh, which presumably listens on port 20000, as the README asks you to check that port after starting it. The training machine runs train.py, which likely communicates with that server to issue commands. The exact protocol is not documented in the README, so you have to read the source to understand it.

## Getting It Running: The Exact Steps

The setup is long and rigid. First, you must place the project in /home/cheng/AutoTuner on both machines, keeping the folder name exactly AutoTuner. On CDBTune1, install sysbench 1.0 and on CDBTune2 install MySQL 5.6, not 5.7 or 8.0. The README links to external blog posts for these installations, which is a sign that the project expects a very specific environment. Create a database named sbtest on the MySQL server, grant remote access to root, and enable the InnoDB metric adaptive_hash_searches_btree with the command set global innodb_monitor_enable = "adaptive_hash_searches_btree". Then run the prepare.sh script from the scripts directory with arguments read, the server IP, port, and password: sh prepare.sh read 192.168.110.11 3306 123456. This creates 8 tables with 1,000,000 rows each. Install requirements.txt with pip, not pip3, on both machines. On CDBTune2, install pexpect and start the server with sh ./start_server.sh in the server directory. On CDBTune1, create a start_train.sh script that runs nohup python train.py >> train.log &. Edit configs.py to add your MySQL instance, edit mysql.py to change the username to cheng, edit knobs.py to set default values for each knob, and replace /etc/mysql/my.cnf with the provided template, substituting DEFAULT_VALUE for each knob. Finally, run train.py and then evaluate.py with a params argument like train_ddpg_1571382343_4600. The README provides a troubleshooting section for common errors, such as the sh versus bash issue and MySQL-python installation failures.

## The Python 2.7 and MySQL 5.6 Straightjacket

The project is tied to Python 2.7 and MySQL 5.6 in a way that will cause pain for anyone using a modern system. The README explicitly says to use pip, not pip3, and to install scikit-learn 0.19, which is an old version that supports Python 2.7. The commands use python2 for evaluate.py. The MySQL version is stressed with three exclamation marks: "注意，是5.6！！！" (note, it is 5.6!!!). The my.cnf template includes options like binlog_checksum and skip_name_resolve that exist in 5.6, but the hard requirement likely comes from the InnoDB metric names and the sysbench script paths. The README also requires editing the script path to /usr/share/sysbench/ in two scripts, which is a path specific to Ubuntu's sysbench 1.0 package. If you are on a newer Ubuntu or a different distribution, that path will not exist. The project has no setup script or Docker container, so every user must manually replicate this exact environment. That is a serious usability barrier.

## What the README Does Not Tell You

The README gives no information about the algorithm's performance, expected training time, or the quality of the tuned configurations. It does not mention any evaluation results or comparisons to default MySQL settings. The only way to know if the model works is to run the training yourself and inspect the output of evaluate.py. The README also does not explain the role of the pexpect package on the server machine, nor the protocol used on port 20000. You have to read the source code to understand how the server and trainer communicate. The hyperparameters in tuner_configs.py are left for the user to set, with no guidance on reasonable values. The default knob values in knobs.py are likewise left blank, which means the first run will fail unless you know what values to put in. This is a research prototype, not a polished tool.

## A Real Alternative: OtterTune

A well-known alternative to CDBTune is OtterTune, an open-source project from Carnegie Mellon University that also uses machine learning to tune database knobs. The key difference is that OtterTune is designed to work with multiple database systems, including PostgreSQL and MySQL, and it uses a more mature architecture with a web interface and a central tuning service. OtterTune also supports a wider range of database versions and does not require a fixed two-machine setup with hard-coded IPs. While OtterTune is also research-oriented, it provides more documentation and a more structured data collection pipeline. CDBTune, by contrast, is a single-purpose script set that requires you to manually edit configuration files and run sysbench from a specific path. If you want a tool that you can adapt to your own database environment with less effort, OtterTune is a more practical starting point. However, OtterTune also has its own setup complexity, so neither is a turnkey solution.

## Maintenance and License Implications

The repository has no license listed, which is a red flag for any commercial use. Without a license, you do not have explicit permission to use, modify, or distribute the code. The README does not mention any maintenance or upgrade path. The last push date is unknown, and there are no recent releases. The project appears to be a one-off research artifact from a university lab. The dependencies are pinned to old versions (scikit-learn 0.19, Python 2.7), and those packages are no longer maintained, so you will face security and compatibility issues if you try to run it today. The setup instructions reference external blog posts that may disappear. If you adopt this project, you are on your own for any bug fixes or updates. For a production environment, that is unacceptable. For a research project, it might be fine if you only need to replicate a specific experiment.

## Conclusion

Adopt CDBTune if you are a researcher or graduate student working on database auto-tuning and you have the patience to run a two-machine lab on Ubuntu 16.04 with Python 2.7 and MySQL 5.6. Do not use it on a live database or on any MySQL version newer than 5.6, because the README hard-codes version-specific metrics and paths. Before you start, verify that you can reproduce the exact environment: two hosts with those IPs, a user named cheng, root MySQL password 123456, and the sbtest database. Also confirm that you are willing to edit knobs.py and tuner_configs.py by hand, because the project provides no defaults and no automated discovery. If you need a tool that works with modern MySQL or any cloud database, look elsewhere.

## FAQ

### What does database tuning mean in the CDBTune project?

Tuning means choosing values for MySQL and InnoDB parameters. Here you set each knob's default in environment/knobs.py, substitute those defaults into /etc/mysql/my.cnf, set hyperparameters in tuner/tuner_configs.py, then train tuner/train.py against a sysbench load and score it with tuner/evaluate.py.

### What are the two machines CDBTune needs?

CDBTune1 at 192.168.110.10 runs sysbench1.0 and does network training and active load testing, and CDBTune2 at 192.168.110.11 runs mysql5.6 as the database server. Both are Ubuntu 16.04 with Python 2.7.

### Which InnoDB counter must be enabled for CDBTune?

The adaptive_hash_searches_btree counter. Enable it with set global innodb_monitor_enable = "adaptive_hash_searches_btree"; after listing the currently enabled ones with select name from innodb_metrics where status="enabled" order by name;

### How do I load the test data for CDBTune?

Set script_path in prepare.sh to /usr/share/sysbench/ with the trailing slash, then run sh prepare.sh read 192.168.110.11 3306 123456 from the scripts directory. That creates eight tables of 1,000,000 rows each in the sbtest database.

### What does the CDBTune error [: read: unexpected operator mean?

It means the script was run with sh, which on Ubuntu is dash, while the script expects bash. Run it with bash instead of sh, or change what sh points to permanently.

## Sources

- [Official README](https://github.com/HustAIsGroup/CDBTune#readme)
- [Project repository](https://github.com/HustAIsGroup/CDBTune)
- [README](https://github.com/HustAIsGroup/CDBTune/blob/master/README.md)
- [Releases](https://github.com/HustAIsGroup/CDBTune/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hustaisgroup-cdbtune