Confluence 7.15.2 MySQL 5.7 to MySQL 8 Migration

In an enterprise level, managing upgrades, database migrations and configuration of application certificates could be overwhelming. Having migrated the DB, I decided to write the steps here would help you, either. This paper will cover steps to migrate Confluence database MySQL 5.7 to MySQL 8 gracefully.

Before Migration

There are few things you must do before the migration;

MySQL Server Configurations

• Configure /etc/my.cnf file so that it has the following configurations,

[mysqld]
.
.
character-set-server=utf8mb4
collation-server=utf8mb_bin
default-storage-engine=INNODB
max_allowed_packet=256M
innodb_log_file_size=2GB
transaction-isolation=READ-COMMITED
.
.

• Remove the following configuration if exists,

sql_mode=NO_AUTO_VALUE_ON_ZERO

Restart the mysql.service for changes to take effect.

• Create DB and user with the following commands,

CREATE DATABASE <database-name> CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
GRANT ALL PRIVILEGES ON <database-name>.* TO '<confluenceuser>'@'<confluence_server_ip>'

• Confirm that your <confluenceuser> has DROP privileges especially,
• Be sure you can establish a connection to your MySQL Server 8 using telnet from the Confluence server,

curl -v telnet://<mysql_server_ip>:3306
# telnet <mysql_server_ip> 3306 # for Windows powershell

Server Side Configurations

Before moving on to the migration step let’s backup some important data about the existing application. We will be using those files later,

• Copy your <installation-dir>/conf/server.xml . This file contains information about the keystore and the password for TLS configurations. Please take look at the paper written about the TLS Configurations for Confluence on Windows.
• Take look at the <home-dir>/confluence.cfg.xml for any changes about your directory.
• Take a note of your service that is running for Confluence instance. This is a precautionary step for not to tackle with old Confluence instance.
• Transfer your MySQL Connector to the server. MySQL Connector should look like mysql-connector-x.x.x.jar . This provides connection with your remote MySQL Server.
• List of active user installed apps. You must install the same versions of each app as before the migration.

Migration Steps

1. Take an XML backup from the UI. Uncheck “Save Attachments” and “Save also backups folder” options,
2. Stop the Confluence,
3. Copy <home-directory>/attachments ,
4. Follow the Setup Your MySQL Server Configurations steps above,
5. Setup New DB and take note of the following credentials,
   - Hostname: <mysql_server_address>`,
   - Port: 3306 (default),
   - DB Name: <database-name> you provided above,
   - DB Password: <password> you created on the DB creation step above,
6. Install Confluence in a new location with run the installer as Administrator,
   - Choose Custom Install,
   - new Destination Directory — Installation Directory -,
   - new Home Directory
   The last two must not be the same as the old directories
7. Add the MySQL connector you transfered to the server under <installation-directory>/confluence/WEB-INF/lib ,
8. Installer will start the Confluence and run the Setup Wizard from UI on localhost:8090. When running the setup wizard,
   - Enter your licence — if necessary -
   - Choose Production Installation,
   - Choose My Own Database and enter the values you noted in the step 6,
9. On the Load Content step, choose Restore From Backup,
   - After clicking the button, put your XML backup from the first step under <home-directory>/restore ,
   - Uncheck the Build Index box and click the import button. You will now see the XML file on the screen. Click the file and uncheck again the Build Index box, just load the old content. You can reindex from the UI if necessary after installation is complete.
10. Copy the content of the attachments under <home-directory>/attachments ,
11. Configure the user added applications from the UI.
12. Configure the TLS via <installation-dir>/conf/server.xmlfile on the new installed directory.

We are done !

Thanks for your time,
Kasım