Skip to main content

Upgrading a Mirror

This section provides instructions for upgrading InterSystems IRIS instances, an application, or both on the members of an InterSystems IRIS mirror.

As noted in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide, all failover and DR async members of a mirror must be of the same InterSystems IRIS version, and can differ only for the duration of an upgrade. Once an upgraded member becomes primary, you cannot make use of the other failover member and any DR async members (and in particular cannot allow them to become the primary) until the upgrade is completed.

Mirroring does not require reporting async members to be of the same InterSystems IRIS version as the failover members, although application functionality may require it; for more information, see InterSystems IRIS Instance Compatibility in the “Mirroring” chapter of High Availability Guide.

Note:

Mirroring relies on journal file restoration to synchronize data among mirror members. Journal file restores are guaranteed to succeed only when performed on an InterSystems IRIS instance running the same or a more recent version than the one that created them. InterSystems strongly recommends adhering to this practice in mirrored environments to ensure compatibility.

InterSystems IRIS 2025.1 introduced a new journal file format incompatible with earlier versions. Journal files created by instances running InterSystems IRIS 2025.1 or later cannot be restored on instances running any version prior to InterSystems IRIS 2025.1. For more details, see Journal Restore Interoperability (Upgrade Implications).

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 below. The four procedures are located in the Mirror Upgrade Procedures section below.

Also review the following two sections about upgrading a mirror:

Important:

On Linux systems supporting systemd, although it is possible to use either systemctl commands or the /etc/init.d/ISCAgent script to manage the ISCAgent, you must choose one method and use it exclusively; the ISCAgent should always be stopped using the method with which it was started. For more information, see Starting the ISCAgent on Linux Systems in the “Mirroring” chapter of the InterSystems High Availability Guide.

When you upgrade InterSystems IRIS on such a Linux system, a running ISCAgent is automatically restarted using systemd. If you are using the /etc/init.d/ISCAgent script to manage the ISCAgent, stop the agent before performing the upgrade so that it is not automatically restarted, then restart it using the script after the upgrade.

Choosing Mirror Upgrade Procedure

To upgrade your mirrored environment, you must choose one of four supported upgrade procedures. To determine the best upgrade procedure, review the following criteria for each procedure.

Procedure 1: Maintenance Release Upgrades with No Application Changes

If you are upgrading to a maintenance release and you aren’t making any application changes during the upgrade process, you can use this simplified procedure.

For details, see Procedure 1: Maintenance Release Upgrades with No Application Changes.

Procedure 2: Major Version Upgrades with Planned Downtime

This procedure can be used for major version upgrades or upgrades with application changes where downtime is not a concern and simplifies some steps by shutting down all mirror members at the same time.

For details, see Procedure 2: Major Version Upgrades with Planned Downtime.

Procedures 3 & 4: Major Version Upgrades with Minimal Downtime

If you are upgrading to a major version or performing applications changes and you need to minimize downtime you must use Procedure 3 or 4.

If any of the following conditions apply, your upgrade involves mirrored database changes and you should use Procedure 4: Major Version Upgrade with Mirrored Database Changes.

  • Classes and routines are stored in mirrored databases that also contain application data.

  • An application upgrade you are performing includes changes to data in a mirrored database.

  • Your system uses interoperability productions.

If none of the above conditions apply, you should use Procedure 3: Major Version Upgrade with No Mirrored Database Changes.

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:

Upgrade classes and routines

Recompile all classes in all application namespaces on the instance. This should be done after an InterSystems IRIS major version upgrade (as described in Post-Upgrade Tasks) and/or application upgrade, which may involve one or more of the following operations, depending on your situation:

  • As noted in the foregoing, when classes exist in any mirrored database that also contains application data, they must be recompiled locally on the functioning primary failover member (regardless of whether they are modified by an application upgrade). It is recommended that any existing routines are recompiled.

  • Classes and routines stored in nonmirrored routines databases that are separate from application data can be recompiled on a mirror member regardless of whether it is the current primary.

  • Classes and routines stored in separate nonmirrored routines database can also be “precompiled” by recompiling a copy of the database on a system that has already been upgraded to the target InterSystems IRIS release, then distributed to each mirror member following the upgrade.

System A

The mirror member that is initially the primary failover member.

System B

The mirror member that is initially the backup failover member.

