Charmed MySQL

  • By Canonical Data Platform
  • Cloud
Channel Revision Published Runs on
8.0/stable 240 20 Jun 2024
Ubuntu 22.04
8.0/candidate 240 17 Jun 2024
Ubuntu 22.04
8.0/beta 240 17 Jun 2024
Ubuntu 22.04
8.0/edge 255 Today
Ubuntu 22.04
8.0/edge 254 Today
Ubuntu 22.04
juju deploy mysql --channel 8.0/edge
Show information



DB data migration using ‘mysqldump’

:information_source: NOTE: This document describes DB data migration only!
Use separate manual to migrate charm on new juju interfaces, etc.

The list of MariaDB/MySQL legacy VM charms:

The minor difference in commands necessary for each of the legacy charm, but the general logic is common:

  • deploy the modern charm nearby
  • request credentials from legacy charm
  • remove relation to legacy charm (to stop data changes)
  • perform legacy DB dump (using the credentials above)
  • upload the legacy charm dump into the modern charm
  • add relation to modern charm
  • validate results and remove legacy charm

Before the data migration check all limitations of the modern Charmed MySQL charm!
Please check your application compatibility with Charmed MySQL before migrating production data from legacy charm!

Tip: Always test migration in LAB before performing it in Production!

Do you need to migrate?

A database migration is only required if the output of the following command is NOT mysql:

# replace DB_CHARM with your legacy DB application name
DB_CHARM= < mariadb | percona-cluster | mysql-innodb-cluster >
juju show-application ${DB_CHARM} | yq '.[] | .charm'

Tip: No migration necessary if the output above is mysql! Still, this manual can be used to copy data between different installations of the same (modern) charm mysql, however the backup/restore is recommended for migrations between modern charms.


  • Client machine with access to deployed legacy charm
  • Juju version 2.9 (check the Juju tech details for the different Juju versions)
  • Enough storage in the cluster to support backup/restore of the databases.
  • mysql-client on client machine (install by running sudo apt install mysql-client).

WARNING: the most legacy DB charms support old Ubuntu series only, while Juju 3.x does NOT support Ubuntu bionic. The migration to the new charm recommended in Juju 2.9.x!

Obtain existing database credentials

To obtain credentials for existing databases execute the following commands for each database to be migrated. Use those credentials in migration steps.

# replace DB_APP with desired unit name
DB_APP= < mariadb/0 | percona-cluster/leader | mysql-innodb-cluster/1 >

# obtain username and password of existing legacy database from DB relation
# username is usually `root` and password is specified in `mysql` relation by 'root_password'
OLD_DB_RELATION_ID=$(juju show-unit ${DB_APP} | yq '.[] | .relation-info | select(.[].endpoint == "mysql") | .[0] | .relation-id')
OLD_DB_PASS=$(bash -c "juju run --unit ${DB_APP} 'relation-get -r ${OLD_DB_RELATION_ID} - ${DB_APP}' | grep root_password" | awk '{print $2}')
OLD_DB_IP=$(juju show-unit ${DB_APP} | yq '.[] | .address')

Deploy new MySQL databases and obtain credentials

Deploy new MySQL databases and obtain credentials for each new database by executing the following commands, once per database:

# deploy new MySQL database charm
juju deploy mysql --channel 8.0/stable -n 3

# obtain username and password of new MySQL database from MySQL charm
NEW_DB_USER=$(juju run mysql/leader get-password | yq '.username')
NEW_DB_PASS=$(juju run mysql/leader get-password | yq '.password')
NEW_DB_IP=$(juju show-unit mysql/0 | yq '.[] | .address')

DB migration

Use the credentials and information obtained in previous steps to perform the database migration by executing the following commands:

# ensure that there are no new connections are made and that database is not altered
# remove relation between your_application charm and  legacy charm
juju remove-relation <your_application> <mariadb | percona-cluster | mysql-innodb-cluster>

# connect to the legacy database to verify connection
mysql \
  --host=${OLD_DB_IP} \
  --user=${OLD_DB_USER} \
  --password=${OLD_DB_PASS} \
  -e "show databases"

# choose which databases to dump/migrate to the new charm (one by one!)
DB_NAME=< e.g. wordpress >

# create backup of each database file using `mysqldump` utility, username, password, and unit's IP address, obtained earlier
# The dump will be created that can be used to restore database


mysqldump \
  --host=${OLD_DB_IP} \
  --user=${OLD_DB_USER} \
  --password=${OLD_DB_PASS} \
  --column-statistics=0 \
  --databases ${OLD_DB_NAME} \
  > "${OLD_DB_DUMP}"

# connect to new DB using username, password, and unit's IP address and restore database from backup
mysql \
  --host=${NEW_DB_IP} \
  --user=${NEW_DB_USER} \
  --password=${NEW_DB_PASS} \
  < "${OLD_DB_DUMP}"

Relate to modern charm

# relate your application and new MySQL database charm (using database or mysql endpoint)
juju relate <your_application> mysql:database

# if database endpoint (mysql_client interface) is not yes supported, use legacy mysql interface: 
juju relate <your_application> mysql:mysql

Verify DB migration

Note: some variables will vary for legacy and modern charms, namely: ${NEW_DB_PASS} and ${NEW_DB_IP}. These must be adjusted for the correct database, accordingly.

# compare new MySQL database and compare it to the backup created earlier

mysqldump \
  --host=${NEW_DB_IP} \
  --user=${NEW_DB_USER} \
  --password=${NEW_DB_PASS} \
  --column-statistics=0 \
  --databases ${DB_NAME}  \
  > "${NEW_DB_DUMP}"

diff "${OLD_DB_DUMP}" "${NEW_DB_DUMP}"

The difference between two SQL backup files should be limited to server versions, IP addresses, timestamps and other non data related information. Example of difference:

< -- Host:    Database: katib
> -- Host:    Database: katib
< -- Server version	5.5.5-10.3.17-MariaDB-1:10.3.17+maria~bionic
> -- Server version	8.0.34-0ubuntu0.22.04.1
> --
> -- GTID state at the beginning of the backup 
> --
> SET @@GLOBAL.GTID_PURGED=/*!80000 '+'*/ '0d3210b9-587f-11ee-acf3-b26305f815ec:1-4,
> 34442d83-587f-11ee-84f5-b26305f815ec:1-85,
> 34444583-587f-11ee-84f5-b26305f815ec:1';
< CREATE DATABASE /*!32312 IF NOT EXISTS*/ `katib` /*!40100 DEFAULT CHARACTER SET latin1 */;
> CREATE DATABASE /*!32312 IF NOT EXISTS*/ `katib` /*!40100 DEFAULT CHARACTER SET latin1 */ /*!80016 DEFAULT ENCRYPTION='N' */;
<   `id` int(11) NOT NULL,
>   `id` int NOT NULL,
<   `id` int(11) NOT NULL AUTO_INCREMENT,
< -- Dump completed on 2023-09-21 17:05:54
> -- Dump completed on 2023-09-21 17:09:40

Remove old databases

Test your application and if you are happy with a data migration, do not forget to remove legacy charms to keep the house clean:

juju remove-application --destroy-storage < mariadb | percona-cluster | mysql-innodb-cluster >


DB data migration is also possible using mydumper.

:tipping_hand_man: This manual based on Kubeflow DB migration guide.

Help improve this document in the forum (guidelines). Last updated 9 months ago.