Documentation for JIRA 6.4. Not using this? See below:
(JIRA 6.3.x documentation | JIRA Cloud documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

The latest official documentation on configuring JIRA with MySQL can be found in the Connecting JIRA to MySQL guide.

This is a step-by-step supplement guide for setting up your MySQL database for JIRA. Although this guide assumes that your MySQL database server is running on Linux, the various procedures described below can be adapted (or may be applicable) to other similar operating systems.

Enable MySQL TCP/IP networking

Some Linux distributions (eg. Debian) disable MySQL's TCP/IP networking as a security precaution. You can test that MySQL is listening on the default port (3306) as follows:

Or if netstat isn't available:

On Debian, you can enable MySQL TCP connections by editing /etc/my.cnf, commenting out the 'skip-networking' flag, and restarting mysqld.

Create MySQL database and user

Create a MySQL user called 'jirauser' and database called 'jiradb':

The 'IDENTIFIED BY' phrase sets the password for the user (in this case, 'mypassword'). Your hostname may be different; you will find out in the next steps.

Now verify that user 'jirauser' can connect:

If you get errors like:

You will need to adjust the 'host' field for the JIRA user record:

Tip: make it so that only one production server can connect to the database, so that when you later bring up a clone of the production server as a staging server, you will be protected from having two JIRA instances using the same database.

See also Atlassian's MySQL Tips.

If problems persist, see the MySQL Causes of Access Denied Errors page.

For more general information, see Adding New User Accounts to MySQL.

Start JIRA

Check for errors in the log files.

Again, if you see an 'Access denied' error:

Then you need to adjust your /etc/hosts so that 'localhost' comes before 'localhost.localdomain', and restart MySQL. This is a MySQL bug fixed in 5.0.11.

Run the Setup Wizard

Point a browser at http://localhost:8080/, and set up JIRA as described in the Setup Wizard.


Q: I get the following error message in MySQL, "Attempted reconnect 3 times. Giving up." What should I do?
A: MySQL error message

To troubleshoot your MySQL connection, please follow the steps below:

  1. Enter the following command to connect to MySQL:

    For example,

  2. If you cannot connect to MySQL after entering your password, login to your mysql with the root account:

    And enter following command:

    <dbname> is your database name,
    <user> is your database user name,
    <password> is your database password.
    Do not forget the last command: 'FLUSH PRIVILEGES'

  3. If you still cannot connect, please check that your MySQL is listening on the default port of 3306 and bind in your IP, running either of the following commands:


    If MySQL is listening, you should see the following message:

    Alternatively, you also could check if your MySQL is listening on the default port by running this command:

  4. If you can connect successfully from the command line but JIRA cannot connect it may because a non-default port is in use. Note that the {{mysql}} tool can connect to non-standard ports without you having to specify a port, so it isn't always a guarantee of connectivity.


  • No labels


  1. This is a great tutorial.  I've just posted a little script I made in part based on this, that automates the process of configuring JIRA for MySQL, including creating the database, configuring the jira user, unpacking the jira tgz, etc.  It's for JIRA standalone only, but it saves time.  It also allows you to easily customize your JIRA port if you wish.

    I write about it in more detail at on my blog.  Makes setting up JIRA for MySQL dead simple! 

  2. Anonymous

    Please make sure to start mysqld with the option --default-table-type=InnoDB to use InnoDB as default engine. MyISAM does not support transactions and will cause corrupt workflows on errors.

  3. I agree with Adam above that this is an extremely helpful set of instructions for using standalone Jira on Linux with MySQL..  I recently migrated a Jira installation from one Red Hat server to another and upgraded from Jira 3.12 to 4.0.1.  Both Jira instances are standalone using MySQL databases.  In reading the Atlassian documentation, I found that the information I needed was spread across several different parts of the Installation and Upgrade Guide, and in some cases, the documentation made different suggestions at different places.  I thought I would post what worked for me:

    The task was to migrate a Jira 3.12 installation on one server to Jira 4.0.1 on a different server.  After installing JDK 1.6 and MySQL 5.0, these are the steps that we followed:

    - as the jira user, install the new version of jira with the default configuration

    - start jira to make sure all is well.  Connect to host:8080 and also check out the catalina.out log file.

    - create an empty mysql database and add a user as mentioned above

    - copy the jdbc connector jar file to common/lib

    - update the Jira configuration to match the old version ... don't copy files, edit the files.  This includes entityengine.xml, osuser.xml,, and server.xml.

    - export the old jira data as XML and copy the file to the new machine

    - restart jira.  If all is well, when you go to localhost:8080, you will get the configuration set up page with an option to import data from an existing installation.  Go with the import data option.

    - enter a Jira 4.0 license key that is associated with the OLD installation's server id

    - import the XML file ... it takes several minutes to load.

    - Reload localhost:8080 and check the logs to make sure all is working properly.

  4. Re anonymous's comment above, I recommend before creating the jira database that you set your MySQL defaults to InnoDB and UTF-8 server-wide. This can save a lot pf pain later. To do this, edit /etc/my.cnf and add the following two lines in the [mysqld] section:

    Then restart your MySQL instance with:

    1. For Ubuntu 10.04 you want to edit /etc/mysql/my.cnf.  

      You may need to install with:

      Then you can restart with:

  5. The suggestion to change the Jira user to have host "localhost.localdomain" cause Jira to not start on Ubuntu Karmic.  Leaving it as is (i.e. "localhost") works just fine.

  6. Anonymous

    broken link in "If problems persist, see the MySQL Causes of Access Denied Errors page."

  7. Hi,

    In this page example, you mention 'jirauser'@'localhost' but here Connecting JIRA to MySQL#sampledbconfigxml , '<USERNAME>'@'<JIRA_SERVER_HOSTNAME>' . So, this user has to be able to connect to the DB remotely or not?

    Tks for your answer.