Upgrading from an Earlier Version

Windows Upgrade Procedure

The installer provides all the functionality required to upgrade to a new version of InterSystems IRIS. To instead perform a silent upgrade, which is necessary when using a manifest, review the information in the Running an Unattended Upgrade or Reinstall section of the “Installing on Microsoft Windows” chapter of this guide.

To perform the upgrade:

1. Double-click the installer file, for example, IRIS-win_x64.exe.

2. The installer displays a list of all existing InterSystems IRIS instances on the host. Select the name of the instance you want to upgrade and click OK.

3. When prompted for an InterSystems IRIS license key, click License and browse for the new iris.key file. If the installer detects a new key file in the install-dir/mgr directory, it proceeds without prompting you for the license key.

4. After the installer validates the license key, click Upgrade.

   Important:

   Do not interrupt the installation while it is in progress. If the upgrade fails with any error messages, correct the issues and restart the upgrade installation.

5. After the upgrade is completed, click Finish.

6. Examine messages.log, iboot.log, and ensinstall.log in the install-dir\mgr directory for any errors. If any fatal error is found, correct the error, and then run the installer again.

Important:

If your operating system is configured to use large memory pages, check the startup messages to make sure shared memory is being allocated in accordance with these settings. If you see a message similar to the following, reboot your server to avoid an out-of-memory situation.

Failed to allocate 592MB shared memory using large pages.  Switching to small pages.

UNIX®, Linux, and macOS Upgrade Procedure

The installation script, irisinstall, provides all the functionality required to upgrade to a new version of InterSystems IRIS. To instead perform a silent upgrade, review the information in the Unattended InterSystems IRIS Installation section of the “Installing on UNIX®, Linux, and macOS” chapter of this guide.

To perform the upgrade:

1. If your installation kit is in the form of a .tar file, you must first uncompress it (see the “Uncompress the Installation Kit” section in the “Installing on UNIX®, Linux, and macOS” chapter of this book).

2. As a user with root privileges, start the installation procedure by running the irisinstall script, located at the top level of the installation files:

   sudo sh /<pathname>/irisinstall
   
   

   

   where <pathname> is the location of the installation kit, typically the temporary directory to which you have extracted the kit.

3. The script displays a list of all existing InterSystems IRIS instances on the host.

4. At the Enter instance name: prompt, type the name of the InterSystems IRIS instance you want to upgrade, and press Enter.

5. When prompted for a license key file, type keypath\iris.key, where keypath is the location of the new iris.key file. If the installation script detects the new license key in the install-dir/mgr directory, the script proceeds without prompting you for the license key file.

6. The installation script summarizes the upgrade options and again asks you to confirm the upgrade. Press Enter to continue with the upgrade.

   Important:

   Do not interrupt the installation while it is in progress. If the upgrade fails with any error messages, correct the issues and restart the upgrade installation.

7. Examine messages.log, iboot.log, and ensinstall.log in the install-dir/mgr directory for any errors. If any fatal error is found, correct the error, and then run the installation script again.

After the upgrade finishes, the instance restarts and any installation manifest is run.

Important:

If your operating system is configured to use huge memory pages, check the startup messages to make sure shared memory is being allocated in accordance with these settings. If you see a message similar to the following, reboot your server to avoid an out-of-memory situation.

Failed to allocate 1468MB shared memory using Huge Pages. Startup will retry with standard pages.

Choosing Mirror Upgrade Procedure

There are two primary factors to consider in choosing the procedure appropriate for your mirror upgrade:

• Are you upgrading to a maintenance release of the installed version of InterSystems IRIS, or to a new major version of InterSystems IRIS?

• Does the upgrade involve changes to mirrored databases?

Whenever you upgrade to a maintenance release and are not making any application upgrades, you do not have to consider the second question; you can always use the simple Maintenance Release Upgrade procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover.

However, when you upgrade from one major InterSystems IRIS version to another, perform application upgrades, or both, there is the possibility that your upgrade involves changes to mirrored databases. Such changes must occur on the functioning primary failover member as part of the upgrade procedure, while application access is disabled. As a result, the upgrade requires more downtime than if you are not making any mirrored database changes. (The changes are then replicated by the mirror on the backup and any async members.)

If you are upgrading to a major release, are performing application upgrades, or both, you must determine whether any of the following conditions apply:

• Classes and routines are stored in mirrored databases that also contain application data. Classes must be recompiled on the primary (even if the application has not been upgraded). Recompiling routines on the primary is recommended.

• Data in mirrored databases must be upgraded due to an application upgrade; these changes must take place on the primary.

If your major upgrade and/or application upgrade involves any of these conditions, use the Major Version Upgrade (Mirrored Database Changes) procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover and make the required mirrored database changes.

If your upgrade does not involve any of the listed mirrored database changes, consider the Major Version Upgrade (No Mirrored Database Changes) procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover.

If you have a significant planned maintenance window and minimizing mirror downtime is not a major concern, you may choose to use the simpler Major Version Upgrade with Planned Downtime procedure instead.

In the case of major upgrades, the general sequence of each procedure applies to upgrades of the mirror’s InterSystems IRIS instances, application code, or both; adapt individual steps depending on what you are upgrading.

Adding Mirror Members During an Upgrade

If you plan to add members to a mirror, you may want to defer this until you plan to perform one of the upgrades described in this section and add members of the new version during the upgrade, so that you do not have to upgrade them later. You can always add members of a newer version to a mirror during an upgrade, provided you immediately continue with and complete the upgrade as described, with one restriction: once a member of the newer version becomes primary, it must remain primary until all other members have been upgraded.

