Database compatibility

jBPM runs on any database that is supported by hibernate.

The example configuration files in jBPM (src/config.files) specify the use of the hypersonic in-memory database. That database is ideal during development and for testing. The hypersonic in-memory database keeps all its data in memory and doesn't store it on disk.

Isolation level of the JDBC connection

Make sure that the database isolation level that you configure for your JDBC connection is at least READ_COMMITTED.

Almost all features run OK even with READ_UNCOMMITTED (isolation level 0 and the only isolation level supported by HSQLDB). But race conditions might occur in the job executor and with synchronizing multiple tokens.

Changing the jBPM DB

Following is an indicative list of things to do when changing jBPM to use a different database:

  • put the jdbc-driver library archive in the classpath
  • update the hibernate configuration used by jBPM
  • create the schema in the new database

The jBPM database schema

The database and config directories in the distribution contain scripts and Hibernate configuration files to help you get started on your choice database.

While jBPM is capable of generating DDL scripts for any database supported by Hibernate, the resulting schemas are not always optimized. You might want to have your DBA review the DDL that is generated to optimize the column types and use of indexes.

In development you might be interested in the following hibernate configuration: If you set hibernate configuration property hibernate.hbm2ddl.auto to create-drop in the Hibernate configuration file, the database schema will be automatically created the first time the application accesses the database. When the application closes down, the schema will be dropped.

Programmatic database schema operations

jBPM provides an API for creating and droping the database schema through the org.jbpm.JbpmConfiguration methods createSchema and dropSchema. Be aware that there is no constraint on invoking these methods other than the privileges of the configured database user.

The aforementioned APIs constitute a facade to the broader functionality offered by class org.jbpm.db.JbpmSchema:

  • Create, drop, update and clean (drop-create) the database schema
  • Generate SQL scripts for the above operations
  • List the mapped tables and query the existing tables in the database

The jBPM schema Ant task

As an alternative to programmatic schema manipulation, jBPM provides an Ant task for generating scripts that create, drop and update the database schema. The listing below illustrates the task being used to generate the schema creation script and save it to file create.sql. The Hibernate configuration is read from the resource hibernate.cfg.xml.

<taskdef name="jbpmschema" classname="org.jbpm.ant.JbpmSchemaTask">
  <classpath>
    <pathelement location="jbpm-jpdl.jar" />
    <pathelement location="hibernate.jar" />
    <pathelement location="dom4j.jar" />
    <pathelement location="commons-logging.jar"/>
    <pathelement location="commons-collections.jar"/>
  </classpath>
</taskdef>

<jbpmschema config="hibernate.cfg.xml" action="create" output="create.sql" />

The task parameters are documented below.

Table 6.1. jBPM schema task parameters

AttributeDescriptionRequired
configHibernate configuration resourceNo, default hibernate.cfg.xml
propertiesHibernate properties resource. These properties override property values from the config resource.No
actionDatabase schema operation to script. Can be create, drop, update or clean.No, default create
outputThe output file. The generated script is written to this file.Yes
delimiterString that separates SQL statementsNo, default ;
delimiterTypeControl whether the delimiter should be placed on a line by itself. Can be normal, at the end of line, or row, on a line by itself.No, default normal