Persistent State Data Storage
To persist process data, the persistent state engine writes entries to generic database tables. Generic in this context means that the database tables do not depend on the process class - any process will be mapped to the same tables.
These tables hold information about the state of the process instance and all instance data (persistent states, data and pending events). The lifecycle of the process instance is defined by the underlying state machine. This means, changes to the state of an instance are triggered by events.
Events in this context are completion events (triggered by an automatic state transition), signal events (triggered by a signal reception), and time events (triggered by a time trigger).
After having created a persistent state object representing the process instance, the object lives on the database until it reaches its final state (where it will be deleted).
To do all this, the persistent state engine needs a database. What database and configuration is used as per default, depends on the PAS environment you are using: Kubernetes or Docker/Integration (Bridge). The database model is automatically initialized upon start-up and updated if a new firmware version should require it.
You can change the default settings to the database setup that fits best with your technical requirements.
Kubernetes: MariaDB
Your PAS installation comes with a MariaDB deployment, which is used to store the process data in Kubernetes environment. This database is configured as a default external database for all services.
Upon first deployment of a service to a Kubernetes system, the following is done automatically:
A dedicated MariaDB database is created for this service, together with dedicated credentials.
The existing alias StateDB is changed to match with the newly created database (type, connection string, credentials).
The database attribute of the persistent state definitions is set to StateDB.
Do not change this automatically generated configuration.
In case you delete a service container with that default configuration, all stored process instance data will be deleted, too. In case you only start, stop or redeploy a service, the stored process data will remain intact.
Refer to Troubleshooting Kubernetes if you have got problems with your persistent state database setup for Kubernetes.
Docker/Integration (Bridge): SQLite
SQLite, an embedded, small footprint, relational database is provided with the base xUML Runtime firmware package. This database is the default database for Docker/Integration deployments.
With SQLite, a separate database file is kept in the home directory of the deployed service instance. The filename is pstate.db, and the command shell provided by the SQLite project can explore its contents. There are also several free or inexpensive visual management tools.
This setup implies that, in case you delete a service container, all stored process instance data will be gone.
In case you only start, stop or redeploy a service, the stored process data will remain intact.
SQLite as a persistent state database should only be used for development and testing.
For productive usage, we strongly recommend to set up an external database, as SQLite is not ready for heavy data load and high performance data handling, and you risk to lose data.
How to switch from SQLite
A database alias StateDB is generated to all services to make a switch to an external database easier. To switch to an external database (see Other Database Systems below):
Configure the StateDB alias.
Switch the persistent state database setting of your service to StateDB.
Refer to Adapting the Configuration of Containerized xUML Services (Docker) for more information on how to configure an xUML service.
Other Database Systems
The persistent state engine works with the following other RDBMS that is supported by the PAS platform:
MariaDB
Oracle
Microsoft SQL Server
MySQL
If you are hosting one of these RDBMS yourself, you can configure xUML services to use it instead of the default configuration.
You need to create a dedicated database user and an empty instance/schema for each service. The database then can be configured in the service configuration.
Now, the database model is automatically initialized on start-up, and updated if a new firmware version should require it. A modification of the database schema will be announced in the PAS release notes.
The major advantage of this approach is that backup, restore procedures and scaling mechanisms are delegated to the database management system. Additionally, any service that accesses the same state database can send signals to the same objects. This includes, for example, services that are sharing the same objects in load-balancing environment, e.g. Kubernetes.
Oracle
Using Oracle as a persistent state database has some advantages:
Database Locks
With shared databases, Oracle has a better performance because of a better locking implementation for the persistent state use case.
With Microsoft SQL Server, there may sometimes happen temporary deadlocks which decrease the performance.
Related Content
Related Pages: