Limitations of database migration

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.

Migrating to an Amazon Aurora database

If you plan to migrate to an Amazon Aurora database, see Configuring Confluence Data Center to work with Amazon Aurora.  This guide explains how to migrate to an Amazon Aurora cluster and connect it to Confluence Data Center.

Method one – standard procedure

Step 1: Take note of your Marketplace apps

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

• App name and vendor
• 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. See Back up a Site. Make a note of the location where you put the XML file. You will need it later to restore your Confluence data into your new database.
2. Stop Confluence.

3. Back up your security-related assets:

   • secrets-config.yaml

   • keys/

   • secured/

4. 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.
5. Make a separate backup using the utilities that were installed with your external database. This also is a precautionary measure.

Step 3: Set up the new database

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

Step 5. Download and install the database driver if necessary

Step 6. Copy security-related assets

Copy the security-related assets that you backed up (from step 2.3) to the shared home directory of the new instance.

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

When running the Confluence setup wizard:

• Select Production Installation as the installation type.
• Enter your license key.
• Under Choose your deployment type, select either non-clustered (single node) or clustered.
• Enter your database details. Use test connection to check your database is set up correctly.
• On the load content step, select Empty Site. You will need to restore from backup after you've completed the setup wizard.
• After you've completed the setup wizard, go to Administration menu , then General Configuration. > Backup and restore and follow the steps on Restore a Site to restore an existing backup.

Step 8. Re-install your Marketplace apps

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.  

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 Marketplace apps

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

• App name and vendor
• 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. See Back up a Site. Make a note of the location where you put the XML file. You will need it later to restore your Confluence data into your new database.
2. Stop Confluence.

3. Back up your security-related assets:

   • secrets-config.yaml

   • keys/

   • secured/

4. 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.
5. Make a separate backup using the utilities that were installed with your external database. This is also a precautionary measure.

Step 3: Set up the new database

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

Step 5. Download and install the database driver if necessary

Step 6. Copy security-related assets

Copy the security-related assets that you backed up (from step 2.3) to the shared home directory of the new instance.

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

When running the Confluence setup wizard:

• Select Production Installation as the installation type.
• Enter your license key.
• Under Choose your deployment type, select either non-clustered (single node) or clustered.
• Enter your database details. Use test connection to check your database is set up correctly.
• On the load content step, select Empty Site. You will need to restore from backup after you've completed the setup wizard.
• After you've completed the setup wizard, go to Administration menu , then General Configuration. > Backup and restore and follow the steps on Restore a Site to restore an existing backup.

Step 8: 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 9. Re-install your Marketplace apps

Step 10. 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).

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.

Migrating MySQL database between servers

Confluence 7.11 and higher versions introduced Database triggers and procedures. If you use mysqldump for migration, you need to add additional parameters to your mysqldump command. For more details see Confluence MySQL database migration causes content_procedure_for_denormalised_permissions does not exist error.

In addition, Confluence uses DEFINER clauses for its procedures that have hardcoded user information and hostname/IP of the server. When a database dump is generated that will export procedures having username/account in their DDL. Errors will happen if that dump is imported into a Database without the same username/account and privileges granted. For more information, see MySQL error 1449: The user specified as a definer does not exist.

Troubleshooting

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