Upgrade MySQL to 8.4 (Docker)
Move a self-hosted NetLock RMM installation from MySQL 8.0 (or 5.7) to the 8.4 LTS release: backup, compose changes, first start and checks.
Upgrade MySQL to 8.4 (Docker)
Self-hosted only: This guide applies to self-hosted deployments. Cloud customers do not run a database server — the hosted platform is run for them.
This guide moves the MySQL container of a self-hosted NetLock RMM installation from MySQL 8.0 (or 5.7) to MySQL 8.4, the current long-term support release. It follows the Docker Compose layout of Install the NetLock RMM server with Docker: the compose file at /home/netlock/docker-compose.yml, the mysql service with the container name mysql-container, and the data directory /home/netlock/mysql/data. Plan for downtime: the server and the Web Console are stopped while the database upgrades its files. On a small installation that is a matter of minutes; on a large database the first start of the new version can take considerably longer (see step 4).
Why and when
Oracle publishes security fixes only for MySQL releases that are still in support:
| Release | Oracle support ended / ends | Status |
|---|---|---|
| MySQL 5.7 | 31 October 2023 | Out of support |
| MySQL 8.0 | 30 April 2026 (last release 8.0.46) | Out of support |
| MySQL 8.4 LTS | 30 April 2032 | Recommended |
The dates follow Oracle's lifetime support policy; a compact overview is kept at endoflife.date/mysql. NetLock RMM is developed and tested against MySQL 8.4, and every current installation path — the guided installer and the compose file in the installation guide — deploys mysql:8.4. Installations created earlier usually still pin mysql:8.0.
The Web Console tells you when the database server is older than 8.4:
- A warning icon next to the update notice in the top bar (on phones, an entry in the account menu). It opens a short dialog with the running version, the date its support ended, the recommended version, the upgrade steps and a link to this guide.
- A warning above the status card on
Settings → Database, with the same link.
Both are visible to accounts that may open Settings → Database (settings_enabled and settings_database_enabled), only on self-hosted installations, and they stay until the database reports version 8.4 or newer. There is no dismiss button.
Short version
On an installation that follows the Docker layout above, the upgrade takes six steps:
- SSH into the NetLock RMM server.
- Navigate to
/home/netlock - Run
sudo docker compose down - Run
sudo nano docker-compose.yml - Locate the mysql image entry, change from
mysql:8.0tomysql:8.4, save and exit. - Run
sudo docker compose up -d
Keep these points in mind:
- Take the backup before step 3 of this list:
mysqldumpneeds a running database. downwaits only 10 seconds by default. With a large buffer pool usesudo docker compose down -t 120so MySQL can shut down cleanly.up -dstarts everything at once. The Web Console and the server restart until MySQL is ready; do not interrupt the first start.
The sections below are the same upgrade in smaller stages, with the check of the MySQL options that 8.4 no longer accepts. On MySQL 5.7, the note under "Before you start" applies.
Before you start
You need:
-
Shell access to the host that runs the containers, with permission to run
docker(the commands below usesudo). -
The compose file. The installation guide places it at
/home/netlock/docker-compose.yml; adjust the paths below if yours differs. -
The running MySQL version.
Settings → Databaseshows it on the status card. From the host, the container's own client reports it as well; the root password comes from the container's environment, so nothing is typed into the shell:sudo docker exec mysql-container sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "SELECT VERSION();"' -
A current backup of the database. Step 1 explains why there is no way back without one.
Note: MySQL 5.7 cannot be upgraded to 8.4 directly — a release series cannot be skipped (upgrade paths). Run this guide twice: first with the image
mysql:8.0, wait until that upgrade has finished and the server is up, then again withmysql:8.4.
Note: Pin the image tag.
mysql:8.4stays on the 8.4 series and receives its patch releases through normal image pulls. A container-update watcher such as Watchtower follows the tag you pinned and never movesmysql:8.0to 8.4 on its own. The tagsmysql:8andmysql:latestalready resolve to 8.4 and would jump versions on the next pull without the preparation below, so replace them withmysql:8.4.
Step 1 — Stop the application and check your backup
Stop the two application containers so nothing writes to the database while you work:
sudo docker compose -f /home/netlock/docker-compose.yml stop netlock-rmm-web-console netlock-rmm-serverMake sure you have a current backup of the database before you change the image. There is no way back in place: once 8.4 has started on the data directory, 8.0 will not open it again, and the only route back is a backup loaded into a fresh 8.0 database (downgrading MySQL). If your regular backup has not run since the last changes, take a logical dump now. The root password and the database name are read from the container's environment (MYSQL_ROOT_PASSWORD and MYSQL_DATABASE in the compose file), so neither ends up in the shell history:
sudo docker exec mysql-container sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --routines --triggers "$MYSQL_DATABASE"' > /home/netlock/mysql-backup-$(date +%F).sqlThen stop the database container. The stop command waits up to two minutes; the default of ten seconds can end a server with a large buffer pool before it has written everything out.
sudo docker compose -f /home/netlock/docker-compose.yml stop -t 120 mysqlNote: Upgrade only a server that was shut down cleanly;
docker compose stopdoes that. A server that crashed and was not restarted since must be started once and stopped again before you continue (upgrade prerequisites).
Step 2 — Check the MySQL options
MySQL 8.4 refuses to start on options it has removed and writes unknown variable to the log. The compose file from the installation guide passes its options in the command: block of the mysql service; a mounted my.cnf, if you added one, needs the same check. Compare what you have against this table:
| Option | What to do for 8.4 |
|---|---|
--skip-log-bin, --innodb_buffer_pool_size, --innodb_flush_log_at_trx_commit, --max_connections | Keep. |
--innodb_log_file_size=256M (older NetLock guides) | Replace with --innodb_redo_log_capacity=512M. The old option is deprecated but still accepted; the new one sets the same total (two files of 256M). |
--default-authentication-plugin=... | Delete. Removed in 8.4; the server does not start with it. See Troubleshooting if accounts were created with mysql_native_password. |
--expire-logs-days, --skip-host-cache, --skip-innodb, --innodb | Delete. Removed in 8.4. |
The list of removed options is in What Is New in MySQL 8.4 since MySQL 8.0; the redo log sizing is described under innodb_redo_log_capacity.
Step 3 — Change the image
In the mysql service of the compose file, change the image tag from mysql:8.0 to mysql:8.4:
mysql:
image: mysql:8.4Leave the rest of the service as it is: the data directory volume, the environment variables and the network settings carry over unchanged.
Step 4 — Start MySQL and watch the log
sudo docker compose -f /home/netlock/docker-compose.yml up -d mysql
sudo docker logs -f mysql-containerDocker pulls mysql:8.4 and starts a new container on the existing data directory, which is how a MySQL container is upgraded (upgrading a MySQL container). On this first start the server upgrades its data dictionary and system tables on its own; no option is needed, this is the default --upgrade=AUTO (what is upgraded). The log shows a line like Server upgrade from '800xx' to '804xx' started, later a matching completed line, and finally ready for connections. Leave the log with Ctrl + C; that does not stop the container.
Note: The upgrade can take a while. On this first start MySQL rewrites its data dictionary and system tables and checks every table of the database. On a small installation that is done in seconds; on a database that has collected events, inventory and patch data for years it can take many minutes, and the time grows with the size of the data directory and the speed of the disk. The container is not stuck while the log stays quiet between
startedandcompleted. Do not stop, restart or recreate it during that time: an interrupted upgrade leaves a data directory that only the backup from step 1 brings back.
Step 5 — Start the rest and verify
sudo docker compose -f /home/netlock/docker-compose.yml up -dOpen Settings → Database. The status card shows Version: 8.4.x, the warning above it is gone, and the warning icon in the top bar disappears as soon as the page has read the new version.
Keep the backup from step 1 until the installation has run on 8.4 for a few days.
Troubleshooting
-
The container stops right after the start and the log says
unknown variable. An option that 8.4 removed is still in thecommand:block or in a mountedmy.cnf. Go back to step 2, fix the option, and run theup -d mysqlcommand again. -
The log says
Plugin 'mysql_native_password' is not loaded, or an application cannot sign in after the upgrade. Themysql_native_passwordplugin is disabled by default since 8.4.0. Therootaccount the image creates usescaching_sha2_passwordand is not affected, and the Web Console's connection parameters keepAllowPublicKeyRetrieval=True, which that method needs. Only accounts created by hand withmysql_native_passwordare affected. Enable the plugin once by adding--mysql-native-password=ONto thecommand:block, start the container, and switch the account:ALTER USER 'name'@'%' IDENTIFIED WITH caching_sha2_password BY '<password>';Then remove the flag again and recreate the container. The plugin change is listed in What Is New in MySQL 8.4 since MySQL 8.0.
-
The log has shown
Server upgrade … startedfor a long time and nothing else. The upgrade is still running; see the note in step 4. Wait for thecompletedline, do not restart the container. -
A 5.7 data directory with
mysql:8.4. The server refuses to start; a release series cannot be skipped. Set the tag tomysql:8.0, let that upgrade finish, then continue with 8.4. -
Going back to 8.0. The upgraded data directory cannot be opened by 8.0 again. Stop the database container, move the directory aside, set the tag back to
mysql:8.0and start the container on an empty directory; the image then creates the database and the accounts from the compose environment again. Wait forready for connectionsin the log, then load the backup from step 1:sudo docker compose -f /home/netlock/docker-compose.yml stop mysql sudo mv /home/netlock/mysql/data /home/netlock/mysql/data-8.4 sudo mkdir /home/netlock/mysql/data # change image: to mysql:8.0 in the compose file, then sudo docker compose -f /home/netlock/docker-compose.yml up -d mysql sudo docker logs -f mysql-container sudo docker exec -i mysql-container sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE"' < /home/netlock/mysql-backup-<date>.sqlThen run the
up -dcommand from step 5. Delete/home/netlock/mysql/data-8.4once the installation runs again.
Related
- Install the NetLock RMM server with Docker — the compose file this guide refers to.
- Upgrade NetLock RMM — upgrading the server and Web Console images.
- A.2 — Updates & maintenance — the database version notice in the Console.
- A.3 — Database management — the
Settings → Databasepage with the status card.