# Stash Latest : Connecting Stash to MySQL

This page last changed on Sep 20, 2012 by pwatson.

This page describes how to connect Stash to a MySQL database. The overall process for using a MySQL database with Stash is: Install MySQL where it is accessible to Stash. Create a database and user on the MySQL server for Stash to use. Install Stash on Windows, or on Linux or Mac. Either: at Stash install time, run the Setup Wizard to connect Stash to the MySQL database, or at a later time, migrate Stash to the MySQL database. It is assumed here that you already have MySQL installed and running. MySQL documentation is available at http://dev.mysql.com/doc/. See Supported platforms for the versions of MySQL supported by Stash. | On this page: 1. Prerequisites Download and install the JDBC driver Backup your data Create the Stash database 2. Connect Stash to the MySQL database Related pages: Connecting Stash to an external database Connecting Stash to Oracle Connecting Stash to PostgreSQL Connecting Stash to SQL Server

### 1. Prerequisites

#### Download and install the JDBC driver

The JDBC drivers for MySQL Enterprise Server are not bundled with Stash (due to licensing restrictions). You need to download and install the driver yourself.

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 the``<Stash installation directory>```/lib` directory (create the `lib/` directory if it doesn't already exist).
4. Stop Stash, on Windows, or on Linux and Mac .
5. Restart Stash, on Windows, or on Linux and Mac.

#### Backup your data

If you are migrating your data from the internal Stash database, back up the Stash home directory.

If you are migrating your Stash data from another external database, back up that database by following the instructions provided by the database vendor before proceeding with these instructions.

See Data recovery and backups.

#### Create the Stash database

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

- create a database on MySQL for Stash to use
- create a Stash user on the database
- configure the database to use `utf8` character set encoding
- configure the database to use`utf8_bin` collation (ensures case sensitivity)
- configure the database to use the InnoDB storage engine.

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> SET GLOBAL storage_engine = 'InnoDB';
    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 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 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.

### 2. Connect Stash to the MySQL database

You can now connect Stash to the MySQL database, either:

- when you run the Setup Wizard, at install time,
- when you wish to migrate to MySQL, either from the embedded database or from another external database.

When running the Setup Wizard at install time:

1. Select External at the 'Database' step.
2. Select MySQL for Database Type.
3. Complete the form. See the table below for details.
4. Click Next, and follow the instructions in the Stash Setup Wizard.

When migrating to MySQL:

1. Click Administration and then 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.

Hostname | The host name or IP address of the computer running the database server.
Port | The 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 | The name of the database that Stash should connect to.
Username | The username that Stash should use to access the database.
Password | The password that Stash should use to access the database.

## Attachments:

Stash_012_mysql.png (image/png)