This document will guide you through the installation and update of the Fluxnova database schema used by the process engine. Regardless of the architecture of your application setup, the process engine always requires this database schema. In a production environment, we recommend setting up this schema yourself and reference the prepared database instance in your application configuration. Consult the installation guide related to your setup to configure the database for a remote engine, shared engine, or embedded engine accordingly.

This guide will not detail how to set up an instance of your target database or how to create a schema object on it. Consult the documentation of your target database on how to do that. Fluxnova supports a variety of databases that are documented in the supported environments.

Fluxnova supports the following ways of installing the database schema:

• Use the database migration tool Liquibase with the provided changelogs for a semi-automatic installation and update. Liquibase keeps track of database schema changes. This allows you to focus on when changes should be applied rather than also on which changes are relevant. Alongside the existing camunda-changelog.xml, Fluxnova introduces fluxnova-changelog.xml:
  • fluxnova-changelog.xml (new): recommended for new installations and for databases already on Camunda 7.23 or any Fluxnova version. It starts from the Fluxnova 1.0 baseline and detects schema changes that are already applied.
  • camunda-changelog.xml (existing): continues to be shipped and supported. Use it for databases on Camunda versions older than 7.23, or if you already use it to manage your schema.
• Use the provided SQL scripts with the tools related to your database for a fully manual installation and update. A manual procedure allows you to fully control the SQL statements that are executed on your database instance and to adjust those statements to your needs if necessary.

Installation

You can either install your database schema using Liquibase or using the provided SQL scripts manually. You can switch between those mechanisms when updating your Fluxnova version at a later stage if desired. However, this might come with additional preparation work to work reliably. The update paragraph provides more details on this topic.

Liquibase installation

Fluxnova comes with two maintained changelog files that Liquibase can consume. These changelogs define which SQL statements to execute on a database. You can find the changelogs and their referenced resources on our Artifact Repository. Select the respective version ($PLATFORM_VERSION) and download the resources as a zip or tar.gz file. Open the fluxnova-sql-scripts-$PLATFORM_VERSION/liquibase folder to find the changelogs. In case you are using a pre-packaged distribution, the Liquibase resources already reside in the sql/liquibase folder of the distribution.

The liquibase folder contains the following resources:

• fluxnova-changelog.xml (new)
• camunda-changelog.xml (existing)
• fluxnova-baseline directory (new)
• fluxnova-upgrade directory (new)
• baseline directory

Liquibase uses these resources to install the schema. fluxnova-changelog.xml uses the fluxnova-baseline and fluxnova-upgrade directories. camunda-changelog.xml uses the baseline directory together with the scripts in the upgrade folder next to the liquibase folder.

Choosing a changelog

Fluxnova ships two Liquibase changelogs. Select the changelog based on the current state of your database:

Perform the following steps to install the database schema on your database instance:

1. Setup Liquibase, e.g. by downloading Liquibase CLI
2. Run Liquibase’s update command referencing the changelog selected in Choosing a changelog. For databases on Camunda versions older than 7.23, run the changelogSyncToTag step first. You can pass on the connection details to your database instance via parameters as described in the Liquibase documentation or create a properties file.

Liquibase creates two additional tables to keep track of the changes that have been applied to your database. The DATABASECHANGELOG table keeps track of all applied changes. The DATABASECHANGELOGLOCK table prevents conflicts from concurrent updates on your database instance by multiple Liquibase instances. You can read more about it in the Liquibase guide.

As you create the tables externally via Liquibase, you have to configure the engine to not create tables at startup as well. Set the databaseSchemaUpdate property to false (or, in case you are using Oracle, to noop). Consult the manual installation guide of your distribution for further information on how to achieve that.

Using a custom changelog

If your application manages its own database objects with Liquibase, you can use your own master changelog instead of referencing a Fluxnova changelog directly. To create the Fluxnova schema from scratch, your master changelog must include fluxnova-changelog.xml. Otherwise the Fluxnova tables are not created on an empty database. Include it before any changesets that reference Fluxnova tables:

<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.1.xsd">

<include file="org/finos/fluxnova/bpm/engine/db/liquibase/fluxnova-changelog.xml"/>
<include file="db/changelog/my-app-changes.xml"/>

</databaseChangeLog>