Adding new members during an upgrade can be very helpful when migrating a mirror to new hardware. Rather than upgrading one of the failover members before failing over to it, you can install a new instance of the new version on the target system, add it to the mirror as a DR async member, promote it to backup and then fail over to it, thus migrating the mirror primary to the new system. By repeating this technique you can then migrate the remaining failover member. The procedures in this section include steps for adding a new backup of the new version as an alternative to upgrading the existing backup, to illustrate this approach.

Mirror Upgrade Terms

In the procedures in this section, the following terms are used:

Mirror Upgrade Procedures

There are four mirror upgrade paths to choose from. To determine which procedure you should follow, review the factors in the Choosing Mirror Upgrade Procedure section. The four procedures are:

• Maintenance Release Upgrade

• Major Version Upgrade (Mirrored Database Changes)

• Major Version Upgrade (No Mirrored Database Changes)

• Major Version Upgrade with Planned Downtime

The first three procedures are designed to let you perform the upgrade you need with the shortest possible application downtime; they differ to accommodate different upgrade circumstances. The last, which is a bit simpler, can be used for any type of upgrade when minimizing downtime is not a priority.

Maintenance Release Post-Upgrade Tasks

When the upgrade is complete, if your system runs any productions, follow the instructions in the Starting a Production section of the “Starting and Stopping Productions” chapter in Managing Productions to restart the productions.

Typically, maintenance release upgrades do not require you to change external files and clients, or to recompile classes and routines. However, the Studio version on a client must be the same or later than the InterSystems IRIS server version to which it connects.

If you choose to recompile, review the information in the Major Version Post-Installation Tasks section.

Major Version Post-Installation Tasks

After upgrading InterSystems IRIS to a new major version, it is important to follow the guidance provided in the General Upgrade Information in the Release Notes. You must also perform the following tasks (if you have not already done so as part of one of the previous procedures in this chapter):

• Recompile classes and routines — InterSystems recommends that customers recompile all classes and all routines in each namespace. See How to Compile Namespaces for instructions. You may have your own tools and procedures for this purpose, taking into account any dependencies and other needs particular to the instance that was upgraded.

• Regenerate proxy classes — You must regenerate any proxy classes you had generated in the upgraded instance by following the instructions in the appropriate guides in the InterSystems IRIS Language Bindings set.

  This item does not apply to web services and web clients; it is not necessary to re-import any Web Service Definition (WSDL) files.

• Clear browser cache — Your browser cache may contain JavaScript files that are no longer compatible with the installed version of InterSystems IRIS and may cause errors; clear your browser cache immediately after completing the upgrade.

The following tasks may be necessary depending on your environment and the components you use:

• Review query plans. When you upgrade to a new major version, existing Query Plans are automatically frozen. This ensures that a major software upgrade will never degrade the performance of an existing query. For performance-critical queries, you should test if you can achieve improved performance.

• Restart productions — If your system runs any productions, follow the instructions in the Starting a Production section of the “Starting and Stopping Productions” chapter in Managing Productions.

• Upgrade Studio clients — The Studio version on a client must be the same or later than the InterSystems IRIS server version to which it connects.

• Upgrade the Web Gateway — If your Web Gateway is on a separate machine from the InterSystems IRIS server you are upgrading, you must also upgrade the Web Gateway on that separate machine. You can accomplish this by following the Windows Upgrade Procedure in this chapter, or performing a silent installation with the ADDLOCAL property as discussed in Running an Unattended Installation section of the “Installing InterSystems IRIS on Microsoft Windows” chapter of this book.

• Update web server files — Following upgrades you must deploy these using established practices at your site.

How to Compile Namespaces

After an upgrade, you must compile the code in each namespace so that it runs under the new version of InterSystems IRIS. If the compiler detects any errors, you may need to recompile one or more times for the compiler to resolve all dependencies.

After your code compiles successfully, you may want to export any updated classes or routines, in case you need to run the upgrade in any additional environments. Importing these classes or routines during future upgrades allows you to update your code quickly, minimizing downtime.

Note:

If you are using a manifest as part of your upgrade process, you can compile your code from within the manifest. See the instructions in the Perform Post-Upgrade Tasks section of the Creating and Using an Installation Manifest appendix of this guide.

Compiling Classes

To compile the classes in all namespaces from the Terminal:

do $system.OBJ.CompileAllNamespaces("u")

To compile the classes in a single namespace from the Terminal:

set $namespace = "<namespace>"
do $system.OBJ.CompileAll("u")

Note:

If your namespaces contain mapped classes, include the /mapped qualifier in the call to CompileAllNamespaces() or CompileAll():

do $system.OBJ.CompileAllNamespaces("u /mapped")
do $system.OBJ.CompileAll("u /mapped")

Class compiler version utility

To assist customers in determining which class compiler version a class or classes in a namespace have been compiled with, InterSystems provides two assists

• Method – $System.OBJ.CompileInfoClass(<classname>)

  This method returns the version of the class compiler used to compile this <classname> and the datetime the class was compiled

• Query – $System.OBJ.CompileInfo(<sortby>)

  This query generates a report for the current namespace that includes all classes, the version of the compiler used to compile each one, and the datetime each was compiled. The first argument <sortby> may have the following values:

  • 0 – the time the class was compiled

  • 1 – the class name

  • 2 – the version of InterSystems IRIS the class was compiled in

Compiling Routines

To compile the routines in all namespaces from the Terminal:

do ##Class(%Routine).CompileAllNamespaces()

To compile the routines in a single namespace from the Terminal:

set $namespace = "<namespace>"
do ##Class(%Routine).CompileAll()