Skip to main content
Version: 8.9 (unreleased)

Schema creation and management

This page covers schema creation, upgrades, and management for RDBMS deployments. For configuration reference and troubleshooting, see configure RDBMS in Helm charts.

Related pages

Automatic schema creation (autoDDL)​

By default, autoDDL: true enables automatic schema creation via Liquibase. This happens at pod startup:

  1. Liquibase detects that the schema does not exist or is outdated.
  2. Liquibase executes all SQL migrations to initialize the schema.
  3. The exporter begins writing data.

Prerequisites for autoDDL:

For all databases, the database user must have CREATE TABLE, ALTER TABLE, and DROP TABLE permissions.

Additional database-specific requirements:

  • PostgreSQL: CREATE permission on the database.
  • Oracle: CREATE TABLE and TABLESPACE (if using non-default tablespaces).
  • SQL Server: CREATE TABLE, ALTER TABLE, and CONTROL on the schema.
  • MariaDB/MySQL: ALL PRIVILEGES on the target database.

Database user permissions​

PostgreSQL​

CREATE ROLE camunda WITH LOGIN PASSWORD 'password';
GRANT CONNECT ON DATABASE camunda TO camunda;
GRANT USAGE ON SCHEMA public TO camunda;
GRANT CREATE ON DATABASE camunda TO camunda;

Oracle​

CREATE USER camunda IDENTIFIED BY password;
GRANT CREATE TABLE TO camunda;
GRANT UNLIMITED TABLESPACE TO camunda;

MariaDB/MySQL​

CREATE USER camunda@'%' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON camunda.* TO camunda@'%';
FLUSH PRIVILEGES;

SQL Server​

CREATE LOGIN camunda WITH PASSWORD = 'password';
CREATE USER camunda FOR LOGIN camunda;
GRANT CREATE TABLE TO camunda;
GRANT ALTER ON SCHEMA::dbo TO camunda;

Manual schema management​

If your database is managed by a dedicated DBA, disable autoDDL and manage schema updates manually:

orchestration:
  data:
    secondaryStorage:
      type: rdbms
      rdbms:
        autoDDL: false

With autoDDL: false, you must:

  1. Apply SQL scripts to the database before deploying Camunda.
  2. SQL scripts are available in the Camunda release bundle or from the Liquibase scripts page.

When to use manual schema management​

  • Your organization requires a separate schema deployment phase.
  • A dedicated DBA manages the database and DDL changes.
  • You need to validate schema changes before applying them to production.

Schema verification​

After initial deployment or upgrade, verify the schema:

-- PostgreSQL: Check tables exist
SELECT table_name FROM information_schema.tables
WHERE table_schema = 'public';

-- MySQL/MariaDB: Check tables exist
SELECT table_name FROM information_schema.tables
WHERE table_schema = DATABASE();

-- Oracle: Check tables
SELECT table_name FROM user_tables;

-- SQL Server: Check tables
SELECT table_name FROM information_schema.tables
WHERE table_schema = 'dbo';

Expected tables include workflow and history tables (for example, process_instance, variable, and job) and Liquibase metadata tables like databasechangelog and databasechangeloglock.

You can also verify by checking logs:

kubectl logs <pod-name> | grep -i liquibase

Success indicators:

INFO  io.camunda.application.commons.rdbms.MyBatisConfiguration - Initializing Liquibase for RDBMS
INFO  org.springframework.web.servlet.DispatcherServlet - Completed initialization in X ms

Upgrading the schema​

When upgrading Camunda versions:

Step 1: Backup your database​

Backup your database before upgrading. Use your database vendor's native tools:

Step 2: Test the upgrade in staging​

Deploy the new Camunda version in a staging environment first to validate schema migrations.

For large production clusters, scale down to avoid connection pool exhaustion during migration:

kubectl scale deployment camunda-orchestration --replicas=0 -n camunda

Step 4: Deploy the new Camunda version​

helm upgrade camunda camunda/camunda-platform --version X.Y.Z -f values.yaml -n camunda

Liquibase will automatically apply new migrations if autoDDL: true.

Step 5: Scale back up​

kubectl scale deployment camunda-orchestration --replicas=3 -n camunda

Monitor the rollout:

kubectl rollout status deployment/camunda-orchestration -n camunda

Step 6: Verify schema initialization​

Verify that Liquibase completed the schema migration successfully by checking logs:

kubectl logs <pod-name> | grep -i liquibase

Look for "Liquibase: Update successful" or similar completion messages. If the migration fails, Liquibase will log the specific error.

You can also verify schema initialization by checking the databasechangelog table:

-- Verify Liquibase changelog table exists and contains entries
SELECT COUNT(*) FROM databasechangelog;

This table should exist and contain entries for a fresh Camunda 8.9 installation. On upgrades, this number increases as new changesets are applied.

For troubleshooting, see schema troubleshooting.

Schema troubleshooting​

Liquibase lock issues​

If a previous schema migration failed, Liquibase may hold a lock:

-- PostgreSQL/MariaDB: Release the lock
DELETE FROM databasechangeloglock WHERE locked = true;

-- Oracle: Connect as schema owner and release
DELETE FROM databasechangeloglock WHERE locked = 1;

Then redeploy.

Permission errors during autoDDL​

Symptom: Logs show "permission denied" or "cannot create table."

Fix: Verify database user has DDL permissions (see Database user permissions above).

Out-of-sync schema​

If your schema doesn't match the expected version:

  1. Check Liquibase logs for failed migrations.
  2. Restore from backup if necessary.
  3. Manually apply missing SQL scripts from the Liquibase scripts page.

Liquibase resource access​

SQL migration scripts and Liquibase change logs are available in the Camunda release bundle. For details on accessing these resources, see access SQL and Liquibase scripts.