When upgrading to a newer Fluxnova version, update the Fluxnova resources. Your master changelog does not need to change, and Liquibase applies only the new Fluxnova changesets.

Liquibase with the Spring Boot Starter

The Fluxnova Spring Boot Starter integrates with Spring Boot’s Liquibase auto-configuration and brings the spring-boot-starter-liquibase dependency with it. Instead of running the Liquibase CLI, you can let the application apply the changelog on startup.

The starter applies the following defaults:

spring.liquibase.enabled=false
spring.liquibase.change-log=classpath:org/finos/fluxnova/bpm/engine/db/liquibase/fluxnova-changelog.xml

These defaults have the lowest precedence. Any value you set in application.properties/application.yml, environment variables, or command-line arguments overrides them.

To enable Liquibase, set:

spring.liquibase.enabled=true

To use a different changelog, for example camunda-changelog.xml for Camunda databases older than 7.23 or your own master changelog (see Using a custom changelog), also set:

spring.liquibase.change-log=classpath:org/finos/fluxnova/bpm/engine/db/liquibase/camunda-changelog.xml

When Liquibase is enabled, the starter sets the engine’s databaseSchemaUpdate to false and ignores fluxnova.bpm.database.schema-update, so the process engine does not create or update tables itself. When Liquibase is disabled, the engine uses fluxnova.bpm.database.schema-update as before.

Manual installation

To install the database schema required for Fluxnova, we provide a set of scripts with prepared DDL statements. Those scripts create all required tables and default indices. You can find the provided SQL scripts on our Artifact Repository. Select the respective version ($PLATFORM_VERSION) and download the scripts as a zip or tar.gz file. Open the fluxnova-sql-scripts-$PLATFORM_VERSION/create folder to find all available scripts. In case you are using a pre-packaged distribution, the SQL scripts already reside in the sql/create folder of the distribution.

The create folder contains the following SQL scripts:

• $DATABASENAME_engine_$PLATFORM_VERSION.sql
• $DATABASENAME_identity_$PLATFORM_VERSION.sql

There are individual SQL scripts for each supported database ($DATABASENAME). Select the appropriate scripts for your database and run them with your database administration tool (e.g., SqlDeveloper for Oracle).

As you create the tables manually, you have to configure the engine to not create tables at startup as well. Set the databaseSchemaUpdate property to false (or, in case you are using Oracle, to noop). Consult the manual installation guide of your distribution for further information on how to achieve that.

Update

Updating to a newer Fluxnova minor version also requires a database schema update. You can reuse all the options available for a schema installation here as well. If you are switching from one option to another, you might need to perform additional preparation work to update reliably. The individual sections on the mechanisms will provide details if necessary.

In case you are just updating to a newer patch level of your Fluxnova installation, a schema update might not be necessary. Section patch level update provides details on how this can be achieved depending on the mechanism you want to apply.

Liquibase update

This section assumes you are already set up with Liquibase as described in the installation section. In case you have not set up Liquibase itself yet and want to update a database that you manually installed and updated until now, please consult the migration section first.

Fluxnova comes with two maintained changelog files that Liquibase can consume. These changelogs help Liquibase to keep track of the changes that have been made to your database already. Based on the changelog and the tracking tables, Liquibase determines which changes it needs to apply when you instruct it to update your schema.

Perform the following steps to update the database schema on your database instance:

1. Select the respective version you want to update to ($Y) on our Artifact Repository and download the resources as a zip or tar.gz file. Open the fluxnova-sql-scripts-$Y/liquibase folder to find the changelog files. In case you are using a pre-packaged distribution, the Liquibase resources already reside in the sql/liquibase folder of the distribution with version $Y.

2. Run Liquibase’s update command referencing the changelog of version $Y that you already use for this database (fluxnova-changelog.xml or camunda-changelog.xml). Liquibase takes care of determining the necessary changes and applying them to your database according to the new changelog. You can pass on the connection details to your database instance via parameters as described in the Liquibase documentation or create a properties file.

3. We highly recommend updating to the latest patch version that is within the bounds of the new minor version you are updating to ($Y).

   Attention: This step is only relevant when you are using an enterprise version of Fluxnova, e.g., 7.16.X where X > 0.

Migrate to Liquibase

