Data recovery and backups

Stash backup essentials

An effective backup strategy is essential:

• for avoiding data loss in the event of any system breakdown
• for restoring Stash after any system breakdown
• as part of the Stash 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 Stash 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 Stash availability. You might consider checking the access logs to determine patterns of lowest usage to help with this.

Two ways to back up Stash

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 Stash Backup Client,

• Stash DIY Backup.

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.
Downtime	Locks Stash for the entire duration of the back up.	Only locks Stash 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 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

How Stash backup and restore works

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 Stash home directory on the file system, containing your repository data, cache and log files (see Stash home directory for more detail).
• The Stash 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 Stash 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 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.

Backing up Stash when using the internal database

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.

Backing up Stash when using an external database

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.

Restoring Stash from a cold backup

Whether you use the Stash Backup Client or Stash DIY Backup, recovering a Stash instance from backup requires restoring both:

1. the file system backup, and
2. the database backup.

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.