Review docs if we are clear enough about the limits of H2

[christinaausley]

Review and clarify H2 database limitations in documentation

Background

H2 is the default secondary storage for Camunda 8 Run and lightweight Self-Managed installations (8.9-alpha3+). It is intended only for development, testing, and evaluation, and is not suitable for production use.

Current documentation does not clearly explain how H2 behaves in Helm-based deployments, particularly when multiple brokers are started by default. This can result in clusters that appear valid but return incomplete or inconsistent results.

Current state

H2 limitations are referenced across multiple pages, but without consistent emphasis or operational clarity.

• JDBC driver management: Development and testing only; not recommended for production
• RDBMS support policy: Supported for development, testing, and evaluation only
• Configuring secondary storage: Not recommended for production workloads
• Helm quick install – Orchestration Cluster only: Starts three brokers by default, each using a separate file-based H2 database, without explaining the implications

Observed issue

A Helm installation using the default three brokers with H2 results in three independent databases, one per broker. Queries are routed only to the broker handling a given partition, leading to incomplete or inconsistent results such as missing user tasks.

Engineering confirmed this is not a valid setup. H2 is intended only for use with a single broker and a single partition. Multi-broker clusters require a shared external RDBMS such as PostgreSQL.

Issues to address

• Ensure consistent messaging that H2 is non-production only
• Explicitly document that H2 does not support multi-broker clusters
• Clarify concrete limitations:
  • No shared database across brokers
  • Broker-local query results only
  • Limited concurrency and scalability
  • File-based persistence only
• Add prominent warnings on pages that include H2 configuration examples
• Update Helm quick-install guidance to either:
  • Use a single broker when H2 is selected, or
  • Clearly warn that the default multi-broker setup is invalid with H2
• Add a brief note on the secondary storage overview explaining H2 as a default convenience option rather than a reference architecture

Open questions

1. Which H2 limitations must be explicitly documented?
2. Should there be a short, dedicated H2 limitations section?
3. Should Helm quick install enforce brokers: 1 when H2 is used?
4. Do we need warning or migration guidance for users currently using H2?