Migrating to MySQL Enterprise Server

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

On this page:

1. Install MySQL

Install MySQL Enterprise Server and follow the steps below.

2. Install the JDBC Drivers

The JDBC drivers for MySQL Enterprise Server are bundled with FishEye. Skip to step 3 if this meets your needs. If you want to install a specific, different version of the bundled JDBC driver, download the MySQL Enterprise Server JDBC driver .JAR file from the download 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 UTF-8 Database

Run the commands below to create a UTF-8 database. Note that the DB must be case-sensitive, i.e. it must use the utf8_bin collation sequence.

CREATE DATABASE crucible CHARACTER SET utf8 COLLATE utf8_bin;

4. Set the Server Characterset to UTF-8

You will need to set the Server Characterset to utf8. This can be done by adding the following in my.ini for Windows or my.cnf for other OS. It has to be declared in the Server section, which is the section after [mysqld]:

[mysqld]
default-character-set=utf8

Also set the value here:

[mysql]
default-character-set=utf8

5. Verify Database Character Encoding Information

Use the status command to verify database character encoding information:

Screenshot: Using the MySQL Enterprise Server Status Command

6. Create a Database User

Create a user that can log in from the host that Crucible or FishEye is running on and make sure that the user has full access to the newly created database. In particular, the user should be allowed to create and drop tables, indexes and other constraints.

For instance, when Crucible and MySQL Enterprise Server run on the same machine (accessible through localhost), issue the following commands (replacing username and password with the appropriate values):

mysql> grant all on crucible.* to 'username'@'localhost' identified by 'password';
Query OK, 0 rows affected (0.00 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.01 sec)

7. Configure the Database for FishEye/Crucible

With the database prepared, navigate to the 'Database Configuration' section in the admin interface, select MySQL Enterprise Server from the drop down and fill out the database URL, username and password.

Then click 'Test Connection' to verify that Crucible or FishEye can log in to the database:

Screenshot: Testing the Connection

If this fails, verify that you have the MySQL Enterprise Server JDBC driver .JAR file in the classpath (by placing the .JAR file in FISHEYE_INST/lib). Also, ensure that the database user can log in to the database from the machine that Crucible or FishEye is running on and that all the required privileges are present.

8. Start the Migration Process

Click 'Save & Migrate Data' to start the migration process.

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.

Screenshot: Migrating the Database

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 MySQL. 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>."