Database Schema

  • ACTRE*: RE stands for repository. Tables with this prefix contain ‘static’ information such as process definitions and process resources (images, rules, etc.).
  • ACTRU*: RU stands for runtime. These are the runtime tables that contain the runtime data of process instances, user tasks, variables, jobs, etc. The engine only stores the runtime data during process instance execution and removes the records when a process instance ends. This keeps the runtime tables small and fast.
  • ACTID*: ID stands for identity. These tables contain identity information such as users, groups, etc.
  • ACTHI*: HI stands for history. These are the tables that contain historical data such as past process instances, variables, tasks, etc.
  • ACTGE*: General data, which is used in various use cases.
    The main tables of the process engines are the entities of process definitions, executions, tasks, variables andevent subscriptions. Their relationship is shown in the following UML model.

The table contains all deployed process definitions. Itincludes information like the version details, the resource name or thesuspension state.

Executions (ACT_RU_EXECUTION)

The ACT_RU_EXECUTION table contains all current executions. It includesinformation like the process definition, parent execution, business key, thecurrent activity and different metadata about the state of the execution.

Tasks (ACT_RU_TASK)

The ACT_RU_TASK table contains all open tasks of all running processinstances. It includes information like the corresponding process instance,execution and also metadata such as creation time, assignee or due date.

Variables (ACT_RU_VARIABLE)

The ACT_RU_VARIABLE table contains all currently set process or taskvariables. It includes the names, types and values of the variables andinformation about the corresponding process instance or task.

Event Subscriptions (ACT_RU_EVENT_SUBSCR)

The ACT_RU_EVENT_SUBSCR table contains all currently existing eventsubscriptions. It includes the type, name and configuration of the expectedevent along with information about the corresponding process instance andexecution.

Entity Relationship Diagrams

The database is not part of the public API. The database schema may change for MINOR and MAJOR version updates.

Please note: The following diagrams are based on the MySQL database schema. For other databases the diagram may be slightly different.

The following Entity Relationship Diagrams visualize the database tables and their explicit foreign key constraints, grouped by Engine with focus on BPMN, Engine with focus on DMN, Engine with focus on CMMN, the Engine History and the Identity. Please note that the diagrams do not visualize implicit connections between the tables.

Database - 图1

Engine DMN

Engine CMMN

Database - 图2

History

To allow different configurations and to keep the tables more flexible, the history tables contain no foreign key constraints.

Identity

Database Configuration

There are two ways to configure the database that the Camunda engine will use. The first option is to define the JDBC properties of the database:

  • jdbcUrl: JDBC URL of the database.
  • jdbcDriver: implementation of the driver for the specific database type.
  • jdbcUsername: username to connect to the database.
  • jdbcPassword: password to connect to the database.
    Note that the engine uses internally for persistence.

The data source that is constructed based on the provided JDBC properties will have the default MyBatis connection pool settings. The following attributes can optionally be set to tweak that connection pool (taken from the MyBatis documentation):

  • jdbcMaxActiveConnections: The maximum number of active connections that the connection pool can contain at any given time. Default is 10.
  • jdbcMaxIdleConnections: The maximum number of idle connections that the connection pool can contain at any given time.
  • jdbcMaxCheckoutTime: The amount of time in milliseconds that a connection can be ‘checked out’ for from the connection pool before it is forcefully returned. Default is 20000 (20 seconds).
  • jdbcMaxWaitTime: This is a low level setting that gives the pool a chance to print a log status and re-attempt the acquisition of a connection in the case that it takes unusually long (to avoid failing silently forever if the pool is misconfigured). Default is 20000 (20 seconds).
  • jdbcStatementTimeout: The amount of time in seconds the JDBC driver will wait for a response from the database. Default is null which means that there is no timeout.

Another configuration - jdbcBatchProcessing - sets if batch processing mode must be used when sending SQL statements to the database. When switched off, statements are executed one by one.Values: true (default), false.

Known issues with batch processing:

  • when using batch processing on MariaDB and DB2, jdbcStatementTimeout is being ignored.

    Example database configuration

Alternatively, a javax.sql.DataSource implementation can be used (e.g., DBCP from Apache Commons):

  1. <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" >
  2.   <property name="driverClassName" value="com.mysql.jdbc.Driver" />
  3.   <property name="url" value="jdbc:mysql://localhost:3306/camunda" />
  4.   <property name="username" value="camunda" />
  5.   <property name="password" value="camunda" />
  6.   <property name="defaultAutoCommit" value="false" />
  7. </bean>
  9. <bean id="processEngineConfiguration" class="org.camunda.bpm.engine.impl.cfg.StandaloneProcessEngineConfiguration">
  11.     <property name="dataSource" ref="dataSource" />
  12.     ...

