Skip to content

Backward-compatible migration/upgrade

Definition

A backward-compatible modification is a modification that allows the future Catalogue schema to be used by the current CTA version and the new version of CTA.

Example: CTA version 1.0 currently runs on Catalogue version 1.0. Updating the schema from 1.0 to 1.1 with only backward-compatible modifications will not avoid the version 1.0 of CTA to run against the new schema version 1.1.

Backward-compatible modifications

Here is a list of backward-compatible modifications:

  • Add a TABLE or a VIEW
  • Add a COLUMN
  • Remove a COLUMN that is not used by the current CTA version nor the new version of CTA
  • Remove a CONSTRAINT
  • Add an INDEX

Upgrade script creation and testing steps

1. Check the Catalogue database-to-migrate schema consistency

Check that the Catalogue database-to-migrate schema is the version you expect and that it does not contain any modifications. This check has to be done with the cta-catalogue-schema-verify tool.

$ cta-catalogue-schema-verify path_to_catalogue_configfile.conf
Schema version : 1.0
Checking indexes...
  SUCCESS
Checking tables, columns and constraints...
  SUCCESS
Status of the checking : SUCCESS

2. Create the Liquibase Changelog file

Follow the instructions to create the liquibase changelog file.

3. Run the Liquibase updateSQL command

Run the Liquibase updateSQL command to display the SQL statements that will be executed for the upgrade.

$ JAVA_OPTS="-Doracle.net.tns_admin=/etc" liquibase --defaultsFile=path_to_configuration_properties --changeLogFile=relative/Path/to/CTA/catalogue/s/liquibase/databasetype/1.0to1.1.sql updateSQL

4. Run the upgrade

$ JAVA_OPTS="-Doracle.net.tns_admin=/etc" liquibase --defaultsFile=path_to_configuration_properties --changeLogFile=relative/Path/to/CTA/catalogue/migrations/liquibase/databasetype/1.0to1.1.sql update

5. Check the upgrade is successful

Use the cta-catalogue-schema-verify tool in order to verify the upgrade is successful against the new version of the Catalogue schema.

$ cta-catalogue-schema-verify path/to/catalogue/configfile.conf

How to rollback the upgrade

Warning

Rollback an upgrade is not always possible

If you defined --rollback statements in all your ChangeSets, you can Rollback the upgrade of the Catalogue schema. You have to choose the number of ChangeSets you wish to rollback.

Display the SQL statements that will be executed for the rollback :

$ JAVA_OPTS="-Doracle.net.tns_admin=/etc" liquibase --defaultsFile=path_to_configuration_properties --changeLogFile=relative/Path/to/CTA/catalogue/migrations/liquibase/databasetype/1.0to1.1.sql rollbackCountSQL <number_of_changeSets_to_rollback>

Run the rollback :

$ JAVA_OPTS="-Doracle.net.tns_admin=/etc" liquibase --defaultsFile=path_to_configuration_properties --changeLogFile=relative/Path/to/CTA/catalogue/migrations/liquibase/databasetype/1.0to1.1.sql rollbackCount <number_of_changeSets_to_rollback>