Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Configuring Persistent Datasources

JBoss Data Grid lets you persist data stored in the cache to a datasource. There are two types of datasources for Red Hat JBoss Data Grid for OpenShift:

  • Internal datasources that run on OpenShift. These datasources are available through the Red Hat Container Registry and do not require you to configure additional environment files.

    Note

    Internal datasources include PostgreSQL, MySQL, and MongoDB. However, Red Hat JBoss Data Grid for OpenShift currently supports PostgreSQL and MySQL only.

  • External datasources that do not run on OpenShift. You must configure these external datasources with environment files that you add to OpenShift Secrets.

6.1. Configuring Internal Datasources
Copy link

The DB_SERVICE_PREFIX_MAPPING environment variable defines JNDI mappings for internal datasources.

You can define multiple JNDI mappings as comma-separated values for the DB_SERVICE_PREFIX_MAPPING environment variable. When you run the JBoss Data Grid for OpenShift image, the launch script creates a separate datasource for each JNDI mapping. The JBoss Data Grid for OpenShift then automatically discovers each datasource.

To define a JNDI mapping, specify a value for the environment variable in the following format:

<poolname>-<database_type>=<PREFIX>

  • <poolname> is the pool-name attribute for the datasource. Use any alphanumeric value that is meaningful and easy to identify. The value cannot contain special characters. Likewise, the value must contain lowercase characters only.

  • <database_type> specifies the database driver to use. The value must contain lowercase characters only.

    Note

    Only mysql and postgresql are supported values for <database_type>.

  • <PREFIX> is used for the names of environment variables that configure the datasource.

6.1.1. Single Datasource Example
Copy link

If you specify test-postgresql=TEST as the value for the DB_SERVICE_PREFIX_MAPPING environment variable, it creates a datasource with the following name:

java:jboss/datasources/test_postgresql

You must use the TEST_ prefix when specifying other environment variables for the datasource. For example, to set the username and password, use TEST_USERNAME and TEST_PASSWORD as the environment variables.

6.1.2. Multiple Datasource Example
Copy link

If you specify cloud-postgresql=CLOUD,test-mysql=TEST_MYSQL as the value for the DB_SERVICE_PREFIX_MAPPING environment variable, it creates two datasources with the following names:

  • java:jboss/datasources/test_mysql
  • java:jboss/datasources/cloud_postgresql

When specifying other environment variables for the datasources, you must use the TEST_MYSQL prefix to configure the MySQL datasource. For example, use TEST_MYSQL_USERNAME as the environment variable to specify the username.

Similarly, you must use the CLOUD_ prefix to configure the PostgreSQL datasource. For example, use CLOUD_USERNAME as the environment variable to specify the username.

6.2. Configuring External Datasources
Copy link

To use an external datasource, you define a custom image template and then use the Source-to-Image (S2I) build tool to create an image. S2I is a framework that takes application source code as an input and produces a new image that runs the assembled application as output.

The following high-level steps provide an overview of the process:

  1. Specify the CUSTOM_INSTALL_DIRECTORIES environment variable in the image template JSON. This variable defines the location where S2I artifacts reside, as in the following example: 

    {
    "name": "CUSTOM_INSTALL_DIRECTORIES",
    "value": "extensions/*"
}
    Copy to Clipboard Toggle word wrap

  2. Create an install.sh script in that directory. This script installs the modules and drivers for the external datasource in the image.

    The following is an example install.sh script: 

    #!/bin/bash

# Import the common functions for installing modules and configuring drivers
source /usr/local/s2i/install-common.sh

# Directory where this script is located
injected_dir=$1

# Install the modules for the datasource
install_modules ${injected_dir}/modules

# Configure the drivers for the datasource
configure_drivers ${injected_dir}/drivers.properties
    Copy to Clipboard Toggle word wrap

  3. Include a modules subdirectory that contains a module.xml file and the driver for the datasource. The resulting image uses the module to load classes and define dependencies.

    As an example, you plan to use Derby as an external datasource. You need to obtain a driver such as derby-10.12.1.1.jar and place it in the following directory: modules/org/apache/derby/main/

    In the same directory, you also need to create a module.xml file that defines the driver as a resource and declares dependencies.

    The following is an example module.xml file: 

    <?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.3" name="org.apache.derby">
 <resources>
   <resource-root path="derby-10.12.1.1.jar"/>
   <resource-root path="derbyclient-10.12.1.1.jar"/>
 </resources>

 <dependencies>
   <module name="javax.api"/>
   <module name="javax.transaction.api"/>
 </dependencies>
</module>
    Copy to Clipboard Toggle word wrap

  4. Define the driver configuration properties in a drivers.property environment variable file.

    The following is an example drivers.property file: 

    #DRIVERS
DRIVERS=DERBY

DERBY_DRIVER_NAME=derby
DERBY_DRIVER_MODULE=org.apache.derby
DERBY_DRIVER_CLASS=org.apache.derby.jdbc.EmbeddedDriver
DERBY_XA_DATASOURCE_CLASS=org.apache.derby.jdbc.EmbeddedXADataSource
    Copy to Clipboard Toggle word wrap

  5. After you build and deploy the image, specify environment variables for the datasource.

    The following example shows a datasource definition with the DATASOURCES environment variable: 

    # Set a unique prefix for the datasource
DATASOURCES=ACCOUNTS_DERBY
# Specify other environment variables using the prefix
ACCOUNTS_DERBY_DATABASE=accounts
ACCOUNTS_DERBY_JNDI=java:/accounts-ds
ACCOUNTS_DERBY_DRIVER=derby
ACCOUNTS_DERBY_JTA=true
ACCOUNTS_DERBY_NONXA=false
ACCOUNTS_DERBY_USERNAME=username
ACCOUNTS_DERBY_PASSWORD=password
ACCOUNTS_DERBY_XA_CONNECTION_PROPERTY_DatabaseName=/opt/eap/standalone/data/databases/derby/accounts
# _HOST and _PORT are required but not used
ACCOUNTS_ORACLE_HOST=dummy
ACCOUNTS_ORACLE_PORT=1527
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat