Persistent State Databases

To save the process data, 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).

You can change the default settings to the database setup that fits best with your technical requirements.

Docker/Integration (Bridge): SQLite

SQLite, an embedded, small footprint, relational database is provided with the base xUML Runtime firmware package. The database model is automatically initialized upon start-up and updated if a new firmware version should require it.
This database is the default database for Docker/Integration deployments (see :local: scenario below).

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:

1. Configure the StateDB alias.

2. 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.

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.

The default MariaDB database configuration behaves the same way as SQLite:

In case you delete a service container that uses the default MariaDB configuration, all stored process instance data will be gone.

In opposition to SQLite, you can create a dedicated MariaDB database for your service (see Other Database Systems below). This then can be used in a configuration of distributed services that have access to the same persisted data, and can work on processes in parallel. In this case, the limitations mentioned above do not apply.

Service Deployment on Kubernetes

The local scenario is the default for new xUML services. Nevertheless, a database alias StateDB is generated to 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 switched from :local: to StateDB.

Refer to Troubleshooting Kubernetes if you have got problems with your persistent state database setup for Kubernetes.

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 and 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.

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.

Configuring the Persistent State Database

You can configure the database settings for each xUML service in the service configuration.

To filter for the persistent state settings, enter persistent state to the configuration filter.

Attribute	Description	Allowed Values / Example
Database	Define where the process data (persisted data, pending events, current states and more) are kept. Refer to Persistent State Data Storage for a detailed overview on the possibilities. On Kubernetes installations, memory and local behave more or less the same as volatile: On service startup, all data is lost.	:memory:	Kubernetes: more or less the same as volatile. On service startup, all data is lost.[1] Docker: The persistent state data is kept in memory. On service shutdown, data is written to a local SQLite database.[1]
		:local:	Kubernetes: more or less the same as volatile. On service startup, all data is lost.[1] Docker: The persistent state data is kept in a local SQLite database (default).[1]
		:volatile:	The persistent state data is kept in memory. On service shutdown, all data is lost.
		StateDB	The persistent state data is kept in an external database that can be configured via the alias StateDB.
Owner	Defines the owner name of the service. The persistent state objects are distinguished by an owner and owner id reflecting the actual service that owns these objects.	Idea_Management_Example
Worker Limit	Define the maximum number of parallel threads used to process pending events. Each active worker requires one license slot (concurrent connection) to process activities.	an integer number
		5	5 events can be processed in parallel (default).

External Database Settings

Via the Database attribute of the persistent state configuration, you can specify an external database. The configuration of this database can also be specified in the service configuration.

To filter for the persistent state settings, enter statedb to the configuration filter.

You can find a detailed explanation of all database settings in the SQL Adapter Reference.

Footnotes

[1]

Related Content