Chapter 6. Configuring Persistent Datasources

download PDF

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.


    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

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> 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.


    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

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:


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

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

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:

        "value": "extensions/*"
  2. Create an script in that directory. This script installs the modules and drivers for the external datasource in the image.

    The following is an example script:

    # Import the common functions for installing modules and configuring drivers
    source /usr/local/s2i/
    # Directory where this script is located
    # Install the modules for the datasource
    install_modules ${injected_dir}/modules
    # Configure the drivers for the datasource
    configure_drivers ${injected_dir}/
  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- 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">
       <resource-root path="derby-"/>
       <resource-root path="derbyclient-"/>
       <module name="javax.api"/>
       <module name="javax.transaction.api"/>
  4. Define the driver configuration properties in a environment variable file.

    The following is an example file:

  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
    # Specify other environment variables using the prefix
    # _HOST and _PORT are required but not used
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

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

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.

© 2024 Red Hat, Inc.