Preparing the MySQL Database for Installation

CodeBeamer is delivered with the database Derby that should be used only for evaluation purposes. It is strongly recommend using codeBeamer with MySQL or Oracle because they are faster and more robust databases.

This page describes how to setup a MySQL for codeBeamer. Currently MySQL 5.5.x and 5.6.x are supported and InnoDB storage engine is required. To use this document you should be familiar with MySQL database setup and administration.

Windows, Unix, MAC-OS

Downloading and installing the MySQL database is not part of this document. Please refer to the MySQL homepage for instructions. We recommend installing the latest recommended release for your platform.

Linux

Install MySql via your distribution's package manager.

MySql Configuration

When installing MySQL, be sure to set and remember a sensible root password.

Please ensure that the following settings are configured in your database. You can find these settings in my.ini, that typically resides in the MySQL installation directory (e.g. in Windows: C:\Program Files\MySQL\MySQL Server 5.5, or Linux/Unix: /etc/mysql/my.cnf, or MAC-OS: /usr/local/mysql/my.cnf).

• Allow using up to 128MB large attachments.

  [mysqld]
  max_allowed_packet=128M

• From MySql 5.5.x the option below is required to avoid Thread stack overrun:

  [mysqld]
  thread_stack=256K

With MySQL 5.5 (and later), InnoDB becomes the default storage engine, therefore no transaction support configuration is required. However if you use an earlier version for legacy reasons please make sure InnoDB is configured.

Creating the database

In the following examples, it is assumed that the database is running on the same machine as codeBeamer (localhost) and listens to default port 3306, but this is not required.

Prepare the codebeamer MySQL database

In order for codeBeamer to access a MySQL database, an appropriate database schema and user have to be prepared. You can use any username and password instead of the cbroot and cbpasswordused below:

1. Open a command prompt (on Windows XP execute "cmd"), and go into your$MYSQL_HOME$/bin directory (for example in Windows it could be C:\Program Files\MySQL\MySQL Server 5.1\bin).
2. Execute the command: mysql -u root -p. When asked provide it with the password which was configured during installation.
3. Execute commands:

CREATE DATABASE codebeamer default character set 'utf8' default collate 'utf8_general_ci';
GRANT ALL PRIVILEGES ON codebeamer.* TO 'cbroot'@'localhost' IDENTIFIED BY 'cbpassword';
GRANT FILE, PROCESS ON *.* TO 'cbroot'@'localhost';
COMMIT;
FLUSH PRIVILEGES;

Check cbroot user permissions

The codebeamer database user ("cbroot") needs sufficient permissions to create stored procedures. In some older MySQL 5.0 installations, therefore also the "SUPER" privilege may be required. If creating the stored procedures is not possible during the database installation or upgrade, the resulting database schema may be unusable.

To check permissions, connect to the MySQL instance as user "cbroot" (mysql -u cbroot -p codebeamer) and execute the following commands:

DROP FUNCTION IF EXISTS testProcPermissions;
DELIMITER //
CREATE FUNCTION testProcPermissions(mask INT, bits INT) RETURNS INT DETERMINISTIC NO SQL SQL SECURITY INVOKER
BEGIN
  RETURN mask & bits;
END;
//
DELIMITER ;
DROP FUNCTION testProcPermissions;
SHOW ENGINE INNODB STATUS;

If any of these commands fails with an error that says something like "You do not have the SUPER privilege ...", then you must also grant the SUPER privilege to the cbroot user (mysql -u root -p mysql):

GRANT SUPER ON *.* TO 'cbroot'@'localhost';
COMMIT;
FLUSH PRIVILEGES;

Configure codeBeamer to use the MySQL database

Edit the configuration file: <cb-installation-dir>/tomcat/webapps/cb/WEB-INF/classes/general.xml

The database connection is defined in the <database ... ></database> section.

The configuration should already contain a template for MySQL (as example below), that you can simply uncomment and modify, otherwise you will have to add a new section as follows:

<database
  JDBC_Driver="com.mysql.jdbc.Driver"
  JDBC_ConnectionURL="jdbc:mysql://localhost:3306/codebeamer?autoReconnect=true&zeroDateTimeBehavior=convertToNull&emulateLocators=true&characterEncoding=UTF-8"
  JDBC_Username="cbroot"
  JDBC_Password="cbpassword"
></database>

You will probably have to adjust the hostname, port, database, username and password for your installation.

<!--
<database
   JDBC_Driver="org.apache.derby.jdbc.ClientDriver"
  ...
></database>

-->

Start codeBeamer

Please note, that after switching to a new database, the initial codeBeamer server start will take longer than usual, because codeBeamer will first initialise the new empty database schema.