Adding Databases to a Mirror

This section describes the procedures for adding both new and existing databases to a mirror, along with related requirements and synchronization considerations. The steps differ depending on whether the database is newly created for mirroring (that is, containing no data) or converted from an existing non-mirrored database with data. It also covers methods for making mirrored databases available on additional mirror members, including automatic download, InterSystems IRIS backup and restore, and copying database files.

You must add the same set of mirrored databases to both the primary and backup failover members, as well as to any DR async members; which mirrored databases you add to reporting async members depends on your reporting needs. The namespaces and global/routine/package mappings associated with a mirrored database must be the same on all mirror members, including all async members on which the database exists. The mirrored databases on the backup failover member must be mounted and caught up to be able to take over as the primary in the event of a failover; the mirrored databases on a DR async member must be mounted and caught up to make it suitable for promotion to failover member. All mirrored databases must be journaled.

Mirrored Database Considerations

Bear the following points in mind when creating and adding mirrored databases:

Only data in IRIS.DAT files can be mirrored. Data that is external (that is, stored on the file system) cannot be mirrored by InterSystems IRIS (for more information, see Mirror Configuration Guidelines).
System databases (IRISSYS, IRISSECURITY, IRISLIB, IRISLOCALDATA, IRISTEMP, IRISAUDIT, and ENSLIB) cannot be mirrored.
Because more database directory information is stored for mirrored databases, they reduce the maximum number of databases that can be configured within an InterSystems IRIS instance. For more information, see Configuring Databases.
The mirror automatically and continually synchronizes the following properties of a mirrored database on a backup or async with the properties of the database on the primary:
- Maximum Size
- Expansion Size
- Resource Name
- Collation
For example, when the Maximum Size of a mirrored database is increased on the primary, it is automatically increased for that database on the other members to match the primary, if necessary; if Maximum Size is then reduced on an async, synchronization automatically increases it to the value on the primary. If database properties are changed on either the primary or another mirror member while that member is disconnected, they are automatically synchronized when the member reconnects to the mirror. There are two exceptions to automatic synchronization of these database properties, as follows:
- The values of the Maximum Size and Expansion Size properties on an async can be increased by synchronization, but never reduced. For example, if the Maximum Size of a database on the primary is reduced, the value of this property is reduced on the backup, but not on any asyncs belonging to the mirror; if the Maximum Size of a database on an async is increased to be larger than on the primary, it is not reduced by synchronization to the value on the primary.
- The Resource Name property of a database is synchronized with the primary on any mirror member who has the given database marked as a failover database. In practice, this generally means that the Resource Name is synchronized to all mirror members except for read-write reporting async members.
See Edit Mirrored Local Database Properties for information about mirrored database properties.
If the database you are copying is encrypted on the primary, the key with which it is encrypted must also be activated on the backup (and asyncs, if any), or the database must be converted to use a key that is activated on the destination system, as described in Convert an Encrypted Database to Use a New Key.
If a backup failover member or async member has a different endianness than the primary failover member, you must use the procedure described in Member Endianness Considerations to add the database to the backup or async member after adding it to the primary, rather than adding it on that member as described in Copying a Mirrored Database to Additional Members.
If you are mirroring an IRIS for Health or Health Connect system, refer to Configuring Mirroring for Healthcare Products for important details on which databases to mirror.

Adding a New Database to the Mirror

Use the ^DATABASE routine to create a mirrored database. See Creating a Mirrored Database Using the ^DATABASE Routine for more details.

Alternatively, create a new mirrored database with no data and add it to a mirror using this procedure:

