Connecting JIRA to HSQLDB
These instructions will help you connect JIRA to an HSQL database.
Before you begin
Do not use HSQLDB in production
JIRA ships with a built-in HSQLDB (HyperSQL DataBase) database. While this database is suitable for evaluation purposes, it is susceptible to data loss during system crashes. Hence, for production environments we strongly recommend that you configure JIRA to use an external database. See our list of supported databases on Supported Platforms.
- 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:
1. Copy the HSQLDB Driver to Your Application Server (JIRA WAR Only)
Skip this step if you installed a 'Recommended' distribution of JIRA, which includes the PostgreSQL JDBC driver. The JIRA WAR distribution does not include this 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 three ways to configure your JIRA server to connect to your PostgreSQL database:
- Using the JIRA setup wizard (not applicable to JIRA WAR) — Use this method, if you have just installed JIRA and are setting it up for the first time. Your settings will be saved to the
dbconfig.xmlfile in your JIRA Home Directory. - Using the JIRA configuration tool (not applicable to JIRA WAR) — Use this method, if you have an existing JIRA instance. Your settings will be saved to the
dbconfig.xmlfile in your JIRA Home Directory. - Manually — Only use this method if you have a JIRA WAR instance or you have a console-only connection to your JIRA server. You will be required to manually update the
dbconfig.xmlfile in your JIRA Home Directory.
Instructions for each configuration method
JIRA setup wizard
The JIRA setup wizard will display when you access JIRA for the first time in your browser.
- In the first screen, 'Configure Language and Database', set Database Connection to Database bundled with JIRA.
- Go to the next step in the setup wizard. The setup wizard will set up the bundled HSQL database automatically.
JIRA configuration tool
- Run the JIRA configuration tool as follows:
- Windows: Open a command prompt and run
config.batin thebinsub-directory of the JIRA Installation Directory. - Linux/Unix: Open a console and execute
config.shin thebinsub-directory of the JIRA Installation Directory.
This may fail with the error as described in our Unable to Start JIRA applications Config Tool due to No X11 DISPLAY variable was set error KB article. Please refer to it for the workaround.
- Windows: Open a command prompt and run
- Navigate to the Database tab and set Database type to HSQL.
- Test your connection and save. The JIRA configuration tool will configure your bundled HSQL database automatically.
This tool adds the following elements to thedbconfig.xml, 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> - Restart JIRA.
Manually
- Locate 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 (shown below) into this file.
- Update the file, as described in the Database connection fields section below. Escape any '
&' characters by adding 'amp;' to the end of each one.- Note, the
<database-type/>element must specify your type of database, e.g.hsql. If you forget to do this and you start JIRA, your database tables may be created incorrectly. See Incorrect database type specified if this happens to you.
- Note, the
- Save the file and restart JIRA.
Database connection fields
| Field name | dbconfig.xml | Description |
|---|---|---|
| Hostname | Located in the | The name or IP address of the machine that the HSQL server is installed on. |
| Database | Located in the | The name of your HSQL database (into which JIRA will save its data). |
| Username | Located in the | The user that JIRA uses to connect to the HSQL server. You should have created this in Step 1 above. |
| Password | Located in the <password> tag (see bold text in example below):<password></password> | The user's password — used to authenticate with the HSQL server. |
| Schema | Located in the <schema-name> tag (see bold text in example below):<schema-name>PUBLIC</schema-name> | The name of the schema that your HSQL database uses. |
Sample dbconfig.xml file
For more information about the child elements of <jdbc-datasource/> beginning with pool in the dbconfig.xml file above, see Tuning Database Connections.
<?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:C:\Data\JIRA 5.2.7/database/jiradb</url>
<driver-class>org.hsqldb.jdbcDriver</driver-class>
<username>sa</username>
<password></password>
<pool-min-size>20</pool-min-size>
<pool-max-size>20</pool-max-size>
<pool-max-wait>30000</pool-max-wait>
<min-evictable-idle-time-millis>4000</min-evictable-idle-time-millis>
<time-between-eviction-runs-millis>5000</time-between-eviction-runs-millis>
<pool-max-idle>20</pool-max-idle>
<pool-remove-abandoned>true</pool-remove-abandoned>
<pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
</jdbc-datasource>
</jira-database-config>
4. Start JIRA
You should now have JIRA configured to connect to your HSQL database. The next step is to start it up!
- 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.