Data recovery and backups

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 .

Related pages:

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.

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:

The Stash home directory on the file system contains data about your repositories, as well as cache and log files (see Stash home directory for more detail).
The Stash database contains data about pull requests (pointers to branches in the repos, comments and pull request diffs) and user management.

Any backup strategy that captures both the file system and database while Stash is still available to users runs the risk that the backed up Git repositories are 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.

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	The backup is generic and does not depend on the underlying database configuration.	The backup relies on database-specific tools; for example, `pg_dump` is used if your back end database is PostgreSQL.
Destination	Saves the backup on the local filesystem.	Backups can be saved anywhere.
Documentation	Using the Stash Backup Client	Using Stash DIY Backup

How Stash backup and restore works

Whether you use the Stash Backup Client or Stash DIY Backup, 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.

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:

the file system backup, and
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.

Child pages