System C

A newly-added DR async of the new InterSystems IRIS version that has been promoted to failover member.

Set no failover

Use the ^MIRROR routine to set the no failover state so that failover cannot occur; see Avoiding Unwanted Failover During Maintenance of Failover Members in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide for instructions.

Perform a graceful shutdown

Use the iris stop command to shut the instance down cleanly (see Controlling InterSystems IRIS Instances in the “Using Multiple Instances of InterSystems IRIS” chapter of the InterSystems IRIS System Administration Guide).

Promote to failover member

Follow the procedure for promoting a DR async mirror member to failover member as described in Promoting a DR Async Member to Failover Member in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide.

Viewing the Mirror Monitor

Use the Mirror Monitor page in the instance’s Management Portal to review the status of the mirror and its members; see Using the Mirror Monitor in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide for more information.

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:

Procedure 1: Maintenance Release Upgrades with No Application Changes

If you are upgrading to an InterSystems IRIS maintenance release rather than a new major InterSystems IRIS version and are not making any application changes, use the following procedure, which renders the mirror unavailable only for the time required to execute a planned failover:

  1. To prevent failover from occurring until the backup is fully upgraded, set no failover.

  2. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. Perform a graceful shutdown of the backup (B).

      2. Upgrade the backup (B) with the new version of InterSystems IRIS. System B becomes backup.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup and System B becomes a DR async.

  3. Ensure that the backup (B or C) has become active by viewing the Mirror Monitor.

  4. Clear no failover.

  5. Perform a graceful shutdown of the primary (A). The mirror fails over and the backup (B or C) takes over as primary.

  6. Upgrade system A with the new version of InterSystems IRIS. System A becomes backup.

  7. If system C became primary and system B was demoted to DR async, upgrade system B.

  8. Perform a graceful shutdown of the new primary (B or C). The mirror fails over and the backup (A) becomes the primary. If you are using a third instance as a DR async member, you should failover once more, so that each member has become the primary once. This ensures that all automated upgrade and reactivation steps are performed on all mirror members and that all instances are ready to act as primary.

Procedure 2: Major Version Upgrades with Planned Downtime

If you are upgrading to a new major InterSystems IRIS version and/or performing an application upgrade and have a significant planned maintenance window that obviates the need to minimize mirror downtime, you may prefer to use the following simpler procedure, regardless of whether changes to mirrored databases on the primary are required:

  1. Disallow all user access to the mirror using established practices at your site. Additionally, you must disable any application jobs that would normally start on instance startup.

  2. Perform a graceful shutdown of the backup (B).

  3. Perform a graceful shutdown of the primary (A).

  4. Upgrade system A with the new version of InterSystems IRIS. System A becomes primary.

  5. Upgrade mirrored classes and routines on system A. If an application upgrade requires further changes to mirrored databases, make these changes.

  6. Upgrade nonmirrored classes and routines on system A, if any.

  7. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. Upgrade system B with the new version of InterSystems IRIS. System B becomes backup.

      2. Upgrade nonmirrored classes and routines on system B, if any.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup.

      4. Upgrade system B with the new version of InterSystems IRIS. System B becomes a DR async.

      5. Upgrade nonmirrored classes and routines on system B, if any.

  8. If system C became primary and system B was demoted to DR async, upgrade system B and upgrade nonmirrored classes and routines on system B, if any.

  9. Perform a graceful shutdown of the new primary (B or C). The mirror fails over and the backup (A) becomes the primary. If you are using a third instance as a DR async member, you should failover once more, so that each member has become the primary once. This ensures that all automated upgrade and reactivation steps are performed on all mirror members and that all instances are ready to act as primary.

  10. Restore user access to the mirror.

Procedure 3: Major Version Upgrade with No Mirrored Database Changes

If you are upgrading to a new major InterSystems IRIS version and/or performing an application upgrade and have determined that changes to mirrored databases are not required (as described in Choosing a Mirror Upgrade Procedure), you may be able to use the following procedure.

This procedure is simplest for static applications where separate nonmirrored routines databases are always maintained. It can, however, be used even if the separate routines databases are normally mirrored by removing these databases from the mirror for the duration of the upgrade.

Important:

If the routines databases are normally mirrored, ensure that they do not contain any application data before removing them from the mirror.

