Databases

Relational databases are used, among others, by Replication and the Database-based identity provider In order to access the databases, JDBC drivers suitable for your database system must first be installed.

Only after the driver installation do you create a database connection. See Backend Connections of type data_source

Driver installation

If you want to access database systems from different manufacturers, carry out the driver installation steps for each database type.

The driver installation causes the Karaf to restart various bundles. This also includes the BPC Backend Core Bundle (bpc-be-core). As the user sessions are stored transiently in this bundle, they are lost after the restart and the users must log in again.

It is recommended that the database drivers are installed via the central configuration file In this case, you can perform a Karaf update without having to carry out a new configuration. Only the database driver needs to be provided in the new Karaf. In this case, you can ignore the following points.

If the driver is available for different Java versions (e.g. for MSSQL), it is not necessary to configure the database driver.E.g. for MSSQL), then use the Java 21 version.

Oracle

Option: Latest driver
- An Internet connection is required to automatically download the latest driver
- Open the Karaf console and execute the following command: feature:install pax-jdbc-oracle
Option: Specific version of the driver
- Download the JDBC driver for your Oracle version: Download
- Copy the JDBC driver (e.g. ojdbc8.jar) to the folder INSTALLATIONSVERZEICHNIS/karaf/deploy
- Open the Karaf console and execute the following command: feature:install pax-jdbc-oracle

For Oracle database configurations, see Oracle database.

Microsoft SQL Server (MSSQL)

Option: Relatively current driver
- An Internet connection is required to automatically download the driver
- Open the Karaf console and execute the following command: feature:install pax-jdbc-mssql
Option: Specific version of the driver (offline)
- Download the JDBC driver for your MSSQL version: Download
- Copy the JDBC driver (e.g. mssql-jdbc-11.2.3.jre11.jar) to the folder INSTALLATIONSVERZEICHNIS/karaf/deploy
- It is not necessary to execute the command here: feature:install pax-jdbc-mssql
Option: Specific version of the driver (online)
- An Internet connection is required to automatically download the driver
- Open the Karaf console and execute the following command: bundle:install -s mvn:com.microsoft.sqlserver/mssql-jdbc/13.2.0.jre11
- It is not necessary to execute the command: feature:install pax-jdbc-mssql

Please note that the internal driver name for MSSQL is not constant across the different versions. This means that you may have to adapt the specified driver name to existing Backend Connections if the driver is changed.

MariaDB

Option: Relatively current driver
- An Internet connection is required to automatically download the driver
- Open the Karaf console and execute the following command:
  feature:install pax-jdbc-mariadb
Option: Specific version of the driver
- Download the JDBC driver for your MariaDB version: Download
- Copy the JDBC driver (e.g. mariadb-java-client-3.5.7.jar) to the folder INSTALLATIONSVERZEICHNIS/karaf/deploy
- Open the Karaf console and execute the following command:
  feature:install pax-jdbc-mariadb

MySQL

Option: Relatively current driver
- An Internet connection is required to automatically download the driver
- An installed MariaDB driver must be uninstalled beforehand. Open the Karaf console and execute the following command:
  feature:uninstall pax-jdbc-mariadb
- Find out the pax-jdbc version of your installation. To do this, execute the following in the Karaf console:
  feature:repo-list | grep pax.jdbc
- Now execute the following commands in the Karaf console and, if necessary, adjust the version: + - Now execute the following commands in the Karaf console and, if necessary, adjust the version if necessary, adjust the version:
  feature:repo-add mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.5.7/xml/features-gpl feature:install pax-jdbc-mysql
  If the relatively current driver e.g. 8.3.0 is not current enough and e.g. 8.4.0 must be used. Then first load this version and copy it into the folder INSTALLATIONSVERZEICHNIS/karaf/deploy. Then carry out the steps from above. If the JDBC driver has a major version change, use the next option.
Option: New major version of the driver

If the JDBC driver of the first option listed is not current enough (e.g. 8.3.0) and the JDBC driver to be used must be a new major version (e.g. 9.5.0). Then the pax-jdbc-mysql jar file must be patched.
- If the JDBC driver of the first option listed is not current enough (e.g. 8.3.0) and the JDBC driver to be used must be a new major version (e.g. 9.5.0) An installed MariaDB driver must be uninstalled beforehand. Open the Karaf console and execute the following command:
  feature:uninstall pax-jdbc-mariadb
- Find out the pax-jdbc version of your installation. To do this, execute the following in the Karaf console:
  feature:info pax-jdbc
- Execute the following commands in a shell to load and unpack the jar archive and, if necessary, adjust the version: + - Execute the following commands in a shell to load and unpack the jar archive. adjust the version:
  mkdir pax-jdbc-mysql-patch cd pax-jdbc-mysql-patch wget https://repo1.maven.org/maven2/org/ops4j/pax/jdbc/pax-jdbc-mysql/1.5.7/pax-jdbc-mysql-1.5.7.jar jar xf pax-jdbc-mysql-1.5.7.jar rm pax-jdbc-mysql-1.5.7.jar
- Use a text editor in META-INF/MANIFEST.MF to increase the existing from/to version ranges, e.g. [8.3,9) to [8.3,10). [8.3,9) specifies that only MySQL JDBC drivers from version 8.3.0 to version 9.0.0 can be used. We increase this by changing to 10.0.0. This means that driver version 9.5.0 can also be used.
- Create the jar file with the changes Create the jar file with the changes
  jar cfM pax-jdbc-mysql-1.5.7.jar .
