MySQL™ Audit Trail Database Setup

This section addresses the setup and installation of a MySQL audit trail database. The section includes setup of MySQL, creation of the MySQL audit trail database and schema.

Prerequisites

The following sections assume as basic understanding of MySQL database server installation and configuration.

Before an audit trail database can be created, a properly installed and configured instance of a MySQL database server must exist. Refer to the Stardust Release Notes for details on the currently supported MySQL version. MySQL can be downloaded from the following MySQL Download Website.

After downloading MySQL, install MySQL onto the database server. The server installation directory is referred to as %MYSQL_INSTALL%.

Create an empty directory to store the MySQL databases. This directory is referred to as %MYSQL_DATA%.

Configure the %MYSQL_INSTALL%/mysql.ini file, to contain the following entries in the [mysqld] section:

[mysqld]
# set basedir to your installation path
basedir=%MYSQL_INSTALL%
# set datadir to the location of your data directory
datadir=%MYSQL_DATA%
# set transaction isolation level to read-committed as required by Stardust
transaction-isolation = READ-COMMITTED

If MySQL is executing in a Unix environment, you should also add the following line to the [mysqld] section of the mysql.ini file to make the database portable between Unix and Windows:

lower_case_table_names = 1

Start the database server by issuing the following command from directory %MYSQL_DATA%:

%MYSQL_INSTALL%/bin/mysqld

Other methods to start the MySQL database server may be available such as the Service Control Panel for Windows based installations.

Once the database is started, invoke the MySQL client to continue the creation of the Stardust audit trail database.

%MYSQL_SYSTEM%/bin/mysql -h <hostname> -u <username> -p

Enter the password at the prompt.

If login is successful, the following is displayed:

Enter password: *****
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 29 to server version: 5.0.27-community-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql>

Verify the configuration by issuing the following command

mysql> show variables like '';
+---------------+-------------------+
| Variable_name | Value             |
+---------------+-------------------+
| base_dir      | %MYSQL_INSTALL% |
| datadir	| %MYSQL_DATA |
| tx_isolation  | READ-COMMITTED    |
+---------------+-------------------+

The next sections discuss database and schema creation for a MySQL audit trail database. This process utilizes the Stardust System Console utility. To execute properly, the MySQL JDBC driver must be copied into the default/lib directory of your working environment.

More information on the System Console utility can be found at Sysconsole.

Enforcing Unicode Usage

In case you use a language with multi-byte character sets, like Chinese or Japanese, you might face deployment issues. To avoid these issues, explicitly inform the driver that the database Strings are UTF-8 encoded.

Setting Unicode for Spring / MySQL

Using Spring, you have the following two options:

  1. In your carnot.properties file append the following line to property Audittrail.URL, where you pass the connection properties to the driver: 
    ?useUnicode=true&characterEncoding=UTF-8

    e.g.:

    AuditTrail.URL = jdbc:mysql://localhost/mydatabase?useUnicode=true&characterEncoding=UTF-8
  2. or, in your carnot-spring-ds-jndi-context.xml file enter the URL directly in the spring bean carnotXaAuditTrailDataSourceLocalURL, e.g.: 
    <bean id="carnotXaAuditTrailDataSourceLocalUrl" class="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource" lazy-init="true">
    <property name="url" value="${AuditTrail.URL}?useUnicode=true&characterEncoding=UTF-8" />
    <property name="user" value="${AuditTrail.User}" />
    <property name="password" value="${AuditTrail.Password}" />
</bean>

Setting Unicode for JBoss / MySQL

To set unicode for JBoss / MySQL, open the datasource definition and in the property defining the URL append the following:

?useUnicode=true&characterEncoding=UTF-8

For example:

<datasources>
   ...
      <connection-url>jdbc:mysql://localhost:3306/jboss?useUnicode=true&characterEncoding=UTF-8</connection-url>

Note that you have to quote & because it is a xml file.

Setting Unicode for other Application Server / MySQL

For all other application server applies to append the connection properties to the connection URL:

?useUnicode=true&characterEncoding=UTF-8

Database Creation

At the mysql> prompt, execute the following commands to create the database with name dbName:

mysql> CREATE DATABASE <dbName>;

Create a new user with all privileges:

mysql> GRANT ALL PRIVILEGES ON *.* TO '<username>'@'localhost' IDENTIFIED BY '<password>' WITH GRANT OPTION;

