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 used for the memory and local scenarios (see Configuring the Persistent State Database 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.

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.

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.

For Docker/Integration (Bridge), SQLite is the default configuration. This configuration should only be used for development and testing, though.
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.

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:

• Workers
  A single xUML service can have several persistent state workers, that have their own database connection. All databases (with exception of SQLite) use connection pooling to manage the connections. Rare but possible deadlocks are circumvented by a retry mechanism.

• 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.	:memory:	The persistent state data is kept in memory. On service shutdown, data is written to a local SQLite database.
		:local:	The persistent state data is kept in a local SQLite database (default).
		: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.