This procedure cannot be used with normally mirrored routines databases if ECP application servers connect to the mirror.

  1. Enact a code freeze and application configuration freeze to disallow application changes during the upgrade, using established procedures at your site, to ensure that routines databases are not modified during the upgrade.

  2. To prevent failover from occurring until the backup is fully upgraded, set no failover.

  3. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. If the routines databases are mirrored, remove them from the mirror on system B.

      2. Ensure that the backup (B) has become active by viewing the Mirror Monitor.

      3. Perform a graceful shutdown of the backup (B).

      4. Upgrade the backup (B) with the new version of InterSystems IRIS. System B becomes backup.

      5. Upgrade classes and routines on system B.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup and System B becomes a DR async.

      4. If the routines databases are mirrored, remove them from the mirror on systems C and B.

      5. Ensure that the backup (C) has become active by viewing the Mirror Monitor.

  4. Clear no failover.

  5. Perform a graceful shutdown of the primary (A). The mirror fails over and the backup (B or C) takes over as primary.

  6. To prevent system A from taking over as primary until fully upgraded, set no failover.

  7. Upgrade system A with the new version of InterSystems IRIS. System A becomes backup.

  8. Upgrade any nonmirrored classes and routines on system A.

  9. If system C became primary and system B was demoted to DR async, upgrade system B and upgrade nonmirrored classes and routines on system B, if any.

  10. For any mirrored routines databases that you removed from the mirror on backup (B or C) before it became the new primary, do the following:

    1. Remove the routines databases from the mirror on system A.

    2. Add the databases to the mirror on the new primary (B or C), then back them up and restore them on the backup (A) and DR async (B, if C is the primary), using the procedures for adding an existing database to a mirror provided in Adding Databases to a Mirror in the “Mirror” chapter of the InterSystems IRIS High Availability Guide. Retain these backups, as they represent the first backups of newly-added mirrored databases; older backups made prior to the upgrade cannot be used to restore these databases in the event of disaster.

  11. Clear no failover.

  12. Perform a graceful shutdown of the new primary (B or C). The mirror fails over and the backup (A) becomes the primary. If you are using a third instance as a DR async member, you should failover once more, so that each member has become the primary once. This ensures that all automated upgrade and reactivation steps are performed on all mirror members and that all instances are ready to act as primary.

Procedure 4: Major Version Upgrade with Mirrored Database Changes

If you are upgrading to a new major InterSystems IRIS version and/or performing an application upgrade and have determined that changes to mirrored databases are required (as described in Choosing a Mirror Upgrade Procedure), use the following procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover and make the required mirrored database changes:

  1. To prevent failover from occurring until the backup is fully upgraded, set no failover.

  2. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. Perform a graceful shutdown of the backup (B).

      2. Upgrade the backup (B) with the new version of InterSystems IRIS. System B becomes backup.

      3. Upgrade nonmirrored classes and routines on system B, if any.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup and System B becomes a DR async.

  3. Ensure that the backup (B or C) has become active by viewing the Mirror Monitor.

  4. Disallow new user access to the mirror using established practices at your site. Additionally, you must disable any application jobs that would normally start on system B when it becomes primary.

  5. Clear no failover.

  6. Perform a graceful shutdown of the primary (A). The mirror fails over and the backup (B or C) takes over as primary

  7. Upgrade mirrored classes and routines on the new primary (B or C). If an application upgrade requires further changes to mirrored databases, make these changes.

  8. Restore user access to the mirror.

  9. To prevent system A from taking over as primary until fully upgraded, set no failover

  10. Upgrade system A with the new version of InterSystems IRIS. System A becomes backup.

  11. Upgrade nonmirrored classes and routines on system A, if any.

  12. Clear no failover.

  13. If system C became primary and system B was demoted to DR async, upgrade system B and upgrade nonmirrored classes and routines on system B, if any.

  14. Perform a graceful shutdown of the new primary (B or C). The mirror fails over and the backup (A) becomes the primary. If you are using a third instance as a DR async member, you should failover once more, so that each member has become the primary once. This ensures that all automated upgrade and reactivation steps are performed on all mirror members and that all instances are ready to act as primary.

Upgrading ECP ConfigurationsNext section
Previous sectionUpgrading or Modifying on UNIX®, Linux, and macOS
FeedbackOpens in a new tab