Documentation for Confluence 5.7.
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

If you've gone through Migrating to Another Database and cannot migrate because of a failed xml backup, this page might help.


MySQL Migration Toolkit is released by the makers of MySQL and as such, problems with the software should be directed to them. Atlassian Support does not offer support for the Migration Toolkit, nor do we provide support for this migration path. These instructions are offered for strictly informational purposes, and your mileage may vary.

Backup Reminder

Please backup your database and your home folder before attempting this.

(warning) The information on this page does not apply to Confluence Cloud.

Resources needed

  • Empty MySQL DB with appropriate credentials to allow creation, deletion, and insertion of tables and rows.
  • A Windows machine that can both communicate to the Confluence server and the destination DB.
  • MySQL Migration Toolkit
  • HSQL Database Engine

Preparation for migrating to MySQL from HSQLDB

  1. Shutdown Confluence
  2. Make a copy of the confluence home folder for backup purposes
  3. Install the Migration Toolkit
  4. Unzip the hsqldb package.
  5. Copy the hsqldb.jar from hsqldb/lib into C:\Program Files\MySQL\MySQL Tools for 5.0\java\lib
  6. Start the MySQL Migration Toolkit

Running the Migration Toolkit

You should be presented with the following screen.

Choose Direct Migration

Source Database

Database System:

Generic JDBC

Connection String:







No password. Leave this field blank

Destination Database

Please make sure that the computer that is running MySQL Toolkit is able to access the MySQL server and that the user listed has the ability to create, drop, insert, and update tables.

If your MySQL user has a $ character in the password (such as 'pa$sword'), please change the password or create a temporary account with full permissions. If you do not, the toolkit will throw an "Illegal group reference" error and you will not be able to proceed with the migration.

Connecting to Servers

You should see the toolkit trying to connect. If you have problems, please click on the advanced options and sql will show you debugging information. Click Advanced to see the log. If you see "Java Heap Space: Out of Memory", you can start the MySQL Migration Toolkit with a -Xmx flag to allocate more memory to the JVM.

After this screen you should come to reverse engineering. Click next.

Source Schemata Selection

You should see 2 databases, INFORMATION_SCHEMA and PUBLIC. Choose PUBLIC

Object Type Selection

Click Next.

Object Type Mapping

Click Show Details on both sections. For Migration Method for Type Schema, choose Multilanguage. For Migration Method for Type Table, choose Data Consistancy/Multilanguage

Click Advanced. Check Enabled Detailed Mappings in Next Step

Detailed Object Mapping

Click to rename the destination database to be the one set aside to migrate to.

From this point on, you should be able to click next all the way through to finish the migration.


  1. Hi.

    I did several HSQLDB-to-MySQL migrations before (using Confluence 3.0.x) and never had a problem. But now that we are trialing 3.2, unfortunately I wasn't able to perform the steps above successfully. 

    When trying to execute step "Connecting to servers", I get the following error in the MySQL Migration Toolkit message log:

    I'm using:

    • MySQL 5.0
    • Confluence 3.2
    • hsqldb.jar 1.7.3

    Any ideas?


  2. Also, a suggestion for improving these step-by-step instructions: please specify what versions were used when performing the steps. I had the problem described above using hsqldb 1.7, 1.8 and 2.0.

  3. Nevermind... just found the solution: just use hsqldb.jar version (and not and be happy.

  4. Anonymous

    Can't find the migration toolkit from MySQL as it's already EOLed

    How do you do this using the MySQL Workbench?

    1. Anonymous

      The GUI Tools are still available for download at:

  5. Anonymous

    MySQL Migration Toolkit is still available, but NOT supported. I've faced with this blocker BUG. That is why you need to update current guide.

  6. This entire page seems outdated.

    I've been trying to migrate a Linux installation from a Windows client PC for days now, and although I was able to resolve many problems on my own, I was still unable to complete the migration.

    If you're thinking about a migration, you should know that:

    • The MySQL migration tool is dicontinued and no longer supported. The link is broken. To find the original download, you have to dig your way through the archived files section.
    • Once installed, the migration tool complains about a missing JDK. A search on the internet pointed me to a workaround; on Windows, use the -jvm command line parameter to point the bin\client\jvm.dll file of you currently installed JRE and you may be able to get the tool running.
    • The source database selection screenshot and the table below both contain invalid database names. Following the first example, you'll point the importer to the database directory rather than the database itself, which will surprisingly not yield an error, but result in an empty import set. The second example in the table is also wrong, or, more specifically, the two trailing backslashes in the database name. Remove these and pray for a populated import screen.
    • If you're looking for a context menu, button or whatever to change the target database name default from "public" to the actual db name, here is how it works: select the line with a click, then wait for a few seconds and click again for the label to become editable.
    • The following screens showed me no errors, but the finally the table generation in the destination database fails due to invalid column counts and the keyword "nil" that seems to appear somewhere in the auto-generated export from HSQLDB.

    I'm writing this to help others, and hoping that somebody at Atlassian will possibly notice the trouble that people are having after being talked into a quick initial evaluation of Confluence with HSQLDB.

    Atlassian promises that the contents could be easily migrated to MySQL anytime ... that may have been true in the past but is obviously no longer the case.

    1. Hi Daniel, I'm sorry you had such a bad experience migrating from the embedded HSQLDB.   I've created an issue for this page to be investigated and either removed if its now completely invalid or updated. 

      Can I ask, did you start with the migration method on this page Migrating to Another Database (which involves taking a full site backup and importing that backup into your new instance) first, and had problems? 

  7. Hi Rachel. Thanks, worked like a charm with the other tutorial and took me only 15 minutes.

    A pity that I didn't notice that page earlier and used this one instead. I had been taken here as the first search result for confluence+mysql+migration, and to my shame I have to admit that I didn't read the information at the top of the page thoroughly, or at least I'm now reading it differently, like "you should try the other way first and only proceed if that didn't work".

    Anyway, thanks for opening the ticket. Either way I suppose the page needs a review.

    1. Hi Daniel, so glad you're up and running.  I'll still make sure this page gets sorted out however, and if its still valid, beef up the warning about trying the standard method first (smile)