This page last changed on Mar 10, 2011 by ggaskell.
Full Size
A Gliffy Diagram named: Install

These instructions will help you connect JIRA to a PostgreSQL 8.2+ database.

Note: A version of these instructions specific to Linux and JIRA Standalone is available.

On this page:

1. Before you begin

1.1 Export your existing JIRA data

If you are already using JIRA, 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.

1.2 Shut down JIRA

2. Configure PostgreSQL

  1. Create a database user which JIRA will connect as (e.g. jirauser).
  2. Create a database for JIRA to store issues in (e.g. jiradb) with Unicode collation
    CREATE DATABASE jiradb WITH ENCODING 'UNICODE';

    Or from the command-line:

    $ createdb -E UNICODE jiradb
  3. Ensure that the user has permission to connect to the database, and create and populate tables.

3. Copy the PostgreSQL driver to your application server

Skip this step if you are using JIRA Standalone, as JIRA Standalone includes the driver.
  1. Download the PostgreSQL JDBC driver from http://jdbc.postgresql.org/download.html. (If you have Java 1.6 installed, get version 8.4 of the JDBC 4 driver.)
  2. Add the PostgreSQL JDBC driver jar to the lib/ directory.

4. Use the JIRA Configuration Tool

The JIRA Configuration Tool is a GUI tool only available if you are using JIRA Standalone distribution. If you are running a WAR-EAR distribution of JIRA, or have a text-only connection to the JIRA server, you will need to configure the files manually.

The JIRA Configuration Tool requires that Java be installed and configured on your operating system. We recommend using a Java platform supported by JIRA — refer to JIRA Requirements for details.

The Configuration Tool will display your current configuration settings if any are already set.

  1. Click the 'Database' tab.
  2. From the 'Database type' drop-down choose 'PostgreSQL'.
  3. Fill in the connection details for your PostgreSQL database:
    • Hostname — The name or IP address of the machine that the PostgreSQL DB is installed on.
    • Port — The TCP/IP port that the PostgreSQL server is listening on.
      You can leave this blank to use the default port.
    • Database — The database that you want to save your data in.
    • Username — The user to connect to the PostgreSQL server as.
    • Password — The password to use to authenticate with the PostgreSQL server.
    • Schema — You can use this to configure a schema on the PostgreSQL server. Please ensure the schema name in the database is upper-case.
  4. After typing in your settings, use the 'Test Connection' button to test the connection settings. The tool will attempt to connect to the database, and give a message with the results.
  5. Click 'Save' to save your settings when you are done.
  6. Restart JIRA in order for your new settings to take effect.

Congratulations — you have finished!

5. Configure the database connection manually

Skip this step if you used the JIRA Configuration Tool (see above).

5.1. Configure your application server to connect to PostgreSQL

  1. Edit conf/server.xml (if you are using JIRA Standalone) and customise the username, password, driverClassName and url parameters for the Datasource. (If you are using JIRA WAR/EAR, edit the appropriate file on your application server; e.g. for Tomcat, edit conf/Catalina/localhost/jira.xml).
    <Server port="8005" shutdown="SHUTDOWN">
    
    <Service name="Catalina">
    
    <Connector port="8080"
    maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
    enableLookups="false" redirectPort="8443" acceptCount="100"
    connectionTimeout="20000" disableUploadTimeout="true" />
    
    <Engine name="Catalina" defaultHost="localhost">
    <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    
    <Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">
    <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
    username="[enter db username]"
    password="[enter db password]"
    driverClassName="org.postgresql.Driver"
    url="jdbc:postgresql://host:port/database" [see also http://jdbc.postgresql.org/doc.html ]
    [ delete the minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis params here ]
    maxActive="20"
    [ if maxActive is not set it uses the default number of the connections (8), which may be too little and can cause performance issues ]
    />
    
    <Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"
    factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
    <Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false"/>
    </Context>
    
    </Host>
    </Engine>
    </Service>
    </Server>

(Note: if you can't find this section at all, you've probably got the wrong file - search for mentions of 'jira' in the files under conf/.)

  1. If you are using JIRA Standalone, edit conf/server.xml, and delete the minEvictableIdleTimeMillis and timeBetweenEvictionRunsMillis attributes (which are only needed for HSQL, and degrade performance otherwise).
  2. If you are using an application server that requires an implementation classname, there are currently two datasource providers that can be used: one that does pooling and the one that does not. For details please see the documentation: http://jdbc.postgresql.org/documentation/84/ds-ds.html

5.2 Configure the JIRA Entity Engine

  1. Edit atlassian-jira/WEB-INF/classes/entityengine.xml (if you are using JIRA Standalone) or edit-webapp/WEB-INF/classes/entityengine.xml (JIRA WAR/EAR), and change the field-type-name attribute to the value for your database, as shown below. (If you forget to do this and start JIRA, it may create database tables incorrectly. See this page if this happens to you.)
<datasource name="defaultDS" field-type-name="postgres72"
schema-name="public"
helper-class="org.ofbiz.core.entity.GenericHelperDAO"
check-on-start="true"
use-foreign-keys="false"
use-foreign-key-indices="false"
check-fks-on-start="false"
check-fk-indices-on-start="false"
add-missing-on-start="true"
check-indices-on-start="true">

PostgreSQL 7.2 and above require a schema to be specified. The default schema in PostgreSQL is public. If you are working with JIRA Standalone, be sure to change schema-name from PUBLIC to public (lowercase).

If you are using JIRA WAR/EAR, your application server may require other changes to entityengine.xml (e.g. to customise the jndi-jdbc tag).

5.3. Next steps

You should now have an application server configured to connect to a database, and JIRA configured to use the correct database type. If you are using JIRA Standalone, start it up and watch the logs for any errors. If you are using the JIRA WAR/EAR distribution, rebuild and redeploy the webapp in your application server.

Installation notes

Please see JIRA and PostgreSQL.


Document generated by Confluence on Mar 27, 2011 18:38