Connecting Jira applications to MySQL 8.0
These instructions will help you connect Jira to a supported MySQL database.
Before you begin
Here is some prerequisite information you should know about:
- Check known issues.
- If you are migrating Jira to another server, create an export of your data as an XML backup. You will then be able to transfer data from your old database to your new database, as described in Switching databases.
- If you plan to set up Confluence and Jira on the same MySQL server, read the Confluence MySQL setup guide. Confluence requirements are more strict than Jira's, so you should configure MySQL to suit Confluence. This configuration will work for Jira, too.
- Shut down Jira before you begin, unless you are running the setup wizard.
- In this guide, we recommend that you use the
utf8mb4_bin
collation, howeverutf8mb4_0900_ai_ci
, which is the default collation for MySQL 8.0, is also supported. Note that if you use MySQL on Amazon RDS, you'll get the default collation unless you specifically change it.
1. Create and configure the MySQL database
When creating the database, remember your database name, user name, and port number, because you'll need them later to connect Jira to your database.
Create a database user which Jira will connect as, for example jiradbuser.
CREATE USER '<USERNAME>' IDENTIFIED BY '<PASSWORD>';
Create a database for Jira to store issues in, for example jiradb.
The database must have a character set of UTF8. To set it, enter the following command from within the MySQL command client:CREATE DATABASE jiradb CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
Make sure the user has permission to connect to the database, and permission to create and populate tables. You can provide these permissions with the following commands.
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,REFERENCES,ALTER,INDEX on <JIRADB>.* TO '<USERNAME>'@'<JIRA_SERVER_HOSTNAME>'; flush privileges;
- Edit the
my.cnf
ormy.ini
(Windows) file in your MySQL Server (for detailed instructions on editing these files, see MySQL Option Files). - Locate the
[mysqld]
section in the file, and add or modify the following parameters:
Set the default storage engine to InnoDB:
[mysqld] ... default-storage-engine=INNODB ...
Specify the character set used by the database server:
[mysqld] ... character_set_server=utf8mb4 ...
Set the default row format to
DYNAMIC
:[mysqld] ... innodb_default_row_format=DYNAMIC ...
Specify the value of
innodb_log_file_size
to be at least 2G:[mysqld] ... innodb_log_file_size=2G ...
Ensure the sql_mode parameter does not specify NO_AUTO_VALUE_ON_ZERO
// remove this if it exists sql_mode = NO_AUTO_VALUE_ON_ZERO
Restart your MySQL server for the changes to take effect.
2. Copy the MySQL JDBC driver
Copy the MySQL JDBC driver to the Jira installation directory.
- Download the recommended MySQL driver JDBC Connector/J 8.0.
Copy the driver to the following directory:
<Jira-installation-directory>/lib
If you are installing Jira using the Windows installer, you will need to do this step after running the Windows installer, but before running the setup wizard.
- Restart the Jira service.
- If you are installing Jira, skip the rest of the instructions on this page and access Jira in your browser to run the setup wizard instead.
3. Configure Jira to connect to the database
There are two ways to configure your Jira server to connect to your MySQL database:
Setup wizard
Use the setup wizard if you have just installed Jira, and are setting it up for the first time. Your settings will be saved to the dbconfig.xml
file in your Jira home directory.
Configuration tool
Use the configuration tool if you have an existing Jira instance. Your settings will be saved to the dbconfig.xml
file in your Jira home directory.
4. Start Jira
You should now have Jira configured to connect to your MySQL database. The next step is to start it up!
Database connection fields
The table below explains database connection fields that you can find in the setup wizard, Jira configuration tool, or the dbconfig.xml
file.
Known issues
Here's a list of known issues for this database. Expand each of them for more details.