Upgrade MySQL 8.0 to 8.4 in Docker Compose safely

To upgrade MySQL 8.0 to 8.4 in Docker, back up the database, change the image to a pinned mysql:8.4.x tag and replace the removed --default-authentication-plugin flag in the same edit, then run docker compose up -d and let the server upgrade the data directory on its first start. The upgrade is one-way: an 8.4 data directory will not start on 8.0 again, so the backup is your only rollback.

Why upgrade from MySQL 8.0 to 8.4 now?

Because MySQL 8.0 is no longer maintained: Oracle states that MySQL 8.0 reached end of life in April 2026, with 8.0.46 as the last bugfix release. An 8.0 container keeps running, but it gets no more security fixes, and every new CVE in the server stays open on your machine.

MySQL 8.4 is the long-term support (LTS) series that follows 8.0. The official upgrade paths list "8.0 to 8.4.x LTS" as supported by an in-place upgrade, by a logical dump and load, or by replication. For a single Docker container the in-place upgrade is the simple choice: you start the new image on the old data volume, and the server upgrades the data dictionary and system tables itself. Since MySQL 8.0.16 the server does this on its own, so no separate mysql_upgrade run is needed.

Two things on Docker Hub make the move urgent for self-hosters. First, the official mysql image no longer lists an 8.0 tag among its supported tags; 8.4 and 8 now both point to 8.4.13. Second, the floating tags moved on: lts points to 9.7 and latest to the 26.x innovation series. A compose file with an unpinned image: mysql or mysql:lts can jump over 8.4 entirely on the next docker compose pull, into a version where mysql_native_password no longer exists.

⚠️ Warning: Always pin the MySQL image to a series or a patch version (mysql:8.4 or mysql:8.4.13). A major version change should be a decision you make with a backup in hand, never a side effect of pulling images.

What breaks when you change the image to mysql:8.4?

The most common failure is that the container exits immediately because its command: still passes --default-authentication-plugin=mysql_native_password, a server option that 8.4 removed. Many compose files written for MySQL 8.0 contain exactly this line:

services:
  db:
    image: mysql:8.0
    command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    volumes:
      - dbdata:/var/lib/mysql

Started with mysql:8.4, that service stops before it opens the data directory, and the log shows:

$ docker compose logs db
db  | [ERROR] [MY-000067] [Server] unknown variable 'default-authentication-plugin=mysql_native_password'.
db  | [ERROR] [MY-010119] [Server] Aborting

According to What Is New in MySQL 8.4, setting a removed option is an error, not a warning. The good news: the server aborts before it touches your data, so nothing has been upgraded yet. The same applies to a my.cnf mounted into /etc/mysql/conf.d/; check it as well as the command: line.

Removed options and their replacements

As of November 2026. Source: MySQL 8.4 Reference Manual, What Is New.

Changes that start fine but behave differently

Some changes don't stop the server and only show up later:

• Authentication. mysql_native_password is disabled by default in 8.4. An application user created on 8.0 with that plugin gets ERROR 1045 (28000): Access denied, and creating such a user fails with ERROR 1524 (HY000): Plugin 'mysql_native_password' is not loaded. The next section covers both ways out.
• Nonstandard foreign keys. Foreign keys that reference a non-unique or partial key are now rejected in new CREATE TABLE statements while restrict_fk_on_non_standard_key is ON (the default). Existing tables upgrade fine; the server logs a warning for each such key. Schema migrations that create new ones will fail.
• New reserved words. MANUAL, PARALLEL, QUALIFY and TABLESAMPLE became reserved keywords. A column named manual must be quoted with backticks in raw SQL; ORMs that always quote identifiers are not affected.
• InnoDB defaults. Several InnoDB defaults changed, which matters on small VPS instances with slow disks. If you relied on the old values, set them explicitly.

As of November 2026. Source: MySQL 8.4 Reference Manual, What Is New.

