Chapter 8. Configuring the Default Database

8.1. Hypersonic Database

Hypersonic is a database that comes included with the JBoss Enterprise SOA Platform product and works out-of-the-box. It is a demonstration database only and is not suitable for use on production systems. Use it for development and evaluation purposes only. Red Hat does not support the use of Hypersonic on a production system.

8.2. Hypersonic is Not Supported

The Hypersonic database is included for testing purposes only and is not supported.
Known issues with the Hypersonic Database include:
  1. No transaction isolation thread and socket leaks (connection.close() does not tidy up resources)
  2. Persistence quality (logs commonly become corrupted after a failure, preventing automatic recovery)
  3. Database corruption stability under load (database processes cease when dealing with too much data)
  4. Not viable in clustered environments

8.3. H2 Database

H2 is an in-memory reference database that comes included with the JBoss Enterprise SOA Platform product and works out-of-the-box. Use it in testing environments only. It is not suitable for production systems and Red Hat does not support its use in such environments.

8.4. Database Configuration Tool

The Database Configuration Tool (found in the SOA_ROOT/jboss-as/tools/schema/ directory) is an Apache Ant script. It sets the database to be used by the JBoss Enterprise SOA Platform. A list of the supported databases can be found at http://www.jboss.com/products/platforms/soa/supportedconfigurations/.

8.5. Configure a Database for Production System Use

Prerequisites

  • Apache Ant
  • the database that you wish to use must already exist
  • a user with permission to make changes to that database must already exist.
  • the JDBC driver JAR file for the database must be in the server configuration's lib/ directory.
The JBoss Enterprise SOA Platform uses a database to persist registry services and the Message Store. The default database is Hypersonic but this is not suitable for production systems and is not supported. You must switch to a supported database before running the JBoss Enterprise SOA Platform in a production environment.

Warning

You can only use the Database Configuration Tool to change the database configuration once. Also, it must be run before any other changes are made. If you try to run the script on an installation that has already been configured, it may not work as intended.

  1. Back Up Your Server Profile

    Make a copy of the server profile for which you plan to configure your database as the Database Configuration Tool modifies the configuration settings. cp -R SOA_ROOT/jboss-as/server/Profile /path/to/backup/folder.

  2. Running the Database Configuration Tool

    Change to the directory containing the Database Configuration script: cd SOA_ROOT/jboss-as/tools/schema

  3. Run Ant

    Run the ant command to launch the script.

  4. Enter Data

    Following the prompts, enter the following information as it is requested:
    • the type of database being used,
    • the name of the database,
    • the host name or IP Address of the database,
    • the TCP port being used for the database,
    • the user name needed to access the database, and
    • the password for this user account.

    Note

    You could also add these values directly to the build.properties file (found in the same directory) before running the script. The Database Schema Tool will not prompt you for these properties if it finds you have already added them to the file.
Result

The Tool updates the relevant configuration files and exits.

Important

Users may experience deadlocks in jBPM 5 when running this process. To avoid this, add the following code to to jbpm.esb/jbpm-ds.xml: 
<datasources>
    <local-tx-datasource>
        <jndi-name>BPELDB</jndi-name>
        ...
        <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
        <new-connection-sql>SET TRANSACTION ISOLATION LEVEL SNAPSHOT;</new-connection-sql>
        ...
    </local-tx-datasource>
</datasources>

8.6. SOA_ROOT/jboss-as/tools/schema/build.xml

The SOA_ROOT/jboss-as/tools/schema/build.xml contains the settings for the Database Schema Tool. It is used by the ant command to run through the database setting options.

8.7. SOA_ROOT/jboss-as/tools/schema/build.properties

This is the file in which the Database Schema Tool saves settings. You can also edit it by hand using a text editor.