Data recovery and backups
This page provides an overview of the backup and restore strategies that Atlassian recommends for use with Bitbucket Server:
Questions? Check out FAQ - Data recovery and backup.
Bitbucket Server backup essentials
An effective backup strategy is essential:
- for avoiding data loss in the event of any system breakdown
- for restoring Bitbucket Server after any system breakdown
- as part of the Bitbucket Server upgrade process.
We highly recommend that you establish a data recovery plan that is aligned with your company's policies. At the very least, you should consider these aspects:
- How frequently should Bitbucket Server be backed up? We recommend that backups are made daily.
- How much downtime is acceptable?
- How long should backups be stored for? We recommend that backups be kept for at least one month.
- Where should the backups be stored? We recommend that backups are stored offsite.
With any strategy, you should schedule the backup window so as to minimise the impact on Bitbucket Server availability. You might consider checking the access logs to determine patterns of lowest usage to help with this.
Two ways to back up Bitbucket Server
When it comes to backing up, every organization has slightly different policies and requirements. Some organizations will want a backup solution that just works with minimal intervention, is independent of the underlying database and file system configuration, and don't mind a little downtime when the backup is run as part of a nightly maintenance schedule. Other organizations will have more specific policies and requirements surrounding the use of vendor-specific database and storage backup tools, the maximum acceptable downtime, the format of backups, and where the backups are ultimately stored.
To cater for these different policies and requirements, Bitbucket Server provides two different backup strategies:
- the Bitbucket Server Backup Client,
- Bitbucket Server DIY Backup.
The features of each backup strategy are summarized in the following table:
| Bitbucket Server Backup Client | Bitbucket Server DIY Backup | |
|---|---|---|
| Audience | Recommended for people who don't want to have to script the backup process at the database and file system level. | Recommended for developers and system administrators who want to customize the Bitbucket Server backup process for their specific database and file system configuration. |
| Usage | Ready to use out of the box. | Requires you to write some code (in your preferred language) to perform the backup steps. |
| Downtime | Locks Bitbucket Server for the entire duration of the backup. | Only locks Bitbucket Server for the minimum time necessary. |
| Backup | Backup files are in a vendor-independent format and do not depend on the underlying database configuration. | Backup files rely on vendor-specific database and/or storage tools; for example, pg_dump is used if your back end database is PostgreSQL. |
| Destination | Backups are saved on the local filesystem. | Backups can be saved anywhere. |
| Supports Bitbucket Server |  Yes | Yes |
| Supports Bitbucket Data Center |  Not supported with two or more cluster nodes running. | Yes |
| Documentation | Using the Bitbucket Server Backup Client | Using Bitbucket Server DIY Backup |
The Bitbucket Server Backup Client does not support clustered Bitbucket Data Center instances, even if you switch to a single node. In order to back up a clustered instance of Bitbucket Data Center, you must switch to Bitbucket Server DIY Backup.
How Bitbucket Server backup and restore works
Whether you choose Bitbucket Server Backup Client or Bitbucket Server DIY Backup, it is important to understand that there is a tight coupling between the Bitbucket Server file system on disk and the database that Bitbucket Server uses. The following types of data are stored in the backup process:
- The Bitbucket Server home directory on the file system, containing your repository data, cache and log files (see Bitbucket Server home directory for more detail).
- The Bitbucket Server database, containing data about pull requests (pointers to branches in the repos, comments and pull request diffs) and user management.
The backup process must ensure that you keep the repository data and the database perfectly synchronised, by:
- Shutting down Bitbucket Server before performing the backup.
- Restoring the database and file system at the same time.
- Using the same version or snapshot of the database and file system.
Any backup strategy that captures both the file system and database while Bitbucket Server is still available to users would run the risk that the backed up Git repositories might be corrupted or that the data in the database doesn't reflect the repository state on disk. Therefore, strategies for backing up and restoring Bitbucket Server data must keep the repository data and the database perfectly synchronised.
Backing up Bitbucket Server when using the internal database
When Bitbucket Server uses the built-in HSQL database, the database files are stored in the Bitbucket Server file system. See Bitbucket Server home directory for more detail.
Making a backup of Bitbucket Server involves copying the Bitbucket home directory.
Note that Atlassian does not recommend using the internal database for a production instance.
Backing up Bitbucket Server when using an external database
When Bitbucket Server uses an external database, both the Bitbucket Server home directory and the external database must be backed up.
If you use the Bitbucket Server Backup Client, the external database is automatically included as part of the backup in a vendor-independent format.
If you use Bitbucket Server DIY Backup, you have full control over the database backup tools and procedures, and can use your database vendor's specific backup tooling that is optimized for your database back end and stores the dump in a vendor-specific format.
Restoring Bitbucket Server from a cold backup
Whether you use the Bitbucket Server Backup Client or Bitbucket Server DIY Backup, recovering a Bitbucket Server instance from backup requires restoring both:
- the file system backup, and
- the database backup.
If you use the Bitbucket Server Backup Client, these components are both automatically included when you run the Bitbucket Server Restore Client.
If you use Bitbucket Server DIY Backup, the backup script restores the file system backup, and you need to use your database vendor's specific restore tooling to restore the database backup.