Creating an upgrade environment

When you upgrade one or more colonies in a sharded environment, you must first create an upgrade environment and then move the colonies that are to be upgraded from the production environment to the upgrade environment.

About this task

Note: You must create a new upgrade environment each time you upgrade colonies. For example, if colonies 1 and 2 were upgraded six months ago, and you are now upgrading colonies 3 and 4, you must create a new upgrade environment.

To create an upgrade environment, perform these steps:


  1. In sharded mode, install a new run time in the version that corresponds to the current version of your production environment. This new run time will serve as your upgrade environment. For purposes of describing the two run times, let us refer to the new run time as Upgrade_V1 and the run time for the production environment as Production_V1.

    For example, if you are running a sharded deployment on Release 9.5, perform a complete installation of Release 9.5 in sharded mode. When you perform a complete installation, a DEFAULT colony is created with new METADATA, SYSTEM CONFIGURATION, STATISTICS, and TRANSACTION/MASTER shards.

    Note: As part of creating Upgrade_V1, perform the following tasks:
    • Copy all extensions from Production_V1 to Upgrade_V1.
    • If you installed any PCAs on Production_V1, install the same PCAs on Upgrade_V1.
    • Ensure the database tables in Upgrade_V1 are identical to the database tables in Production_V1 by rebuilding the resources.jar and entities.jar files on Upgrade_V1.
  2. For each colony you are upgrading, you must add a new colony to Upgrade_V1. The new colonies correspond to the colonies that you are moving from Production_V1.

    Use the manageColony command to add the new colonies to Upgrade_V1. This command passes the addColony.xml file, which contains database information for the new colonies and their shards. In Upgrade_V1, execute the following command, where <path> corresponds to the absolute path for addColony.xml.

    For UNIX and Linux® operating systems:

    • <INSTALL_DIR>/bin ./ <path>/addColony.xml

      For Windows operating systems:

    • <INSTALL_DIR>\bin manageColony.cmd <path>\addColony.xml

      You must manually configure the addColony.xml file before you can execute the manageColony command.

      Note: When configuring a new colony in the addColony.xml file, you must make the following edits:
      • Ensure that the new colony's shards point to the DEFAULT colony's shards in Upgrade_V1, and the new colony's information, such as name and pkprefix, are identical to the corresponding colony in Production_V1.

        For example, if the colony you are moving from Production_V1 has the parameters name=colony_01 and pkprefix=11, the new colony in the XML file should have the parameters name=colony_01 and pkprefix=11, and the new colony's shards should point to the DEFAULT colony's shards on Upgrade_V1.
      • Ensure that the pool ids for the new colony's CONFIGURATION and STATISTICS table types are identical to the corresponding pool ids in Upgrade_V1.
  3. If a hot fix was applied to Production_V1, apply the same hot fix to Upgrade_V1.
  4. Use the CDT to move the configuration data for the colonies to be upgraded and the DEFAULT colony from Production_V1 to Upgrade_V1.
    Note: If you are creating an upgrade environment as part of the process to migrate history data before transaction data for all colonies, do not perform this step.