documentation - database configuration - 2014-08-18

8/10/2019 Documentation - Database Configuration - 2014-08-18

1/11

Published on Bonita Documentation(http://documentation.bonitasoft.com)

Database configurationProduct version:6.3

Product edition:

Teamwork

Efficiency

Performance

Database usage

Business Data data sources

Default h2 database

Database creation

Specify db vendor

Add the database driver

Configure the datasource

Change to another database (not default h2)

Specific database configuration - PostgreSQL

Specific database configuration - MS SQL

Specific configuration database- MySQL

Specific configuration database - Oracle DB

Database usage

Bonita BPM Engine uses a database to store information about deployed processes definition,

processes configuration, history of process execution, users, etc. One database schema is

required by Bonita to store all information.

Connection to the database is through Hibernate (version 4.2). This provides a level ofabstraction between Bonita and DBMS. Bonita comes with a set of optimized initialization

scripts for the supported DBMSs.

Business Data datasources

In the new feature Business Data Management, two new datasources have been added:

BusinessDataDS, NotManagedBizDataDS. Use the standard method to change the default

h2 database to a replacement by changing the datasources configuration. You will need to

make the new business datasource point to an alternative database too, if necessary.

For better performance, Bonita uses the JEE application server data source feature. Data

sources usually offer connection pooling, which significantly improves performance.
http://documentation.bonitasoft.com/http://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#usagehttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#datasourceshttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#h2defaulthttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#dbcreationhttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#specdbvendorhttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#adddriverhttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#configdatasourcehttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#removeh2http://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#postgresqlspechttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#mssqlspechttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#mysqlspechttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#oraclespechttp://documentation.bonitasoft.com/hardware-and-software-requirements#serversoftwarehttp://documentation.bonitasoft.com/hardware-and-software-requirements#serversoftwarehttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#oraclespechttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#mysqlspechttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#mssqlspechttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#postgresqlspechttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#removeh2http://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#configdatasourcehttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#adddriverhttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#specdbvendorhttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#dbcreationhttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#h2defaulthttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#datasourceshttp://localhost/var/www/apps/conversion/tmp/scratch_8/node/455#usagehttp://documentation.bonitasoft.com/


2/11

Bonita also relies on the JTA(Java Transaction API) JEE service. This service is not available

in a standard Tomcat setup because it is not a full JEE application server. In order to get JTA

support in Tomcat, Bonita includes the Bitronix library.

Bonita BPM Engine use two data sources:

Hibernate data source

Used to store Java objects in a database.

Uses transaction provided by JTA.

Uses Hibernate for conversion between Java object to SQL queries.

Sequence data source

Used to get unique id for persisted objects.

Does not use JTA.

Does not use Hibernate (only runs standard SQL queries).

Default h2 database

Bonita BPM Studio, and the Tomcat and JBoss bundles come with a default h2 database

included in the package.

h2 is suitable for testing only. For production purposes, you should modify the configuration to

use another database.

In order to configure Bonita BPM to work with your DBMS, you will need to perform the

following steps:

Database creation

Specify the database vendor


Configure data source

Remove h2

DBMS specific configuration

Database creation

Warning:Some databases require specific configuration, which must be done before youcomplete your installation. If you do not complete the specific configuration for your database,

your installation may fail.

Note: You will need to have already created a new "Bonita" database that you can name as

you like, as long as you remember to "point to it" in your configuration file.

Configure Bonita to work with another database

The first step in configuring Bonita with another DBMS would be to create a new database

(schema).

In order to do so, make sure you have a DBMS user account that has sufficient privileges.
http://www.oracle.com/technetwork/java/javaee/jta/index.htmlhttp://www.oracle.com/technetwork/java/javaee/jta/index.html


3/11

Note: the new Bonita database name you use will be needed in the following configuration

steps.

Also note that owner of the new schema must have following privileges:

CREATE TABLECREATE INDEX

SELECT, INSERT, UPDATE, DELETE on created TABLE

Note: CREATE TABLE and CREATE INDEX are no longer required after first start.

See also Set up a database schema with SQL Server 2012

See also Create a schema (Transact-SQL)

Specify the database vendor

Bonita BPM Engine and your application server need to know which type of DBMS you are

using. This must be set as an environment variable,db.vendor, in the application server

configuration.

For Tomcat, edit setenv.sh(for Linux) or setenv.bat(for Windows) and modify the

DB_OPTS. For example: set DB_OPTS="-Dsysprop.bonita.db.vendor=mysql"

For JBoss, edit server\default\deploy\properties-service.xmland set the

value of sysprop.bonita.db.vendor. For example:

sysprop.bonita.db.vendor=postgresFor other application servers, either use a setenv file as with Tomcat, or set the variable

as described in the application server documentation.

The possible settings for db.vendorare:

Database vendor Property value

MySQL mysql

MS SQL sqlserver

PostgreSQL postgres

Oracle database oracle

h2 (default for testing, not for production) h2

It is also possible to set db.vendorin the bonita-platform.propertiesfile of your

bonita_home, but this is not recommended. The default setting in bonita-

platform.propertiesis db.vendor=${sysprop.bonita.db.vendor:h2}

This means that db.vendoris set to the value of the system property if it is set, or to h2

otherwise. If you set the database vendor explicitly in bonita-platform.properties, you

also need to set it as an environment variable for your application server. For simplicity and toavoid error, we strongly recommend that you configure the db.vendor only in an environment
http://technet.microsoft.com/en-us/library/dd207005.aspxhttp://technet.microsoft.com/en-us/library/ms189462.aspxhttp://documentation.bonitasoft.com/mysql-specifichttp://documentation.bonitasoft.com/ms-sql-serverhttp://documentation.bonitasoft.com/oracle-databasehttp://documentation.bonitasoft.com/oracle-databasehttp://documentation.bonitasoft.com/ms-sql-serverhttp://documentation.bonitasoft.com/mysql-specifichttp://technet.microsoft.com/en-us/library/ms189462.aspxhttp://technet.microsoft.com/en-us/library/dd207005.aspx


4/11

variable, and you do not change bonita-platform.properties.


Download

First you need to download the JDBC driver for your database system. Use links below to

download the driver directly.

Database vendor Download link

MySQL download

Microsoft SQL Server download

PostgreSQL (use "Current Version") download

Oracle Database downloadNote that if you run on Linux, JDBC driver might also be available in the distribution packages

repository. On Ubuntu and Debian you can for example install the libpostgresql-jdbc-

javapackage to get the PostgreSQL JDBC Driver (install in /usr/share/java).

Add JDBC driver to application server

The way to install the JDBC driver depend on the application server and the way this one is

installed:

Tomcat 6 or 7Bonita Tomcat bundle: in the bundle folder add the driver to the lib/bonitafolder.

zip distribution: in the Tomcat folder add the driver to the lib/bonitafolder.

Ubuntu/Debian package: add the driver to /usr/share/tomcat6/libor

/usr/share/tomcat7/lib.

Windows as a service: add the driver to C:\Program Files\Apache

Software Foundation\Tomcat 6.0\libor C:\Program Files\ApacheSoftware Foundation\Tomcat 7.0\lib

JBoss 5.1

Bonita JBoss bundle: inside bundle folder add the driver to theserver/default/libfolder.

zip distribution: in the JBoss folder add the driver to the server//libfolder.

Configure the data source

As explained on the overviewpage, Bonita requires the configuration of two data sources.

The data source declaration will define how to connect to the DBMS. The following

information is required to configure the data sources:

Address of the DBMS server.Port number of the DBMS server.

Database name.
http://dev.mysql.com/downloads/connector/j/http://go.microsoft.com/fwlink/?LinkId=245496http://jdbc.postgresql.org/download.html#currenthttp://www.oracle.com/technetwork/database/features/jdbc/index-091264.htmlhttp://documentation.bonitasoft.com/database-overviewhttp://documentation.bonitasoft.com/database-overviewhttp://www.oracle.com/technetwork/database/features/jdbc/index-091264.htmlhttp://jdbc.postgresql.org/download.html#currenthttp://go.microsoft.com/fwlink/?LinkId=245496http://dev.mysql.com/downloads/connector/j/


5/11

User name to connect to the database.

Password to connect to the database.

JDBC Driver fully qualified class name (see table below).

XADataSource fully qualified class name (see table below).

Database

vendorDriver class name XADataSource class name

MySQL com.mysql.jdbc.Driver com.mysql.jdbc.jdbc2.optional.MysqlXA

Microsoft

SQL Servercom.microsoft.sqlserver.jdbc.SQLServerDriver com.microsoft.sqlserver.jdbc.SQLServer

PostgreSQL org.postgresql.Driver org.postgresql.xa.PGXADataSource

Oracle

Databaseoracle.jdbc.driver.OracleDriver oracle.jdbc.xa.client.OracleXADataSourc

h2 (not for

production)org.h2.Driver org.h2.jdbcx.JdbcDataSource

Tomcat

Configuration of data source for Tomcat is a little bit specific. As Tomcat doesn't support JTA

natively, one data source will be configured in the Bitronix configuration file and the other data

source will be configured in the standard Tomcat context configuration file.

JTA data source (managed by Bitronix)

Open /conf/bitronix-resources.propertiesfile.

Remove or comment the lines regarding the h2 database.

Uncomment the line matching your DBMS.

Update the value for the following settings:

resource.ds1.driverProperties.userput your DBMS user name.

resource.ds1.driverProperties.passwordput your DBMS password.

resource.ds1.driverProperties.serverNameput the address (IP or

hostname) of your DBMS server.

resource.ds1.driverProperties.portNumberput the port of your DBMS

server.resource.ds1.driverProperties.databaseNameput the database name.

Save and close the file.

Non-transactional data source

The second data source run SQL queries outside any transaction. To configure it:

Open /conf/Catalina/localhost/bonita.xmlfile.

Remove or comment the lines regarding h2 database.

Uncomment the line matching your DBMS.Update following attributes value:

usernamewith your DBMS user name.


6/11

passwordwith your DBMS password.

url: note that URL include: DBMS server address, DBMS server port and

database name

Business Data data source configuration for Tomcat

Tomcat datasource configuration

For Business data data source, change the last 4 lines of the resource named

NotManagedBizDataDSfound in Tomcat

folder/conf/Catalina/localhost/bonita.xml.

username="sa" password="" driverClassName="org.h2.Driver"url="jdbc:h2:tcp://localhost:9091/business_data.db;MVCC=TRUE;DB_CLOSE_ON_EXI

Bitronix configuration

For Business data data source (default name DS2 specific to business data), change the DS2

to DBMS value.

To do this:

Open /conf/bitronix-resources.propertiesfile.

Update the value for the following settings:

resource.ds2.driverProperties.userput your DBMS user name.

resource.ds2.driverProperties.passwordput your DBMS password.

resource.ds2.driverProperties.serverNameput the address (IP orhostname) of your DBMS server.

resource.ds2.driverProperties.portNumberput the port of your DBMS

server.

resource.ds2.driverProperties.databaseNameput the database name.

Save and close the file.

In addition, change the dialectin the following file: \server\platform\tenant-template\conf\bonita-server.properties

before changes (MySQL example):

businessdata.hibernate.dialect=org.hibernate.dialect.H2Dialect

after changes (MySQL example):businessdata.hibernate.dialect=org.hibernate.dialect.MySQLDialect

Note:if the tenant is already created, then the user should change the /server/tenants/

/conf/bonita-server.propertiesas the business database configuration is at a tenant

level.

Business Data data source configuration for JBoss

To configure the data source for JBoss:

If you want to change the configuration of the engine database, modify the configuration of


7/11

two data sources: the XA data source called bonitaDSand the no-tx data source called

bonitaSequenceManagerDS

1. Open the /server/default/deploy/bonita-ds.xmlfile.

2. Remove or comment the 2 blocks regarding the h2 database ( and ) as above.

3. Go to Examples, and uncomment the line matching your DBMS.4. Update value for the following settings in :

with your DBMS user name.

with your DBMS password.

with the address (IP or hostname), port of your DBMS server, and database name.

5. Update value for the following settings in :




6. Save and close the file.

In addition, change the dialectin the following file: \server\platform\tenant-template\conf\bonita-server.properties

before changes(MySQL example):businessdata.hibernate.dialect=org.hibernate.dialect.H2Dialect

after changes (MySQL example):businessdata.hibernate.dialect=org.hibernate.dialect.MySQLDialect

Note: if the tenant is already created, then the user should change the /server/tenants/

/conf/bonita-server.propertiesas the business database configuration is at a tenant

level.

If you want to change the configuration of the Business Data database, modify the

configuration of two data sources: the XA data source called BusinessDataDSand the no-tx

data source called NotManagedBizDataDS

1. Open the /server/default/deploy/bonita-ds.xmlfile.

2. Remove or comment the 2 blocks regarding the h2 database ( and ) as above.

3. Go to Examples, and uncomment the line matching your DBMS.


with your DBMS user name.with your DBMS password.






6. Save and close the file.

Change to another database (Not default h2)

Warning:If you use the default configuration for business data, do not remove h2. The

standard way to change the database from H2 to another has not changed.


8/11

If you want to change the default h2 database to another, you will need to go through the

following steps to remove h2.

Remove h2 listener, so that H2 is not started automatically.

Tomcat: comment out the H2 listener in the /conf/server.xml file.

JBoss: remove the mbean declaration in theserver/your_server_configuration/deploy/bonita-ds.xmlfile

Remove h2 jar files (bonita-jboss-h2-mbean-1.0.0.jar, bonita-tomcat-h2-listener-

1.0.1.jar, h2-1.3.170.jar)

Tomcat: files are located in: /libor in /lib/bonita.

JBoss: files are located in: server//libTo make sure that the H2 is not run, go to run.conf.batfile in /bin/and in "set

Bonita OPTS", remove the part which refers to H2.

Specific database configuration - PostgreSQL

Before you start PostgreSQL, edit postgresql.confand set a non-zero value for

max_prepared_transactions. The default value, 0, disables prepared transactions, which

is not recommended for Bonita BPM Engine. The value should be at least as large as the

value set for max_connections. See the PostgreSQL documentationfor details.

Specific configuration - MS SQL

XA Transactions

MS SQL Server requires specific configuration in order to support XA transactions.

You can refer to MSDNfor more information.

Here is the list of steps to perform:

1. Download the Microsoft SQL Server JDBC Driver 4.0from Microsoft web site.

2. Install it (run the.exe).

3. Copy the sqljdbc_xa.dllfrom

%JDBC_DRIVER_INSTALL_ROOT%\sqljdbc_4.0\enu\xa\x64\(x64 for 64 bit

version of Windows, x86 for 32 bit version of Windows) to%SQLSERVER_INSTALL_ROO%\Instance_root\MSSQL10.MSSQLSERVER\MSSQL\Binn\.

4. Copy/paste the content of xa_install.sql file (located in

%JDBC_DRIVER_INSTALL_ROOT%\sqljdbc_4.0\enu\xa) to SQL Server Management

Studio's Query Editor.

5. Then execute it.

6. To confirm successful execution of the script, you should open the "Object Explorer" and

go to: Master> Programmability> Extended Stored Procedures.

7. Here you should have 12 new procedures with name starting with

dbo.xp.sqljdbc_xa_.

8. Next step is to assign the new role 'SqlJDBCXAUser' to the user who owns the Bonitadatabase.

9. Create a new Login (you may use the Microsoft SQL Management Studio)e.g. bonitadev
http://www.postgresql.org/docs/9.1/static/runtime-config-resource.htmlhttp://msdn.microsoft.com/en-us/library/aa342335(v=sql.100).aspxhttp://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=11774http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=11774http://msdn.microsoft.com/en-us/library/aa342335(v=sql.100).aspxhttp://www.postgresql.org/docs/9.1/static/runtime-config-resource.html


9/11

10. Execute following command in SQL editor: USE master GO CREATE USER'bonitadev', 'bonitadev' GO sp_addrolemember [SqlJDBCXAUser],'bonitadev'

11. In Windows "Start" menu select Administrative Tools-> Services.

12. In "Services" window, make sure that the Distributed Transaction Coordinatorservice

is set to start automatically. If it's not yet started, start it.13. Also make sure that the other services it depends on, namely "Remote Procedure Call"

and "Security Accounts Manager" are also set to start automatically.

14. Then run dcomcnfgcommand or go inside "Start" menu to Administrative Tools >

Component Services.

15. In the left navigation pane, navigate to Component Services> Computers> My

Computer> Distributed Transaction Coordinator

16. Select and right-click on Local DTCand thenProperties.

17. Click on Securitytab. Ensure that the checkbox for Enable XA Transactionsis

checked.

18. Click Applythen OK19. Then stop and restart SQLServer.

20. Create BONITA_v6 database CREATE DATABASE BONITA_v6 GO

21. Set bonitadev as owner of BONITA_v6 database (use for example: 'Microsoft SQL

Management Studio')

Recommended configuration for lock management

Run the script below to avoid deadlock:

ALTER DATABASE BONITA_v6 SET SINGLE_USER WITH ROLLBACK IMMEDIATE

ALTER DATABASE BONITA_v6 SET ALLOW_SNAPSHOT_ISOLATION ON

ALTER DATABASE BONITA_v6 SET READ_COMMITTED_SNAPSHOT ON

ALTER DATABASE BONITA_v6 SET MULTI_USER

See MSDN.

Note about Hibernate configuration

Only the org.hibernate.dialect.SQLServerDialectHibernate dialect is supported.Hence org.hibernate.dialect.SQLServer2005Dialectand

org.hibernate.dialect.SQLServer2008Dialectdialects are not supported.

Specific configuration - MySQL

MySQL define a maximum packet size both on server side. The default value for this settings

should be fine in most standard use cases. If you get:Error: 1153 SQLSTATE: 08S01 (ER_NET_PACKET_TOO_LARGE) Message: Got a

packet bigger than 'max_allowed_packet' bytes

you will need to adjust this setting.

On the MySQL server side, you need to update the file my.ini(for Windows) or my.cnf(for
http://msdn.microsoft.com/en-us/library/ms175095(v=sql.105).aspxhttp://msdn.microsoft.com/en-us/library/ms175095(v=sql.105).aspx


10/11

Linux) to avoid the ER_NET_PACKET_TOO_LARGEproblem. Look for max_allowed_packetsettings and adjust the value.

For more information, see the Mysql website.

Specific configuration - Oracle Database

Make sure your database is configured to use the AL32UTF8 character set. If your database

already exists, see the Oracle documentation for details of how to migrate the character set.

To use the transaction, (XADataSource) it requires extra privileges for the Oracle user used

by Bonita, and also specific settings for XA activation.

Important information for a successful connection

The procedure below is used to create the settings in order to enable the Bonita BPM to

connect to the Oracle Database.

It is assumed in the procedure that:

Oracle product is already installed and running

An 'Oracle' OS user is already created

A database already exists

The environment is already set:

ORACLE_HOME=/u01/app/oracle/product/11.2.0/dbhome_1 ORACLE_SID=...1. Connect as the System Administrator

SQL query >

oracle@ubuntu:~$ sqlplus / as sysdba

1.1 Check that the following components exist and are valid:

SQL query >

select comp_name, version, status from dba_registry;

Comp_name Version Status

Oracle Database Catalog Views 11.2.0.1.0 VALID

Oracle Database Packages and Types 11.2.0.1.0 VALID

JServer JAVA Virtual Machine 11.2.0.1.0 VALID

Oracle XDK 11.2.0.1.0 VALID

Oracle Database Java Packages 11.2.0.1.0 VALID

OLAP Analytic Workspace 11.2.0.1.0 VALID

Oracle OLAP API 11.2.0.1.0 VALID
http://dev.mysql.com/doc/refman/5.5/en/packet-too-large.htmlhttp://docs.oracle.com/cd/B28359_01/server.111/b28298/ch11charsetmig.htm#g1011430http://docs.oracle.com/cd/B28359_01/server.111/b28298/ch11charsetmig.htm#g1011430http://dev.mysql.com/doc/refman/5.5/en/packet-too-large.html


11/11

2. Add XA elements

SQL query >@/u01/app/oracle/product/11.2.0/dbhome_1/javavm/install/initxa.sql

This only needs to be done once, after the installation of Oracle.

3. Create user to be used by the Bonita Engine and grant the proper rights

SQL query >@/u01/app/oracle/product/11.2.0/dbhome_1/rdbms/admin/xaview.sql

The following queries must be done for each new user: i.e. one user = one database schema.

SQL query >

CREATE USER bonita IDENTIFIED BY bonita; GRANT connect, resource TO

bonita IDENTIFIED BY bonita; GRANT select ON

sys.dba_pending_transactions TO bonita; GRANT select ON

sys.pending_trans$ TO bonita; GRANT select ON sys.dba_2pc_pending TO

bonita; GRANT execute ON sys.dbms_system TO bonita; GRANT select ONsys.v$xatrans$ TO bonita;

2014 Bonitasoft, Inc. All rights reserved.

documentation - database configuration - 2014-08-18

Documents