Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<table class="wysiwyg-macro" data-macro-name="unmigrated-wiki-markup" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3VubWlncmF0ZWQtd2lraS1tYXJrdXB9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>h1. 1 Overview

If you want to add support for an unsupported database system, you found the right documentation. This step-by-step guide describes all the steps that need to be processed in order to support a new database system.

h2. 1.1 QA Test suite

First we need to make sure, what is the qa test suite. With Activiti there are two projects that make up the qa. These are:

# activiti-engine-examples
# activiti-engine-test-api

These tests need to be run successfully before we consider Activiti to support a database system.

h2. 1.2 Run a test with H2

Before we start to go through all the steps, we should execute the test scripts on an already supported database. We assume, you already checked out the activiti project, setup the demo and configured ant and maven on your system.

Before we can run the test, we need to provide a database connection. This is done via a properties file located in &lt;user_home>/.activiti/jdbc. There create a file called h2.properties adding this content:

{code:title=h2.properties|borderStyle=solid}
jdbc.driver=org.h2.Driver
jdbc.url=jdbc:h2:tcp://localhost/activiti
jdbc.username=sa
jdbc.password=
{code}

This setup assumes an installed h2 database with no tables in it\! All tests are constructed to create the database before running the test and dropping the database after finishing the tests. If you have setup the database and the configuration file, you can proceed with the next command.

Navigate to the “activiti-engine-examples”-project and execute following command:

*mvn \--Ddatabase=h2 clean install*

You should see lots of info on the console. Most important are the tests that are run with this command. You also saw the creation and dropping of the database before and after the testing. This defines another point in the configuration for a new database system.

h1. 2 Step-by-Step Guide

Now we will describe the parts that have to be completed for the purpose of this document. These are:

# Setup a database with schema and user
# Modify the database creation and deletion
# Add configuration file to activiti´s user_home
# Modify the pom.xml
# Running the test project
# Analyze test-results
# Run QA Test suite script

h2. 2.1 Setup a database with schema and user

This should be the easiest part of the description. You need to setup the database you want to test with a schema and a user. The user needs to have enough privileges to execute all the following sql statements.

You may already write down the information that is needed to connect to this database and fetch the jdbc driver for this database. Then you can proceed to the next step.

h2. 2.2 Modify the database creation and deletion

Activiti uses two sql files to create and drop the database tables. These are located at:

*/activiti-engine/src/main/resources/org/activiti/db/create/activiti.&lt;db-profile>.create.sql*

*/activiti-engine/src/main/resources/org/activiti/db/drop/activiti.&lt;db-profile>.drop.sql*

&lt;db-profile> is an identifier; you would also use it to run your tests against. We did that in chapter “Run a test with H2”. Before you can start the testing of Activiti against a new database, you need to setup these two scripts. Start with copying the two files and rename them to your &lt;db-profile> setting. After that you need to work out create, alter and drop statements for your database system. Be cautious to place those files in the same directory\!

h2. 2.3 Add configuration file to activiti´s user home

As we did in the introduction sample, you have to provide the database connection configuration in the activiti user home directory. Please create a properties file like this:

&lt;db-profile>.properties

You need to add the jdbc parameters like this
{code:title=&lt;db-profile>.properties|borderStyle=solid}
jdbc.driver=org.h2.Driver
jdbc.url=jdbc:h2:tcp://localhost/activiti
jdbc.username=sa
jdbc.password=
{code}

This is just a sample configuration for h2\! You need to change the properties to your database environment.

h2. 2.4 Modify the pom.xml

Since the database connection is achieved by jdbc, you need to provide a jdbc-driver for the tests. There are two ways you can provide the jdbc driver:

# Adding the appropriate dependency to maven pom.xml
# Install jdbc driver to your local maven repository

If you have a maven dependency xml snippet for your jdbc driver, fine\! Then you can skip the next step and go directly to step 2 “Modify maven pom.xml”. Otherwise you need to install the library into your local maven repository first.
*1 Install the library into your local maven repository*

*mvn install:install-file \-Dfile=&lt;path to library> \-DgroupId=&lt;groupId>-DartifactId=&lt;artifactId> \-Dversion=&lt;version> \-Dpackaging=jar*

Example for mysql:

*mvn install:install-file \-Dfile=mysql.jar \-DgroupId=mysql \-DartifactId=mysql-connector-java driver \-Dversion=5.1.6 \-Dpackaging=jar*

After having installed the library you should now get the dependency snippet like this:

{code:xml}
&lt;dependency>
   &lt;groupId>mysql&lt;/groupId>
   &lt;artifactId>mysql-connector-java&lt;/artifactId>
   &lt;version>5.1.6&lt;/version>
   *&lt;scope>test&lt;/scope>*
