Data recovery and backups

Administer Bitbucket Data Center and Server

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This page provides an overview of the backup and restore options available for use with Bitbucket Data Center and Server:

Questions? Check out FAQ - Data recovery and backup.

Bitbucket backup essentials

An effective backup strategy is essential:

  • for avoiding data loss in the event of any system breakdown,
  • for restoring Bitbucket after any system breakdown,
  • as part of the Bitbucket 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 be backed up? We recommend that backups are made at least daily.
  • How much downtime is acceptable? When using a backup strategy with any downtime we recommend scheduling backups at a time of day that minimizes impact on users, e.g., out of office hours.
  • How long should backups be retained for? We recommend that backups be retained for at least one month.
  • Where should the backups be stored? We recommend that backups are stored at an offsite location.
  • How quickly and easily can you restore your data in an emergency? We recommend restoring your backups in a staging environment on a regular basis to ensure that your backup strategy works in the event of a real emergency scenario.

The importance of being consistent

All backup strategies for Bitbucket need to capture the state of three fundamental data sources:

  • The home directory on the file system, which contains your repository data, log files, plugins, and so on (see Set the home directory for more detail).
  • If you’re using Mesh to manage your repositories, each Mesh node’s home directory, which contains your repository data and Mesh log files.
  • The database, which contains data about pull requests, comments, users, groups, permissions, and so on.

These data sources hold the entire state of a Bitbucket instance. To backup the complete state of your instance, you need to take consistent snapshots of each using one of the strategies below. If you attempt to restore snapshots containing inconsistencies then there is a risk of corruption or data loss in your repositories and pull requests.

(In addition, if you have a remote Elasticsearch instance then search indexes are maintained in Elasticsearch's data directory, but you don't have to include this in your backup as it can be completely rebuilt if necessary from the data in your home directory and database.)

Bitbucket backup strategies

Bitbucket provides multiple strategies for taking backups free of inconsistencies, and each are summarized in the table below. Each option has tradeoffs between technical requirements and the amount of downtime involved. Which strategy you choose depends on the scale of your instance, your file system and database technologies, your recovery point objective, and your users' tolerance of downtime when backups are taken.


Zero Downtime BackupDIY BackupBackup Client
SummaryA technique that eliminates downtime completely using internally consistent database snapshots and block-level filesystem snapshotsA technique that minimizes downtime using incremental copy or vendor-specific snapshot technology

Simple but unsuitable for use in high availability environments.

An external utility which locks a Bitbucket Server instance and backs up its entire home directory and database in a vendor-independent format.

Downtime(tick) Zero at backup time.

(warning) Low. Only needs to lock Bitbucket briefly to create a consistent snapshot. Downtime can be as low as a few seconds.

(error) High. Bitbucket is locked for the entire duration of the backup process, which may take several minutes or longer, especially in large organizations.

Minimum product versionBitbucket 4.8+

Stash 2.12+

Bitbucket 4.0+

Stash 2.7+

Bitbucket 4.0+

Bitbucket Server(tick) Supported. Bitbucket tolerates (but does not attempt to resolve) any inconsistencies between the home directory and database after restoring.(tick) Supported(tick) Supported
Bitbucket Data Center

(tick) Supported. Bitbucket can perform an integrity check at restore time to scan for inconsistencies between the home directory and database, and resolve them.

Note that Mesh does not yet automatically resolve inconsistencies between replicas at restore time. For more details, see BSERV-13312 - Getting issue details... STATUS

(tick) Supported

Note that Mesh does not yet automatically resolve inconsistencies between replicas at restore time. For more details, see BSERV-13312 - Getting issue details... STATUS

(error) Not supported, even if you are running on one cluster node.
Minimum requirements
  • Requires you to use the snapshot tools of your file system and database vendor. Example scripts are provided.
  • Requires your home directories to be on a file system volume capable of atomic (block level) snapshots, for example, Amazon EBSLVMNetAppXFS, or ZFS.
  • Minimizing the time between database and filesystem snapshots (or using vendor-specific point-in-time recovery) reduces the chances of inconsistencies occurring

Requires you to use the snapshot tools of your file system and database vendor. Example scripts are provided.

No special requirements. "Just works" out of the box.
Backup formatVendor-specific database snapshot and block level file system snapshot of the entire disk volume.Vendor-specific database dump and file system snapshot.

Database vendor-independent.

DocumentationBitbucket zero downtime backupBitbucket DIY BackupBitbucket Server Backup Client


Further information

Bitbucket zero downtime backup

Bitbucket DIY Backup

Bitbucket Server Backup Client

Last modified on Mar 7, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.