Data recovery and backups

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.

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 each:

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. Atlassian only recommends the backup and restore strategies described on this page:

Use the Stash backup client.
Perform a full cold backup.

With either strategy, 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.

We highly recommend that you establish a data recovery plan that is aligned with your company's policies.

On this page:

Related pages:

Using the Stash backup client

The Stash backup client locks access to Stash, the repositories managed by Stash and the Stash database (this state is called 'maintenance mode'). It checks that all Git and database operations have completed, then performs a concurrent backup of the Stash database (for example MySQL), repositories and data. The client then unlocks Stash from maintenance mode.

A user will get an error message if they try to access the Stash web interface, or use the Stash hosting services, when Stash is in maintenance mode.

The backup client creates a single tar file for the backup in the specified location.

The client supports Windows and Linux platforms, and Stash versions 2.7 and higher.

As an indication of the unavailability time that can be expected when using the Stash backup client, in our testing and internal use we have seen downtimes for Stash of 7–8 minutes with repositories totalling 6 GB in size.

Download and installation

You can download the Stash backup client from the Atlassian Marketplace.

Unzip the client into a directory on the Stash server.

Backing up Stash using the backup client

The backup client must be run from somewhere with access to the Stash home directory. Usually, you will run the backup client directly on the Stash server. Run the client with the following command:

java -jar <path/to/stash-backup-client.jar>

Configuration options are kept in the backup-config.properties file that is included with the client – this file is automatically read when the client is run. The required properties include:

`stash.home`	The full path to the Stash home directory. On Windows, you must use two backslashes (`\\`) or a single forward slash (`/`) to separate paths.
`backup.home`	The full path to the location where the backup files should be saved. If `backup.home` is not specified, the backup client will use the current working directory. The client will create a `backup` subdirectory to store backups and a `log` directory to store logs within `backup.home`. On Windows, you must use two backslashes (`\\`) or a single forward slash (`/`) to separate paths.
`stash.baseUrl`	The Stash base URL.
`stash.user`	The username of the Stash sysadmin user that will perform the backup.
`stash.password`	The password of the Stash sysadmin user that will perform the backup.

Alternatively, these properties can be given on the command-line, when they need to be prefixed with "-D", and be placed before the "-jar" parameter. For example:

java -Dstash.password="pass" -Dstash.user="user" -Dstash.baseUrl="http://stash" -jar stash-backup-client.jar

What is backed up

The client backs up the following:

The database Stash is connected to (either the internal or external DB)
Managed Git repositories
The Stash audit logs
Installed plugins and their data

The backup does NOT include the following files and directories:

export/*
log/* (except for the audit logs)
data/db* (HSQL data in the DB is backed up, but the files on disk are not)
tmp
the plugins directory (except for the installed-plugins directory)

Note that the caches directory is included in the backup because it contains previously indexed heads.

Cancelling the client backup

You can cancel the running client backup operation if necessary.

To cancel the backup:

Copy the cancel token echoed by the client in the terminal (or the Command Prompt on Windows):
Go to the Stash interface in your browser. Stash will display the this screen:
Click Cancel backup, enter the cancel token:
Click the Cancel backup button.

Restoring Stash into a new DB

When restoring Stash, the restore client must be run on the machine that Stash should be restored to. In order to ensure accidental restores do not delete existing data, the restore client will only restore into an empty home directory and an empty database.

Run the client with the following command:

java -jar <path/to/stash-restore-client.jar> <path to backup file>

The restore client also uses the backup-config.properties file, where the properties can include:

`stash.home`	The full path to a directory that the restore client will populate with the Stash home data. This directory must be empty. On Windows, you must use two backslashes (`\\`) or a single forward slash (`/`) to separate paths.
`jdbc.override`	By default, the restore client will restore into the same database that was backed up. If `jdbc.override` is set to `true`, the restore client will restore into the database specified by the below `jdbc` properties. The database must be empty.
`jdbc.driver`	The driver class that Stash should use to login to the new database. See examples below.
`jdbc.url`	The connection details for the new database, formatted as a JDBC URL. See examples below.
`jdbc.user`	The username that Stash should use to login to the new database.
`jdbc.password`	The username that Stash should use to login to the new database.

When given on the command-line, the system properties need to be prefixed with "-D", and be placed before the "-jar" parameter For example:

java -Dstash.home="path/to/stash/home" -jar stash-restore-client.jar

Sample JDBC properties

Sample jdbc.driver and jdbc.url properties are shown below.

Database	`jdbc.driver`	`jdbc.url`
MySQL	com.mysql.jdbc.Driver	jdbc:mysql://HOSTNAME:PORT/DATABASE?autoReconnect=true&characterEncoding=utf8&useUnicode=true&sessionVariables=storage_engine%3DInnoDB
Oracle	oracle.jdbc.driver.OracleDriver	jdbc:oracle:thin:@//HOSTNAME:PORT/SERVICE
PostgreSQL	org.postgresql.Driver	jdbc:postgresql://HOSTNAME:PORT/DATABASE
SQL Server	com.microsoft.sqlserver.jdbc.SQLServerDriver	jdbc:sqlserver://HOSTNAME:PORT;databaseName=DATABASE;

Using your organisation's backup processes

When you back up Stash using your standard process you 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. You should follow your database vendor's recommendations regarding database backup tools and procedures.

Restoring Stash from a cold backup

Recovering a Stash instance typically involves restoring both the file system backup and the database backup.

Child pages