Last updated Jul 12, 2024

Configuring an external database for a cluster

Introduction

Whereas server products can run with an embedded H2 or HSQL database, Data Center products require an external database to which all nodes connect. As an AMPS or SDK user, it is up to you to provision that database, for example:

Configuration

Once you've provisioned the database, configure AMPS to use it by adding a <dataSource> element to either your global AMPS configuration (if you’re only configuring one product instance) or to the relevant <product> elements:

Your global AMPS configuration

1
2
<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>amps-maven-plugin</artifactId>
    <version>8.3.0</version>
    <extensions>true</extensions>
    <configuration>
        <!-- ... your existing AMPS configuration remains here ... -->
        <!-- add this `dataSource` element -->
        <dataSource>
            ...
        </dataSource>
    </configuration>
    ...
</plugin>

Relevant elements

1
2
<configuration>
    <products>
        <product>
            <!-- ... your existing product configuration remains here ... -->
            <!-- add this `datasource` element -->
            <dataSource>
                ...
            </dataSource>
        </product>
    </products>
</configuration>

The example above shows the amps-maven-plugin, but the same technique applies to product-specific AMPS plugins, such as the jira-maven-plugin, etc.

Datasource options

The <dataSource> element supports the following child elements:

1
2
<dataSource>
    <cargoString/>
    <defaultDatabase/>
    <driver/>
    <dropAndReCreateDatabase/>
    <dumpFilePath/>
    <importMethod/>
    <jndi/>
    <libArtifacts/>
    <password/>
    <properties/>
    <schema/>
    <systemPassword/>
    <systemUsername/>
    <transactionSupport/>
    <type/>
    <url/>
    <username/>
    <validationQuery/>
</dataSource>

Here's what each option means:

dataSource optionDescription
cargoStringCargo-style string to pass to Cargo via the cargo.datasource.datasource property. Not usually needed.
defaultDatabaseThe JDBC URL of the system database, namely the one to which a DBA would connect in order to perform privileged operations such as dropping or creating a schema, database, or user.
driverThe fully-qualified name of the JDBC driver class.
dropAndReCreateDatabase (new in 8.3)Whether the AMPS prepare-database goal should drop and re-create the database and its associated product user. Defaults to false.
dumpFilePathThe file from which to import data into the database. This file needs to be in the correct format for the configured importMethod.
importMethodHow AMPS should import the specified dump file: sql, psql, impdp, or sqlcmd. Defaults to sql.
jndiIf the dataSource is to be made available via JNDI, this is its JNDI name, such as jdbc/JiraDS.
libArtifactsAny Maven artifacts required by Tomcat for making a JDBC connection, typically just the JDBC driver artifact.
passwordThe password that the product (not the DBA) uses to connect to the database.
propertiesA semicolon-delimited list of JDBC driver properties.
schemaThe name of the database schema, e.g. "public". Not all types of database use this.
systemPasswordThe DBA password that AMPS uses when connecting to the defaultDatabase URL.
systemUsernameThe DBA username that AMPS uses when connecting to the defaultDatabase URL.
transactionSupportThe transaction type, typically LOCAL_TRANSACTION or XA_TRANSACTION. Can be left blank.
typeThe driver type, usually java.sql.Driver or javax.sql.XADataSource. Can be left blank.
urlThe JDBC URL via which the product (not the DBA) connects to the database.
usernameThe username that the product (not the DBA) uses to connect to the database.
validationQueryAn optional SQL-92 query for validating the database connection. Not all products use this.

Example dataSource element

Here’s a minimal configuration for connecting to a local Postgres instance:

1
2
<dataSource>
    <driver>org.postgresql.Driver</driver>
    <libArtifacts>
        <libArtifact>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>42.2.23</version>
        </libArtifact>
    </libArtifacts>
    <!-- DBA config -->
    <defaultDatabase>jdbc:postgresql://localhost:5432/postgres</defaultDatabase>
    <systemUsername>theDbaUsername</systemUsername>
    <systemPassword>theDbaPassword</systemPassword>
    <!-- Product config -->
    <url>jdbc:postgresql://localhost:5432/confdb</url>
    <schema>public</schema>
    <username>theProductDbUsername</username>
    <password>theProductDbPassword</password>
</dataSource>

In your own POM, it's good practice to use Maven properties to reduce the duplication of, for example, the database server’s hostname and port number.

AMPS dependencies

If you’re using the AMPS prepare-database goal to create the database and product user, you must add the Maven artifact for the JDBC driver as a dependency of the AMPS plugin itself. This ensures that AMPS has this driver on its own classpath:

1
2
<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>amps-maven-plugin</artifactId>
    <version>8.3.0</version>
    <extensions>true</extensions>
    <configuration>
        <!-- ... dataSource and other AMPS configuration ... -->
    </configuration>
    <dependencies>
        <dependency>
            <!-- Required for the prepare-database goal -->
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>42.2.23</version>
        </dependency>
    </dependencies>
</plugin>

Rate this page: