MySQL or MariaDB Upgrade — Simple & Complete Guide

This interface upgrades your server’s database engine (MySQL or MariaDB) to a newer supported version. Use it during a maintenance window—databases will be temporarily unavailable while the upgrade runs.

Before You Start

• Backups: Create full database dumps and a copy of your configuration file (for example, /etc/my.cnf).
• Disk space: Ensure free space for packages, temporary files, and rebuilds.
• Compatibility: Check application code, ORMs, and CMS plugins for version support; review removed/changed options.
• Replication: If using replication, confirm the correct upgrade order and compatibility on all nodes.
• Maintenance window: Schedule off-peak time; notify users of brief outage.

# lock and dump all databases (adjust options as needed)
mysqldump --all-databases --single-transaction --routines --events --triggers > /root/db-backup-$(date +%F).sql

# copy current config
cp -a /etc/my.cnf /root/my.cnf.backup.$(date +%F)

Supported Paths

• Upgrade within MySQL (for example, 5.7 → 8.0) or within MariaDB (for example, 10.x → newer 10.x).
• Switching from MySQL to MariaDB is supported in many environments.
• Switching back from MariaDB to MySQL is typically not supported—treat this as one-way unless your platform explicitly supports reversal.

How to Run the Upgrade

1. Open the database upgrade interface.
2. Select the target version (MySQL or MariaDB) from the list of supported options.
3. Review the warnings and confirm you have backups.
4. Click Continue/Start Upgrade.
5. Monitor progress. The system will stop the service, install packages, run post-upgrade tasks, and start the service.

What the Tool Does

• Installs the target server packages and dependencies.
• Migrates system tables to the new format and updates metadata.
• Attempts to keep your existing config, skipping unsupported/deprecated options where needed.
• Restarts the database service and reports status.

Post-Upgrade Checks

• Verify the service is running and version is correct.
• Review logs for warnings or failures.
• Test your applications (read/write, migrations, background jobs).
• Remove or update any deprecated options in my.cnf.

# check service
systemctl status mysqld  # or: systemctl status mariadb

# confirm version (replace with your client path if needed)
mysql -V

# connect and ping
mysql -e 'SELECT VERSION() AS version, @@version_comment AS build, NOW() AS time;'

Common Issues & Tips

• Unsupported options: Newer versions may drop settings (for example, old query_cache options). Remove or replace them.
• Authentication changes: Some versions change default auth plugins—update application connectors if login fails.
• SQL mode differences: Strict modes may surface old data issues—fix data and adjust modes as needed.
• Storage engines: Ensure required engines (for example, InnoDB) are enabled; repair/convert tables if necessary.
• Replication: Re-establish replication using the documented version-compatible procedure.

Rollback Strategy

Major downgrades are not supported. If you must revert, restore your full database backup and previous packages/configuration from before the upgrade.

Summary

• Back up, schedule downtime, and verify disk space.
• Select a supported target version and start the upgrade.
• Let the tool install packages, migrate system tables, and restart the service.
• Run post-upgrade checks, test apps, and clean up deprecated configs.
• Remember: no in-place major downgrades—use backups to roll back.