Configure RDBMS in Helm chart

Camunda 8 Self-Managed supports using an external relational database (RDBMS) as the Orchestration Cluster's secondary storage instead of Elasticsearch or OpenSearch.

This page provides:

• Configuration reference: All Helm values organized by function.
• Quick example: Minimal YAML to get started.
• Links to detailed guides for specific tasks.

Related guides:

• Secondary storage architecture
• Secondary storage overview
• RDBMS example deployment
• JDBC driver management

Prerequisites

Provide a supported relational database that is reachable by the Camunda components.

See the RDBMS support policy for the complete list of supported databases and versions.

Ensure that:

• Your network allows traffic from Camunda pods to the database.
• Required JDBC parameters (SSL/TLS, authentication, failover) are configured as needed.
• The database user has permissions to create and modify schema objects if autoDDL is enabled.

For a short checklist and troubleshooting steps you can run after configuring the database, see validate RDBMS connectivity (Helm).

Configuration

Connection parameters (required)

Parameter	Type	Default	Description
orchestration.data.secondaryStorage.type	string	""	Must be rdbms to use a relational database.
orchestration.data.secondaryStorage.rdbms.url	string	""	JDBC connection URL for the database.
orchestration.data.secondaryStorage.rdbms.username	string	""	Username for database authentication.

Database credentials

Store the database password in a Kubernetes secret and reference it. For testing only, you can use inlineSecret.

Parameter	Type	Default	Description
orchestration.data.secondaryStorage.rdbms.secret.existingSecret	string	""	Name of Kubernetes secret containing the password.
orchestration.data.secondaryStorage.rdbms.secret.existingSecretKey	string	""	Key within the secret storing the password.
orchestration.data.secondaryStorage.rdbms.secret.inlineSecret	string	""	Password value (testing only, not production-safe).

Other parameters

RDBMS supports other configuration options that can be configured in the helm chart values.yaml via extraConfiguration. See RDBMS options.

For Liquibase lock recovery behavior, configure camunda.data.secondary-storage.rdbms.ddl-lock-wait-timeout (default: PT15M) via extraConfiguration if you need a longer wait time for heavy schema migrations.

Example usage

note

RDBMS is fully supported as secondary storage. For production planning, review the RDBMS support policy.

orchestration:
  exporters:
    camunda:
      enabled: false
    rdbms:
      enabled: true
  data:
    secondaryStorage:
      type: rdbms
      rdbms:
        url: jdbc:postgresql://hostname:5432/camunda
        username: camunda
        secret:
          existingSecret: camunda-db-secret
          existingSecretKey: password

Bundled vs. custom JDBC drivers

Camunda bundles JDBC drivers for some databases. For others, you must supply a custom driver. See RDBMS support policy for the complete list of supported databases.

See: JDBC driver management for:

• Which drivers are bundled
• When to supply custom drivers
• How to load drivers (init containers, custom images, volumes)

Search APIs and result limits

RDBMS search APIs return a totalResults field capped at 10,000 to improve performance. However, actual query performance depends on filter selectivity and database optimization.

See search APIs and result limits for configuration options, performance trade-offs, optimization best practices, and database-specific tuning.

Schema creation and management

Camunda automatically creates your database schema using Liquibase (when autoDDL: true). You can also manage the schema manually if required.

See: Schema management for:

• Automatic schema creation with autoDDL
• Database user permissions for each RDBMS type
• Manual schema management and DBA workflows
• Schema upgrades and verification

Troubleshooting and operations

For detailed troubleshooting of common issues and post-deployment operations, see RDBMS troubleshooting and operations, which covers:

• Connection failures and authentication errors
• JDBC driver loading issues
• Schema creation failures
• Slow data export and performance tuning
• TLS/SSL configuration
• Post-deployment operations (password rotation, driver updates, schema validation)

Verifying connectivity

After deployment, verify the Orchestration Cluster is writing to the database:

1. Confirm tables were created:

-- PostgreSQL example
SELECT table_name FROM information_schema.tables
WHERE table_schema = 'public';

2. Deploy a process and start an instance using Web Modeler.

3. Query the database to confirm the instance was recorded:

SELECT * FROM process_instances;

4. Review logs for successful initialization:

INFO  io.camunda.exporter.rdbms.RdbmsExporter - RdbmsExporter created with Configuration: flushInterval=PT0.5S
INFO  io.camunda.exporter.rdbms.RdbmsExporter - Exporter opened with last exported position

For a complete post-deployment checklist, see validate RDBMS connectivity (Helm).

Using AWS Aurora PostgreSQL (optional)

If you are using AWS Aurora PostgreSQL as your relational database, you can configure it the same way as a standard PostgreSQL instance.

Optionally, Camunda also supports the AWS JDBC wrapper driver, which provides additional features such as improved failover handling and IAM-based authentication.

For details and examples, see using AWS Aurora PostgreSQL with Camunda.

Limitations and unsupported scenarios

Component-specific RDBMS support

• Orchestration Cluster: ✅ Full RDBMS support for secondary storage (includes Zeebe, Operate, Tasklist, Orchestration Identity).
• Connectors: ✅ Supports RDBMS for process definitions and state.
• Web Modeler: ✅ RDBMS support available in 8.9.
• Optimize: ❌ Requires Elasticsearch or OpenSearch only. Optimize cannot use RDBMS.

If you deploy Optimize, you must still provision Elasticsearch or OpenSearch.

Multi-region deployments

Cross-region RDBMS deployments are not yet tested or supported in Camunda 8.9. Deploy RDBMS in the same region as your Kubernetes cluster.

Self-managed database HA

Camunda assumes your RDBMS handles its own HA (replication, failover). Use cloud-managed databases or vendor-specific HA solutions for production.

v1 API not supported

❌ v1 API not supported: Only the v2 Orchestration Cluster REST API works with RDBMS. See migrate to the Orchestration Cluster API.

Custom JDBC driver libraries

Only JDBC drivers from official vendor sources are supported. Custom or modified drivers may cause unexpected behavior.