Skip to content

feat(webmodeler): H2, MariaDB and MySQL configuration #7208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
+368 −92
Open

feat(webmodeler): H2, MariaDB and MySQL configuration #7208

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4992039
feat(webmodeler): H2, MariaDB and MySQL configuration
JacobiCamunda Oct 30, 2025
066fdf0
chore(webmodeler): incorporate review feedback
JacobiCamunda Nov 3, 2025
4fe6783
feat(webmodeler): incorporate review feedback
JacobiCamunda Nov 4, 2025
09582a2
Merge branch 'main' into web-modeler-add-h2-mariadb-mysql-configuration
JacobiCamunda Nov 4, 2025
020dce8
style(formatting): technical review
christinaausley Nov 4, 2025
6603857
resolve comments
christinaausley Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/reference/supported-environments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ Requirements for the components can be seen below:
| Optimize | OpenJDK 21+ | Elasticsearch 8.16+<br/>Amazon OpenSearch 2.17+ |
| Connectors | OpenJDK 21+ | |
| Management Identity | OpenJDK 17+ | Keycloak 25.x, 26.x<br/>PostgreSQL 14.x, 15.x, 16.x, 17.x, or Amazon Aurora PostgreSQL 13.x, 14.x, 15.x, 16.x, 17.x (required for [certain features](/self-managed/components/management-identity/miscellaneous/configuration-variables.md#database-configuration))<br/>Oracle 19c<br/>Microsoft SQL Server 2019 |
| Web Modeler | - | PostgreSQL 13.x, 14.x, 15.x, 16.x, 17.x, 18.x<br/>or Amazon Aurora PostgreSQL 13.x, 14.x, 15.x, 16.x, 17.x<br/>or Oracle 19c, 23ai<br/>or Microsoft SQL Server (MSSQL) 2019, 2022 |
| Web Modeler | - | PostgreSQL 13.x, 14.x, 15.x, 16.x, 17.x, 18.x<br/>or Amazon Aurora PostgreSQL 13.x, 14.x, 15.x, 16.x, 17.x<br/>or Oracle 19c, 23ai<br/>or Microsoft SQL Server (MSSQL) 2019, 2022<br/>or MariaDB 10.4, 11.4, 11.8<br/>or MySQL 8.4<br/>or H2 2.3 |
| Self-Managed Console | - | - |

When running Elasticsearch, you must have the [appropriate Elasticsearch privileges](/self-managed/concepts/elasticsearch-privileges.md).
Expand Down
11 changes: 4 additions & 7 deletions docs/self-managed/components/modeler/web-modeler/configuration/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,11 +72,11 @@ The available configuration options depend on the version of the cluster:

### Database

Web Modeler currently supports PostgreSQL, Oracle, and Microsoft SQL Server (MSSQL) as persistent data storage.
Web Modeler currently supports PostgreSQL, Oracle, Microsoft SQL Server (MSSQL), MySQL, MariaDB, and H2 as persistent data storage.

:::info Oracle driver
The Oracle driver is not provided by default and must be downloaded and supplied for the application to load.
Refer to the [Oracle database configuration section](database.md#oracle) for details.
:::info Oracle and MySQL driver
The Oracle and MySQL drivers are not provided by default and must be downloaded and supplied for the application to load.
Refer to the [Oracle](database.md#oracle) and [MySQL](database.md#mysql) database configuration section for details.
:::

| Environment variable | Description | Example value |
Expand All @@ -89,9 +89,6 @@ Refer to the [Oracle database configuration section](database.md#oracle) for det

Refer to the [Advanced Database Configuration Guide](./database.md) for additional details on how to configure Web Modeler's database connection.

Using a custom database schema via `SPRING_DATASOURCE_HIKARI_SCHEMA` is supported for PostgreSQL only. Oracle does not support custom schemas. MSSQL supports custom schemas, but this is not configurable in Web Modeler.
If you want to use a custom schema in MSSQL, you must set the default schema for the database user accordingly.

### SMTP / email

Web Modeler requires an SMTP server to send notification emails to users.
Expand Down
256 changes: 225 additions & 31 deletions docs/self-managed/components/modeler/web-modeler/configuration/database.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,16 +80,186 @@ instance, in addition to the adjustments described [above](#running-web-modeler-

## Using alternative database vendors

### Oracle
### H2

As the Oracle driver is not provided by default in each of the Camunda 8 distributions, you must download the driver and supply it for the application to load.
The H2 driver is provided by default, so no additional steps are necessary to provide the driver.

1. Download the appropriate Oracle driver: https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html.
To use a custom database driver, set `SPRING_DATASOURCE_DRIVER_CLASS_NAME` to the fully qualified class name of your driver. Otherwise, omit this variable.

<Tabs groupId="h2-config" defaultValue="envVars" queryString values={
[
{label: 'Environment variables', value: 'envVars' },
{label: 'values.yaml', value: 'valuesYaml' },
{label: 'application.yaml', value: 'applicationYaml' },
]}>

<TabItem value="envVars">
```sh
SPRING_DATASOURCE_URL="jdbc:h2:mem:[DB_NAME]" # Or any other connection mode (See https://www.h2database.com/html/features.html)
SPRING_DATASOURCE_USERNAME="[DB_USER]"
SPRING_DATASOURCE_PASSWORD="[DB_PASSWORD]"
SPRING_DATASOURCE_DRIVER_CLASS_NAME="[YOUR_CUSTOM_DRIVER]" # Optional; omit to use default H2 driver
```
</TabItem>
<TabItem value="valuesYaml">
```yaml
webModeler:
restapi:
externalDatabase:
enabled: true
url: "jdbc:h2:mem:[DB_NAME]" # Or any other connection mode (See https://www.h2database.com/html/features.html)
user: "[DB_USER]"
password: "[DB_PASSWORD]"
env:
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME # Optional; omit to use default H2 driver
value: "[YOUR_CUSTOM_DRIVER]"
```
</TabItem>
<TabItem value="applicationYaml">
```yaml
spring:
datasource:
url: jdbc:h2:mem:[DB_NAME] # Or any other connection mode (See https://www.h2database.com/html/features.html)
username: [DB_USER]
password: [DB_PASSWORD]
driver-class-name: [YOUR_CUSTOM_DRIVER] # Optional; omit to use default H2 driver
```
</TabItem>
</Tabs>

#### Custom schema

By default, H2 uses the `PUBLIC` schema. To use a different schema you can add an initialization command to the JDBC URL like the following:

```yml
jdbc:h2:mem:[DB_NAME];INIT=CREATE SCHEMA IF NOT EXISTS [CUSTOM_SCHEMA]\;SET SCHEMA [CUSTOM_SCHEMA]
```

### MariaDB

The MariaDB driver is provided by default, so no additional steps are necessary to provide the driver.

To use a custom database driver, set `SPRING_DATASOURCE_DRIVER_CLASS_NAME` to the fully qualified class name of your driver. Otherwise, omit this variable.

<Tabs groupId="mariadb-config" defaultValue="envVars" queryString values={
[
{label: 'Environment variables', value: 'envVars' },
{label: 'values.yaml', value: 'valuesYaml' },
{label: 'application.yaml', value: 'applicationYaml' },
]}>

<TabItem value="envVars">
```sh
SPRING_DATASOURCE_URL="jdbc:mariadb://[DB_HOST]:[DB_PORT]/[DB_NAME]"
SPRING_DATASOURCE_USERNAME="[DB_USER]"
SPRING_DATASOURCE_PASSWORD="[DB_PASSWORD]"
SPRING_DATASOURCE_DRIVER_CLASS_NAME="[YOUR_CUSTOM_DRIVER]" # Optional; omit to use default MariaDB driver
```
</TabItem>
<TabItem value="valuesYaml">
```yaml
webModeler:
restapi:
externalDatabase:
enabled: true
url: "jdbc:mariadb://[DB_HOST]:[DB_PORT]/[DB_NAME]"
user: "[DB_USER]"
password: "[DB_PASSWORD]"
env:
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME # Optional; omit to use default MariaDB driver
value: "[YOUR_CUSTOM_DRIVER]"
```
</TabItem>
<TabItem value="applicationYaml">
```yaml
spring:
datasource:
url: jdbc:mariadb://[DB_HOST]:[DB_PORT]/[DB_NAME]
username: [DB_USER]
password: [DB_PASSWORD]
driver-class-name: [YOUR_CUSTOM_DRIVER] # Optional; omit to use default MariaDB driver
```
</TabItem>
</Tabs>

#### Case sensitivity

MariaDB usually uses case-insensitive collations by default. To enable case sensitivity, set the database collation to a case-sensitive one like `utf8mb4_bin`.

Not doing so may lead to unexpected behavior.
The only known restriction currently is that extraction fields in [IDP extraction](../../../../../components/modeler/web-modeler/idp/idp-unstructured-extraction.md#extract-fields) will not be case-sensitive.
This means that if you have a field named `amount`, you can't create another field named `Amount` as the database will treat them as the same.

### MSSQL

The MSSQL driver is provided by default, so no additional steps are necessary to provide the driver.

To use a custom database driver, set `SPRING_DATASOURCE_DRIVER_CLASS_NAME` to the fully qualified class name of your driver. Otherwise, omit this variable.

<Tabs groupId="mssql-config" defaultValue="envVars" queryString values={
[
{label: 'Environment variables', value: 'envVars' },
{label: 'values.yaml', value: 'valuesYaml' },
{label: 'application.yaml', value: 'applicationYaml' },
]}>

<TabItem value="envVars">
```sh
SPRING_DATASOURCE_URL="jdbc:sqlserver://[DB_HOST]:[DB_PORT];databaseName=[DB_NAME]"
SPRING_DATASOURCE_USERNAME="[DB_USER]"
SPRING_DATASOURCE_PASSWORD="[DB_PASSWORD]"
SPRING_DATASOURCE_DRIVER_CLASS_NAME="[YOUR_CUSTOM_DRIVER]" # Optional; omit to use default MSSQL driver
```
</TabItem>
<TabItem value="valuesYaml">
```yaml
webModeler:
restapi:
externalDatabase:
enabled: true
url: "jdbc:sqlserver://[DB_HOST]:[DB_PORT];databaseName=[DB_NAME]"
user: "[DB_USER]"
password: "[DB_PASSWORD]"
env:
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME # Optional; omit to use default MSSQL driver
value: "[YOUR_CUSTOM_DRIVER]"
```
</TabItem>
<TabItem value="applicationYaml">
```yaml
spring:
datasource:
url: jdbc:sqlserver://[DB_HOST]:[DB_PORT];databaseName=[DB_NAME]
username: [DB_USER]
password: [DB_PASSWORD]
driver-class-name: [YOUR_CUSTOM_DRIVER] # Optional; omit to use default MSSQL driver
```
</TabItem>
</Tabs>

#### Case sensitivity

MSSQL is case-insensitive by default. To enable case sensitivity, set the database collation to a case-sensitive one like `Latin1_General_CS_AS`.

Not doing so may lead to unexpected behavior.
The only known restriction currently is that extraction fields in [IDP extraction](../../../../../components/modeler/web-modeler/idp/idp-unstructured-extraction.md#extract-fields) will not be case-sensitive.
This means that if you have a field named `amount`, you can't create another field named `Amount` as the database will treat them as the same.

#### Custom schema

MSSQL supports custom schemas, but this is not configurable in Web Modeler.
If you want to use a custom schema in MSSQL, you must set the default schema for the database user accordingly.

### MySQL

As the MySQL driver is not provided by default in each of the Camunda 8 distributions, you must download the driver and supply it for the application to load.

1. Download the appropriate (platform independent) MySQL driver: https://dev.mysql.com/downloads/connector/j/.
2. If you are using Docker or Kubernetes, ensure that the folder with the library is properly mounted as a volume at this location: `/driver-lib`. It will be automatically loaded by the application.

To use a custom database driver, set `SPRING_DATASOURCE_DRIVER_CLASS_NAME` to the fully qualified class name of your driver. Otherwise, omit this variable.

<Tabs groupId="oracle-config" defaultValue="envVars" queryString values={
<Tabs groupId="mysql-config" defaultValue="envVars" queryString values={
[
{label: 'Environment variables', value: 'envVars' },
{label: 'values.yaml', value: 'valuesYaml' },
Expand All @@ -98,10 +268,10 @@ To use a custom database driver, set `SPRING_DATASOURCE_DRIVER_CLASS_NAME` to th

<TabItem value="envVars">
```sh
SPRING_DATASOURCE_URL="jdbc:oracle:thin:@//[DB_HOST]:[DB_PORT]/[DB_NAME]"
SPRING_DATASOURCE_URL="jdbc:mysql://[DB_HOST]:[DB_PORT]/[DB_NAME]"
SPRING_DATASOURCE_USERNAME="[DB_USER]"
SPRING_DATASOURCE_PASSWORD="[DB_PASSWORD]"
SPRING_DATASOURCE_DRIVER_CLASS_NAME="[YOUR_CUSTOM_DRIVER]" # Optional; omit to use default Oracle driver
SPRING_DATASOURCE_DRIVER_CLASS_NAME="[YOUR_CUSTOM_DRIVER]" # Optional; omit to use default MySQL driver
```
</TabItem>
<TabItem value="valuesYaml">
Expand All @@ -110,17 +280,17 @@ webModeler:
restapi:
externalDatabase:
enabled: true
url: "jdbc:oracle:thin:@//[DB_HOST]:[DB_PORT]/[DB_NAME]"
url: "jdbc:mysql://[DB_HOST]:[DB_PORT]/[DB_NAME]"
user: "[DB_USER]"
password: "[DB_PASSWORD]"
env:
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME # Optional; omit to use default Oracle driver
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME # Optional; omit to use default MySQL driver
value: "[YOUR_CUSTOM_DRIVER]"
extraVolumeMounts:
- name: oracle-driver
- name: mysql-driver
mountPath: /driver-lib
extraVolumes:
- name: oracle-driver
- name: mysql-driver
emptyDir: {}
initContainers:
- name: fetch-jdbc-drivers
Expand All @@ -130,10 +300,10 @@ webModeler:
[
"sh",
"-c",
"wget https://download.oracle.com/otn-pub/otn_software/jdbc/237/ojdbc17.jar -O /driver-lib/ojdbc.jar",
"wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-9.5.0.tar.gz -O /driver-lib/mysql.tar.gz && tar -xzf /driver-lib/mysql.tar.gz -C /driver-lib --strip-components=1 && sh /docker-entrypoint.sh",
]
volumeMounts:
- name: oracle-driver
- name: mysql-driver
mountPath: /driver-lib
securityContext:
runAsUser: 1001
Expand All @@ -143,21 +313,32 @@ webModeler:
```yaml
spring:
datasource:
url: jdbc:oracle:thin:@//[DB_HOST]:[DB_PORT]/[DB_NAME]
url: jdbc:mysql://[DB_HOST]:[DB_PORT]/[DB_NAME]
username: [DB_USER]
password: [DB_PASSWORD]
driver-class-name: [YOUR_CUSTOM_DRIVER] # Optional; omit to use default Oracle driver
driver-class-name: [YOUR_CUSTOM_DRIVER] # Optional; omit to use default MySQL driver
```
</TabItem>
</Tabs>

### MSSQL
#### Case sensitivity

The MSSQL driver is provided by default, so no additional steps are necessary to provide the driver.
MySQL usually uses case-insensitive collations by default. To enable case sensitivity, set the database collation to a case-sensitive one like `utf8mb4_0900_as_cs`.

Not doing so may lead to unexpected behavior.
The only known restriction currently is that extraction fields in [IDP extraction](../../../../../components/modeler/web-modeler/idp/idp-unstructured-extraction.md#extract-fields) will not be case-sensitive.
This means that if you have a field named `amount`, you can't create another field named `Amount` as the database will treat them as the same.

### Oracle

As the Oracle driver is not provided by default in each of the Camunda 8 distributions, you must download the driver and supply it for the application to load.

1. Download the appropriate Oracle driver: https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html.
2. If you are using Docker or Kubernetes, ensure that the folder with the library is properly mounted as a volume at this location: `/driver-lib`. It will be automatically loaded by the application.

To use a custom database driver, set `SPRING_DATASOURCE_DRIVER_CLASS_NAME` to the fully qualified class name of your driver. Otherwise, omit this variable.

<Tabs groupId="mssql-config" defaultValue="envVars" queryString values={
<Tabs groupId="oracle-config" defaultValue="envVars" queryString values={
[
{label: 'Environment variables', value: 'envVars' },
{label: 'values.yaml', value: 'valuesYaml' },
Expand All @@ -166,10 +347,10 @@ To use a custom database driver, set `SPRING_DATASOURCE_DRIVER_CLASS_NAME` to th

<TabItem value="envVars">
```sh
SPRING_DATASOURCE_URL="jdbc:sqlserver://[DB_HOST]:[DB_PORT];databaseName=[DB_NAME]"
SPRING_DATASOURCE_URL="jdbc:oracle:thin:@//[DB_HOST]:[DB_PORT]/[DB_NAME]"
SPRING_DATASOURCE_USERNAME="[DB_USER]"
SPRING_DATASOURCE_PASSWORD="[DB_PASSWORD]"
SPRING_DATASOURCE_DRIVER_CLASS_NAME="[YOUR_CUSTOM_DRIVER]" # Optional; omit to use default MSSQL driver
SPRING_DATASOURCE_DRIVER_CLASS_NAME="[YOUR_CUSTOM_DRIVER]" # Optional; omit to use default Oracle driver
```
</TabItem>
<TabItem value="valuesYaml">
Expand All @@ -178,30 +359,43 @@ webModeler:
restapi:
externalDatabase:
enabled: true
url: "jdbc:sqlserver://[DB_HOST]:[DB_PORT];databaseName=[DB_NAME]"
url: "jdbc:oracle:thin:@//[DB_HOST]:[DB_PORT]/[DB_NAME]"
user: "[DB_USER]"
password: "[DB_PASSWORD]"
env:
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME # Optional; omit to use default MSSQL driver
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME # Optional; omit to use default Oracle driver
value: "[YOUR_CUSTOM_DRIVER]"
extraVolumeMounts:
- name: oracle-driver
mountPath: /driver-lib
extraVolumes:
- name: oracle-driver
emptyDir: {}
initContainers:
- name: fetch-jdbc-drivers
image: alpine:3.22.1
imagePullPolicy: "Always"
command:
[
"sh",
"-c",
"wget https://download.oracle.com/otn-pub/otn_software/jdbc/237/ojdbc17.jar -O /driver-lib/ojdbc.jar",
]
volumeMounts:
- name: oracle-driver
mountPath: /driver-lib
securityContext:
runAsUser: 1001
```
</TabItem>
<TabItem value="applicationYaml">
```yaml
spring:
datasource:
url: jdbc:sqlserver://[DB_HOST]:[DB_PORT];databaseName=[DB_NAME]
url: jdbc:oracle:thin:@//[DB_HOST]:[DB_PORT]/[DB_NAME]
username: [DB_USER]
password: [DB_PASSWORD]
driver-class-name: [YOUR_CUSTOM_DRIVER] # Optional; omit to use default MSSQL driver
driver-class-name: [YOUR_CUSTOM_DRIVER] # Optional; omit to use default Oracle driver
```
</TabItem>
</Tabs>

#### Case sensitivity

MSSQL is case-insensitive by default. To enable case sensitivity, set the database collation to a case-sensitive one. We recommend using `Latin1_General_CS_AS`.

Not doing so may lead to unexpected behavior.
The only known restriction currently is that extraction fields in [IDP extraction](../../../../../components/modeler/web-modeler/idp/idp-unstructured-extraction.md#extract-fields) will not be case-sensitive.
This means that if you have a field named `amount`, you can't create another field named `Amount` as the database will treat them as the same.
Loading