This is an automated email from the ASF dual-hosted git repository.
ricardozanini pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 35ccd491a kie-kogito-docs-554: Guide to help DB Admins to understand
Serverless Workflows persistence (#555)
35ccd491a is described below
commit 35ccd491a94a6e1b9b3cfeb7f81cfc7281213bf3
Author: Walter Medvedeo <[email protected]>
AuthorDate: Mon Mar 4 20:03:04 2024 +0100
kie-kogito-docs-554: Guide to help DB Admins to understand Serverless
Workflows persistence (#555)
---
.../persistence/Persistence-Configuration.drawio | 40 +++++++++++
.../persistence/Persistence-Configuration.png | Bin 0 -> 21329 bytes
.../persistence/Persistence-Core-Concepts.drawio | 73 +++++++++++++++++++
.../persistence/Persistence-Core-Concepts.png | Bin 0 -> 46237 bytes
.../Persistence-PostgreSQL-Advanced.drawio | 55 +++++++++++++++
.../Persistence-PostgreSQL-Advanced.png | Bin 0 -> 44415 bytes
serverlessworkflow/modules/ROOT/nav.adoc | 2 +
.../persistence/persistence-core-concepts.adoc | 44 ++++++++++++
.../persistence/persistence-with-postgresql.adoc | 32 ++++-----
.../persistence/postgresql-advanced-concepts.adoc | 78 +++++++++++++++++++++
10 files changed, 307 insertions(+), 17 deletions(-)
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Configuration.drawio
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Configuration.drawio
new file mode 100644
index 000000000..09b121c3b
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Configuration.drawio
@@ -0,0 +1,40 @@
+<mxfile host="Electron" modified="2024-02-19T11:23:51.234Z" agent="Mozilla/5.0
(X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/23.1.5
Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36"
etag="LNIzEL7fbCfWU6o_j4r4" version="23.1.5" type="device">
+ <diagram name="Page-1" id="JTKxfpPEzqUzuXzLvSPj">
+ <mxGraphModel dx="839" dy="384" grid="0" gridSize="10" guides="1"
tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1"
pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="EVICSTCxTQ7WN30AzL8C-1" value=""
style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="255" y="213" width="250" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="4hVNnn_8sVpHoIyQFyNl-3" value="Quarkus Workflow Project"
style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="250" y="73" width="250" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="4hVNnn_8sVpHoIyQFyNl-5" value="SonataFlow Persistence
Addon" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="250" y="158" width="250" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="4hVNnn_8sVpHoIyQFyNl-7" value="<pre
style="background-color: rgb(255, 255, 255); color: rgb(8, 8, 8);
font-family: &quot;JetBrains Mono&quot;,
monospace;"><br></pre>"
style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontSize=12;fontFamily=Helvetica;"
parent="1" vertex="1">
+ <mxGeometry x="779" y="560" width="20" height="50" as="geometry" />
+ </mxCell>
+ <mxCell id="4hVNnn_8sVpHoIyQFyNl-9" value=""
style="shape=cross;whiteSpace=wrap;html=1;fillColor=#33001A;strokeColor=#000000;gradientColor=default;"
parent="1" vertex="1">
+ <mxGeometry x="363" y="138" width="15" height="15" as="geometry" />
+ </mxCell>
+ <mxCell id="4hVNnn_8sVpHoIyQFyNl-12" value=""
style="shape=cross;whiteSpace=wrap;html=1;fillColor=#33001A;strokeColor=#000000;gradientColor=default;"
parent="1" vertex="1">
+ <mxGeometry x="363" y="185" width="15" height="15" as="geometry" />
+ </mxCell>
+ <mxCell id="4hVNnn_8sVpHoIyQFyNl-11" value="Other Quarkus Persistence
Extensions&nbsp;" style="rounded=1;whiteSpace=wrap;html=1;" parent="1"
vertex="1">
+ <mxGeometry x="250" y="207" width="250" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="ckIIAczoE2gYTY13vM26-1" value=""
style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="250" y="263" width="250" height="37" as="geometry" />
+ </mxCell>
+ <mxCell id="ckIIAczoE2gYTY13vM26-2" value=""
style="shape=cross;whiteSpace=wrap;html=1;fillColor=#33001A;strokeColor=#000000;gradientColor=default;"
parent="1" vertex="1">
+ <mxGeometry x="362" y="240" width="15" height="15" as="geometry" />
+ </mxCell>
+ <mxCell id="ckIIAczoE2gYTY13vM26-4" value="application.properties"
style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
parent="1" vertex="1">
+ <mxGeometry x="345" y="266.5" width="60" height="30" as="geometry" />
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Configuration.png
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Configuration.png
new file mode 100644
index 000000000..25a4ec24a
Binary files /dev/null and
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Configuration.png
differ
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Core-Concepts.drawio
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Core-Concepts.drawio
new file mode 100644
index 000000000..7db7a2ff5
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Core-Concepts.drawio
@@ -0,0 +1,73 @@
+<mxfile host="Electron" modified="2024-02-19T10:52:51.962Z" agent="Mozilla/5.0
(X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/23.1.5
Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36"
etag="rlLioUBu5FmjtyiYi71T" version="23.1.5" type="device">
+ <diagram name="Page-1" id="CsZ2FxxG6tZcgXgf0lRF">
+ <mxGraphModel dx="979" dy="529" grid="0" gridSize="10" guides="1"
tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1"
pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-2" value="Wait for an event state
reached" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="283" y="137" width="150" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-8" value=""
style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;"
parent="1" vertex="1">
+ <mxGeometry x="561" y="242" width="60" height="47" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-9" value=""
style="endArrow=classic;html=1;rounded=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;entryPerimeter=0;dashed=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;"
parent="1" source="QGvM4vl__vyeh6SA8aqo-2" target="QGvM4vl__vyeh6SA8aqo-8"
edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="548" y="117" as="sourcePoint" />
+ <mxPoint x="547.5" y="161" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="591" y="167" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-13" value=""
style="endArrow=classic;html=1;rounded=0;dashed=1;" parent="1" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="163" y="253" as="sourcePoint" />
+ <mxPoint x="274" y="253" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-14" value=""
style="endArrow=classic;html=1;rounded=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;dashed=1;"
parent="1" target="QGvM4vl__vyeh6SA8aqo-2" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="357.5" y="97" as="sourcePoint" />
+ <mxPoint x="357.5" y="151" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-15" value="<b><font
style="font-size: 14px;">2)</font></b> store workflow
snapshot&nbsp; in database"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
parent="1" vertex="1">
+ <mxGeometry x="446" y="137" width="230" height="24" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-18" value="Process the expected
event" style="rounded=1;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="283" y="240" width="150" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-21" value="Workflow instance"
style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="298" y="37" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-22" value="<font
style="font-size: 14px;"><b>3)</b></font>
expected event arrives"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
parent="1" vertex="1">
+ <mxGeometry x="131" y="220" width="175" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-24" value=""
style="endArrow=classic;html=1;rounded=0;dashed=1;" parent="1" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="550" y="284" as="sourcePoint" />
+ <mxPoint x="439" y="284" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-25" value="<b><font
style="font-size:
14px;">4)</font></b>&nbsp;retreive from
databae&nbsp;"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
parent="1" vertex="1">
+ <mxGeometry x="448" y="287" width="140" height="24" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-26" value="Workflow instance"
style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
+ <mxGeometry x="298" y="347" width="120" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-29" value=""
style="endArrow=classic;html=1;rounded=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;dashed=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;"
parent="1" source="QGvM4vl__vyeh6SA8aqo-18" edge="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="358.5" y="308" as="sourcePoint" />
+ <mxPoint x="359" y="348" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="QGvM4vl__vyeh6SA8aqo-31" value="<b><font
style="font-size: 14px;">5)</font></b>&nbsp;resume
workflow instance execution"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
parent="1" vertex="1">
+ <mxGeometry x="365" y="316" width="230" height="24" as="geometry" />
+ </mxCell>
+ <mxCell id="Z03DzwZWvSobYdzSOWjp-1" value="<b><font
style="font-size:
14px;">1)</font></b>&nbsp;executing workflow
instance&nbsp;"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
vertex="1" parent="1">
+ <mxGeometry x="366" y="100" width="184" height="24" as="geometry" />
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Core-Concepts.png
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Core-Concepts.png
new file mode 100644
index 000000000..393f16563
Binary files /dev/null and
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-Core-Concepts.png
differ
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-PostgreSQL-Advanced.drawio
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-PostgreSQL-Advanced.drawio
new file mode 100644
index 000000000..83f956c28
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-PostgreSQL-Advanced.drawio
@@ -0,0 +1,55 @@
+<mxfile host="Electron" modified="2024-02-28T15:06:49.359Z" agent="Mozilla/5.0
(X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/23.1.5
Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36"
etag="4Iq8t0b1lsZ31KtZ3L9S" version="23.1.5" type="device">
+ <diagram name="Page-1" id="ohW414weAMjfF7zPGFYP">
+ <mxGraphModel dx="979" dy="529" grid="0" gridSize="10" guides="1"
tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1"
pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="mPxZNNTQL4VJy8QZwQUN-29" value="process_instances"
style="swimlane;fontStyle=0;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;"
parent="1" vertex="1">
+ <mxGeometry x="195" y="246" width="140" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="mPxZNNTQL4VJy8QZwQUN-33" value="correlation_instances"
style="swimlane;fontStyle=0;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;"
parent="1" vertex="1">
+ <mxGeometry x="312.5" y="396" width="140" height="60" as="geometry"
/>
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-1" value="flyway_schema_history"
style="swimlane;fontStyle=0;childLayout=stackLayout;horizontal=1;startSize=30;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;"
vertex="1" parent="1">
+ <mxGeometry x="440" y="246" width="140" height="60" as="geometry" />
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-2" value="Workflows Runtime
Persistence PostgreSQL" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1"
parent="1">
+ <mxGeometry x="312.5" y="126" width="150" height="60" as="geometry"
/>
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-5" value=""
style="endArrow=classic;html=1;rounded=0;dashed=1;exitX=0;exitY=0.75;exitDx=0;exitDy=0;"
edge="1" parent="1" source="g4UiwubL2sIvR2kkYWUs-2">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="264.5" y="147" as="sourcePoint" />
+ <mxPoint x="265.5" y="246" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="265" y="171" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-6" value="workflow snapshots are
stored in<br>the process_instances table"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
vertex="1" parent="1">
+ <mxGeometry x="75" y="186" width="230" height="24" as="geometry" />
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-7" value=""
style="endArrow=classic;html=1;rounded=0;dashed=1;exitX=1;exitY=0.75;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;"
edge="1" parent="1" source="g4UiwubL2sIvR2kkYWUs-2"
target="g4UiwubL2sIvR2kkYWUs-1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="465" y="166" as="sourcePoint" />
+ <mxPoint x="510" y="241" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="510" y="171" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-8" value="flyway updates on the
database schema are registered in the flyway_schema_history table"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
vertex="1" parent="1">
+ <mxGeometry x="525" y="186" width="250" height="24" as="geometry" />
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-9" value=""
style="endArrow=classic;html=1;rounded=0;dashed=1;" edge="1" parent="1"
target="mPxZNNTQL4VJy8QZwQUN-33">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="382.15999999999997" y="186" as="sourcePoint" />
+ <mxPoint x="382.65999999999997" y="226" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="g4UiwubL2sIvR2kkYWUs-10" value="event correlations defned
in a workflow are stored in the correlation_instances table"
style="text;html=1;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;"
vertex="1" parent="1">
+ <mxGeometry x="465" y="406" width="300" height="24" as="geometry" />
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git
a/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-PostgreSQL-Advanced.png
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-PostgreSQL-Advanced.png
new file mode 100644
index 000000000..1d2ee5a82
Binary files /dev/null and
b/serverlessworkflow/modules/ROOT/assets/images/persistence/Persistence-PostgreSQL-Advanced.png
differ
diff --git a/serverlessworkflow/modules/ROOT/nav.adoc
b/serverlessworkflow/modules/ROOT/nav.adoc
index 4fff5c654..02313c8a9 100644
--- a/serverlessworkflow/modules/ROOT/nav.adoc
+++ b/serverlessworkflow/modules/ROOT/nav.adoc
@@ -96,7 +96,9 @@
****
xref:use-cases/advanced-developer-use-cases/deployments/deploying-on-kubernetes.adoc[Deploying
on Kubernetes]
****
xref:use-cases/advanced-developer-use-cases/deployments/deploying-on-openshift.adoc[Deploying
on OpenShift]
*** Persistence
+****
xref:use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc[]
****
xref:use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc[]
+****
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-advanced-concepts.adoc[]
****
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc[]
****
xref:use-cases/advanced-developer-use-cases/persistence/integration-tests-with-postgresql.adoc[]
*** Job Service
diff --git
a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc
new file mode 100644
index 000000000..d88596675
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc
@@ -0,0 +1,44 @@
+= Core Concepts
+:compat-mode!:
+// Metadata:
+:description: Running Quarkus Workflow Application using PostgresSQL
+:keywords: kogito, workflow, quarkus, serverless, quarkus-cli, persistence,
postgresql
+
+The {product_name} workflow runtime persistence is the mechanism to ensure
that your workflow instances remain consistent in the context of an error or a
runtime restart. For example, a pod restart, a programmed maintenance shutdown,
etc.
+
+Every workflow instance requires some status information and data to execute,
this information is automatically managed by the workflow's runtime and is
persisted at different moments of the workflow execution.
+
+For example, when a workflow instance reaches a state that needs to wait for
an event, the engine takes a snapshot of the most relevant information, stores
it in the database, and pauses that instance execution.
+In this way, resources like memory are released and can be used by other
executing instances.
+
+This snapshot contains the workflow id, the instance id and version, the
workflow data, and other relevant information required to resume that instance
execution when the expected event arrives.
+
+When the persistence is not configured, an in-memory repository is used,
making all this information volatile upon runtime restarts.
+And thus, if the workflow runtime is restarted while the workflow is waiting
for the event, and the event arrives at a later point in time, that instance
won't be resumed.
+
+image::persistence/Persistence-Core-Concepts.png[]
+
+[NOTE]
+====
+For non-testing or development environments, it's strongly recommended to
configure any of the available persistence mechanisms.
+====
+
+Finally, to configure the persistence for a given Quarkus Workflow Project you
must:
+
+1. Add the {product_name} persistence addon required for the database type of
your choice
+2. Add other quarkus database connectivity extensions that usually depends on
the selected database type
+3. Set the necessary configuration parameters in the `application.properties`
+
+image::persistence/Persistence-Configuration.png[]
+
+[[postgresql-persistence-additional-resources]]
+== Additional resources
+
+*
xref:use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc[{product_name}
Persistence with PostreSQL]
+*
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-advanced-concepts.adoc[Postgresql
Advanced Concepts]
+*
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc[PostgreSQL
Database Migration]
+*
xref:use-cases/advanced-developer-use-cases/persistence/integration-tests-with-postgresql.adoc[{product_name}
integration test using PostgreSQL]
+
+
+include::../../../_common-content/report-issue.adoc[]
+
diff --git
a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc
index efb8341c0..fa26f651f 100644
---
a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc
@@ -14,24 +14,19 @@
:postgresql_doc_url: https://www.postgresql.org/docs/current/
:flyway_url: https://flywaydb.org/
-This document describes how you can run your workflow application using
PostgreSQL persistence.
+The {product_name} PostgreSQL persistence is provided by the
`kogito-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
link:{quarkus_datasource_guide}[Quarkus Datasources].
-When your workflow execution requires `wait` states, then running your
workflow application with persistence enabled is a recommended approach.
+To see how to configure the PostgreSQL persistence, we recommend that follow
the `serverless-workflow-callback-quarkus` example application in the
link:{kogito_examples_repository_url}[GitHub repository], or apply the
<<#configuration_procedure, configuration procedure>> directly in your project.
-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 {product_name}, 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
link:{quarkus_datasource_guide}[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
-[source,shell]
+.Getting the serverless-workflow-callback-quarkus application
+. In a command terminal, clone the `kogito-examples` repository, navigate to
the cloned directory, and follow
link:{kogito_sw_examples_url}/serverless-workflow-callback-quarkus/README.md[these
steps]:
+[source, bash]
----
-git clone [email protected]:apache/incubator-kie-kogito-examples.git
+git clone https://github.com/apache/incubator-kie-kogito-examples.git
+
+cd
kogito-examples/serverless-workflow-examples/serverless-workflow-callback-quarkus
----
.Prerequisites
@@ -41,9 +36,10 @@
include::../../../../pages/_common-content/getting-started-requirement.adoc[]
[NOTE]
====
-This document relies on running PostgreSQL as a Docker service, even though
PostgreSQL installation is mentioned as a prerequisite.
+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.
====
+[#configuration_procedure]
.Procedure
. Add required dependencies to the `pom.xml` file of your project to use the
persistence add-on:
+
@@ -97,6 +93,7 @@
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/postgres
. Create PostgreSQL database schema.
+
+[#create-database-schema]
--
The persistence add-on uses link:{flyway_url}[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.
@@ -166,7 +163,8 @@ The following table serves as a quick reference of commonly
used persistence con
[[postgresql-persistence-additional-resources]]
== Additional resources
+*
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-advanced-concepts.adoc[Postgresql
Advanced Concepts]
+*
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc[PostgreSQL
Database Migration]
*
xref:use-cases/advanced-developer-use-cases/persistence/integration-tests-with-postgresql.adoc[{product_name}
integration test using PostgreSQL]
-*
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc[Migrating
Your PostgreSQL Database]
include::../../../../pages/_common-content/report-issue.adoc[]
\ No newline at end of file
diff --git
a/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/postgresql-advanced-concepts.adoc
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/postgresql-advanced-concepts.adoc
new file mode 100644
index 000000000..26ea3e24c
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/pages/use-cases/advanced-developer-use-cases/persistence/postgresql-advanced-concepts.adoc
@@ -0,0 +1,78 @@
+= Postgresql Advanced Concepts
+:compat-mode!:
+// Metadata:
+:description: Running Quarkus Workflow Application using PostgresSQL
+:keywords: kogito, workflow, quarkus, serverless, quarkus-cli, persistence,
postgresql
+:flyway_url: https://flywaydb.org/
+
+This document shows a detailed view of the database structure when you use the
PostgreSQL persistence.
+
+.Prerequisites
+* You are familiar with the
xref:use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc[Persistence
Core concepts] guide
+* You are familiar with the
xref:use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc[Persistence
with PostreSQL] guide
+
+As it was introduced in the
xref:use-cases/advanced-developer-use-cases/persistence/persistence-core-concepts.adoc[Persistence
Core concepts], every workflow instance requires some status information and
data to execute, this information is automatically managed by the workflow's
runtime. And is persisted at different moments of the workflow execution in the
form of a snapshot.
+
+In the following diagram you can see the tables that support these information:
+
+image::persistence/Persistence-PostgreSQL-Advanced.png[]
+
+[NOTE]
+====
+Regular backup procedures are not performed by the workflow's runtime
persistence, and thus, they must be provided by the installation owner.
+====
+
+== `process_instances`
+This table stores the workflow snapshots. These snapshots are stored in binary
format, and by default, are maintained in the database as long as the workflow
instance is active. When a workflow instance finalizes its execution, the
corresponding snapshot is removed from the database for optimization purposes.
+However, if you have installed the
xref:data-index/data-index-core-concepts.adoc[Data Index] service, information
about that workflow execution is kept by this service.
+
+[source, sql]
+----
+CREATE TABLE process_instances
+(
+ id character(36) NOT NULL,
+ payload bytea NOT NULL,
+ process_id character varying NOT NULL,
+ version bigint,
+ process_version character varying,
+ CONSTRAINT process_instances_pkey PRIMARY KEY (id)
+);
+CREATE INDEX idx_process_instances_process_id ON process_instances
(process_id, id, process_version);
+----
+
+== `correlation_instances`
+This table stores the information about the
xref:eventing/event-correlation-with-workflows.adoc[Event Correlations] defined
for a workflow.
+
+[source, sql]
+----
+CREATE TABLE correlation_instances
+(
+ id character(36) NOT NULL,
+ encoded_correlation_id character varying(36) NOT NULL UNIQUE,
+ correlated_id character varying(36) NOT NULL,
+ correlation json NOT NULL,
+ version bigint,
+ CONSTRAINT correlation_instances_pkey PRIMARY KEY (id)
+);
+CREATE INDEX idx_correlation_instances_encoded_id ON correlation_instances
(encoded_correlation_id);
+CREATE INDEX idx_correlation_instances_correlated_id ON correlation_instances
(correlated_id);
+----
+
+== `flyway_schema_history`
+If the link:{flyway_url}[Flyway] database schema generation was enabled for
the current workflow project, this table contains information about the schema
versions and the corresponding updates and that framework completely manages it.
+
+* To enable the Flyway managed database schema generation, you must follow
this
xref:use-cases/advanced-developer-use-cases/persistence/persistence-with-postgresql.adoc#create-database-schema[procedure].
+* To create the database schema manually, you must be sure that the following
application property `quarkus.flyway.migrate-at-start` is not configured, or is
set to `false`, and follow this
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc#manually-executing-scripts[procedure].
+
+[[postgresql-persistence-additional-resources]]
+== Additional resources
+
+*
xref:use-cases/advanced-developer-use-cases/persistence/postgresql-flyway-migration.adoc[PostgreSQL
Database Migration]
+*
xref:use-cases/advanced-developer-use-cases/persistence/integration-tests-with-postgresql.adoc[{product_name}
integration test using PostgreSQL]
+
+include::../../../_common-content/report-issue.adoc[]
+
+
+
+
+
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