Liquibase provides workflows to update databases that were not set up using Liquibase from the very beginning. For such a scenario to work, you need to populate a tracking table that represents the current state of your database with regards to the changelog file you want to update against. In other words, you need to let Liquibase know which parts of the changelog your database already contains.

Perform the following steps to migrate your manual installation to Liquibase:

1. Setup Liquibase, e.g. by downloading Liquibase CLI

2. Identify your current database schema version. You can extract this information from the ACT_GE_SCHEMA_LOG table. Find the row with the highest value in the ID_ column and use the value of this row’s VERSION_ column.

3. Run Liquibase’s changelogSyncToTag command using your current database schema version as the tag:

   • Camunda 7.16 to 7.22: reference camunda-changelog.xml, e.g. with tag 7.21.0.
   • Camunda 7.23 or Fluxnova: this step is optional. fluxnova-changelog.xml detects the existing schema, so you can run the update command directly.

   You can pass on the connection details to your database instance via parameters as described in the Liquibase documentation or create a properties file.

Liquibase uses this information to create the tracking tables and mark all changesets until the tag you defined as executed. Liquibase determines if there are any changes that it needs to apply to your database for any subsequent update commands. You have migrated your manual installation to Liquibase.

Manual update

Updating from your current minor version ($X) to its follow-up version ($Y) requires updating the database schema as well. Follow the outlined procedure to perform this update:

1. Check for available database patch scripts for your database that are within the bounds of your update path. You can find the scripts on our Artifact Repository. Select the respective version you want to update to ($Y) and download the scripts as a zip or tar.gz file. Open the fluxnova-sql-scripts-$Y/upgrade folder to find all available scripts. In case you are using a pre-packaged distribution, the SQL scripts already reside in the sql/upgrade folder of the distribution with version $Y. We highly recommend executing these patches before updating. Execute those related to your database type ($DATABASENAME) in ascending order by version number. The naming pattern is $DATABASENAME_engine_$X_patch_*.sql.

2. Execute the corresponding update scripts named $DATABASENAME_engine_$X_to_$Y.sql. The scripts update the database from one minor version to the next and change the underlying database structure. So make sure to backup your database in case there are any failures during the update process.

3. We highly recommend checking for any existing patch scripts for your database that are within the bounds of the new minor version you are updating to ($Y). Execute them in ascending order by version number. The procedure is the same as in step 1, only for the new minor version.

   Attention: This step is only relevant when you are using an enterprise version of Fluxnova, e.g., 7.16.X where X > 0.

Patch level update

This section explains how to perform a patch-level update for your database schema. The patch level is the version number “after the second dot”. For example, update from 7.14.2 to 7.14.3.

Between patch levels, the structure of the database schema does not change. The database structure of all patch releases is backward compatible with the corresponding minor version. For example, the database schema of all 7.14.x versions are backward compatible with the 7.14.0 schema.

The one exception to this is a bug in the database schema itself. If you are affected by such a bug, you have the option to run a patch script. The following list contains all available patch scripts, information on what the fixes are related to, and a link to the corresponding Fluxnova Jira issue:

Liquibase patch level update

Fluxnova comes with two maintained changelog files that Liquibase can consume. These changelogs help Liquibase to keep track of the changes that have been made to your database already. Based on the changelog and the tracking tables, Liquibase determines which changes it needs to apply when instructing it to update your schema. Therefore, the procedure for patch-level updates is equivalent to that for minor version updates.

Manual patch level update

You can find the necessary scripts on our Artifact Repository. Select the respective patch version you want to update to ($Y) and download the scripts as a zip or tar.gz file. Open the fluxnova-sql-scripts-$Y/upgrade folder to find all available patch scripts. In case you are using a pre-packaged distribution, the SQL scripts reside in the sql/upgrade folder of the distribution you want to update to.

The patch scripts are named $DATABASENAME_engine_$MINOR_patch_$A_to_$B, with $A being the patch level version to update from, $B the patch level to update to, and $MINOR the minor version they are on, e.g., 7.16. If you do choose to apply a database patch, then you must apply all patch scripts that are within the bounds of your update path. This means if your current patch version is X.X.1 and you update to X.X.5 you have to execute all patch scripts first where $A ≥ X.X.1 and $B ≤ X.X.5.

Note: Some patches are provided for multiple versions. It is not required to execute them more than once. See the description of the patch version list for information on duplicate fixes.