Migrating to Another Database

This document describes how to migrate your Confluence data from your existing database to another database. The instructions are designed primarily for migrating from an evaluation to a production database. Large data sets will require third party database migration tools.

This page covers the following scenarios:

  • Moving from the embedded, trial database to a supported external database. 

  • Moving from one external database to another, for example from Oracle to PostgreSQL (provided your dataset is not large)
  • Upgrading to a new version of the same external database. Note: you don't need to migrate your data if you're upgrading the database in place. 

Note: If you are moving your database from one server to another you can change the JDBC URL in <confluence.home>/confluence.cfg.xml (if you are using a direct JDBC connection) or in the definition of your datasource (if you are connecting via a datasource).

Limitations of database migration

Note: The XML export built into Confluence is not suited for the backup or migration of large data sets. There are a number of third party tools that may be able to assist you with the data migration. If you would like help in selecting the right tool, or help with the migration itself, we can put you in touch with one of the Atlassian Experts.

Database migration

There are two ways you can perform the migration, both described on this page:

  1. Method one is the standard procedure.

  2. Use method two if the total size of attachments in your installation exceeds 500MB.

Method one – standard procedure

Step 1: Take note of your add-ons

Take note of the add-ons (plugins) currently installed and enabled in Confluence, so that you can reinstate them later. Make a note of the following for each add-on:

  • Add-on name
  • Version
  • Enabled or disabled status. This is useful if you have enabled or disabled modules yourself, making your configuration differ from the default.

Step 2: Back up your data

  1. Create an XML backup of your existing data, via the Confluence administration console. See Manually Backing Up the Site. Make a note of the location where you put the XML file. You will need it later to import your Confluence data into your new database.
  2. Shut down Confluence.
  3. Make a copy of the Confluence Home directory. This is a precautionary measure, to ensure you can recover your data if it is mistakenly overwritten.
  4. If you are using an external database, make a separate backup using the utilities that were installed with that database. This also is a precautionary measure.

Step 3: Set up the new database

Choose the database setup instructions for your new database, and follow those instructions to do the following:
  • Install the database server.
  • Perform any required configuration of the database server, as instructed.
  • Add the Confluence database and user. Make a note of the username and password that you define in this step. You will need them later, when running the Confluence Setup Wizard.

Step 4. Install Confluence (same version number) in a new location

Now you will install Confluence again, with a different home directory path and installation path.

Note: You must use the same version of Confluence as the existing installation. (If you want to upgrade Confluence, you must do it as a separate step.) For example, if your current site is running Confluence 5.1.2, your new installation must also be Confluence 5.1.2.

When running the Confluence installer:

  • Choose Custom Install. (Do not choose to upgrade your existing installation.)
  • Choose a new destination directory. This is the installation directory for your new Confluence. It must not be the same as the existing Confluence installation.
  • Choose a new home directory. This is the data directory for your new Confluence. It must not be the same as the existing Confluence installation.

Step 5. Download and install the database driver if necessary

Note that Confluence bundles some database drivers, but you'll need to install the driver yourself if it is not bundled. Follow the database setup instructions for your new database, to download and install the database driver if necessary.

Step 6. Run the Confluence setup wizard and copy your data to your new database

When running the Confluence setup wizard:
  • Enter your license key, as usual.
  • Choose Production Installation as the installation type.
  • In the database configuration step, choose your new database type from the dropdown menu, then choose External Database.
  • Choose the connection type: Direct JDBC or Datasource. If you are not sure which, choose 'Direct JDBC'. This is the most common connection type.
  • When prompted for the database user and password, supply the credentials you defined earlier when adding the Confluence database to your database server.
  • On the load content step, choose Restore From Backup. This is where you will import the data from your XML backup. There are two options for accessing the XML file:
    • Browse to the location of your XML backup on your network, and choose Upload and Restore.
    • Alternatively, put the XML file in the Confluence home directory of the new site (<CONFLUENCE-HOME-DIRECTORY>\restore) then choose Restore.

Note: If you choose not to restore during the Confluence setup wizard, you can do the import later. Go to the Confluence administration console and choose to restore an XML backup. See Site Backup and Restore.

Step 7. Re-install your add-ons

Re-install any add-ons (plugins) that are not bundled with Confluence.
  • Use the same version of the add-on as on your old Confluence site.
  • The data created by the add-ons will already exist in your new Confluence site, because it is included in the XML backup.

Step 8. Check settings for new machine

If you are moving Confluence to a different machine, you need to check the following settings:

  • Configure your new base URL. See Configuring the Server Base URL.
  • Check your application links. See Linking to Another Application.
  • Update any gadget subscriptions from external sites pointing to this Confluence site. For example, if your JIRA site subscribes to Confluence gadgets, you will need to update your JIRA site. 
  • Review any other resources that other systems are consuming from Confluence.  

Method two – for installations with a large volume of attachments

Before you start

These instructions only apply to attachments stored in the file system. If you store attachments in the database see Attachment Storage Configuration to find out how to migrate between different attachment storage methods.

Step 1: Take note of your add-ons

