It is strongly recommended also reading Preparing MySQL Database for Installation - v10 and Later

Preparing the MySQL Database for Installation

codeBeamer is delivered with a Derby database 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 and reliable databases.

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

IMPORTANT: Backup your data! Before doing anything, backup your existing database. Also ensure that during migration nobody uses the database, because it may cause loss of data.

Windows, Unix, MAC-OS

Downloading and installing the MySQL database is not part of this document. Please refer to the MySQL homepage for instructions.

Linux

Install MySql via your distribution's package manager.

We highly recommend to use the same version that codeBeamer was tested on. You can this version in the release note of the current version.

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:\ProgramData\MySQL\MySQL Server 5.7, or Linux/Unix: /etc/mysql/my.cnf, or MAC-OS: /usr/local/mysql/my.cnf).

[mysqld]
character-set-server=utf8
collation-server=utf8_general_ci
max_allowed_packet=128M

Creating the database

The following steps are not required for new installations, because the database is created automatically by the installer. These steps are only necessary when upgrading or migrating codeBeamer, or when the database is created manually for any other reason.

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 cbpassword used below:

1. Open a command prompt (on Windows execute "cmd"), and go into your $MYSQL_HOME$/bin directory (for example in Windows it could be C:\Program Files\MySQL\MySQL Server 5.7\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';
   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/create the configuration file: <cb-installation-dir>/config/configuration.properties

database.driver=com.mysql.jdbc.Driver
database.connectionURL=jdbc:mysql://localhost:3306/codebeamer?autoReconnect=true&zeroDateTimeBehavior=convertToNull&emulateLocators=true&characterEncoding=UTF-8&useSSL=false
database.username=user
database.password=pass
database.passwordStorageType=PLAIN

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.