Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
193 lines (127 sloc) 7.13 KB

Datasources Configuration

There are two types of datasources, internal and external.

Internal Datasource

Internal datasources uses one of the drivers that have been provisioned along with the WildFly server. The default configuration contains postgresql and mysql drivers.

To specify internal datasources use the DB_SERVICE_PREFIX_MAPPING environment variable. It has the following format


For example testa-postgresql=TEST. The other out of the box valid value for DATABASETYPE is mysql.

You can create more than one datasource by using a comma separated list of entries, e.g: DB_SERVICE_PREFIX_MAPPING="testa-postgresql=TEST,test2-postgresql=TEST2”. One datasource or xa-datasource entry will be created per entry in the list.

The PREFIX is used to determine other relevant datasource variables:


Defines the database server’s host name or IP address to be used in the datasource’s connection-url property. Example value:


Defines the database server’s port for the datasource. Example value: 5432


When set to true database connections are validated periodically in a background thread prior to use. Defaults to false, meaning the validate-on-match method is enabled by default instead.


Specifies frequency of the validation, in milliseconds, when the background-validation database connection validation mechanism is enabled (PREFIX_BACKGROUND_VALIDATION variable is set to true). Defaults to 10000.


Specifies a connection checker class that is used to validate connections for the particular database in use. Example value: org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker


Defines the database name for the datasource. Example value: myDatabase


Specifies the exception sorter class that is used to properly detect and clean up after fatal database connection exceptions. Example value: org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter


Defines the JNDI name for the datasource. Defaults to java:jboss/datasources/POOLNAME_DATABASETYPE, where POOLNAME and DATABASETYPE are taken from the triplet described above. This setting is useful if you want to override the default generated JNDI name. Example value: java:jboss/datasources/test-postgresql


Defines Java Transaction API (JTA) option for the non-XA datasource. The XA datasources are already JTA capable by default. Defaults to true.


Defines the maximum pool size option for the datasource. Example value: 20


Defines the minimum pool size option for the datasource. Example value: 1


Defines the datasource as a non-XA datasource. Defaults to false.


Defines the password for the datasource. Example value: password


Defines the java.sql.Connection transaction isolation level for the datasource. Example value: TRANSACTION_READ_UNCOMMITTED


Defines connection URL for the datasource. Example value: jdbc:postgresql://localhost:5432/postgresdb


Defines the username for the datasource. Example value: admin


When adding drivers to WildFly server, you have 2 choices:

  • Package your drivers (even datasources) as galleon feature-pack as done in wildfly-datasources-galleon-pack and include the Galleon feature-pack in your Galleon project.

  • Use s2i hooks we are offering that allow you to install driver JBOSS modules and update WildFly configuration.

Drivers deployment and configuration using s2i hooks

An example of such approach can be found in this test project.

To be able to deploy a driver module and configure the jdbc-driver resource in datasources subsystem it is necessary to use a special script file called This file will be invoked during the assemble phase of the S2I process.

S2I_IMAGE_SOURCE_MOUNTS is the environment variable that instructs the S2I process where to find this file. This variable will contain a comma-separated list of directories where to find the file.

The following is an example of the content of script:


source /usr/local/s2i/
install_deployments ${injected_dir}/injected-deployments.war
install_modules ${injected_dir}/modules
configure_drivers ${injected_dir}/drivers.env

In this example we are using the following methods exposed by script. This script is available in /usr/local/s2i directory of our image. The methods used by the user define script are:

  • install_deployments: Copy the file passed as an argument to the server deployment directory.
  • install_modules: Copy all the JBOSS modules in the directory passed as argument to the server modules directory.
  • configure_drivers: Configure the desired drivers using the environment file passed as an argument.

The ${injected_dir} in our example will be one of the directories listed in S2I_IMAGE_SOURCE_MOUNTS variable that is currently being processed.

The ${injected_dir}/drivers.env is a file that will contain the environment variables that you want to use to configure drivers.

The available environment variables that you can configure in this file are:

  • DRIVERS: It's a comma separated list of driver prefixes. And for each prefix:

  • ${driver_prefix}_DRIVER_MODULE

  • ${driver_prefix}_DRIVER_NAME

  • ${driver_prefix}_DRIVER_CLASS

  • ${driver_prefix}_XA_DATASOURCE_CLASS

External datasource

External datasources are datasources that are referencing drivers not present in the default configuration. You configure them by using the same PREFIX_* env variable defined for Internal datasources. In addition you use PREFIX_DRIVER env var to specify the driver name.

To specify external datasources, you can create one or more environment files. These will be read on startup of the server. To configure the environment files, you can do something like:


Then assuming that the image contains the env files in these locations, it will use the prefixes in the DATASOURCES variable contained in the file to look for variables in the file with those prefixes. An example:

$cat /etc/extensions/file1.env

# The "MYDB" database

Note: By locating your env file in <application src>/configuration directory it will be automatically copied to $JBOSS_HOME/standalone/configuration directory.

You can’t perform that action at this time.