Skip to main content
Version: 8.9 (unreleased)

Configure RDBMS for manual installations

Configure RDBMS secondary storage drivers, connections, and initial schema for manual Camunda 8 installations (VM, bare metal, or standalone Java).

Prerequisites​

  • Supported RDBMS: See the RDBMS support policy.
  • JDBC drivers: PostgreSQL, MariaDB, SQL Server, and H2 are bundled. Oracle and MySQL must be user-supplied.
  • Java 21+: Required for Orchestration Cluster components (Zeebe, Operate, Tasklist). Management Identity remains Java 17+. See supported environments.
  • Database user: Needs DDL permissions (CREATE TABLE, ALTER TABLE, DROP TABLE) for schema initialization.

JDBC driver management​

Bundled drivers​

Camunda bundles these JDBC drivers for redistribution:

DatabaseDriver artifact
PostgreSQLorg.postgresql:postgresql
MariaDBorg.mariadb.jdbc:mariadb-java-client
Microsoft SQL Servercom.microsoft.sqlserver:mssql-jdbc
H2com.h2database:h2
AWS Aurora JDBCBundled

You can optionally supply your own version of any bundled driver for flexibility or compliance requirements.

User-supplied drivers (Oracle, MySQL)​

Recommended approach: Place drivers in /opt/camunda-drivers and set CLASSPATH:

export CLASSPATH="/opt/camunda-drivers/*:$CLASSPATH"
./camunda.sh

For Docker, mount external drivers using a volume. The driver JAR must be placed directly in the mounted directory (no subdirectories):

services:
  camunda:
    image: camunda/camunda-platform:8.9.0
    ports:
      - "8080:8080"
      - "26500:26500"
      - "9600:9600"
    environment:
      CAMUNDA_DATA_SECONDARY_STORAGE_TYPE: rdbms
      CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_URL: jdbc:mysql://mysql:3306/camunda
      CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_USERNAME: camunda
      CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_PASSWORD: demo
    volumes:
      - /path/to/driver-lib:/driver-lib

Database setup​

Step 1: Create database and user​

PostgreSQL example:

CREATE DATABASE camunda ENCODING 'UTF8';
CREATE USER camunda WITH PASSWORD 'your-secure-password';
GRANT CONNECT ON DATABASE camunda TO camunda;
GRANT USAGE ON SCHEMA public TO camunda;
GRANT CREATE ON DATABASE camunda TO camunda;

For other databases, see RDBMS Helm configuration.

Step 2: Configure connection​

Use the unified Camunda configuration properties:

export CAMUNDA_DATA_SECONDARY_STORAGE_TYPE=rdbms
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_URL="jdbc:postgresql://localhost:5432/camunda"
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_USERNAME="camunda"
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_PASSWORD="your-secure-password"

Step 3: Schema initialization​

By default, Liquibase automatically creates the schema on first startup. To manually manage schema:

export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_AUTO_DDL=false

Then apply SQL/Liquibase scripts manually using your DBA tools. See access SQL and Liquibase scripts.

Orchestration Cluster configuration​

The Orchestration Cluster uses a single RDBMS configuration shared across the orchestration services and the UIs that read from secondary storage.

Connection parameters​

All orchestration services and UIs share the same database connection:

export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_URL="jdbc:postgresql://localhost:5432/camunda"
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_USERNAME="camunda"
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_PASSWORD="your-secure-password"

Zeebe exporter configuration​

Configure Zeebe's exporter flush behavior:

export CAMUNDA_DATA_SNAPSHOTPERIOD=5m
export CAMUNDA_DATA_EXPORTERS_RDBMS_CLASSNAME=io.camunda.exporter.rdbms.RdbmsExporter
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_FLUSHINTERVAL=PT0.5S
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_QUEUESIZE=1000

Schema management​

Liquibase is the recommended approach for schema management. It is supported for the Orchestration Cluster and automatically applies migrations on startup (when auto-ddl=true, the default).

When Liquibase runs successfully, you'll see this log entry at INFO level:

[INFO] io.camunda.application.commons.rdbms.MyBatisConfiguration - Initializing Liquibase for RDBMS with global table trimmedPrefix ''.

Manual SQL execution​

Manual SQL execution is supported as an alternative. When using manual SQL:

  • You must strictly adhere to the bundled scripts in the order provided.
  • Camunda cannot guarantee future updates will work if you modify scripts.
  • This approach is useful when DBAs require strict control over database changes.

Download scripts: Access SQL and Liquibase scripts.

Next steps​