kie-kogito-docs-554: Guide to help DB Admins to understand Serverless Workflows persistence

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="&lt;pre style=&quot;background-color: rgb(255, 255, 255); color: rgb(8, 8, 8); font-family: &amp;quot;JetBrains Mono&amp;quot;, monospace;&quot;&gt;&lt;br&gt;&lt;/pre&gt;" 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&amp;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>

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="&lt;b&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;2)&lt;/font&gt;&lt;/b&gt; store workflow snapshot&amp;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="&lt;font style=&quot;font-size: 14px;&quot;&gt;&lt;b&gt;3)&lt;/b&gt;&lt;/font&gt; 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="&lt;b&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;4)&lt;/font&gt;&lt;/b&gt;&amp;nbsp;retreive from databae&amp;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="&lt;b&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;5)&lt;/font&gt;&lt;/b&gt;&amp;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="&lt;b&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;1)&lt;/font&gt;&lt;/b&gt;&amp;nbsp;executing workflow instance&amp;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>

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&lt;br&gt;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>

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

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 SonataFlow workflows 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[]
+