This document outlines how to migrate your data from your existing database to another database.
You should use this method when moving from the embedded DB to an external DB, or from one type of external DB to another (e.g. Oracle to Postgres). If you are simply moving your DB from one server to another you can just 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).
There are two ways you can perform the migration:
- Method one is the standard procedure.
- For large installations of Confluence using version 2.2 or later: If the total size of attachments on your installation exceeds 500MB, use method two.
On this page:
Method One - Standard Procedure
Step One: Backing up your data
- Create a backup of your existing data. This is done from the Administration Console. Instructions on how to create a backup can be found here.
- Shut down and backup the Confluence Home Directory.
- If you are already using an external database, please make a backup of it using the utilities that were installed with it.
 | Note which plugins are currently installed/enabled, so that you can reinstate them later. |
Step Two: Configuring the Confluence Home Directory
- Create a new Confluence Home Directory. You can place this directory anywhere you like and give it a name of your choice.
- Open WEB-INF/classes/confluence-init.properties file in your Confluence installation and change the confluence.home property to point to this new Confluence Home Directory.
Step Three: Setting up the new database
Perform the database setup instructions for your database.
Step Four: Setting up Confluence with the new database
If your databases are not already configured for Confluence, refer to Database Configuration to setup your database access.
- Make sure that the JDBC drivers for your database are available to the application server. If you don't already have the JDBC driver, please download one from here.
- Make sure that your database is using a case-sensitive collation. Please refer to the section on case sensitivity below and see this issue for more details: CONF-7917.
- If you are running the standalone version of Confluence, copy your JDBC database driver (a .jar file), into the <confluence-install>/lib folder.
- Start up Confluence. You will see the Confluence Setup Wizard.
- Select 'Custom Install'.
- Select your database from the drop down list.
- Select 'Direct JDBC' and then enter the details of the new database you want to migrate to.
Read the documentation on the Setup Wizard for more detailed explanation.
- When prompted, restore the contents of the backup you made in Step One into the new Confluence site
Your old Confluence data will now be imported to your new database.
Method Two - For large installations
Step One: Backing up your data
- Before proceeding with these instructions please check that:
- you are upgrading from at least Confluence version 2.2 and
- your attachments are stored in the file system, and not in your database. (To migrate between attachment storage systems, please see Attachment Storage Configuration)
These instructions will not work if either of the above is not true.
- From Confluence, go to Administration -> Backup & Restore and create a manual backup that excludes attachments.
- Shut down and back up the Confluence Home Directory.
- If you are already using an external database, please make a backup of it using the utilities that were installed with it.
Step Two: Configuring the Confluence Home Directory
- Create a new Confluence Home Directory. You can place this directory anywhere you like and give it a name of your choice.
- Open WEB-INF/classes/confluence-init.properties file in your Confluence installation and change the confluence.home property to point to this new Confluence Home Directory.
Step Three: Moving your attachments
Move the contents of your attachments directory from your old Confluence Home to your new Confluence Home.
Step Four: Setting up new database
Perform the database setup instructions for your database.
Step Five: Setting up Confluence with the new database
If your databases are not already configured for Confluence, refer to Database Configuration to setup your database access.
- Make sure that the JDBC drivers for your database are available to the application server. If you don't already have the JDBC driver, please download one from here.
- Make sure that your database is using a case-sensitive collation. Please refer to the section on case sensitivity below and see this issue for more details: CONF-7917.
- If you are running the standalone version of Confluence, copy your JDBC database driver (a .jar file), into the <confluence-install>/lib folder.
- Start up Confluence. You will see the Confluence Setup Wizard.
- Select 'Custom Install'.
- Select your database from the drop down list.
- Select 'Direct JDBC' and then enter the details of the new database you want to migrate to.
Read the documentation on the Confluence Setup Wizard for more detailed explanation.
- When prompted, restore the contents of the backup you made in Step One into the new Confluence site.
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 case-insensitive collation because it helps enforce uniqueness constraints that make sense in our applications. That is, if you don't want to allow 'joebloggs', 'joeBloggs', 'JoeBloggs', etc. as different valid usernames, you should use case-insensitive collation.
Migrating an Existing Confluence Instance to a Different Database
The default Confluence Standalone configuration uses a case-sensitive database. If you are migrating from this configuration to a new database, you may have existing usernames with 'joebloggs', 'joeBloggs', 'JoeBloggs', etc. In this case, if your new database is case-insensitive, your XML import will fail unless you clean up the data first. That's why we recommend sticking with case sensitivity if you're migrating databases.
Troubleshooting
If you're unable to restore your XML backup, consult our Troubleshooting Guide.
RELATED TOPICS
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.
Comments (10)
Apr 20
Martin Blazek says:
Hi, instructions on this page contradict what is said here. The difference is i...Hi, instructions on this page contradict what is said here.
The difference is in the location of the JDBC driver. This page says:
The PostgreSQL documentation says:
Apr 21
Arie Murdianto says:
Hi, You can use both instructions and Confluence should not be complaining anyt...Hi,
You can use both instructions and Confluence should not be complaining anything if you put the driver in either in <Confluence install>/confluence/WEB-INF/lib or <Confluence install>/lib. If you put it to <Confluence install>/lib, it is accessible to any applications which is deployed in the same application server as your Confluence instance. if you put the driver to <Confluence install>/WEB-INF/lib, the driver is only meant for Confluence only.
Cheers,
Apr 21
Martin Blazek says:
Hi Arie, and thanks a lot for a prompt and competent response!Hi Arie, and thanks a lot for a prompt and competent response!
Apr 23
Sorin Cristescu says:
I migrated from an Oracle DB to a PostgreSQL DB following this procedure. In the...I migrated from an Oracle DB to a PostgreSQL DB following this procedure. In the process, I lost all the custom themes / layouts and a lot of custom macro functionality. On the other hand, the procedure recommends a source DB backup is run using the specific DBMS-provided backup tools but it is not clear to me what use is this backup afterwards - am I wrong or the procedure above doesn't refer to this source DB backup anymore thereafter ?
Apr 23
Martin Blazek says:
Sorin, not sure I got your question right but as far as I know you MUST use an X...Sorin, not sure I got your question right but as far as I know you MUST use an XML backup when migrating between databases (Oracle to Postgres in your case).
Apr 23
Sorin Cristescu says:
Thanks for your quick response I believe I did an XML backup, although I'm not...Thanks for your quick response
I believe I did an XML backup, although I'm not 100% sure ... which brings about another question : what would the rollback procedure look like ? I mean, imagine I'm not happy with the result of my migration and want to go back to using the previous DB - what should I do ? In my specific case, how can I go back to using my original Oracle instance (which still has everything in it, in terms of custom themes and layouts) ?
Apr 23
Martin Blazek says:
Atlassian always recommends that (when migrating) you first setup a system (Conf...Atlassian always recommends that (when migrating) you first setup a system (Confluence, JIRA) in a test environment, make sure everything works to your satisfaction and only when happy you upgrade/migrate your live server.
Jun 04
Anonymous says:
Using ESF Database Migration Toolkit( http://www.easyfrom.net/download/ ) A tool...Using ESF Database Migration Toolkit( http://www.easyfrom.net/download/ )
A toolkit migrates data across various database/file systems. Supporting Oracle, SQL Server, MySQL, PostgreSQL, MS-Access, MS-Excel, Firebird, CSV and so on.
Jun 18
Anonymous says:
Is there any other information on how to move to a different db but not a differ...Is there any other information on how to move to a different db but not a different type of db? For instance we are on an oracle db right now, but in development. We want to move to an oracle db that is production. All I see above is
Do we need to do anything with the confluence data directory? Is there anything we have to back up before this happens? or do we need to have our dba's copy and move the data over?
Thanks in advance.
Jun 22
Azwandi Mohd Aris says:
Hi, The quote above is useful when you are moving to another database server on...Hi,
The quote above is useful when you are moving to another database server only. If you would like to migrate the Confluence installation as well, you will need to follow the guidelines at Migrating Confluence Between Servers.
Cheers,
Azwandi
Add Comment