Note that Camunda does not ship with a library that allows to define such a data source. So you have to make sure that the libraries (e.g., from DBCP) are on your classpath.

The following properties can be set, regardless of whether you are using the JDBC or data source approach:

  • databaseType: It’s normally not necessary to specify this property as it is automatically analyzed from the database connection meta data. Should only be specified in case automatic detection fails. Possible values: {h2, mysql, oracle, postgres, mssql, db2, mariadb}. This setting will determine which create/drop scripts and queries will be used. See the ‘supported databases’ section for an overview of which types are supported.
  • databaseSchemaUpdate: Allows to set the strategy to handle the database schema on process engine boot and shutdown.
    • true (default): Upon building the process engine, a check is performed whether the Camunda tables exist in the database. If they don’t exist, they are created. It must be ensured that the version of the DB schema matches the version of the process engine library, unless performing a . Updates of the database schema have to be done manually as described in the Update and Migration Guide.
    • false: Does not perform any checks and assumes that the Camunda table exist in the database. It must be ensured that the version of the DB schema matches the version of the process engine library, unless performing a . Updates of the database schema have to be done manually as described in the Update and Migration Guide.
    • create-drop: Creates the schema when the process engine is being created and drops the schema when the process engine is being closed.

Supported Databases

For information on supported databases please refer to

Here are some sample JDBC urls:

  • H2: jdbc:h2:tcp://localhost/camunda
  • MySQL: jdbc//localhost:3306/camunda?autoReconnect=true
  • Oracle: jdbc:oracle:thin:@localhostxe
  • PostgreSQL: jdbc:postgresql://localhost:5432/camunda
  • DB2: jdbc//localhost:50000/camunda
  • MSSQL: jdbc:sqlserver://localhost:1433/camunda
  • MariaDB: jdbc//localhost:3306/camunda

    Additional Database Schema Configuration

Since the release of Camunda BPM 7.0.0-alpha9, the unique constraint for the business key is removed in the runtime and history tables and the database schema create and drop scripts.If you rely on the constraint, you can add it manually to your schema by issuing following sql statements:

DB2

  1. Runtime:
  2. alter table ACT_RU_EXECUTION add UNI_BUSINESS_KEY varchar (255) not null generated always as (case when "BUSINESS_KEY_" is null then "ID_" else "BUSINESS_KEY_" end);
  3. alter table ACT_RU_EXECUTION add UNI_PROC_DEF_ID varchar (64) not null generated always as (case when "PROC_DEF_ID_" is null then "ID_" else "PROC_DEF_ID_" end);
  4. create unique index ACT_UNIQ_RU_BUS_KEY on ACT_RU_EXECUTION(UNI_PROC_DEF_ID, UNI_BUSINESS_KEY);
  7. alter table ACT_HI_PROCINST add UNI_BUSINESS_KEY varchar (255) not null generated always as (case when "BUSINESS_KEY_" is null then "ID_" else "BUSINESS_KEY_" end);
  8. alter table ACT_HI_PROCINST add UNI_PROC_DEF_ID varchar (64) not null generated always as (case when "PROC_DEF_ID_" is null then "ID_" else "PROC_DEF_ID_" end);
  9. create unique index ACT_UNIQ_HI_BUS_KEY on ACT_HI_PROCINST(UNI_PROC_DEF_ID, UNI_BUSINESS_KEY);

H2

  1. Runtime:
  2. alter table ACT_RU_EXECUTION add constraint ACT_UNIQ_RU_BUS_KEY unique(PROC_DEF_ID_, BUSINESS_KEY_);
  4. History:
  5. alter table ACT_HI_PROCINST add constraint ACT_UNIQ_HI_BUS_KEY unique(PROC_DEF_ID_, BUSINESS_KEY_);

MSSQL

