Convert non-UTF-8 MySQL database to UTF-8

Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.

Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Summary

Database upgrades may fail due to a wrong character set usage. This article explains how to convert a non-UTF-8 MySQL database into the recommended UTF-8 database.

Always back up your data before making any database modifications. If possible, test any alter, insert, update, or delete SQL commands on a staging server first.

Solution

  1. Let's suppose the database is using latin1 character set and latin1_general_cs collation:

    CREATE DATABASE dbname CHARACTER SET latin1 COLLATE latin1_general_cs;

  2. Make sure that Fisheye / Crucible is not running;

  3. Connect to the database being used by Fisheye / Crucible;

  4. Create a database dump:

    mysqldump --opt -u root -p<secret> dbname > dbname.sql

  5. Open the resulting dbname.sql file and replace all occurrences of latin1_general_cs by utf8_bin and all occurrences of latin1 by utf8, through find / replace, then save changes.

  6. Restore dbname.sql. There are two possibilities here:

    1. Restore into a new database name, if you want to keep the original database untouched. This consists in:

      1. Creating a new database, this time using the correct character set and collation:

        CREATE DATABASE newdbname CHARACTER SET utf8 COLLATE utf8_bin;

      2. Restoring the dump:

        mysql -u root -p<secret> newdbname < dbname.sql

    2. Restore into the existing database name, if you're sure that the manual changes in dbname.sql through find / replace are correct. This consists in:

      1. Deleting the current database dbname:

        DROP DATABASE dbname;

      2. Creating it again, this time using the correct character set and collation:

        CREATE DATABASE dbname CHARACTER SET utf8 COLLATE utf8_bin;

      3. Restoring the dump:

        mysql -u root -p<secret> dbname < dbname.sql

  7. Restart MySQL service

  8. Start Fisheye / Crucible

Updated on September 26, 2025
Platform
Data Center only
Apps
Fisheye Data Center
Crucible Data Center
On this pageSummarySolution

Still need help?

The Atlassian Community is here for you.
Ask the Community