[Other doc versions]
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.
MySQL / MariaDB performance issues
MySQL and MariaDB, while supported by Stash Server, are 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 and MariaDB (no other database engine in Stash's Supported platforms shares this behavior) and are due to the way MySQL and MariaDB perform row-level locking in transactions. See http://dev.mysql.com/doc/refman/5.0/en/innodb-deadlocks.html for some general information on this.
Stash Server does its best to work around the MySQL / MariaDB 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 or MariaDB. Please see Connecting Stash to an external database for instructions on migrating your data to one of these other engines.
MySQL and MariaDB are not supported in Stash Data Center
Stash Data Center does not support any version of MySQL or MariaDB. With Stash Data Center you must use one of the other database engines supported by Stash (such as PostgreSQL which is also freely available). 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
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:
Before you can use Stash with MySQL or MariaDB, you must set up the MySQL or MariaDB server as follows:
Create a database on MySQL or MariaDB for Stash to use.
|Create database user|
Create a Stash user on the database.
Configure the database to use
Note that Stash on MySQL and MariaDB does not support 4 byte UTF-8 characters.
Configure the database to use
If MySQL or MariaDB is using binary logging, configure the database to use a binary logging format of either
Refer to the MySQL documentation. Note that Stash sets the MySQL / MariaDB transaction isolation level to
Packages of MySQL or MariaDB in some Linux distributions may be configured with
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 / MariaDB run on the same physical computer (accessible through
localhost), run the following commands (replacing
password with your own values):
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.
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.
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.
<Stash home directory>/libdirectory (for Stash 2.1 or later).
You can migrate Stash to the MySQL or MariaDB database created above, either from the embedded database or from another external database.
Run the migration as follows:
See these notes about database migration.
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 or MariaDB runs against. You can change that if you know the port that your MySQL or MariaDB instance is using.|
|Database name||The name of the database that Stash should connect to.|
|Database username||The username that Stash should use to access the database.|
|Database password||The password that Stash should use to access the database.|