Preparing the PostgreSQL Database for Installation

codebeamer (Emma or higher) supports PostgreSQL (for details please refer codebeamer release specific requirements) and for some optional and performance improving features requires the contrib extensions. In some cases this needs to be installed separately; for example on some Linux distributions like CentOS.

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 PostgreSQL database is not part of this document. Please refer to the PostgreSQL for instructions.

codebeamer Windows installer comes with a built-in batteries included PostgreSQL instance which has all the necessary pre-requisites to use codebeamer. However the built-in database is only suitable for testing and in production environment it is recommended to install a separate database server.

Built-in Postgres requires the installation of Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019 which is not part of the codebeamer installation package. Please download and install it manually if you wish to use this feature. Architecture of the redistributable has to match the codebeamer installation package's architecture.

Linux

Install PostgreSQL via your distribution's package manager. By some distributions the additional contrib extensions reside in a separate package. It is recommended to install this as well to enable some optional and performance improving features.

PostgreSQL Configuration

When installing PostgreSQL, 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 postgresql.conf, that typically resides in the PostgreSQL data directory (e.g. in Windows: C:\Program Files\PostgreSQL\12\data\postgresql.conf, or Linux/Unix: /var/lib/postgresql/data/postgresql.conf (or /etc/postgresql/12/main/postgresql.conf), or MAC-OS: /usr/local/var/postgres/postgresql.conf).

effective_io_concurrency = 200
jit = on
max_locks_per_transaction = 5000
random_page_cost = 1.1
temp_buffers = 64MB
work_mem = 80000
default_statistics_target = 1000
checkpoint_timeout = 2700

It might be useful checking this https://pgtune.leopard.in.ua page.

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.

Prepare the codebeamer PostgreSQL database

In this step we assume the PostgreSQL is running on the default 5432 port.

In order for codebeamer to access a PostgreSQL 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 $POSTGRESQL_HOME$/bin directory (for example in Windows it could be C:\Program Files\PostgreSQL\12\bin).
2. Execute the command: psql -U postgres. When asked provide it with the password which was configured during installation.
3. Execute commands (if running Postgres on Windows Server use en_US character collation instead of en_US.UTF-8):
   

   CREATE DATABASE codebeamer LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' ENCODING 'UTF8' TEMPLATE = template0;
   CREATE USER cbroot WITH PASSWORD 'CbPassword01!';
   ALTER DATABASE codebeamer OWNER TO cbroot;

4. In case PostgreSQL's contrib package is also installed, execute the following:
   

   \c codebeamer
   CREATE EXTENSION pg_trgm;

Configure codebeamer to use the PostgreSQL database

Edit/create the configuration file: <cb-installation-dir>/config/configuration.properties

database.driver=org.postgresql.Driver
database.connectionURL=jdbc:postgresql://localhost:5432/codebeamer
database.username=cbroot
database.password=CbPassword01!
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.

Full-text index on TASK table

This feature requires the PostgreSQL contrib extensions installed on the database server. By some distributions (for example CentOS) these reside in a separate package and needs to be installed separately.

For more information about the database specific configuration process, see: Database Specific Configurations - PostgreSQL.