Running a Quarkus Workflow Application using PostgreSQL

The SonataFlow PostgreSQL persistence is provided by the kie-addons-quarkus-persistence-jdbc add-on, which is based on the Java Database Connectivity (JDBC). Additionally, it uses the Quarkus JDBC for PostgreSQL and Argoal Datasource extensions to connect with the database. And thus, it automatically inherits all the features of these extensions. For more information about Quarkus and JDBC, see Quarkus Datasources.

To see how to configure the PostgreSQL persistence, we recommend that follow the serverless-workflow-callback-quarkus example application in the GitHub repository, or apply the configuration procedure directly in your project.

Getting the serverless-workflow-callback-quarkus application

  1. In a command terminal, clone the incubator-kie-kogito-examples repository, navigate to the cloned directory, and follow these steps:

git clone https://github.com/apache/incubator-kie-kogito-examples.git

cd incubator-kie-kogito-examples/serverless-workflow-examples/serverless-workflow-callback-quarkus
Prerequisites

This document relies on running PostgreSQL as a Docker service, however, if you are not following the serverless-workflow-callback-quarkus example you can use your own PostgreSQL installation.
Procedure

  1. Add required dependencies to the pom.xml file of your project to use the persistence add-on:

    JDBC persistence add-on
    <dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-persistence-jdbc</artifactId>
</dependency>
    Quarkus JDBC PostgreSQL
    <dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>
    Quarkus Agroal data source
    <dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-agroal</artifactId>
</dependency>

  2. Add the following properties to the application.properties file of your project:

    Persistence property
    kogito.persistence.type=jdbc
    Quarkus properties
    quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=postgres
quarkus.datasource.password=pass
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/postgres

  3. Create PostgreSQL database schema.

    The persistence add-on uses Flyway to create the database schema. To enable the database schema creation during the runtime startup, you must set the following properties in the application.properties file.

    quarkus.flyway.migrate-at-start=true
quarkus.datasource.db-kind=postgresql

    You can find more details regarding the PostgreSQL database schema migration in the Flyway migration guide.

  4. Optional: To handle the concurrent requests to shared workflow instances, enable the persistence-enabled optimistic locking for concurrency control using the version field in the database.

    Add kogito.persistence.optimistic.lock=true property in the application.properties file of your project to enable the optimistic locking.

  5. Change the version in the workflow file.

    Example workflow file
    {
  "id": "applicantworkflow",
  "name": "Applicant Workflow",
  "version": "1.0"
}

    The versioning strategy is used to allow different workflow applications to run different versions of a process at the same time. The different versions of a process share the same database. This is useful when you migrate a process from one version to another. When allowing workflow instances to finish executing, a new version can be deployed using a new workflow application setup.

    By default, the engine considers the version specified in the workflow file as the current version of the asset. Therefore, you need to manually change the version in the workflow file, making the engine consider the specified version as a new version.

    As an alternative, you can set the kogito.workflow.version-strategy=project property in the application.properties file of your project. This enables the engine to consider the Maven or Gradle project version as the version of all workflows in the project. For instance, when you release a new version of your Maven project, the version in the workflow file is automatically updated.

Persistence configuration quick reference

The following table serves as a quick reference of commonly used persistence configuration properties supported in SonataFlow. You can define these properties in the application.properties file of your project.

Table 1. Persistence properties
Configuration property Type Default value

kogito.persistence.type

string

kogito.persistence.query.timeout.millis

long

10000

kogito.persistence.optimistic.lock

boolean

false

kogito.workflow.version-strategy

string

workflow

Additional resources

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!