For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.9

Operations and maintenance for RDBMS manual installations

Operate and maintain RDBMS secondary storage for manual Camunda 8 installations (VM, bare metal, or standalone Java).

Backup and restore​

DBA owns backups using native RDBMS tools (pg_dump, mysqldump, RMAN, and similar). Camunda handles consistency.

  • Use vendor-recommended backup procedures.
  • Backup frequency depends on your RPO (Recovery Point Objective).
  • Database backups capture consistent state (Camunda flushes synchronously).
  • Zeebe exporter position is stored in RDBMS.

Restore procedure:

  1. Restore database from backup.
  2. Start Camunda pointing to restored database.
  3. Check logs for Liquibase completion and RdbmsExporter success.

Schema upgrades​

  1. Backup your database.
  2. Download scripts for target version: access SQL and Liquibase scripts.
  3. If using autoDDL (default): Liquibase runs on Zeebe startup.
  4. If using manual schema management: Apply scripts manually, then start new Camunda version.

Disabling automatic schema updates​

For strict change control environments:

export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_AUTO_DDL=false

DBA must apply schema changes manually using scripts. Zeebe fails to start if schema is out of date.

Verification and troubleshooting​

Success indicators​

Liquibase migration complete:

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

No errors in Liquibase logs means migration was successful.

RdbmsExporter running:

[INFO] io.camunda.exporter.rdbms.RdbmsExporter - [RDBMS Exporter] RdbmsExporter created with Configuration: flushInterval=PT0.5S, queueSize=1000
[INFO] io.camunda.exporter.rdbms.RdbmsExporter - [RDBMS Exporter] Exporter opened with last exported position 126

No errors in RdbmsExporter logs means the exporter is healthy. For more details about exported records, enable DEBUG log level.

Common failure modes​

SymptomRoot causeFix
SQLNonTransientConnectionException: Socket fail to connectInvalid URL or unreachable hostVerify JDBC URL format and hostname/port resolution
SQLInvalidAuthorizationSpecException: Access deniedWrong credentialsCheck username/password and database user permissions
Failed to load driver class oracle.jdbc.OracleDriverMissing JDBC driverVerify driver JAR in /driver-lib or classpath
Table 'camunda.EXPORTER_POSITION' doesn't existautoDDL=false on empty DBRun schema initialization scripts manually

All failure modes above prevent Camunda startup.

Auto-DDL behavior​

When started with auto-ddl=false on an empty database, the RdbmsExporter throws errors like:

### Error querying database. Cause: java.sql.SQLSyntaxErrorException: (conn=3) Table 'camunda.EXPORTER_POSITION' doesn't exist
### The error may exist in URL [jar:file:.../camunda-db-rdbms-8.9.0-SNAPSHOT.jar!/mapper/ExporterPositionMapper.xml]
### The error occurred while setting parameters
### SQL: SELECT PARTITION_ID, EXPORTER, LAST_EXPORTED_POSITION, CREATED, LAST_UPDATED FROM EXPORTER_POSITION WHERE PARTITION_ID = ?
### Cause: java.sql.SQLSyntaxErrorException: (conn=3) Table 'camunda.EXPORTER_POSITION' doesn't exist

Solution: Run schema initialization scripts manually using the bundled SQL or Liquibase scripts before starting Camunda.

Performance tuning​

Exporter batching​

# Lower flush interval = lower latency, more frequent writes
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_FLUSHINTERVAL=PT0.1S

# Higher queue size = higher throughput, more memory
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_QUEUESIZE=5000

Connection pooling​

Tune based on your workload. Camunda uses the Hikari connection pool following Spring Boot best practices:

export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_CONNECTION_POOL_MAXIMUM_POOL_SIZE=20
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_CONNECTION_POOL_MINIMUM_IDLE=10
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_CONNECTION_POOL_IDLE_TIMEOUT=600000
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_CONNECTION_POOL_MAX_LIFETIME=1800000
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_CONNECTION_POOL_CONNECTION_TIMEOUT=30000

Database tuning​

Consult your database vendor's guides:

  • PostgreSQL: Index tuning, autovacuum settings
  • Oracle: SGA size, parallel execution
  • MySQL/MariaDB: Buffer pool sizing
  • SQL Server: Memory configuration
  • AWS Aurora: Consult AWS RDS documentation for Aurora-specific tuning

Security​

TLS/SSL​

All RDBMS connections must use TLS in production:

# PostgreSQL
export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_URL="jdbc:postgresql://localhost:5432/camunda?sslmode=require"

# See [RDBMS Helm configuration](/self-managed/deployment/helm/configure/database/rdbms.md) for other databases

Secrets​

Never hardcode passwords. Use environment variable injection:

export CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_PASSWORD=$(cat /run/secrets/db_password)

Database permissions​

Create user with minimum required privileges:

-- PostgreSQL example
CREATE ROLE camunda LOGIN PASSWORD 'secure-password';
GRANT CONNECT ON DATABASE camunda TO camunda;
GRANT USAGE ON SCHEMA public TO camunda;
GRANT CREATE ON SCHEMA public TO camunda;

Avoid DROP, TRUNCATE, SUPERUSER, or other unnecessary privileges.

Production deployment​

Before deploying to production, review secondary storage architecture for backend trade-offs and the manual production architecture guide for recommended topology. Then use the verification steps in the troubleshooting section above to validate your RDBMS setup is healthy.

Next steps​