Connecting Stash to MySQL

This page describes how to connect Stash to a MySQL or MariaDB database. The procedure for MySQL and MariaDB is the same, except where noted below. See Connecting Stash to an external database for general information.

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

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

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

Create the Stash database

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

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

mysql> CREATE DATABASE stash CHARACTER SET utf8 COLLATE utf8_bin;
mysql> GRANT ALL PRIVILEGES ON stash.* TO 'stashuser'@'localhost' IDENTIFIED BY 'password';
mysql> FLUSH PRIVILEGES;
mysql> QUIT

This creates an empty MySQL / MariaDB 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 / MariaDB 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 / MariaDB 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 http://dev.mysql.com/doc/refman/5.1/en/account-names.html.

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 / MariaDB 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.

   The MariaDB Java Client is not compatible with Stash

   The MySQL Connector/J must be used for both MySQL and MariaDB. The MariaDB Java Client is not compatible with Stash and is not supported.

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 / MariaDB database

You can migrate Stash to the MySQL or MariaDB 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.