Connecting Stash to an external database

Why would I want to use an external database?

Stash ships with an embedded database that is great for evaluation purposes, but for production installations we recommend that you make use of one of the supported external databases, for the following reasons:

• Improved protection against data loss: The Stash built-in database, which runs HSQLDB, is susceptible to data loss during system crashes. External databases are generally more resistant to data loss during a system crash. HSQLDB is not supported in production environments and should only be used for evaluation purposes.
• Performance and scalability: If you have a large number of users on your Stash instance, running the database on the same server as Stash may slow it down. When using the embedded database, the database will always be hosted and run on the same server as Stash, which will limit performance.
• Unified back-up: Use your existing DBMS tools to back up your Stash database alongside your organisation's other databases.

Connect Stash to an external database at install time

You can connect Stash to an external database using the Setup Wizard, which runs automatically when you visit Stash in your browser the first time Stash is started after installation.

You'll need to have created the external database before running the Setup Wizard. See the related pages listed above right for details.

For MySQL, you'll need to have installed the JDBC driver first.

If you have been using Stash for a while with the embedded database, you can migrate to an external database, as described below.

Migrate Stash to an external database

You can use the Database Migration Wizard to migrate Stash from the embedded database to an external database, or from an external database to another external database. You need to have created the DBMS (such as MySQL) that you wish to migrate the Stash data to before running the Migration Wizard.

See the related pages listed above right for details.

Notes about database migration

• Back up the database and Stash home directory:
  Before starting the database migration process you should back up your Stash home directory. If you intend to migrate from one external database to another, you should also backup the existing database before proceeding. See Data recovery and backups for more information.
   
• Stash will be unavailable during the migration:
  Stash will not be available to users during the database migration operation. In addition, running the migration when people are using Stash can sometimes cause the migration to time out waiting for all activity in Stash that uses the database to complete. For these reasons we recommend that you run the database migration outside of normal usage periods.
   
• Migration will usually take less that 30 minutes:
  The duration of the migration process depends on the amount of data in the Stash database being migrated. For new installations of Stash, containing very little data, the migration process typically takes just a few seconds. If you have been using Stash for some time, its database will contain more data, and the migration process will therefore take longer. If Stash has been linked to a JIRA instance, and there are hundreds of thousands of commits in Stash with JIRA keys in the commit messages, the migration may take tens of minutes.
   
• We strongly recommend using a new clean database for the new Stash database: 
  In case of a migration failure, Stash may have partially populated the target database. If the target database is new (therefore empty) and set aside for Stash's exclusive use, it's very easy to clean up after a failed migration; just drop the target database and use a clean target database instance for the next attempt.
   
• Ensure your Stash home directory is secured against unauthorised access:
  
  • After the migration, the connection details (including the username and password) for the database are stored in the stash-config.properties file.
  • Migration will create a dump file of the contents of your database in the Stash home export directory. This is used during the migration and is kept for diagnostic purposes in the case of an error. You may remove this after migration but it may reduce Atlassian Support's ability to help you in the case of migration issues.
    
    

• You can edit the database password if needed after migration.