Connecting Bitbucket Server to MySQL
This page describes how to connect Bitbucket Server to a MySQL or MariaDB database. The procedure for MySQL and MariaDB is the same, except where noted below. See Connect Bitbucket to an external database for general information.
MySQL / MariaDB performance issues
MySQL and MariaDB, while supported by Bitbucket 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 Bitbucket Server'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.
Bitbucket 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 Bitbucket Server (such as PostgreSQL which is also freely available) than you will with MySQL or MariaDB. Please see Connect Bitbucket to an external database for instructions on migrating your data to one of these other engines.
MySQL and MariaDB are not supported in Bitbucket Data Center
Bitbucket Data Center does not support any version of MySQL or MariaDB. With Bitbucket Data Center you must use one of the other database engines supported by Bitbucket Server (such as PostgreSQL which is also freely available). Please see Connect Bitbucket to an external database for instructions on migrating your data to one of these other engines.
MySQL 5.6.x compatibility
Note that Bitbucket Server 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. Bitbucket Server does support versions of MySQL 5.6 from 5.6.16 on.
JDBC driver support
Bitbucket Server only supports MySQL JDBC version 5.1.
See Supported platforms for the versions of MySQL and MariaDB supported by Bitbucket Server.
The overall process for using a MySQL or MariaDB database with Bitbucket Server is:
- Install MySQL or MariaDB where it is accessible to Bitbucket Server. It is assumed here that you already have MySQL or MariaDB installed and running. See the MySQL documentation at http://dev.mysql.com/doc/.
- Create the database and user on the MySQL / MariaDB server for Bitbucket Server to use.
- Download and install the JDBC driver.
- Migrate Bitbucket Server to the MySQL / MariaDB database.
Create the Bitbucket Server database
Before you can use Bitbucket Server with MySQL or MariaDB, you must set up the MySQL or MariaDB server as follows:
Create database
Create a database on MySQL or MariaDB for Bitbucket Server to use.
Create database user
Create a Bitbucket Server user on the database.
Character encoding
Configure the database to use utf8 character set encoding.
Note that Bitbucket Server on MySQL and MariaDB does not support 4 byte UTF-8 characters.
Collation
Configure the database to use utf8_bin collation (to ensure case sensitivity).
Logging format
If MySQL or MariaDB 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 Bitbucket Server sets the MySQL / MariaDB transaction isolation level to READ-COMMITTED when it connects to the database.
Packages of MySQL or MariaDB in some Linux distributions may be configured with binlog_fmt=statement by default. Before using such packages with Bitbucket Server you must change this to either mixed or row. See this KB article for more information.
Connection timeout
Bitbucket Server 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 Bitbucket Server and MySQL / MariaDB run on the same physical computer (accessible through localhost), run the following commands (replacing bitbucketuser and password with your own values):
mysql> CREATE DATABASE bitbucket CHARACTER SET utf8 COLLATE utf8_bin;
mysql> CREATE USER 'bitbucketuser'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON bitbucket.* TO 'bitbucketuser'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> QUITThis creates an empty MySQL / MariaDB database with the name bitbucket, and a user that can log in from the host that Bitbucket Server 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 Bitbucket Server instances 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 Bitbucket Server instances are on different computers, just replace the localhost part of the GRANT ALL statement above with the hostname of the machine that Bitbucket Server is running on. See the documentation at http://dev.mysql.com/doc/refman/5.1/en/account-names.html.
Note that Bitbucket Server 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 Bitbucket Server (due to licensing restrictions). You need to download and install the driver yourself, after you have installed Bitbucket Server.
Download the MySQL Connector/J JDBC driver from the download site.
The MariaDB Java Client is not compatible with Bitbucket Server
The MySQL Connector/J must be used for both MySQL and MariaDB. The MariaDB Java Client is not compatible with Bitbucket Server and is not supported.
- Expand the downloaded zip/tar.gz file.
- Copy the mysql-connector-java-5.1.XX-bin.jar file from the extracted directory to your
<Bitbucket home directory>/libdirectory (for Bitbucket Server 2.1 or later). - Stop, and then restart Bitbucket Server. See Start and stop Bitbucket.
Migrate Bitbucket Server to the MySQL / MariaDB database
You can migrate Bitbucket Server 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 Bitbucket Server database in exports under the Bitbucket Server home directory. See Data recovery and backups for further information about backing up Bitbucket Server.
Run the migration as follows:
- In the administration area, click Database (under 'Settings').
- Click Migrate database.
- Select MySQL for Database Type.
- Complete the form. See the table below for details.
- Click Start Migration.
See these notes about database migration.
Hostname
The hostname or IP address of the computer running the database server.
Port
The TCP port with which Bitbucket Server 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 Bitbucket Server should connect to.
Database username
The username that Bitbucket Server should use to access the database.
Database password
The password that Bitbucket Server should use to access the database.