[Other doc versions]
This page provides an overview of the backup and restore strategies that Atlassian recommends for use with Stash:
Questions? Check out FAQ - Data recovery and backup.
An effective backup strategy is essential:
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:
With any strategy, you should schedule the backup window so as to minimise the impact on Stash availability. You might consider checking the access logs to determine patterns of lowest usage to help with this.
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, Stash provides two different backup strategies:
The features of each backup strategy are summarized in the following table:
|Stash Backup Client||Stash DIY Backup|
|Audience||Recommended for most people without specific backup policies and requirements.||Recommended for developers and system administrators who wish to minimize downtime and/or customize the Stash back up 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.|
Locks Stash for the entire duration of the back up.
Only locks Stash for the minimum time necessary.
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, |
|Destination||Backups are saved on the local filesystem.||Backups can be saved anywhere.|
|Supports Stash Server||Yes||Yes|
|Supports Stash Data Center||Not supported with two or more cluster nodes running.||Yes|
|Documentation||Using the Stash Backup Client||Using Stash DIY Backup|
The Stash Backup Client does not support clustered Stash Data Center instances, even if you switch to a single node. In order to back up a clustered instance of Stash Data Center, you must switch to Stash Server DIY Backup.
Whether you choose Stash Backup Client or Stash DIY Backup, it is important to understand that there is a tight coupling between the Stash file system on disk and the database that Stash uses. The following types of data are stored in the backup process:
The backup process must ensure that you keep the repository data and the database perfectly synchronised, by:
Any backup strategy that captures both the file system and database while Stash 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 Stash data must keep the repository data and the database perfectly synchronised.
When Stash uses the built-in HSQL database, the database files are stored in the Stash file system. See Stash home directory for more detail.
Making a backup of Stash involves copying the Stash home directory.
Note that Atlassian does not recommend using the internal database for a production instance.
When Stash uses an external database, both the Stash home directory and the external database must be backed up.
If you use the Stash Backup Client, the external database is automatically included as part of the backup in a vendor-independent format.
If you use Stash 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.
Whether you use the Stash Backup Client or Stash DIY Backup, recovering a Stash instance from backup requires restoring both:
If you use the Stash Backup Client, these components are both automatically included when you run the Stash Restore Client.
If you use Stash 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.