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:

Via Maven, using for example the docker-maven-plugin to start and stop the database instance.
Via Docker Desktop on your development machine.
On a shared database server in your IT infrastructure.

If you automatically provision the database during the pre-integration-test phase of the default Maven lifecycle, you must also tear it down in the post-integration-test phase.

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` option	Description
`cargoString`	Cargo-style string to pass to Cargo via the `cargo.datasource.datasource` property. Not usually needed.
`defaultDatabase`	The 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.
`driver`	The 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.
`dumpFilePath`	The file from which to import data into the database. This file needs to be in the correct format for the configured `importMethod`.
`importMethod`	How AMPS should import the specified dump file: `sql`, `psql`, `impdp`, or `sqlcmd`. Defaults to `sql`.
`jndi`	If the `dataSource` is to be made available via JNDI, this is its JNDI name, such as `jdbc/JiraDS`.
`libArtifacts`	Any Maven artifacts required by Tomcat for making a JDBC connection, typically just the JDBC driver artifact.
`password`	The password that the product (not the DBA) uses to connect to the database.
`properties`	A semicolon-delimited list of JDBC driver properties.
`schema`	The name of the database schema, e.g. "public". Not all types of database use this.
`systemPassword`	The DBA password that AMPS uses when connecting to the `defaultDatabase` URL.
`systemUsername`	The DBA username that AMPS uses when connecting to the `defaultDatabase` URL.
`transactionSupport`	The transaction type, typically `LOCAL_TRANSACTION` or `XA_TRANSACTION`. Can be left blank.
`type`	The driver type, usually `java.sql.Driver` or `javax.sql.XADataSource`. Can be left blank.
`url`	The JDBC URL via which the product (not the DBA) connects to the database.
`username`	The username that the product (not the DBA) uses to connect to the database.
`validationQuery`	An 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>