End-to-end RDBMS setup guide

This guide provides a unified approach to configuring relational databases for Camunda 8 across the Orchestration Cluster (Zeebe, Operate, Tasklist, Identity) and Web Modeler. It answers the key setup questions and links to detailed, component-specific configuration reference.

info

• For Orchestration Cluster configuration reference, see RDBMS configuration overview.
• For Web Modeler configuration reference, see Web Modeler database configuration.
• For supported vendors and versions, see the RDBMS version support policy.
• For deployment-specific setup, see Helm RDBMS configuration or manual RDBMS configuration.

Step 1: Decide on topology

Before provisioning, choose whether to use a shared database or separate databases for each component.

Aspect	Shared database	Separate databases
Use case	Small deployments, unified DBA team	Large production, multi-team environments
Setup	Single instance with different schemas/databases for OC and Web Modeler	Independent instances per component
Pros	Simplified administration, single backup policy	Independent scaling, isolated credentials, easier troubleshooting
Cons	Shared resources, requires schema/database separation	Additional operational overhead, higher infrastructure costs

Both topologies are fully supported. Choose based on your organizational model and scaling needs.

Step 2: Provision the database

Prerequisites

• Supported RDBMS: PostgreSQL (recommended), MariaDB, MySQL, SQL Server, Oracle, or H2 (development only).
• Versions: See the RDBMS version support policy.
• Network and credentials: Ensure reachable database and user with DDL permissions (CREATE TABLE, ALTER TABLE) for schema initialization.
• SSL/TLS: Optional but recommended. See Web Modeler SSL configuration for guidance on JDBC URL parameters.

Create database and user

Choose your topology (shared or separate) and database vendor:

PostgreSQL

-- Shared topology: single database for both OC and Web Modeler
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;

-- Separate topology: independent instances
-- CREATE DATABASE camunda_oc ENCODING 'UTF8';
-- CREATE USER camunda_oc WITH PASSWORD 'oc-password';
-- GRANT CONNECT ON DATABASE camunda_oc TO camunda_oc;
-- GRANT USAGE ON SCHEMA public TO camunda_oc;
-- GRANT CREATE ON DATABASE camunda_oc TO camunda_oc;

MySQL / MariaDB

-- Shared topology
CREATE DATABASE camunda CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER camunda@'%' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON camunda.* TO camunda@'%';
FLUSH PRIVILEGES;

-- Separate topology: repeat with different database and user names

SQL Server / Oracle

For SQL Server and Oracle, follow your database vendor's user provisioning guidelines. The user must have CREATE TABLE and ALTER permissions. Consult your DBA and the detailed setup guides linked below.

Step 3: Configure connections and authentication

Configuration is component-specific but follows consistent principles across OC and Web Modeler.

Orchestration Cluster connection

Helm

In your values.yaml:

orchestration:
  data:
    secondaryStorage:
      type: rdbms
      rdbms:
        url: jdbc:postgresql://postgres.example.com:5432/camunda_oc
        username: camunda_oc
        secret:
          existingSecret: rdbms-credentials
          existingSecretKey: password

For full Helm reference, see RDBMS configuration in Helm.

Manual

Set environment variables before starting the Orchestration Cluster:

export CAMUNDA_DATA_SECONDARY_STORAGE_TYPE=rdbms
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_URL="jdbc:postgresql://postgres.example.com:5432/camunda_oc"
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_USERNAME="camunda_oc"
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_PASSWORD="your-secure-password"

For full manual setup, see RDBMS configuration for manual installations.

Web Modeler connection

Web Modeler uses Spring Boot datasource configuration (separate from Orchestration Cluster).

Helm

In your values.yaml:

webModeler:
  restapi:
    externalDatabase:
      enabled: true
      url: jdbc:postgresql://postgres.example.com:5432/camunda_wm
      username: camunda_wm
      secret:
        inlineSecret: your-secure-password
      # Or use existingSecret for production

For full Web Modeler reference, see Web Modeler database configuration.

Manual

Set environment variables before starting Web Modeler:

export SPRING_DATASOURCE_URL="jdbc:postgresql://postgres.example.com:5432/camunda_wm"
export SPRING_DATASOURCE_USERNAME="camunda_wm"
export SPRING_DATASOURCE_PASSWORD="your-secure-password"

