Skip to main content
Version: 8.9 (unreleased)

Configure secondary storage in Camunda 8 Run

Camunda 8 Run supports multiple secondary storage options. H2 is the default secondary storage for lightweight Camunda 8 Run setups and quickstarts. If you need full-text indexing, search, or advanced analytics, use an external Elasticsearch instance.

Configure or switch secondary storage (H2 or Elasticsearch)​

Choose the backend that fits your local development and testing needs.

Default: H2 (Camunda 8 Run)​

The default Camunda 8 Run configuration uses an H2 database for secondary storage. This is convenient for local development and demos and stores data on disk.

File-based H2 example:

data:
  secondary-storage:
    type: rdbms
    rdbms:
      url: jdbc:h2:file:./camunda-data/h2db
      username: sa
      password:
Full example configuration
camunda:
  data:
    secondary-storage:
      type: rdbms
      rdbms:
        url: jdbc:h2:file:./camunda-data/h2db
        username: sa
        password:
        flushInterval: PT0.5S
        queueSize: 1000
  security:
    initialization:
      users:
        - username: demo
          password: demo
          name: Demo
          email: demo@example.com
    authentication:
      method: BASIC
      unprotected-api: true
    authorizations:
      enabled: false

zeebe:
  broker:
    network:
      host: localhost
      advertisedHost: localhost
  gateway:
    cluster:
      initialContactPoints: zeebe:26502
      memberId: identity

spring:
  profiles:
    active: "broker,consolidated-auth,identity,tasklist"

External relational database options​

Use an external relational database for secondary storage: PostgreSQL, MariaDB, MySQL, Oracle, or Microsoft SQL Server.

  1. Set camunda.data.secondary-storage with the JDBC URL and credentials.
  2. Ensure the database is reachable before starting Camunda 8 Run.
  3. If you already run a database, reuse the same configuration and update the URL, host or port, and credentials.
  4. If a separate JDBC driver is required, add it with --extra-driver or drop the JAR into camunda-zeebe-<version>/lib.

Secondary storage config

camunda:
  data:
    secondary-storage:
      type: rdbms
      rdbms:
        url: jdbc:postgresql://localhost:5432/camunda_secondary
        username: camunda
        password: camunda

Start database (Docker)

docker run -d --name camunda-postgres \
  -e POSTGRES_USER=camunda \
  -e POSTGRES_PASSWORD=camunda \
  -e POSTGRES_DB=camunda_secondary \
  -p 5432:5432 postgres:latest

Optional: Elasticsearch​

If you need indexing, search, or full Operate or Tasklist functionality, use an external Elasticsearch instance.

To use Elasticsearch:

data:
  secondary-storage:
    type: elasticsearch
    elasticsearch:
      url: http://localhost:9200/

Start Camunda 8 Run with --config <file> and point the configuration to your external cluster.

Switching between storage types and migration notes​

  • Switching the secondary storage type, for example H2 to Elasticsearch, currently does not preserve existing secondary-store data. The system starts with a fresh secondary store.
  • If you upgrade from alpha1 or alpha2 and keep the same secondary storage backend, no migration steps are required.
  • To switch storage, update data.secondary-storage in application.yaml and restart Camunda 8 Run.

Choose H2 for quick local development and Elasticsearch for production-like scenarios where advanced search and analytics are required.

Operate limitations in 8.9​

Operate can run against the default H2 store, but some user-facing Operate features are intentionally limited:

  • Operate may not provide complete analytics, advanced search, or long-running query features when backed by H2.
  • Performance and scaling behavior when using H2 differs from Elasticsearch in production scenarios.
  • Users who require full Operate feature parity should use an external Elasticsearch instance until full H2 parity is confirmed.

Primary vs. secondary storage​

Camunda 8 uses two layers of storage:

  • Primary storage is handled by the Zeebe broker to store workflow execution data.
  • Secondary storage is used by applications like Operate, Tasklist, and Admin to read and present that data.

For more details on how these layers interact, see secondary storage architecture.

Camunda 8 Run uses v2 APIs by default, so no additional configuration is required when H2 becomes the default in a future release.

Known limitations​

  • Tasklist can use H2 through the v2 APIs. Operate support for H2 is under active development and may have limitations in current alpha versions.
  • H2 is intended for testing and local development only.
  • H2 data persists to the configured file path by default. Keep the path stable to avoid accidental data loss.
  • Performance and memory use may vary depending on the local environment.

Next steps​