Adding Databases to a Mirror

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, 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.

• When adding a mirrored database to a new mirror member, existing global operations can automatically be downloaded from another mirror member if a valid copy exists. If no valid source is available, the database must be manually restored from a backup, or if added to the Primary, it will be created as an empty mirrored database. See Automatic Database Download from Mirror Member for more details on the criteria for database download.

  Note:

  For databases with an extremely large amount of global data, manual backup and restore may be more efficient than automatic download. In such cases, follow the steps outlined in Add an Existing Database to the Mirror.

• 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.

To create a mirrored database, follow this procedure.

1. 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.

2. 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; the default is the local database name you provided. The leading character of the mirror database name must be alphabetic or an underscore, and the rest must be alphanumeric characters, hyphens and underscores. Mirror database names are case-insensitive, thus two names cannot differ only in case; if you enter a mirror database name that is already included in the mirror, the new database cannot be added to the mirror and must be deleted. (Names of mirrored databases created under earlier versions of InterSystems IRIS may be stored in lowercase or mixed case, but the addition of databases with duplicate uppercase names is still precluded.)

   On an async member that belongs to more than one mirror, you must also select the mirror the database will belong to.

   Note:

   When you select Yes for Mirrored database, Journal globals is automatically locked to Yes.

3. Confirm the procedure to create the database and add it to the mirror on the primary.

4. 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. (The local database names do not have to match.)

When adding an existing mirrored database to a mirror member, it may be automatically downloaded from another mirror member instead of requiring a manual backup and restore. This could be useful when adding new mirror members or restoring current members.

To trigger the download, create a database on the new member or member to be restored, specify that it will be mirrored, and enter the Mirror DB Name exactly as it appears on the source member. This can be done using the Management Portal (via the Mirror DB Name field in the database creation wizard) or programmatically.

The criteria to determine if a database is valid for download include:

• It is activated

• The FailoverDB flag is not cleared

If a valid copy exists, it is downloaded and journal updates are applied. Should no valid copy be found, 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 a database is eligible for download, InterSystems IRIS selects a download source. It first attempts to download from the Backup. If the Backup is unavailable or becomes offline during the download, InterSystems IRIS then attempts the download from the Primary, followed by any available Async members.

However, if the other members are unable to provide all needed global operations, the process waits for the member originally selected by InterSystems IRIS to return instead of falling back to an unqualified source.

Use the procedure that follows to add one or more existing databases to a mirror.

1. 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.

2. 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; the default is the local database name you provided. The leading character of the mirror database name must be alphabetic or an underscore, and the rest must be alphanumeric characters, hyphens and underscores. Mirror database names are case-insensitive, thus two names cannot differ only in case; if you enter a mirror database name that is already included in the mirror, the operation fails. (Names of mirrored databases created under earlier versions of InterSystems IRIS may be stored in lowercase or mixed case, but the addition of databases with duplicate uppercase names is still precluded.)

   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.

   Note:

   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 the following steps.

3. Once the database has been added to the mirror, back it up on the primary failover member. Review Backup Strategies, Restoring from Backup, and Mirrored Database Considerations for information about different backup techniques and the corresponding restore procedures.

   Important:

   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.

   Ensuring that a mirrored database is synchronized after it is restored from backup (see the following step) 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.

4. 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 just 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. For more information see Mirrored Database Considerations.

        Note:

        When a mirrored database is restored on a nonprimary member, the data to begin the automatic synchronization process may not have been sent yet. If the required data does not arrive within 60 seconds, the process begins anyway; those databases may not catch up if the data does not arrive before it is required, however, in which case a message regarding the database(s) that had the problem is logged in the messages.log file. (During database creation this process would affect only one database, but it also applies to catching up in other situations in which multiple databases are involved.)

      • 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 Activating and Catching up Mirrored Databases, immediately following.

As an alternative to the previous procedure, after adding an existing database to the mirror on the primary, you can copy the databases’s IRIS.DAT file from the primary to the backup and async members instead of backing up and restoring the database. To do so, use this procedure:

1. Ensure that there is a placeholder target database on the backup and each async member.

2. On both failover members and each aysnc member, make sure the source and target databases are not mounted (see Maintaining Local Databases).

3. 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.

   Note:

   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.

4. Mount the database on the all members.

5. Activate and catch up the mirrored databases on the backup failover member and async member(s) as described in Activating and Catching up Mirrored Databases.

You can activate and/or catch up mirrored databases on the backup failover member and async members using the Mirror Monitor.

As noted in Add an Existing Database to a Mirror, a newly added mirrored database containing data can be automatically synchronized with the primary through use of the ^DBREST routine to restore the backup from the primary failover member. 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. On an async member, click the Details link for the mirror containing the database(s) you want to take action on, if necessary.

3. The Mirrored databases list shows the status of each database, as described in Using the Mirror Monitor. Among other possible statuses, Needs Catchup indicates that the Catchup operation is needed, Needs Activation indicates that both the Activate and Catchup operations are needed, and Catchup Running shows that the Catchup operation is currently running on the database.

4. Select the Activate or Catchup link to perform an operation on a single database, or select Activate or Catchup from the Select an action drop-down and click Go to open a dialog in which you can select multiple databases from a list of all those for which the action is appropriate to apply it to all of them at once. When you do this, the Activate and Catchup tasks are run in the background. When you select Catchup, databases of both Needs Activation and Needs Catchup status are displayed; both Activate and Catchup are applied to any Needs Activation databases you select.

You can also use the Mirrored databases list to mount or dismount one or more mirrored databases, or to remove one or more databases from the mirror as described in Removing Mirrored Databases from a Mirror.

If a mirrored database was downloaded from another member, it will begin catching up automatically when the source is available. In these cases, no manual activation is required unless the process fails.