Secrets management

For production, use a secrets store (Kubernetes Secrets, Vault, AWS Secrets Manager) instead of inline passwords.

Kubernetes Secrets example:

kubectl create secret generic rdbms-credentials \
  --from-literal=user=camunda_oc \
  --from-literal=password=your-very-secure-password

Then reference it in values.yaml:

orchestration:
  data:
    secondaryStorage:
      rdbms:
        secret:
          existingSecret: rdbms-credentials
          existingSecretKey: password

Aurora IAM authentication

If using Amazon Aurora PostgreSQL, configure IAM database authentication for enhanced security (no stored passwords).

Orchestration Cluster (Helm):

orchestration:
  data:
    secondaryStorage:
      type: rdbms
      rdbms:
        url: "jdbc:postgresql://aurora-cluster.123456789012.us-east-1.rds.amazonaws.com:5432/camunda?sslmode=require"
        username: db_user # IAM database user
        # No password needed; IAM token generated at runtime
        # Requires IAM role attached to pod (IRSA or Karpenter)

Web Modeler (Helm):

webModeler:
  restapi:
    externalDatabase:
      enabled: true
      url: "jdbc:aws-wrapper:postgresql://aurora-cluster.123456789012.us-east-1.rds.amazonaws.com:5432/camunda?wrapperPlugins=iam"
      username: db_user # IAM database user
      # No password needed; IAM token generated at runtime

For detailed Aurora setup, see Orchestration Cluster RDBMS configuration and Web Modeler configuration.

Step 4: JDBC driver management

Camunda bundles JDBC drivers for PostgreSQL, MariaDB, SQL Server, and H2. You must provide a user-supplied driver for Oracle and MySQL.

For detailed driver provisioning strategies (init containers, custom images, volume mounts), see:

• Helm: JDBC driver management in Helm
• Manual: Manual installation driver setup
• Web Modeler: Web Modeler database configuration

Step 5: Schema management

Orchestration Cluster uses Liquibase → automatically creates and updates schema on startup (configurable via autoDDL: true/false).

Web Modeler uses Flyway → migrations applied automatically on startup; manual DBA execution not supported.

This is the key difference: Orchestration Cluster schema can be managed manually by a DBA if preferred, while Web Modeler schema is automatic only.

For access to SQL/Liquibase scripts or manual DBA procedures, see Access SQL and Liquibase scripts.

Step 6: Validation

Orchestration Cluster checklist

1. Confirm the RDBMS exporter is enabled.
2. Check logs for Liquibase initialization:
   [INFO] io.camunda.application.commons.rdbms.MyBatisConfiguration - Initializing Liquibase for RDBMS
3. Verify database schema was initialized. See access SQL and Liquibase scripts for the complete table list for your database platform.
4. Run RDBMS validation tests.

Web Modeler checklist

1. Confirm the database connection is configured.
2. Check logs for Flyway schema initialization.
3. Verify database contains tables (Flyway creates these automatically on startup).
4. Test the health endpoint: /health.

Common issues

Issue	Resolution
Schema not created	Grant CREATE TABLE, ALTER TABLE permissions to the database user.
Connection timeout	Check firewall rules, security groups, and VPC peering. Verify network connectivity.
TLS/SSL error	Verify database certificate and adjust JDBC SSL mode parameters. See component-specific configuration pages for details.
Driver not found	Load user-supplied drivers via init container, custom image, or volume mount.

For detailed troubleshooting, see:

• RDBMS troubleshooting
• Web Modeler database troubleshooting

Step 7: Backup and restore

Both components require RDBMS backups:

• Orchestration Cluster: Zeebe exports data to RDBMS; backups are DBA responsibility.
• Web Modeler: All data stored in RDBMS; backups are DBA responsibility.

Use vendor-native tools: PostgreSQL (pg_dump), MariaDB/MySQL (mysqldump), SQL Server (native backup), Oracle (RMAN).

Test restore procedures in non-production environments regularly.

Related guides

• Secondary storage overview
• Install with RDBMS as secondary storage
• Operations and maintenance