- Copy the pax-jdbc-mysql-1.5.7.jar into the folder INSTALLATIONSVERZEICHNIS/karaf/deploy
Option: Specific version of the driver (offline)
- Download the JDBC driver for your MySQL version (Platform Independent): Download
- Copy the JDBC driver (e.g. mysql-connector-j-9.5.0.jar) to the folder INSTALLATIONSVERZEICHNIS/karaf/deploy
- Open the Karaf console and execute the following command:
  feature:install pax-jdbc-spec
- Make sure that the additional configuration of the Database connection the value for "xa" is set to "false" and that the driver name com.mysql.cj-native is used.
Option: Specific version of the driver (online)
- An Internet connection is required to automatically download the driver
- Open the Karaf console and execute the following commands:
  bundle:install -s mvn:com.mysql/mysql-connector-j/9.5.0 feature:install pax-jdbc-spec
- Ensure that the value for is set to for the additional configuration of the database connection Database connection the value for "xa" is set to "false" and that the driver name com.mysql.cj-native is used.

PostgreSQL

No driver installation is required
Open the Karaf console and execute the following command: feature:install pax-jdbc-postgresql

Check in case of problems

Driver in the right place?

Make sure that the appropriate JDBC driver can be found in the directory INSTALLATIONSVERZEICHNIS/karaf/deploy.

Has the driver been recognized and registered by Karaf?

To do this, execute the following command in the Karaf console: jdbc:ds-factories

Example output of a registered Oracle JDBC driver

virtimo@bpc()> jdbc:ds-factories
Name              │ Class                    │ Version │ Registration bundle
──────────────────┼──────────────────────────┼─────────┼────────────────────────────────
ojdbc6.jar-native │ oracle.jdbc.OracleDriver │ 0.0.0   │ ojdbc6.jar [229]
oracle            │ oracle.jdbc.OracleDriver │         │ org.ops4j.pax.jdbc.oracle [230]

Have all the necessary JDBC features been installed?

To do this, execute the following command in the Karaf console: feature:list | grep jdbc

In the output, you must ensure that the following features are in the status Started:

jdbc
pax-jdbc-config
pax-jdbc-<datenbankname>
pax-jdbc-pool-dbcp2

If, for example, the feature pax-jdbc-pool-dbcp2 is not in the status Started, enter feature:install pax-jdbc-pool-dbcp2 to install and start it.

Sample output of an installation with Oracle driver

virtimo@bpc()> feature:list | grep jdbc
jdbc                            │ 4.2.8            │ x        │ Started     │ enterprise-4.2.8                  │ JDBC service and commands
pax-transx-jdbc                 │ 0.4.4            │          │ Uninstalled │ pax-transx-0.4.4                  │
pax-jdbc-spec                   │ 1.4.4            │          │ Started     │ org.ops4j.pax.jdbc-1.4.4          │ Provides OSGi JDBC Service spec
pax-jdbc                        │ 1.4.4            │          │ Started     │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Service support
pax-jdbc-config                 │ 1.4.4            │ x        │ Started     │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Config support
pax-jdbc-db2                    │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC DB2 DataSourceFactory
pax-jdbc-teradata               │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Teradata DataSourceFactory
pax-jdbc-derby                  │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Derby Embedded DataSourceFactory
pax-jdbc-derbyclient            │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Derby Client DataSourceFactory
pax-jdbc-h2                     │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC H2 DataSourceFactory
pax-jdbc-hsqldb                 │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC HSQLDB DataSourceFactory
pax-jdbc-mariadb                │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Mariadb DataSourceFactory
pax-jdbc-oracle                 │ 1.4.4            │ x        │ Started     │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Oracle DataSourceFactory
pax-jdbc-postgresql             │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC PostgreSQL DataSourceFactory
pax-jdbc-sqlite                 │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC SQLite DataSourceFactory
pax-jdbc-mssql                  │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC MSSQL DataSourceFactory
pax-jdbc-jtds                   │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC jTDS DataSourceFactory
pax-jdbc-pool-dbcp2             │ 1.4.4            │ x        │ Started     │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Pooling DataSourceFactory
pax-jdbc-pool-c3p0              │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Pooling using C3P0
pax-jdbc-pool-hikaricp          │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Pooling DataSourceFactory using Hik
pax-jdbc-pool-aries             │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Pooling DataSourceFactory using Ari
pax-jdbc-pool-narayana          │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Pooling DataSourceFactory using Nar
pax-jdbc-pool-transx            │ 1.4.4            │          │ Uninstalled │ org.ops4j.pax.jdbc-1.4.4          │ Provides JDBC Pooling DataSourceFactory using Pax

Database connection is available?

The data connections created in the BPC (see Backend Connections) must also be able to be displayed from the Karaf console. Use the following command to list them: jdbc:ds-list

Sample output of an Oracle database connection

virtimo@bpc()> jdbc:ds-list
Name         │ Service Id │ Product │ Version                                                                   │ URL                                 │ Status
─────────────┼────────────┼─────────┼───────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────┼───────
oracle-local │ 245        │ Oracle  │ Oracle Database 11g Express Edition Release 11.2.0.2.0 - 64bit Production │ jdbc:oracle:thin:@localhost:1521:XE │ OK

Keywords: