Restore/Migrate Database to Different Systems

This scenario assumes the following starting point:

One or more databases are being restored to a target system that is different than the system that generated the backup.
The target system may be newer hardware, a different platform, or simply a different instance of InterSystems IRIS on the same hardware.
The target system may have a different filesystem layout than the source.
InterSystems IRIS is already installed on the target system (you cannot copy an InterSystems IRIS installation or its IRISSYS database to a target machine that is not identical to the source).

The purpose of this type of restore includes, but is not limited to:

Hardware migration
Adding databases to a backup or async mirror member (see Mirroring)
Copying databases to another system for development, testing, or deployment

To restore/migrate databases to a different system:

Important:

Do not attempt to replace the IRISSYS database on the destination system with a restore of the IRISSYS database from the source unless it is part of a full system restore. Any data needed from the source IRISSYS database can be exported and then imported into the destination IRISSYS database.

If the source and target systems use a different endianness, see Restoring to a Target of Different Endianness. If the source or target systems use database encryption, see the “Considering Database Encryption” subsection following this procedure.

Start InterSystems IRIS if not started already. Starting InterSystems IRIS ensures that any pending automatic recovery to existing databases occurs immediately and does not conflict with the databases that you are about to restore.
If you are restoring databases that users may attempt to access during the restore process, you should start as described in the as described in Starting InterSystems IRIS for Maintenance.

Depending on the strategy you used to back up the database, restore each database as follows:

Backup Strategy Used	Database Restoration Sub-procedure
External backup or cold backup	To restore databases: Dismount any databases being restored if they are mounted on the target instance. Copy the IRIS.DAT files from the backup media to the desired locations. Add any new databases to the configuration. Remount the database that you dismounted.
Online backup	Follow the instructions in the Online Backup Restore Utility to: Restore the last full backup. If you have done cumulative backups since the full backup, restore the last one; otherwise, continue with the next step. Restore all incremental backups done since the last cumulative backup (if there is one), or the last full backup (if there is no cumulative), in the order in which the backups were run.
Concurrent External Backup	Perform the same steps as documented for External Backup (in this table) to restore the “dirty” copy of the IRIS.DAT files, then apply the incremental backup as documented for Online Backup (in this table). Important: If the database(s) being restored are mirrored and from a different system, you must either activate them in the mirror, or remove them from the mirror (if this is your intention), before applying the incremental backup.

Backup Strategy Used

Database Restoration Sub-procedure

External backup or cold backup

To restore databases:

Dismount any databases being restored if they are mounted on the target instance.
Copy the IRIS.DAT files from the backup media to the desired locations.
Add any new databases to the configuration.
Remount the database that you dismounted.

Online backup

Follow the instructions in the Online Backup Restore Utility to:

Restore the last full backup.
If you have done cumulative backups since the full backup, restore the last one; otherwise, continue with the next step.
Restore all incremental backups done since the last cumulative backup (if there is one), or the last full backup (if there is no cumulative), in the order in which the backups were run.

Concurrent External Backup

Perform the same steps as documented for External Backup (in this table) to restore the “dirty” copy of the IRIS.DAT files, then apply the incremental backup as documented for Online Backup (in this table).

Important:

If the database(s) being restored are mirrored and from a different system, you must either activate them in the mirror, or remove them from the mirror (if this is your intention), before applying the incremental backup.

Follow the instructions in Journal Restore Following Backup Restore.

Note:

If you are restoring from Online Backup to add databases to a backup or async mirror member (see Mirroring), skip this step; journals are applied automatically in these cases.
If you started the system as described in Starting InterSystems IRIS for Maintenance, and you are ready to allow users on the system, stop and restart the system normally.

Restoring to a Target of Different Endianness

Depending on the strategy you used to back up the database, an extra step is required to restore a backup on a target system whose endianness (big-endian vs. little-endian) is different from the source system. For information about the endianness of supported platforms, see Platform Endianness.

For External Backup or Cold Backup — convert a copied IRIS.DAT file as described in Using cvendian to Convert Between Big-endian and Little-endian Systems.
For Online Backup or Concurrent External Backup — You cannot restore an IRIS.DAT file on a target system whose endianness is different from the source system. Instead, do the following:
1. Use the procedure outlined in this section to restore on a system whose endianness is the same as the source.
2. Shut down InterSystems IRIS or dismount the databases.
3. Convert the database as described in Using cvendian to Convert Between Big-endian and Little-endian Systems.
4. Copy the IRIS.DAT files to the target system.
5. Use the procedure outlined in this section to restore on the target system with the converted databases, as described here for External Backup.

Considering Database Encryption

When you restore a database on a target system, it may be necessary to change the database encryption key for the restored database. Depending on the strategy you used to back up the database, you may have to convert the key on the restored database, as follows:

For Online Backup — Online backup stores the database contents unencrypted. When restoring an online backup file to an existing encrypted database on a target system, the online backup restore utility encrypts the file dynamically on the target system; otherwise the restored database is unencrypted.
For External Backup, Cold Backup or Concurrent External Backup — Depending on the state of the IRIS.DAT file on the source system, you may need to manage the database’s encryption after restoring it on the target system; for example, if the database files on the source and target systems use different encryption keys, you activate the key from the source on the target (see Key Management Tasks), or convert the restored database to use the key on the target (see Convert an Encrypted Database to Use a New Key).

Database-Only Restore