How do you back up a MySQL container before upgrading?

Take two backups: a logical dump with mysqldump, which you can load into any MySQL version, and a copy of the stopped data volume, which is the fastest way back to exactly the state you had on 8.0. Then prove that the dump restores.

The reason for two copies is the one-way nature of the upgrade. The MySQL downgrade documentation supports going from 8.4 back to 8.0 only by a logical dump and load (or replication), and only for rollback purposes. An 8.4 data directory cannot simply be opened by an 8.0 server.

Before the backup, run the upgrade checker. It reads the running 8.0 server and lists removed options, authentication problems, reserved words used as identifiers and other incompatibilities. MySQL Shell is included in the mysql:8.4 image, so you don't need to install anything; when no --target-version is given, the checker targets the Shell's own release:

# find the network of your compose project, e.g. myapp_default
docker network ls

# run the 8.4 upgrade checker (MySQL Shell ships in the mysql:8.4 image)
# against the 8.0 server that is still running
docker run --rm -it --network myapp_default mysql:8.4.13 \
  mysqlsh -- util checkForServerUpgrade root@db:3306

Read every Error in the report; warnings about mysql_native_password are expected and are handled below. Then stop the writers and take the backups. Replace myapp_ with your compose project name and the service names with your own:

# 1. stop everything that writes to the database (app, workers, scheduler)
docker compose stop app queue scheduler

# 2. logical dump of the application database
docker compose exec -T db sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" \
  --single-transaction --routines --triggers --events \
  --databases "$MYSQL_DATABASE"' | gzip > db-before-8.4.sql.gz

# 3. physical copy of the stopped data volume
docker compose stop db
docker volume ls | grep dbdata            # e.g. myapp_dbdata
docker run --rm -v myapp_dbdata:/var/lib/mysql:ro -v "$PWD":/backup alpine \
  tar czf /backup/dbdata-8.0.tgz -C /var/lib/mysql .

The dump uses --single-transaction, which gives a consistent snapshot of InnoDB tables without locking them, and includes stored routines, triggers and events. The volume copy is taken only after docker compose stop db: copying the files of a running MySQL server gives you a data directory that may not start. MySQL's own upgrade preparation guide also asks for a clean shutdown before an upgrade, which docker compose stop does as long as the server finishes within the stop timeout (10 seconds by default; raise it with stop_grace_period for large buffer pools).

Test the dump on a throwaway 8.0 container, so you know the file is complete before you need it:

docker run -d --name restore-test -e MYSQL_ROOT_PASSWORD=test mysql:8.0
docker logs -f restore-test               # wait for "ready for connections", then Ctrl+C
gunzip -c db-before-8.4.sql.gz | docker exec -i restore-test mysql -uroot -ptest
docker exec restore-test mysql -uroot -ptest -e \
  "SELECT table_schema, COUNT(*) AS tables FROM information_schema.tables GROUP BY table_schema;"
docker rm -f restore-test

Copy both files off the server, or at least to a different disk. If you already run scheduled backups, our backup and restore guide describes how to keep and test them.

What should you do about mysql_native_password?

Either keep it on for now with --mysql-native-password=ON, or move every account to caching_sha2_password before or right after the upgrade. Both are valid on 8.4; only the second works on MySQL 9, where the plugin is removed.

First find out which accounts use which plugin. Run this on the 8.0 server before the upgrade:

SELECT user, host, plugin
FROM mysql.user
ORDER BY plugin, user;

If every application account already shows caching_sha2_password, which is the default for new accounts since MySQL 8.0, you don't need the native plugin at all: remove the old flag, keep the default authentication_policy of *,,, and you are done. Accounts that show mysql_native_password usually exist because the compose file forced that plugin when the database was first created, often for an old PHP driver.

Option A: keep native authentication

