Page tree

Stash is now known as Bitbucket Server.
See the

Unknown macro: {spacejump}

of this page, or visit the Bitbucket Server documentation home page.

Skip to end of metadata
Go to start of metadata

This page describes how to connect Stash to a MySQL database. 

MySQL performance issues

MySQL, while supported by Stash, is currently not recommended especially in larger instances, due to inherent performance and deadlock issues that occur in this database engine under heavy load.

Affected systems may experience slow response times, deadlock errors and in extreme cases errors due to running out of database connections. These issues are intrinsic to MySQL (no other database engine in Stash's Supported platforms shares this behavior) and are due to the way MySQL performs row-level locking in transactions. See for some general information on this.

Stash does its best to work around the MySQL behavior - see issues STASH-4517, STASH-4701 and others for example. However, under very heavy load you will generally get better performance with any of the other database engines supported by Stash (such as PostgreSQL which is also freely available) than you will with MySQL. Please see Connecting Stash to an external database for instructions on migrating your data to one of these other engines.

MySQL 5.6.x Compatibility

Note that Stash is not compatible at all with versions of MySQL 5.6 earlier than 5.6.16 because of bugs in its query optimizer ( #68424 , #69005 ). Please watch STASH-3164 for further updates on this. Stash does support versions of MySQL 5.6 from 5.6.16 on.

See Supported platforms for the versions of MySQL supported by Stash.

The overall process for using a MySQL database with Stash is:

  1. Install MySQL where it is accessible to Stash. It is assumed here that you already have MySQL installed and running. See the MySQL documentation at
  2. Create the database and user on the MySQL server for Stash to use.
  3. Download and install the JDBC driver.
  4. Migrate Stash to the MySQL database.

Create the Stash database

Before you can use Stash with MySQL, you must set up the MySQL server as follows:

Create database

Create a database on MySQL for Stash to use.

Create database user

Create a Stash user on the database.

Character encoding

Configure the database to use utf8 character set encoding.

Note that Stash on MySQL does not support 4 byte UTF-8 characters.


Configure the database to use utf8_bin collation (to ensure case sensitivity).

Logging format

If MySQL is using binary logging, configure the database to use a binary logging format of either MIXED or ROW.

Refer to the MySQL documentation. Note that Stash sets the MySQL transaction isolation level to READ-COMMITTED when it connects to the database.

Connection timeout

Stash requires the database to keep idle connections alive for at least 10 minutes.

If the database is configured with less than a 10 minute connection timeout, there will be seemingly random connection errors.


Here is an example of how to do that. When Stash and MySQL run on the same physical computer (accessible through localhost), run the following commands (replacing stashuser and password with your own values):

mysql> GRANT ALL PRIVILEGES ON stash.* TO 'stashuser'@'localhost' IDENTIFIED BY 'password';
mysql> QUIT

This creates an empty MySQL database with the name stash, and a user that can log in from the host that Stash is running on who has full access to the newly created database. In particular, the user should be allowed to create and drop tables, indexes and other constraints.

If the MySQL database and Stash servers are on the same physical computer, you can use localhost and not set a password by omitting IDENTIFIED BY 'password' from the 2nd MySQL statement above (if you trust the security within this computer).

If the MySQL database and Stash servers are on different computers, just replace the localhost part of the GRANT ALL statement above with the hostname of the machine that Stash is running on. See the documentation at

Note that Stash will generally require about 25–30 connections to the database. The maximum number of connections is a configurable system property – see Database pool.

Download and install the JDBC driver

The JDBC drivers for MySQL are not bundled with Stash (due to licensing restrictions). You need to download and install the driver yourself, after you have installed Stash.

  1. Download the MySQL Connector/J JDBC driver from the download site.
  2. Expand the downloaded zip/tar.gz file.
  3. Copy the mysql-connector-java-5.1.XX-bin.jar file from the extracted directory to your <Stash home directory>/lib directory (for Stash 2.1 or later).
  4. Stop, and then restart Stash. See Starting and stopping Stash.

Migrate Stash to the MySQL database

You can migrate Stash to the MySQL database created above, either from the embedded database or from another external database.

The migration process makes a backup of your existing Stash database in exports under the Stash home directory. See Data recovery and backups for further information about backing up Stash.

Run the migration as follows:

  1. In the administration area, click Database (under 'Settings').
  2. Click Migrate database.
  3. Select MySQL for Database Type.
  4. Complete the form. See the table below for details.
  5. Click Start Migration.

See these notes about database migration.


The host name or IP address of the computer running the database server.

PortThe TCP port with which Stash can connect to the database server. The default value is the default port that MySQL runs against. You can change that if you know the port that your MySQL instance is using.
Database name
The name of the database that Stash should connect to.
Database usernameThe username that Stash should use to access the database.
Database passwordThe password that Stash should use to access the database.

  • No labels