Schema Setup

Once the database has been created, the audit trail database schema must be created within MySQL. This process utilizes the System Console utility provided with Stardust. Execute the System Console with the following arguments:

sysconsole -v -r <jdbcDriver> -dbtype MYSQL -dbschema <dbschema> -l jdbc:mysql://<host>:<port>/<dbName> -d <user> -s <password> createschema

The following is displayed after the command is invoked:

Stardust (TM) Administration Console, Version 4.x
Copyright (C) SunGard CSA LLC, 2000-2011. All rights reserved.

Create Stardust schema:

Database type   : MYSQL
Database URL    : jdbc:mysql://<host>:<port>/<dbName>
Database user   : <user>
Database driver : <jdbcDriver>

Do you want to proceed? (Y/N):

Answer Y to proceed. The following is displayed after successful creation of the audit trail database schema.

Schema created.

Alternative Schema Setup

If you do not have the ability to directly create the database schema because of privileges within your database environment or desire to create a file with the appropriate SQL commands, the following procedures can be followed to create a file containing the appropriate DDL and DML statements that can be executed within the database as a SQL script.

sysconsole -v -dbtype MYSQL ddl -file <fileName> -schemaName <schemaName>

Once the DDL/DML file has been created by the previous command, follow the Database asetup instructions from the previous sections if not already completed, and then have a user with appropriate privileges execute the created DDL/DML script file as such:

mysql> source <fileName>

Local and Remote Mode Setup

The following sections discuss the datasource / database connection pool setup of the audit trail database based on the deployment mode.

Spring Local Mode Setup

If you use Stardust in Spring local mode, you have to perform the following steps:

  1. In your carnot.properties file add the following properties: 
    AuditTrail.Type = MYSQL
    
AuditTrail.DriverClass = com.mysql.jdbc.Driver
    
AuditTrail.URL = jdbc:mysql://<yourhost>/<dbName>
    
AuditTrail.User = <yourDBUserName>
    
AuditTrail.Password = <yourDBUserPassword>
    Set the type of the audit trail database to MYSQL and use the database driver class com.mysql.jdbc.Driver.
  2. In your carnot-spring-ds-jndi-context.xml replace the parameter ${AuditTrail.XaDataSourceClass} in the carnotXaAuditTrailDataSourceLocalUrl bean part with class com.mysql.jdbc.jdbc2.optional.MysqlXADataSource: 
    <bean id="carnotXaAuditTrailDataSourceLocalUrl" class="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource" lazy-init="true">
    <property name="url" value="${AuditTrail.URL}" />
    <property name="user" value="${AuditTrail.User}" />
    <property name="password" value="${AuditTrail.Password}" />
</bean>

Remote Mode Setup

The audit trail database datasource and connection pool setup is configured based on the application server/container utilized for the Stardust deployment. Refer to Application Server Setup for more information regarding datasource and connection pool setup for an audit trail database.

MySQL Sequence Support (required for using Transient Processes)

Per default, MySQL does not support the usage of transient processes. You need to prepare a MYSQL sequence support. Stardust provides a database descriptor that:

To use this descriptor, set the AuditTrail.Type in your carnot.properties file to MYSQL_SEQ or use the global option -dbtype=MYSQL_SEQ in your Sysconsole command.

Use the Sysconsole command with option auditTrail to provide MySQL sequence support. For details refer to option auditTrail in chapter The Sysconsole Command in the Operation Guide.

Use the FastCachingSequenceGenerator to retrieve sequence numbers in a batch and cache the retrieved sequences separately for every entity type. Set the property AuditTrail.SequenceGenerator in your server-side carnot.properties file to:

AuditTrail.SequenceGenerator = 
   org.eclipse.stardust.engine.core.persistence.jdbc.sequence.FastCachingSequenceGenerator

Refer to section Configure fast caching sequence generators in chapter Tuning for low Latency and high Throughput of the Operation Guide for details.

Using Prepared Statements in case of String Chunks ending with Backslash

During model deployment, the model is split into several chunks of Strings that are stored in the STRING_DATA table. In case such a chunk ends with a backslash, the INSERT statement fails with an SQL exception on MySQL. To avoid this problem set the property AuditTrail.UsePreparedStatements in your carnot.properties file to true to use prepared statements.

AuditTrail.UsePreparedStatements = true

Now the string chunk is added as bind value and the model can be deployed without any problem.