On the current primary failover member, navigate to the Local Databases page of the Management Portal (System Administration > Configuration > System Configuration > Local Databases), and click the Create New Database button.
Follow the procedure in Create a Local Database. On the second panel, select Yes for Mirrored database? and enter a name for the database within the mirror. By default, this name is the same as the local database name. The mirror database name must begin with an alphabetic character or underscore, followed by alphanumeric characters, hyphens, or underscores. Mirror database names are case-insensitive, so two names that differ only by case are considered identical. If you enter a name already in use within the mirror, the database cannot be added and must be deleted. (Note: Mirrored databases created in earlier versions of InterSystems IRIS may be stored in lowercase or mixed case, but duplicate names with differing case are still not allowed.)
On an async member that belongs to more than one mirror, you must also select the mirror the database will belong to.
Confirm the procedure to create the database and add it to the mirror on the primary.
On the backup failover member, and on each async member to which you want to add the mirrored database, follow the previous three steps, taking care to enter the correct mirror database name from the primary as the mirror database name on each of the other members. It is recommended local database names match mirrored database names, though this is not required.

When this procedure has been completed, the new mirrored database is ready for use across the mirror.

Adding an Existing Database to the Mirror

To add an existing database, storing data, to the mirror, use the SYS.Mirror.AddDatabase()Opens in a new tab mirroring API method or follow these steps in the Management Portal:

On the current primary failover member, navigate to the Local Databases page of the Management Portal (System Administration > Configuration > System Configuration > Local Databases) and click the Add to Mirror button.
From the listed databases (nonsystem databases not already in the mirror) select those you want to add and click Add. You must enter a name for each database within the mirror; by default, this is the same as the local database name. Mirror database names must follow the same rules described in Adding a New Database to the Mirror.
To run the task in the background, select Run add in the background; if you select five or more databases, the task is automatically run in the background. Confirm the procedure to add the selected databases to the mirror on the primary.
You can also add an individual database to the mirror by clicking its name to edit its properties and clicking the Add to Mirror <mirrorname> link, then clicking Add and confirming the procedure. (If journaling is not enabled on the database, Databases must be journaled to be mirrored is displayed in place of this link; to enable it, select Yes from the Global Journal State drop-down list.) Alternatively, the Add Mirrored Database(s) option on the Mirror Management menu of the ^MIRROR routine also lets you add an individual database. In either case, you can accept the default of a mirror database name the same as the local name, or enter a different one.
Choose a method to copy the mirrored database to other mirror members, as described in Copying an Existing Mirrored Database to Additional Members.

Copying an Existing Mirrored Database to Additional Members

When adding a mirrored database to a backup failover or async mirror member, there are three options:

Automatic Database Download from Another Mirror Member (no restoring or activating/catching it up required)
Manual Backup and Restore (requires restoring the database and then activating/catching it up)
Copy the IRIS.DAT File (requires activation and catch up)

Option 1: Automatic Database Download from Mirror Member

When adding a mirrored database to a mirror member, it can be automatically downloaded from another member. This is useful when adding or restoring mirror members.

To trigger the download, on all mirror members that do not have the database, use the Management Portal’s database creation wizard (System Administration > Configuration > System Configuration > Local Databases > Create New Database).

Follow the procedure in Create a Local Database with the following addition:

After selecting Yes for Mirrored database?, enter the Mirror DB Name exactly as it appears on the source member.

If a valid mirrored copy is available, it is downloaded automatically and journal updates are applied. No manual backup, restore, activation, or catchup is required unless the process fails.

Automatic database download performance can vary based on factors such as database size and network conditions.

Additional Information

A database is eligible for download if it is activated and the FailoverDB flag is set (not cleared).

If no valid member is able to provide all needed data, behavior depends on the member type:

On a Backup or Async, the database creation fails.
On the Primary, a new empty mirrored database is created instead.

If the database with that name on another member is not valid for download, it may be marked Obsolete.

Option 2: Restore a Mirrored Database from Backup

This option consists of three steps:

