You are not logged in. Click here to log in.

codeBeamer ALM

Search In Project

Search inClear

Tags:  not added yet
IMPORTANT: This page is deprecated and will be removed soon because the user is now able to set up their databases during the installation processes.

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 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. We recommend installing the latest recommended release for your platform.


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).

  • Use UTF-8 as database default:
    character-set-server = utf8

  • Allow using up to 128MB large attachments.

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

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

Following the introduction of the post-installation wizard in version 7.6.0, the following steps are not required for new installations, because the database is created automatically. 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 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';

The extra "GRANT FILE ..." is necessary due to a bug in some MySQL versions, where ALL PRIVILEGES doesn't include FILE. It might be also necessary to change SELinux systems to permissive mode using: setenforce Permissive. For more information see this URL.

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;
  RETURN mask & bits;
DROP FUNCTION testProcPermissions;

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';

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:


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

Please don't forget to remove or disable all other <database ...></database> sections by surrounding them with XML comments.


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.