Troubleshooting database migration issues

When migrating from one version of Unblu to another, you often have to migrate the database as well. Although database migration issues are rare, they can occur. This article describes how to troubleshoot a number of issues that may arise during database migration.

Categories of database migration issues

Database migration issues can be grouped into the following categories:

Connection issues: The Collaboration Server is unable to connect to the database.
Missing database user privileges.
Issues with Liquibase tables.
Migration fails with database errors.
Migration fails while migration changes are in progress.
Creating the main account fails.

Connection issues

There are a number of possible causes if the Collaboration Server has issues connecting to the database:

Verify the values of the following configuration properties:
Connection problems within the customer infrastructure (collab-server → DB-server)
Verify that the Unblu database user and the database admin user exist.
If you’re migrating from your staging to your production environment, check that you’re using the correct password for the environment in question.

Missing database user privileges

These issues fall into two different categories:

The admin user doesn’t have the correct privileges on the database.
The normal user can’t access the Unblu database tables.

The admin user doesn’t have the correct permissions on the database

Verify that the database admin user exists and has the required access privileges.
If you’re trying to recover the Unblu database from a backup, the user may not have been recovered.
If you’re migrating the Unblu database from your staging to your production environment, the required access privileges may not have been granted yet.

The normal user can’t access the Unblu database tables

Error messages such as "Table or view does not exist" or "Object does not exist" are a sign that the Unblu database user lacks the required privileges.

Verify that the user you’ve set up for Unblu to access the database actually has the necessary privileges.
If you’re running the Unblu database on Oracle, there may be a missing trigger. Review Setting up Oracle for Unblu.
If you’re trying to recover the Unblu database from a backup, ensure the Liquibase tables have been restored correctly.
If you’re migrating the Unblu database from your staging to your production environment, check that the Liquibase tables have been migrated correctly.

Issues with Liquibase tables

Changes to Unblu’s database schema may result in a database that doesn’t work with older versions of the Collaboration Server. Verify that the version of your Unblu database is compatible with the version of the Collaboration Server you’re running.
If you’re trying to recover the Unblu database from a backup, ensure the Liquibase tables have been restored correctly.
If you’re migrating the Unblu database from your staging to your production environment, check that the Liquibase tables have been migrated correctly.
Issues with Liquibase tables also arise if you terminated the Collaboration Server while migrating the database.

Migration fails with database errors

Go through the points listed in the section Issues with Liquibase tables above. You may, however, have encountered an issue with Unblu that isn’t covered by our tests.

Migration fails while migration changes are in progress

Go through the points listed in the sections Issues with Liquibase tables and Migration fails with database errors above.

Additionally, this type of issue can arise if the checksum is wrong because the change set has changed after the initial migration run.

Creating the main account fails

This issue can be the result of corrupt Liquibase tables. Go through the points listed in the section Issues with Liquibase tables above.