This section addresses the setup and installation of a Derby audit trail database. The section includes setup of Derby, creation of the Derby audit trail database and schema.
The following sections assume a basic understanding of Derby database server installation, configuration and the Derby 'ij' utility.
Before an audit trail database can be created, a properly installed and configured instance of a Derby database server must exist.
After downloading Derby, install Derby onto the database server. The server installation directory is referred to as %DERBY_HOME%.
Running process instance queries or reporting requests against an audit trail containing process instances having descriptors on uninitialized structured data values may be very slow for Derby databases. In that case we recommend to use prepared statements to improve the performance.To use prepared statements, set the property AuditTrail.UsePreparedStatements in your carnot.properties file to true. For details on using this property refer to section Using Prepared Statements of chapter Database Access Tuning of the Operation Guide.
The following tasks must be performed to setup the Derby server, database directories and security.
Create a new empty directory to contain the new database instance. This directory is referred to as %DERBY_SYSTEM%.
Create a new file %DERBY_SYSTEM%/derby.properties. Add the following entry:
# base setup derby.system.home=%DERBY_SYSTEM%
Stardust databases must run in read-committed mode. By default the transaction isolation level for Derby databases is set to READ_COMMITTED. If set to another value, change the value to the following entry in the %DERBY_SYSTEM%/derby.properties file:
derby.language.defaultIsolationLevel=read_committed
Start the database server by issuing the following command from the directory %DERBY_SYSTEM%, resulting in a message like "server is ready to accept connections on port 1527." on success:
%DERBY_HOME%/bin/startNetworkServer.bat
Create a Derby database to store the Stardust schema by executing the Derby SQL console:
%DERBY_HOME%/bin/ij.bat
At the prompt, execute the commands to create the database with name <dbName>. At this time, the database does not contain any security information.
ij> CONNECT 'jdbc:derby://localhost/<dbName>;create=true';
If security is desired, enable database security by adding the
following entries to
%DERBY_SYSTEM%/derby.properties prior to starting the
database server.
If the database server is running, restart the database server. The
following example shows adding two users: user
sa with password
derby and user
carnot with password
ag.:
# security setup
derby.connection.requireAuthentication=true
derby.authentication.provider=BUILTIN
derby.user.sa=derby
derby.user.carnot=ag
Additional properties can be added to the %DERBY_SYSTEM%/derby.properties as explained in the Derby Tuning Guide.
With security enabled, the CONNECT command must specify authentication information as shown:
ij> CONNECT 'jdbc:derby://<host>/<dbName>;create=true;user=<dbUser>;password=<dbPassword>';
Once the user has been created, the audit trail database schema must
be created within Derby. This process utilizes the System Console
utility provided with Stardust.
Execute the System Console with the following arguments:
sysconsole -v -r <jdbcDriver> -dbtype Derby -dbschema <dbschema> -l jdbc:derby://<host>/<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 : Derby Database URL : jdbc:derby://<host>/<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.
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 Derby ddl -file <fileName> -schemaName <schemaName>
Once the DDL/DML file has been created by the previous command, follow the Database setup instructions from the previous sections if not already completed, and then have a user who has appropriate privileges execute the created DDL/DML script file as such:
ij> run '<fileName>';
The following sections discuss the datasource / database connection pool setup of the audit trail database based on the deployment mode.
If you use Stardust in Spring local mode, you have to perform the following steps:
AuditTrail.Type = DerbySet the type of the audit trail database to Derby and use the database driver class specific to your installation of Derby.
AuditTrail.DriverClass = <jdbcDriver>
AuditTrail.URL = jdbc:derby://<host>/<dbname>
AuditTrail.User = <yourDBUserName>
AuditTrail.Password = <yourDBUserPassword>
AuditTrail.Instance =
AuditTrail.Port =
AuditTrail.Host =
<bean id="carnotXaAuditTrailDataSourceLocal" class="org.apache.derby.jdbc.ClientXADataSource" lazy-init="true">
<property name="serverName" value="${AuditTrail.Host}" />
<property name="portNumber" value="${AuditTrail.Port}" />
<property name="databaseName" value="${AuditTrail.Instance}" />
<property name="user" value="${AuditTrail.User}" />
<property name="password" value="${AuditTrail.Password}" />
</bean>
Appropriate JDBC drivers must be copied from the %DERBY_INSTALL%/lib/ directory to the lib directory of your working environment.
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.