Although HSQLDB is bundled with JIRA, we do not recommend it for production use. Please consider using one of the recommended databases instead. See Connecting JIRA to a Database for more information.
1. Before You BeginAre You Migrating JIRA to Another Server?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. | On this page: |
2. Copy the HSQLDB Driver to Your Application Server (JIRA WAR Only)
Skip this step if you installed a 'Recommended' distribution of JIRA, which (unlike JIRA WAR) includes the HSQLDB JDBC driver.
- Download the HSQLDB JDBC driver — hsqldb-1.8.0.5.jar for JIRA 3.7+, or hsqldb-1.7.1-patched.jar for JIRA 3.6.5 and earlier. We strongly recommend upgrading to 3.7 if you wish to use hsqldb, as hsqldb 1.7.x is prone to data corruption.
- Add the HSQLDB JDBC driver jar to the
lib/directory.
4. Configure Your JIRA Server to Connect to Your HSQL Database
There are two ways to configure your JIRA server to connect to your HSQL database:
- Using the JIRA Configuration Tool (except JIRA WAR distributions) or
- Manually
Please Note:
- The JIRA Configuration Tool requires a Java platform to be installed and configured on your operating system. We recommend using a Java platform supported by JIRA — refer to JIRA Requirements for details.
- If you use the JIRA WAR distribution or have a console-only connection to your JIRA server, you will need to configure JIRA with HSQLDB manually.
4.1 Connecting JIRA to HSQLDB Using the JIRA Configuration Tool
The JIRA Configuration Tool is not available with JIRA WAR distributions.
To start the JIRA Configuration Tool:
- On Windows:
Open a command prompt and runconfig.batin thebinsubdirectory of the JIRA Installation Directory. - On Linux/Unix:
Open a console and executeconfig.shin thebinsubdirectory of the JIRA Installation Directory.
Please Note: You may need to set the JAVA_HOME environment variable to run the JIRA Configuration Tool. See Installing Java for details.
To connect JIRA to HSQLDB using the JIRA Configuration Tool:
- Click the 'Database' tab.
- From the 'Database type' drop-down, choose 'HSQL'.

- JIRA keeps a pool of database connections open to the database server. You can set the maximum size of this pool in the 'Pool Size' text field.
- Click 'Save' to save your settings when you are done.
Please Note:- The JIRA Configuration Tool will save your database configuration to a
dbconfig.xmlfile in your JIRA Home Directory. This tool also adds the following elements to this file, which are normally required when running JIRA with HSQLDB:
<min-evictable-idle-time-millis>4000</min-evictable-idle-time-millis>
<time-between-eviction-runs-millis>5000</time-between-eviction-runs-millis> - JIRA must be restarted for your new settings to take effect.
- The JIRA Configuration Tool will save your database configuration to a
Congratulations — you have finished! Proceed to 'Next Steps' below.
4.2 Connecting JIRA to HSQLDB Manually
Edit the
dbconfig.xmlfile at the root of your JIRA Home Directory.
If this file does not exist, create the file, copy and paste the example XML code below into this file and edit the pasted XML as required.
Please Note: Ensure that the
<database-type/>element's content specifies your type of database, as shown below. If you forget to do this and you start JIRA, your database tables may be created incorrectly. Refer to our Incorrect database type specified documentation if this happens to you.
When editing your dbconfig.xmlfile, escape any '&' characters by adding 'amp;' to the end of each one.<?xml version="1.0" encoding="UTF-8"?> <jira-database-config> <name>defaultDS</name> <delegator-name>default</delegator-name> <database-type>hsql</database-type> <schema-name>PUBLIC</schema-name> <jdbc-datasource> <url>jdbc:hsqldb:/path/to/jira/database/jiradb</url> <driver-class>org.hsqldb.jdbcDriver</driver-class> <username>sa</username> <password></password> <pool-size>15</pool-size> <min-evictable-idle-time-millis>4000</min-evictable-idle-time-millis> <time-between-eviction-runs-millis>5000</time-between-eviction-runs-millis> </jdbc-datasource> </jira-database-config>
Please Note:- The following child elements of the
<jdbc-datasource/>element are normally required when running JIRA with HSQLDB:
<min-evictable-idle-time-millis>4000</min-evictable-idle-time-millis>
<time-between-eviction-runs-millis>5000</time-between-eviction-runs-millis>
- The following child elements of the
- Save your edited
dbconfig.xmlfile (at the root of your JIRA Home Directory).
JIRA must be restarted for your new settings to take effect.
4.2 Next steps
You should now have JIRA configured to connect to your HSQL database.
- If you are using a 'recommended' distribution of JIRA, start it up and watch the logs for any errors.
- If you are using the JIRA WAR distribution, rebuild and redeploy the webapp in your application server.
Installation notes
Please see JIRA and HSQL.