Back Up the Mirrored Database on the Primary Failover Member:
Create a backup of the mirrored database on the primary failover member to use when restoring the database on the backup and async members.
Synchronization after restoring a mirrored database requires that the journal files from the time of the backup on the primary failover member are available and online; for example, if the relevant journal files have been purged, you must make and restore a more up to date backup. For general information about restoring mirror journal files see Restoring Mirror Journal Files; for information about purging mirror journal files see Purge Journal Files.
Review Backup Strategies, Restoring from Backup, and Mirrored Database Considerations for information about different backup techniques and the corresponding restore procedures.
Restore the Mirrored Database on the Backup and Async Members:
On the backup failover member and each connected async member, do the following:
1. If a local database with the same local name and database directory as the mirrored database you added on the primary failover member does not already exist, create it.
2. Restore the backup you made of the mirrored database on the primary, overwriting the existing database.
  The procedure for this depends on the restore method you are using, as follows:
  - Online backup restore (^DBREST routine) — This routine automatically recognizes, activates and catches up a mirrored database on the backup and async members.
    In some cases, catchup may begin before the required data from the primary has arrived, which can prevent the database from fully catching up. Any related issues are recorded in the messages.log file. For more information see Mirrored Database Considerations
  - External backup restore or cold (offline) backup restore — Both of these methods require that you manually activate and catch up the mirrored databases after they are restored and mounted on the backup failover member or async member, as described in Step 3.
Activate and Catch Up the Mirrored Database (if needed)
You can activate and/or catch up mirrored databases on the backup failover member and async members using the Mirror Monitor.
Additional options include the Activate or Catchup mirrored database(s) action in the ^MIRROR routine, or the SYS.Mirror.ActivateMirroredDatabase()Opens in a new tab and SYS.Mirror.CatchupDB()Opens in a new tab API methods.
As noted in Option 1 and the ^DBREST restore method, a newly added mirrored database containing data can be automatically synchronized with the primary. If some other method is used, it must be activated and caught up on the backup failover member and async members.
To activate and catch up mirrored databases, do the following on the backup failover member and async members:
1. Navigate to the Mirror Monitor page (System Operation > Mirror Monitor).
2. If needed, on an async member, click the Details link for the mirror containing the database(s).
3. Review the Mirrored databases list for status:
  - Needs Activation means both Activate and Catchup are needed.
  - Needs Catchup means only Catchup is needed.
  - Catchup Running means Catchup operation is currently running.
4. To activate or catch up mirrored databases:
  - Select Activate or Catchup to perform the operation on a single database.
  - To apply the operation on multiple databases, use the Select an action drop-down and click Go to open a dialog listing all applicable databases. The selected tasks run in the background.
  - If you select Catchup, the list includes databases with either Needs Activation or Needs Catchup status. For any Needs Activation databases selected, both Activate and Catchup are applied.
If a mirrored database cannot be caught up due to an error, it remains inactive. If its host becomes primary and the database is marked Mount Required at Startup, that member cannot take over as primary (see Automatic Failover Rules).
When using the Mirrored databases list, the Databases page of the Management Portal (see Managing Local Databases), or the ^DATABASE routine (see Command-Line Security Management Utilities) to mount a mirrored database, you can choose whether to catch it up after mounting. These tools also allow dismounting or removing databases, as described in Removing Mirrored Databases from a Mirror.
If parallel dejournaling is enabled and resources allow, it is automatically used during catchup (see Configuring Parallel Dejournaling).

Option 3: Copy the IRIS.DAT File

After adding the database to the mirror on the primary, you can copy the IRIS.DAT file to the backup and async members instead of restoring or automatic download. To do so:

Ensure that there is a placeholder target database on the backup and each async member.
On both failover members and each async member, make sure the source and target databases are not mounted (see Maintaining Local Databases).
When you are adding an existing mirrored database to an async member, you can back up the database on, or copy the IRIS.DAT file from, the backup failover member or another async member, assuming it is fully caught up. This may be more convenient if the primary is in a different data center. Use a nonprimary source only if you are confident that its database is consistent and up to date.
Copy the mirrored IRIS.DAT file from the primary failover member to the database directory of the placeholder target database on the backup and each async member, overwriting the existing IRIS.DAT file.
If the database is encrypted, ensure key requirements are met on the destination system as described in Mirrored Database Considerations.
Mount the database on all the members.
Activate and catch up the mirrored databases on the backup failover member and async member(s) as described in Step 3 of Restore a Mirrored Database from Backup.

Removing (Deleting) a Mirror

Creating a Mirror