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.
NoteInternal 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>-<database_type>=<PREFIX>
-
<poolname> is the
pool-nameattribute 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.
NoteOnly 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:
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
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:
Specify the
CUSTOM_INSTALL_DIRECTORIESenvironment 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/*" }Create an
install.shscript in that directory. This script installs the modules and drivers for the external datasource in the image.The following is an example
install.shscript:#!/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.propertiesInclude a
modulessubdirectory that contains amodule.xmlfile 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.jarand place it in the following directory:modules/org/apache/derby/main/In the same directory, you also need to create a
module.xmlfile that defines the driver as a resource and declares dependencies.The following is an example
module.xmlfile:<?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>
Define the driver configuration properties in a
drivers.propertyenvironment variable file.The following is an example
drivers.propertyfile:#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
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