MySQL

  1. alter table ACT_RU_EXECUTION add constraint ACT_UNIQ_RU_BUS_KEY UNIQUE (PROC_DEF_ID_, BUSINESS_KEY_);
  3. History:
  4. alter table ACT_HI_PROCINST add constraint ACT_UNIQ_HI_BUS_KEY UNIQUE (PROC_DEF_ID_, BUSINESS_KEY_);
  1. Runtime:
  2. create unique index ACT_UNIQ_RU_BUS_KEY on ACT_RU_EXECUTION
  3.          (case when BUSINESS_KEY_ is null then null else PROC_DEF_ID_ end,
  4.          case when BUSINESS_KEY_ is null then null else BUSINESS_KEY_ end);
  6. History:
  7. create unique index ACT_UNIQ_HI_BUS_KEY on ACT_HI_PROCINST
  8.          (case when BUSINESS_KEY_ is null then null else PROC_DEF_ID_ end,
  9.          case when BUSINESS_KEY_ is null then null else BUSINESS_KEY_ end);

PostgreSQL

  1. Runtime:
  2. alter table ACT_RU_EXECUTION add constraint ACT_UNIQ_RU_BUS_KEY UNIQUE (PROC_DEF_ID_, BUSINESS_KEY_);
  5. alter table ACT_HI_PROCINST add constraint ACT_UNIQ_HI_BUS_KEY UNIQUE (PROC_DEF_ID_, BUSINESS_KEY_);

Isolation Level Configuration

Most database management systems provide four different isolation levels to be set. For instance the levels defined by ANSI/USO SQL are (from low to high isolation):

  • READ UNCOMMITTED
  • READ COMMITTED
  • REPEATABLE READS
  • SERIALIZABLE
    The required isolation level to run Camunda with is READ COMMITTED, which may have a different name according to your database system. Setting the level to REPEATABLE READS is known to cause deadlocks, so one needs to be careful, when changing the isolation level.

Configuration for Microsoft SQL Server

Microsoft SQL Server implements the isolation level READ_COMMITTED differentthan most databases and does not interact well with the process engine’s scheme.As a result you may suffer deadlocks when putting the process engine under high load.

If you experience deadlocks in your MSSQL installation, you must execute thefollowing statements in order to enable SNAPSHOT isolation:

where [process-engine] contains the name of your database.

This section documents the supported Galera Cluster configuration for MariaDB. Both server and client need to be configured correctly. Please note that there are some known limitations which apply when using Galera cluster, see below.

Warning

Please note that server and client configuration settings defined below are the only configuration that is supported for Galera Cluster. Other configurations are not supported.

The following configuration needs to go into the [galera] configuration section in the my.cnf.d/server.cnf on each server:

  1. [galera]
  2. binlog_format=row
  3. default_storage_engine=InnoDB
  4. innodb_autoinc_lock_mode=2
  5. transaction-isolation=READ-COMMITTED
  6. wsrep_on=ON
  7. wsrep_causal_reads = 1
  8. wsrep_sync_wait = 7
  9. ...

Note that other setting may be present in this section but the settings transaction-isolation, wsrep_on, wsrep_causal_reads and wsrep_sync_wait need to present and need to have exactly the values shown above.

Client Configuration

Only failover and sequential configurations are supported. Other client configuration modes like replication:, loadbalance:, aurora: are not supported.

The following is the required format of the jdbcUrl property in datasource configurations:

  1. jdbc:mariadb:[failover|sequential]://[host1:port],[host2:port],.../[data-base-name]

Examples:

  1. jdbc:mariadb:failover://192.168.1.1:32980,192.168.1.2:32980,192.168.1.3:32980/process-engine

Important: when running Camunda in a cluster, the client configuration needs to be the same on each node.

The following known limitations apply when using Galera Cluster:

  • APIs requiring Pessimistic read locks in the database do not work correctly. Affected APIs: Exclusive Message correlation (.correlateExclusively()). See ().Another possible negative effects:
    • duplication of deployed definitions when deploying the same resources from two threads simultaneously
    • duplication of history cleanup job when calling HistoryService#cleanUpHistoryAsync from two threads simultaneously
  • Duplicate checking during deployment does not work if resources are deployed in a cluster concurrently. Concrete impact: suppose there is a Camunda process engine cluster which connects to the same Galera cluster. On deployment of a new process application the process engine nodes will check if the BPMN processes provided by the process application are already deployed, to avoid duplicate deployments. If the deployment is done simultaneously on multiple process engine nodes an exclusive read lock is acquired on the the database (technically, this means that each node performs an SQL select for update query.), to do the duplicate checking reliably under concurrency. This does not work on Galera Cluster and may lead to multiple versions of the same process being deployed.
  • The jdbcStatementTimeout configuration setting does not work and cannot be used.