Running a Quarkus Workflow Application 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 SonataFlow, 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:
kogito-examples
repositorygit clone git@github.com:kiegroup/kogito-examples.git
-
A workflow project is created.
For more information about creating a workflow project, see Creating your first Serverless Workflow service.
-
Docker is installed.
-
PostgreSQL is installed. For information about PostgreSQL installation and configuration, see PostgreSQL documentation.
This document relies on running PostgreSQL as a Docker service, even though PostgreSQL installation is mentioned as a prerequisite. |
-
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>
-
Add the following properties to the
application.properties
file of your project:Persistence propertykogito.persistence.type=jdbc
Quarkus propertiesquarkus.datasource.db-kind=postgresql quarkus.datasource.username=postgres quarkus.datasource.password=pass quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/postgres
-
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.
-
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 theapplication.properties
file of your project to enable the optimistic locking. -
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 theversion
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 theapplication.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.
Configuration property | Type | Default value |
---|---|---|
|
string |
|
|
long |
|
|
boolean |
|
|
string |
|
Found an issue?
If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!