Introduction

CloudStack DB upgrade takes care of updating the database schema and updating data (if needed) between the releases. The upgrade is initiated by the cloud-management process start - if the version of the software installed is greater than the data base version, the upgrade is being performed.

DB upgrade code structure

• When management server starts up, we perform number of system integrity checks. All the checker classes inherit from SystemIntegrityChecker interface, and have to be listed in components.xml configuration file (last 2 checks are DB upgrade related checks): <system-integrity-checker>
          <checker name="ManagementServerNode"/>
          <checker name="EncryptionSecretKeyChecker"/>
          <checker name="DatabaseIntegrityChecker"/>
          <checker name="DatabaseUpgradeChecker"/>
      </system-integrity-checker>The checkers are executed in the order they are defined.

...

• DataBaseUpgradeChecker determines the current version of the software from the RPM package, and compares it with the latest DB version taken from the last row in cloud.version table. If the DB version is less than the software version, we decide which set of upgrade files should be executed - get the set from _upgradeMap table.
• For each file defined in upgrade set, DataBaseUpgradeChecker  1) DBUpgrade.getPrepareScripts() and run the scripts with runScript() 2) DBUpgrade.performDataMigration(). Execution order is the same as the files appear in upgrade set.
• After prepareScripts and dataMigration is finished, DataBaseUpgradeChecker executes the cleanup part for all the files from upgrade set - DBUpgrade.getCleanupScripts() and run them with runScript(). Cleanup scripts are very useful in case when some data has to be dropped, but only at the end of the upgrade as we rely on this data while performing the "Data Migration" part.
  

Adding new upgrade path

Lets assume we already released 3.0.2 version of the product, and started development for 3.0.3. If anything from below is modified in 3.0.3 release, we need to provide the DB upgrade:

...

6) And the last step - always add the and execute UnitTest for the db upgrade path. You can look atAdvanceZone217To224UpgradeTest to get the idea.

Hints

• When you want to drop the field/key that existed in N-2 version, but was missing in N-1 version, you have to handle both scenarios in N-1->N upgrade. Do it in the Java code, performDataMigration() method using these calls from DbUpgradeUtils helper class:
       - dropKeysIfExist
       - dropPrimaryKeyIfExists
      - dropTableColumnsIfExist* Always close ResultSet and PreparedStatements in finally() block during the DataMigration. It helps to eliminate memory leaks.

• If you want to suppress errors in INSERT (be careful with this though), use INSERT IGNORE as opposed to INSERT. We mostly use it when have to insert global config variable missing in just some of the previous releases:       

  No Format
  INSERT IGNORE INTO `cloud`.`configuration` VALUES ('Advanced', 'DEFAULT', 'management-server', 'direct.agent.load.size', '16', 'The number of direct agents to load each time');

   
  

Known issues

• No rollback is supported. We always insist on saving the DB dump before running the upgrade so in case something goes wrong, the Admin can do manual rollback.