Add --mysql-native-password=ON to the server flags. If new accounts should also use the native plugin (for example because your app's installer creates its own user), replace the removed option with --authentication-policy=mysql_native_password,,. The authentication_policy reference explains the format: up to three comma-separated factors, where the first element sets the plugin for the first factor and the empty elements leave the optional second and third factors open. A softer form, *:mysql_native_password,,, makes native the default while still allowing other plugins.

Option B: move accounts to caching_sha2_password

Start 8.4 with the native plugin on (option A) so the accounts can still log in, then change them one at a time and restart without the flag once none is left:

-- move one account to the 8.4 default plugin (keep or change the password)
ALTER USER 'app_user'@'%' IDENTIFIED WITH caching_sha2_password BY 'the-password';

-- check the result
SELECT user, host, plugin FROM mysql.user WHERE user = 'app_user';

Check that every client can authenticate this way before you switch the plugin off. Current PHP (mysqlnd), Python and Node.js MySQL drivers support caching_sha2_password. The first login of a new session needs either a TLS connection or RSA key exchange; MySQL generates TLS certificates on first start, so connections between containers normally use TLS without any configuration. Backup tools are the usual surprise: if your backup container uses the MariaDB mysqldump, try a real dump with the changed account before you remove the native plugin.

How do you upgrade MySQL 8.0 to 8.4 in Docker Compose, step by step?

Change the image and the server flags in one edit, start only the database, wait for the data dictionary upgrade to finish in the log, then start the rest of the stack.

1. Edit the db service

   Pin mysql:8.4.13 (or mysql:8.4 if you want patch updates on every pull) and replace the old flag. The example keeps native authentication, which is the safe default for an existing database; drop the two auth flags if all your accounts already use caching_sha2_password.

   services:
     db:
       image: mysql:8.4.13
       command: >-
         --mysql-native-password=ON
         --authentication-policy=mysql_native_password,,
         --character-set-server=utf8mb4
         --collation-server=utf8mb4_unicode_ci
       volumes:
         - dbdata:/var/lib/mysql

2. Pull the image and start the database alone

   Starting db on its own keeps the application from connecting while the server upgrades its system tables.

   docker compose pull db
   docker compose up -d db
   docker compose logs -f db

3. Watch the upgrade in the log

   On the first start the server notices the 8.0 data directory, upgrades the data dictionary and the system schemas, and then opens for connections. Expect lines like these (abridged; your version numbers will differ):

   [System] [MY-013381] [Server] Server upgrade from '80046' to '80413' started.
   [System] [MY-013381] [Server] Server upgrade from '80046' to '80413' completed.
   [System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections. Version: '8.4.13'  socket: '/var/run/mysqld/mysqld.sock'  port: 3306  MySQL Community Server - GPL.

   The server upgrades metadata and system tables, not the rows in your tables, so for a typical application database this is a short pause. Don't stop the container while the upgrade is running. If the log shows an error instead, MySQL's upgrade documentation says the server reverts its changes to the data directory, so fix the reported problem and start again.

4. Start the application

   Run docker compose up -d for the whole project. If the app waits for the database with a healthcheck (mysqladmin ping works unchanged on 8.4), it starts by itself once db is healthy.

5. Keep the old compose file and the backups

   Don't delete the .tgz and the dump for at least a few days of normal use. They are the only way back.

ℹ️ Note: docker compose pull never edits your compose file. If an application release ships a new docker-compose.yml with mysql:8.4, you still have to copy that file (or merge the db service) into your install before anything changes.

How do you check that the upgrade worked?

Check four things: the server reports 8.4, the character set and collations are unchanged, the application logs in and sees all its migrations, and your backup command still produces a dump.

# server version and character set
docker compose exec db mysql -uroot -p -e \
  "SELECT VERSION(); SHOW VARIABLES LIKE 'character_set_server'; SHOW VARIABLES LIKE 'collation_server';"

# table collations per schema (compare with the same query before the upgrade)
docker compose exec db mysql -uroot -p -e \
  "SELECT table_schema, table_collation, COUNT(*) FROM information_schema.tables
   WHERE table_schema NOT IN ('mysql','sys','information_schema','performance_schema')
   GROUP BY 1, 2;"

# the application still sees all its migrations (Laravel example)
docker compose exec app php artisan migrate:status

# a dump still works with the client your backups use
docker compose exec -T db sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" \
  --no-data --databases "$MYSQL_DATABASE"' > /dev/null && echo "dump OK"

Compare the collation query with its output from before the upgrade. An in-place upgrade keeps existing tables as they are; a difference usually means a table was recreated by a migration under different server defaults. Keep the --character-set-server and --collation-server flags you used on 8.0, so new tables match the old ones.

Then use the application: log in, save something, run a background job and trigger one scheduled backup. Look at the MySQL log once more for warnings about nonstandard foreign keys or deprecated options, and fix them while you still remember what you changed.

Can you roll back from 8.4 to 8.0?

Only by restoring a backup. MySQL does not support an in-place downgrade from 8.4 to 8.0; the downgrade table allows only a logical dump and load or replication, and only for rollback when no new 8.4 functionality has been used on the data.

In practice there are two ways back. If the upgrade failed or the application misbehaves within minutes, restore the stopped-volume copy: you get exactly the 8.0 state, but you lose everything written after the backup. If 8.4 has been running for a while and you have new data you want to keep, take a fresh mysqldump on 8.4 and load it into a new, empty 8.0 container, which is the supported path.

docker compose stop
docker compose rm -f db
docker volume rm myapp_dbdata             # deletes the upgraded 8.4 data

# put the old docker-compose.yml back (image: mysql:8.0 and the old command:)
docker compose create db                  # recreates the empty volume
docker run --rm -v myapp_dbdata:/var/lib/mysql -v "$PWD":/backup alpine \
  tar xzf /backup/dbdata-8.0.tgz -C /var/lib/mysql
docker compose up -d

⚠️ Warning: docker volume rm deletes the data for good. Run it only after you have checked that dbdata-8.0.tgz exists, is not empty and lists files when you run tar tzf dbdata-8.0.tgz | head.

Keep in mind that rolling back puts you on an unsupported version again. Treat it as a way to buy time while you fix what blocked the upgrade, not as a destination.

Upgrading the database of a NetSendo install

NetSendo moved its docker-compose.yml to MySQL 8.4 LTS in version 2.2.0 (6 November 2026). The db service now uses image: mysql:8.4 with --mysql-native-password=ON --authentication-policy=mysql_native_password,,, so the database user that an 8.0 install created keeps logging in, and the MariaDB mysqldump in the app image, which NetSendo's backups use, can still authenticate.

An existing install does not change by itself. Pulling a new app image leaves your compose file as it is, so the database stays on 8.0 and keeps working with the new image. To upgrade, take a database backup, replace docker-compose.yml with the one from the release (image and command: together), and run docker compose up -d; MySQL upgrades the data directory on its first start. The release notes describe the tested path: migrations on 8.0, the same volume started on 8.4, the app logging in and mysqldump working. The general installation steps are in the quickstart, and the database settings in .env are explained in the configuration docs.

If you are still choosing a platform to host yourself, the comparison of self-hosted email marketing software covers the database each tool needs and what running it involves.

Frequently asked questions

Sources

• MySQL 8.4 Reference Manual: What Is New in MySQL 8.4
• MySQL 8.4 Reference Manual: Upgrade Paths
• MySQL 8.4 Reference Manual: Downgrading MySQL
• MySQL 8.4 Reference Manual: Native Pluggable Authentication
• MySQL 8.4 Reference Manual: authentication_policy
• Oracle Cloud: MySQL Server Versions (MySQL 8.0 end of life)
• Docker Hub: official mysql image and supported tags
• NetSendo v2.2.0 release notes