Take note of the add-ons (plugins) currently installed and enabled in Confluence, so that you can reinstate them later. Make a note of the following for each add-on:

  • Add-on name
  • Version
  • Enabled or disabled status. This is useful if you have enabled or disabled modules yourself, making your configuration differ from the default.

Step 2: Back up your data

  1. Create an XML backup of your existing data, via the Confluence administration console. See Manually Backing Up the Site. Make a note of the location where you put the XML file. You will need it later to import your Confluence data into your new database.
  2. Shut down Confluence.
  3. Make a copy of the attachments directory (<CONFLUENCE-HOME-DIRECTORY>\attachments) in your Confluence Home directory. You will need it later to copy your Confluence attachments data into your new Confluence installation.
  4. If you are using an external database, make a separate backup using the utilities that were installed with that database. This also is a precautionary measure.

Step 3: Set up the new database

Choose the database setup instructions for your new database, and follow those instructions to do the following:
  • Install the database server.
  • Perform any required configuration of the database server, as instructed.
  • Add the Confluence database and user. Make a note of the username and password that you define in this step. You will need them later, when running the Confluence Setup Wizard.

Step 4. Install Confluence (same version number) in a new location

Now you will install Confluence again, with a different home directory path and installation path.

Note: You must use the same version of Confluence as the existing installation. (If you want to upgrade Confluence, you must do it as a separate step.) For example, if your current site is running Confluence 5.1.2, your new installation must also be Confluence 5.1.2.

When running the Confluence installer:

  • Choose Custom Install. (Do not choose to upgrade your existing installation.)
  • Choose a new destination directory. This is the installation directory for your new Confluence. It must not be the same as the existing Confluence installation.
  • Choose a new home directory. This is the data directory for your new Confluence. It must not be the same as the existing Confluence installation.

Step 5. Download and install the database driver if necessary

Note that Confluence bundles some database drivers, but you'll need to install the driver yourself if it is not bundled. Follow the database setup instructions for your new database, to download and install the database driver if necessary.

Step 6. Run the Confluence setup wizard and copy your data to your new database

When running the Confluence setup wizard:
  • Enter your license key, as usual.
  • Choose Production Installation as the installation type.
  • In the database configuration step, choose your new database type from the dropdown menu, then choose External Database.
  • Choose the connection type: Direct JDBC or Datasource. If you are not sure which, choose 'Direct JDBC'. This is the most common connection type.
  • When prompted for the database user and password, supply the credentials you defined earlier when adding the Confluence database to your database server.
  • On the load content step, choose Restore From Backup. This is where you will import the data from your XML backup. There are two options for accessing the XML file:
    • Browse to the location of your XML backup on your network, and choose Upload and Restore.
    • Alternatively, put the XML file in the Confluence home directory of the new site (<CONFLUENCE-HOME-DIRECTORY>\restore) then choose Restore.

Note: If you choose not to restore during the Confluence setup wizard, you can do the import later. Go to the Confluence administration console and choose to restore an XML backup. See Site Backup and Restore.

Step 7: Copy your attachments across

Copy the contents of the attachments directory (<CONFLUENCE-HOME-DIRECTORY>\attachments) from your old Confluence Home directory to your new Confluence Home directory.

Step 8. Re-install your add-ons

Re-install any add-ons (plugins) that are not bundled with Confluence.
  • Use the same version of the add-on as on your old Confluence site.
  • The data created by the add-ons will already exist in your new Confluence site, because it is included in the XML backup.

Step 9. Check settings for new machine

If you are moving Confluence to a different machine, you need to check the following settings:

  • Configure your new base URL. See Configuring the Server Base URL.
  • Check your application links. See Linking to Another Application.
  • Update any gadget subscriptions from external sites pointing to this Confluence site. For example, if your JIRA site subscribes to Confluence gadgets, you will need to update your JIRA site. 
  • Review any other resources that other systems are consuming from Confluence.  

A note about case sensitivity in your database

'Collation' refers to a set of rules that determine how data is sorted and compared. Case sensitivity is one aspect of collation. Other aspects include sensitivity to kana (Japanese script) and to width (single versus double byte characters).

Case sensitive or case insensitive collation – how should you create your Confluence database? What about when you are migrating your existing Confluence instance from one database to another?

Setting up a New Confluence Instance

For new Confluence instances, we recommend using case sensitive collation for your Confluence database. This is the default collation type used by many database systems.

Note: Even if the database is configured for case sensitive collation, Confluence reduces all usernames to lower case characters before storing them in the database. For example, this means that 'joebloggs', 'joeBloggs' and 'JoeBloggs' will be treated as the same username.

Migrating an Existing Confluence Instance to a Different Database

The default Confluence configuration uses case sensitive database collation. This is typical of databases created under default conditions. If you are migrating from this type of configuration to a new database, we recommend that the new database uses case sensitive collation. If you use case insensitive collation, you may encounter data integrity problems after migration (for example, via an XML import) if data stored within your original Confluence site required case sensitive distinctions.

Troubleshooting

See our troubleshooting guide if you're unable to restore your XML backup. 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport