Running a workflow service using PostgreSQL

This document describes how you can run your workflow application using PostgreSQL persistence.

When your workflow execution requires wait states, then running your workflow application with persistence enabled is a recommended approach.

For example, when a process reaches a callback or needs to wait for an event, then the execution of the process is paused and the engine takes a snapshot of the workflow data. The snapshot is persisted in the database as a binary format along with process metadata information. The process metadata information includes process ID, process instance ID, and process version.

Runtime persistence is used for storing data, which is required to resume the workflow execution of a process instance. Once a process is completed, the related data is removed from the database. This means that only required data to resume the execution is persisted.

In Kogito, you can enable persistence using add-ons. This document describes the use of the kogito-addons-quarkus-persistence-jdbc add-on, which is based on Java Database Connectivity (JDBC) along with PostgreSQL.

The kogito-addons-quarkus-persistence-jdbc add-on also extends on the Quarkus capabilities and you can use the available features directly from Quarkus JDBC support. For more information about Quarkus and JDBC, see Quarkus Datasources.

You can also see the serverless-workflow-callback-quarkus example application in GitHub repository. To execute the serverless-workflow-callback-quarkus example application, you can follow the instructions mentioned in the README file. To clone the kogito-example repository, use the following command:

Clone kogito-examples repository
git clone git@github.com:kiegroup/kogito-examples.git
Prerequisites

This document relies on running PostgreSQL as a Docker service, even though PostgreSQL installation is mentioned as a prerequisite.
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.kogito</groupId>
  <artifactId>kogito-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.

    Note that, the persistence add-on creates the required database schema structure by default. To disable the creation of database schema by default, you can set the kogito.persistence.auto.ddl property to false in application.properties file.

    If you want to manually create the database schema, you can use the DDL scripts. The DDL scripts are included in the kogito-ddl-1.29.0.Final-db-scripts.zip artifact.

  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 Serverless Workflow. 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.persistence.auto.ddl

boolean

true

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!