&lt;/dependency>
{code}

You can this example as basis and add your dependency information here. Make sure you have the scope property set to “test”. This dependency is only needed for tests. In a running Activiti scenario you would provide the jdbc driver for the activiti-engine. But this goes beyond the scope of this document.
*2 Modify the pom.xml*

If you open the pom.xml from one of the mentioned projects, you will see an xml file. Navigate to the dependencies area of the database profile. This should like this:

{code:xml}
&lt;profiles>
   &lt;profile>
      &lt;id>database&lt;/id>
      &lt;activation>
         &lt;property>
            &lt;name>database&lt;/name>
         &lt;/property>
      &lt;/activation>
      &lt;dependencies>
         &lt;dependency>
            &lt;groupId>mysql&lt;/groupId>
            &lt;artifactId>mysql-connector-java&lt;/artifactId>
            &lt;version>5.1.6&lt;/version>
            &lt;scope>test&lt;/scope>
         &lt;/dependency>
         &lt;ADD YOUR DEPENDENY HERE>
      &lt;/dependencies>
      &lt;build>
{code}

You can add your database driver dependency at the marked location. Save the file and proceed to the next step. You may return to this step to also modify the pom.xml for the other activiti project.

h2. 2.5 Runing the test project

You can run the test from the command line located in the appropriate test project. This is either “activiti-engine-examples” or “activiti-engine-test-api”. To be sure that your changes in project activiti-engine are up to date, run

*mvn clean install*

from the activiti-engine project location. After that execute this command:

*mvn \--Ddatabase=&lt;db-profile> clean install*

\*&amp;nbsp;*If you got lucky and the test didn´t fail one test, you can proceed with the other project. For the unlucky guys like mine, proceed with the next step\!

h2. 2.6 Analyze test results

This is the hardest part and I can only give you some advice how to get to the cause of test failures. Any test logs errors and output to the target folder. In case of errors search for

*/target/surefire-reports*

These reports should help you a lot to get the conditions on which those errors rely on. The following points are at least a checklist or advice list I found out adding support for some databases:

- If tests fail, drop the database table yourself before running the mvn command once again. The database will only be dropped, if the tests fail on assertion, not on exceptions.

- Debugging tests might help to get the processing right. This helped me a lot to encounter wrong myBatis sqls.

- If you get errors like “database not clean” or “expected 0 got 3”, this could be due to timing problems. We had lots of them adding mysql\! But these might also derive from system performance. At least for some tests with timers.

- Sorting algorithm might also be a point you should consider.

- Always start investigating on the first job that failed. The others might be due to the circumstances that flawed test consigned.

If you encounter a bug in the test, you can file a bug in JIRA\! Otherwise after you fixed something you can once again run the test.

h2. 2.7 Run QA test suite script

Last step is to successfully run the qa script. This test combines creation of activiti-engine and executing all tests for database support. If this test is successful, you have added support for your database environment. We would be happy, if you would provide those scripts to the community.

h2.

h2. 2.7.1 Setup / Configuration

The  following lines will guide you through running the test suite. For this  example we will use MySQL 5.1 as database environment.&amp;nbsp;
* *Checkout activiti project from SVN*
\\
Before you can run the test suite, you need to [checkout activiti&amp;#124;../display/ACT/Developers+Guide#DevelopersGuide-Buildingadistribution\||].  The qa tests are located in the projects 'activiti-engine-examples' and  'activiti-engine-test-api', but you do not need to start            them from there separately. You will start the tests from the  quality assurance project. But before we have to create a new database  schema and user.
* *Create a new schema and user*
\\
First we need to create a new schema and a new user for the  database connection. We set the schema name to 'activiti'.The users name  and  password are 'qa'\! If you need guidance            on how to create a new schema and user for MySQL, please  consult their [documentation|http://dev.mysql.com/doc/]. Now we need to make sure that the test suite gets a database connection.
* *Create a database connection file*
\\
You  need to provide databse connection properties for the test suite to be  executed. This information goes into a file called 'mysql.properties'.  Please create the following folder    structure:
\\
/{user_home}/.activiti/jdbc
\\
Within this directoy create a new file mysql.properties like this:jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://&lt;hostname>:&lt;port>/activiti
jdbc.username=qa
jdbc.password=qa

h2. 2.7.2 Run the test suite

Now we are ready to run the qa script. Navigate to /activiti/trunk/qa/ci and run the script that is suitable for your operating system like this:run-test-db-standalone mysqlIf you would like to run the qa script against H2, then you need to execute this command:run-test-db-standalone h2</pre></td></tr></table>