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 Serverless Workflow, 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

This document relies on running PostgreSQL as a Docker service, even though PostgreSQL installation is mentioned as a prerequisite.

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

    JDBC persistence add-on
    Quarkus JDBC PostgreSQL
    Quarkus Agroal data source
  2. Add the following properties to the file of your project:

    Persistence property
    Quarkus properties
  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 file.


    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 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 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 Kogito Serverless Workflow. You can define these properties in the file of your project.

Table 1. Persistence properties
Configuration property Type Default value












Found an issue?

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