Migrating to PostgreSQL

This page contains instruction on how to migrate Crucible from the built-in HSQLDB database to PostgreSQL.

On this page:

1. Install PostgreSQL

Install PostgreSQL and follow the steps below.

2. Install the JDBC Drivers

The JDBC drivers for PostgreSQL are bundled with FishEye. Skip to step 2 if this meets your needs. If you want to install a specific, different version of the bundled JDBC driver, download the PostgreSQL JDBC driver .JAR file from the PostgreSQL website and copy the .JAR to your FISHEYE_INST/lib directory (create the lib/ directory if it doesn't already exist). Move the existing JDBC .JAR file to another location (and back it up). Restart FishEye or Crucible to have it pick up the new driver.

3. Create a Database User

Create a new database user (replacing 'username' and 'password' with the appropriate values):

$ psql
> create user username password 'password';

4. Create a UTF-8 Database

Create a UTF-8 database and make the newly created user the owner:

> create database crucible ENCODING 'UTF-8' OWNER username;

5. Set Access Permissions

Make sure the user has full access to the database:

> grant all on database crucible to username;

During the migration process (which will take several minutes, depending on the size of your database and network throughput), the product will be inaccessible to users and external API clients. Users will see a maintenance screen that informs them of the process. Should the migration fail for any reason, Crucible will not switch to the new database and report on the encountered problems. Because the destination database may now contain some, but not yet all data, drop all tables, indexes and constraints before attempting a new migration.

Notes

Truncation of Database Fields

If you are using Crucible 1.6 or earlier with an HSQL database, or have an HSQL database which contains data created by Crucible 1.6 or earlier, truncation of some database fields may occur when migrating to PostgreSQL. You will be notified of field truncations by messages in the migration log, displayed during the migration. The following scenarios may occur:

• A database key is truncated: In this case, the migration will fail. This typically occurs for the Revision ID field where ClearCase has been used with Crucible, as ClearCase can create long revision names. If you experience this problem, please contact support for assistance.
  Error Log message: "The value of column <table name.column name>, has a length of <length> which is greater than the maximum allowed length for this column of <max size of column>. As this column is part of a unique index, the migration cannot be completed."
• A non-key field is truncated: In this case, the migration will not fail, however the field will be truncated. This typically occurs for the Review Name field where the review has been created from a commit message. If you experience this problem, you may wish to update the field via Crucible.
  Error Log message: "Truncating value of column <table name.column name> from '<old value>' to '<value>' because its length of <length of old value> is greater than the maximum allowed length for this column of <max size of column>."