5.5.1Migration Technical Details

5.5.1.1Schema

Smile CDR database migrations are tracked via the FLY_CDR_MIGRATION and FLY_HFJ_MIGRATION tables in the Cluster Manager database.

When a migration is performed, the following actions occur on the Smile CDR Process:

• Acquire Migration Lock Record
• Determine New Migrations
• Perform Migrations
• Release Migration Lock Record

This locking mechanism ensures only one process attempts to perform an upgrade.

5.5.1.2Migration Lock Record

The migration tool uses a simple lock-record mechanism to ensure that only one process in a cluster is performing a database migration at a time. This lock-record has an installed_rank of -100 and a unique value (UUID) in the description column. The migration operation automatically deletes this lock record upon completion, even if there was a migration error.

However in some failure scenarios, (e.g. loss of database connection in the middle of a migration), it is possible that this lock record will not be properly removed after the migration is complete. If this happens, you can set the CLEAR_LOCK_TABLE_WITH_DESCRIPTION environment variable (or System Property) to the value of the description of this lock record to instruct Smile CDR to delete it before starting a new migration. See more details about this operation here.

For example, if your server fails to start up with an error message like the following:

HAPI-2153: Unable to obtain table lock - another database migration may be running.
If no other database migration is running, 
then the previous migration did not shut down properly 
and the lock record needs to be deleted manually.
The lock record is located in the FLY_CDR_MIGRATION table with 
INSTALLED_RANK = -100 and DESCRIPTION = 2981dc98-6111-4892-b3f9-56b9d559f4d7

Then before starting Smile CDR you could call:

export CLEAR_LOCK_TABLE_WITH_DESCRIPTION=2981dc98-6111-4892-b3f9-56b9d559f4d7

This will cause Smile CDR to delete this stale lock record before starting a new database migration.

Before 2022.11.R01, Smile CDR used Flyway for tracking migrations. From 2022.11.R01 onwards, it now uses the hapi-fhir-sql-migrate tool.

This tool is backwards compatible with Flyway database migrations and shares the same schema migration history tables that Flyway used: FLY_CDR_MIGRATION for the Cluster Manager database and FLY_HFJ_MIGRATION for the FHIR Repository database.