Skip to main content

Backup and Restore

This topic outlines the factors to consider when developing a solid plan for backing up your system. It discusses techniques for ensuring the integrity and recoverability of your backups, as well as suggested backup strategies. The topic also contains details about the procedures used to perform these tasks using either native or third-party utilities.

Backup strategies can differ depending upon your operating system, preferred backup utilities, disk configurations, and backup devices. If you require more information to help you to develop a backup strategy tailored for your environment, or to review your current backup practices, contact InterSystems Worldwide Response Center (WRC)Opens in a new tab.

Backup Integrity and Recoverability

Regardless of the backup strategies you use, it is critical to restore backups on a regular basis to validate your procedures. The best practice — to restore every backup of the production environment to an alternate server and then validate the integrity of the restored databases (see Verifying Structural Integrity) — provides the following advantages:

  • Validates the recoverability of the backup media.

  • Validates the physical integrity of the databases in the backup, avoiding the problem of false reporting of integrity errors when running integrity checks on volatile databases affected by ongoing updates.

  • Provides a warm copy of the backup, substantially reducing the time required to restore the backup in the event of a disaster. If such an event occurs, you need only restore the updates in the journal files.

  • Establishes a last known good backup.

The backup strategies described in this document preserve the physical structure of the database; therefore, a clean integrity check of the restored copy implies that the integrity of the production database was sound at the time of the backup. The converse, however, is not true: an integrity error detected on the restored copy of a database does not necessarily imply that there are integrity problems on the production database; there could, for example, be errors in the backup media. If you discover an integrity error in the restored database, immediately run an integrity check on the production database to verify the integrity of the production system.

To further validate that the application is working correctly on the restored database, you can also perform application-level checks. To perform these checks, you may need to restore journal files to restore transactional integrity. See Importance of Journals for more information.

Once you restore the backup and establish that it is a viable source of recovery, it is best to preserve that restored copy until you establish the next good backup. Therefore, the server on which you are validating the backup should ideally have twice the storage space required by production—space to store the last-known good backup as well as the backup you are currently validating. (Depending on your needs, you may have less stringent performance requirements of the storage device used for restoring backups, allowing for a less expensive storage solution.) In this way, the last-known good backup is always available for use in a disaster even if validation of the current backup fails. To protect enterprise databases from a disaster that could destroy the data center, regularly ship backup media to a secure off-site location.

Importance of Journal Restore

A restorable backup of an InterSystems IRIS® database alone is not enough to provide a viable restore of production data. In the event of a failure that requires restoring from backup, you must also apply journal files (described in Journaling) to the restored copy of the database. This journal restore accomplishes the following:

  • Restores all journaled updates from the time of the backup to the time of the failure.

  • Restore the transactional integrity of the database by rolling back uncommitted transactions.

While the backup approaches described in this topic can provide you with a physically consistent copy of databases that can be individually restored, you must also do a journal restore, even if you have no journals newer than the time of the backup, to ensure that any transactions that were open at the time of the backup are rolled back. This means that any backup approach you use must include each database’s journal files.

When restoring a crash-consistent snapshot image of your entire system (as in common in a virtualized environment), normal InterSystems IRIS startup recovery automatically ensures both physical integrity (including completion of interrupted writes) through the write image journal or WIJ (see Write Image Journaling), and logical integrity (including transaction rollback) through journaling. This means, however, that any such snapshot backup image of a database must include all components from a single moment in time, including the database, the instance’s installation directory, the WIJ, and the journal files, as well as any other external files associated with the database.

Be sure to see Journaling Best Practices for important information about ensuring journal availability for recovery. In particular, as explained in that section, in the interests of performance and recoverability, InterSystems recommends placing the primary and alternate journal directories on storage devices that are separate from the devices used by databases and the WIJ, as well as separate from each other.

Important:

It is critical to periodically test your entire disaster recovery procedure from start to finish. This includes backup restore, journal restore, and running simulated user activity on the restored environment.

Backup Strategies

The best strategies for backing up databases are external backup and online backup. This section describes these and other special-purpose strategies:

External Backup

External backup is currently the recommended best practice for backing up the entire database. It integrates easily with your existing system backup procedures and typically allows for a zero downtime backup. It is used primarily in conjunction with technology that provides the ability to quickly create a functional “snapshot” of a logical disk volume. Such technologies exist at various levels, from storage arrays, to operating systems, to simple disk mirroring. There are special considerations, discussed in this section, for systems on which snapshot technology is not available.

To ensure the integrity of the snapshot, InterSystems IRIS provides methods to freeze writes to databases while the snapshot is created. Only physical writes to the database files are frozen during the creation of the snapshot, allowing user processes to continue performing updates in memory uninterrupted. The snapshot is typically a snapshot of all file systems in use by the system. At a minimum, this includes all directories used by the InterSystems IRIS database in any way, such as the installation directory, database directories, journal and alternate journal directories, WIJ directory, and any directory containing external files used by the system. After writes are thawed, the snapshot may be backed up and then either rejoined to production or left online as a warm backup (depending on the specific technology used).

Note:

To avoid the problem of false reporting of errors when running integrity checks on databases while they are in use, you can integrate the integrity checks into procedures like those described in this section, so that databases are checked immediately after the file system snapshot is taken. (See Verifying Structural Integrity for information about checking database integrity.)

The following table lists the advantages and disadvantages of the external backup strategy:

Advantages Disadvantages

Allows zero downtime backups with no user interruption for most systems.

If writes are to be frozen for longer than 10 minutes, special consideration is required if you want to allow users to continue uninterrupted.

Integrates easily with existing backup procedures.

 

The class methods that perform the database freeze and thaw operations are Backup.General.ExternalFreeze()Opens in a new tab and Backup.General.ExternalThaw()Opens in a new tab, respectively. In addition to pausing writes, the freeze method also handles switching journal files and writing a backup marker to the journal. The journal file continues to be written normally while physical database writes are frozen. If the system were to crash while the physical database writes are frozen, data would be recovered from the journal as normal during startup.

To set up external backup, write a script that performs the following steps:

  1. Freeze writes to the database using the Backup.General.ExternalFreeze()Opens in a new tab method. Examples of the use of this method on various platforms are included in the class documentation.

    Note:

    When the security configuration requires that the backup script supply database credentials, you can do this by redirecting input from a file containing the needed credentials. Alternatively, you can enable OS-level authentication and create an InterSystems IRIS account for the OS user running the script.

  2. Create a snapshot of the file system using an external snapshot utility.

  3. Resume database writes using the Backup.General.ExternalThaw()Opens in a new tab method.

    Note:

    In the event the Backup.General.ExternalThaw()Opens in a new tab method does not resume the write daemon and unfreeze the instance, you can issue the irisstat command with the -W option to do so. (This option will not unfreeze the write daemon from any hang or suspension caused by anything other than a backup.)

  4. Copy the snapshot to the backup media.

  5. When the backup is complete, you can use the Backup.General.ExternalSetHistory()Opens in a new tab method to record this backup in the backup history. Note that recording the backup can trigger a journal purge, depending on the When to purge journal files > After this many successive backups setting on the Journal Settings page (the default is 2); for more information, see Configuring Journal Settings.

See Backup.GeneralOpens in a new tab for platform-specific examples of these methods.

For systems where snapshot technology is not available, a slower filesystem copy may be used in the external backup approach, described above, by replacing the creation of the snapshot with a filesystem copy. This can be done in one of the following ways or, depending on your needs, Online Backup may be an alternative:

  • Zero Downtime: Specify a value for the ExternalFreezeTimeOut parameter when calling Backup.General.ExternalFreeze()Opens in a new tab and ensure that you have configured sufficient database cache to allow database updates to be buffered in memory for the duration of the freeze. In this case the system allows users to continue working for extended periods with physical writes frozen, up to the specified ExternalFreezeTimeOut. Journaling is critical to prevent data loss in the event that the system crashes while writes are frozen; in the event of a crash, system startup may take longer than usual. The Journal setting for Freeze on Error should be set to Yes (see Journal I/O Errors for more information).

  • Some User Interruption: Allow the expected freeze time to default to 10 minutes, after which users are paused until Backup.General.ExternalThaw()Opens in a new tab is called.

Important:

When the instance being backed up is the primary failover member in a mirror (see Mirroring), an external freeze must not suspend updates for longer than the specified ExternalFreezeTimeOut parameter of Backup.General.ExternalFreeze()Opens in a new tab. If this happens, the mirror may fail over to the backup failover member, thereby terminating the backup operation in progress.

Note:

InterSystems IRIS supports the Volume Shadow Copy Service (VSS) on Windows by acting as a writer on behalf of its databases. Copies of InterSystems IRIS databases included in a VSS shadow are physically consistent, although not logically consistent with respect to transactions, and therefore may be restored individually. To ensure the transactional integrity of these restored databases, journal files should also be restored. Only databases that are mounted at the time of VSS shadow creation are included in the VSS shadow.

The VSS writer for InterSystems IRIS can be started only by an administrator.

On Windows systems, EnableVSSBackup parameter in the iris.cpf file is set to 1 (enabled) by default. At InterSystems IRIS startup, the message “InterSystems IRIS VSS Writer started” is written to the messages log. When you create a VSS shadow copy, InterSystems IRIS automatically calls Backup.General.ExternalFreeze()Opens in a new tab and Backup.General.ExternalThaw()Opens in a new tab, as indicated by messages in the messages log.

Important:

If you use VSS, make to use vSphere snapshot option Quiesce guest file system. This option invokes calls the VSS callbacks, which will freeze the database before the snapshot and thaw the database after the snapshot. The messages log will show VSS Writer: OnFreeze and VSS Writer: OnThaw.

In contrast, without this option, vSphere performs only a memory snapshot and the messages log does not contain these messages.

Backing Up on the Command Line

You can use the following command-line options to execute your backup:

iris freeze <instance> [timeout=<seconds>] [namespace=<shard master namespace>]

Calls the Backup.General.CommandLineFreeze()Opens in a new tab class method, which determines whether the instance is a member of a sharded cluster, then calls the appropriate class method as follows:

iris thaw <instance> [namespace=<shard master namespace>]

Calls the Backup.General.CommandLineThaw()Opens in a new tab class method, which determines whether the instance is a member of a sharded cluster, then calls the appropriate class method as follows:

Upon completion, the command-line methods pass a binary success/failure to the OS caller and halt the process. For testing purposes, the doHalt parameter of CommandLineFreeze() or CommandLineThaw() can be set to 0 to return the status instead of halting.

The command line argument timeout corresponds to the ExternalFreezeTimeout argument in ExternalFreeze() or ExternalThaw(). The system default (600 seconds) is usually sufficient, but you may want to extend the timeout on slow systems. When time runs out, the system pauses all operations instead of just pausing database writes.

The command line argument namespace corresponds to the ShardMasterNamespace argument in ExternalFreeze() or ExternalThaw(). The namespace argument is ignored in the general case and optional in the sharded case. CommandLineFreeze() and CommandLineThaw() default to the cluster’s MasterNamespace metadata value. If called from the data master, the default should suffice.

Recommended usage is as follows:

  1. Call iris freeze <instance> for all non-sharded data servers or on the shard data master only.

  2. Take snapshots for backup.

  3. Call iris thaw <instance> wherever you called iris freeze <instance>.

Online Backup

InterSystems IRIS implements a proprietary backup mechanism designed to cause very minimal or no downtime to users of the production system. Online backup, which only backs up data in IRIS.DAT files, captures all blocks in the databases that are allocated for data. The output goes to a sequential file. This must be coordinated with a system backup to copy the online backup output file to the backup media along with other files. This system backup must include all file systems in use by the system, excluding IRIS.DAT files. At a minimum it must include the installation directory, journal and alternate journal directories, Web Gateway files, and any directory containing external files used by InterSystems IRIS. Do not include IRIS.DAT files.

The online backup procedure uses multiple passes to copy data, where each consecutive pass copies an incrementally reduced list of data blocks that changed during the previous pass. Generally, three passes are sufficient to complete a backup. During the entire final pass and for a brief moment during each prior pass, the process pauses writes to the database. The backup pauses physical writes to the database while allowing user processes to continue performing updates in memory.

Given the capabilities of today’s external backup options, it is usually possible to find an external backup approach that suits your needs better than online backup. The following table lists the advantages and disadvantages of the online backup strategy:

Advantages Disadvantages

Allows zero downtime backups for most systems.

Backs up databases only.

Supports cumulative and incremental backups on a regular basis.

Backup and restore are relatively slow.
Does not require enterprise-class storage.

Restoring a single database requires processing the entire backup file.

 

Requires a running instance of InterSystems IRIS to perform a restore.

 

Restores can be cumbersome with extremely large amounts of data.

 

Backups of encrypted databases are unencrypted.

  May lack some features typical of modern external backup technology.

There are different types of online backup, which you can combine to manage the trade-offs between the size of the backup output and the time needed to recover from the backup:

  • Full Backup — Writes an image of all in-use blocks to the backup media.

  • Cumulative Backup — Writes all blocks that have been modified since the last full backup. Must be used in conjunction with a previous full backup.

  • Incremental Backup — Writes all blocks that have been modified since the last backup of any type. Must be used in conjunction with a previous full backup and (optionally) subsequent cumulative or incremental backups.

When using online backup, you must first run a full backup, after which you can run cumulative and/or incremental backups.

Online backup writes all database blocks to a single file in an interleaved fashion. When you back up an extremely large amount of data using the online backup, restores can become somewhat cumbersome; consider this when planning your backup strategy.

The restore validation process helps resolve any limitations by providing an online, restored copy of the databases. Use the same backup validation strategy when running incremental or cumulative backups. After you perform each incremental or cumulative backup, you can immediately restore to the alternate server. For example, a strategy of weekly full backups and daily incremental backups can work well because each daily backup contains only the blocks modified that day. Using this strategy, you should restore the incremental backup to the alternate server each day, and check the integrity of the restored databases.

Avoid overwriting the warm copy of the last known good backup when restoring the backup you are currently validating. The same concept applies when restoring an incremental to the existing restored database. After you establish that the backup is the last known good backup and before applying the next day’s incremental or cumulative backup to it, save a copy so that the last known good backup is always online and ready for use in case the subsequent incremental restore fails. If a restored backup fails an integrity check, you must discard it; you cannot use it as a target of a subsequent incremental restore.

When restoring a system from an online backup, first restore the most recent full backup, followed by the most recent cumulative backup, and then all incremental backups taken since the cumulative backup.

For information about configuring online backup, see Configuring Online Backup Settings; for information about performing online backups, see Managing Online Backups.

Cold Backup

Cold backup refers to an external backup of the system taken when the database has been shut down normally. The backup is typically a backup of all file systems in use by the system. At a minimum, this includes all directories used by InterSystems IRIS in any way, including the installation directory, database directories, journal and alternate journal directories, WIJ directory, and any directory containing external files used by the database. This strategy may be appropriate for systems where InterSystems IRIS is typically shut down at night.

The following table lists the advantages and disadvantages of the cold backup strategy:

Advantages Disadvantages

Simple procedure (stop and copy entire instance).

The database is not available.

Occasionally, it is useful to perform backups while the system is shut down.

 

Concurrent External Backup

The concurrent external backup strategy (also known as “dirty backup”) can be used when a zero-downtime backup is needed but deployment circumstances preclude standard zero-downtime external backup or zero-downtime online backup. A typical scenario under which this strategy might be considered, for example, is when snapshot technology is not available and the databases are so large that both of the following are true:

  • Using external backup, writes would be frozen (while the databases were being copied) long enough to impact users.

  • Using online backup would be impractical.

The concurrent external backup strategy works by allowing an external system backup to run while normal databases writes are taking place. The copies of the databases obtained in this manner are expected to be corrupt (“dirty”). This copy is then followed by an Incremental Online Backup, which captures any database blocks that were modified while the copy took place. When restoring the backup, first the copy of the databases are restored, then the incremental backup is restored. The steps in detail are as follows:

  1. Clear the list of database blocks modified since the last backup:

     Do CLRINC^DBACK("QUIET")

    For information, see CLRINC^DBACK.

  2. Copy the IRIS.DAT database files, using your chosen operating system or third-party backup utility.

  3. Call $$BACKUP^DBACK with the E parameter to indicate you used an external backup utility; for example:

     Set x=$$BACKUP^DBACK("","E","Dirty external backup - incrementals must be applied.","","","")

    For information, see BACKUP^DBACK.

  4. Perform an incremental backup, which copies any blocks that changed while the IRIS.DAT files were being copied; this may cause a very brief suspension of user processes in some configurations:

     Set x=$$BACKUP^DBACK("","I","Nightly","test.bck","N","bck.log","QUIET","N","Y")
    

    For information, see BACKUP^DBACK.

  5. Restore the backup according to the instructions under Full System Restore from Online Backup or Concurrent External Backup in Full System Restore.

The following table lists the advantages and disadvantages of the concurrent external backup strategy:

Advantages Disadvantages

Provides a backup strategy with little or no interruption for sites that are not able to use one of the other recommended approaches.

Multiple files need to be restored (IRIS.DAT database files and incremental backup files), which causes the restore process to take longer.

 

The procedure is complex.

 

Requires a running instance of InterSystems IRIS to perform a restore.

Restoring from a Backup

It is critical to restore backups on a regular basis to test your procedures. As described in Backup Integrity and Recoverability, InterSystems recommends restoring every backup onto an alternate server for validation and to serve as a warm copy of the restore.

Backup restores can be complex and time consuming, and the practice of regular restores helps mitigate the risks involved. Backup restore should be considered as part of your larger disaster recovery plan. Mirroring also provides alternate mechanisms for disaster recovery.

For additional help with backup restore scenarios, contact InterSystems Worldwide Response Center (WRC)Opens in a new tab.

This section includes the following topics:

Backup Restore Scenarios

There are many scenarios where a backup restore is performed, often with unique sets of requirements and restore procedures. This section describes the following general restore scenarios, including variations for different backup strategies:

  • Full System Restore — All or most of the storage used by InterSystems IRIS or the system as a whole has been rendered unusable. The full system backup has been restored from the backup media and now InterSystems IRIS must be recovered to a production-ready state.

  • Database-Only Restore — Some or all InterSystems IRIS databases have been rendered unusable and must be recovered from backup.

  • Restore/Migrate Database to Different Systems — One or more databases are being restored to a different system. The target system may be newer hardware, a different platform, or another instance of the database on the same hardware. The target system may have a different file system layout. This may be used to add databases to a backup or async mirror member (see Mirroring).

Important:

To avoid data incompatibility, the following requirements must be met when restoring or migrating a database to a different database instance than the one in which the backup was created:

  • The target instance must use the same character width (8-bit or Unicode; see Character Width Setting in the Installation Guide) and the same locale (see Using the NLS Settings Page of the Management Portal) as the source instance.

    The one exception to this requirement is that an 8-bit instance using a locale based on the ISO 8859 Latin-1 character set is compatible with a Unicode instance using the corresponding wide character locale. For example, a database created in an 8-bit instance using the enu8 locale can be used in a Unicode instance using the enuw locale.

  • If the source and target instances are on systems of different endianness (see Platform Endianness), the database must be converted to the endianness of the target instance before being used; see Restoring to a Target of Different Endianness for procedures.

Note:

If you have auto-start configured, you may want to prevent the instance from starting automatically when the host OS restarts. This can only be done at the OS level and is dependent on your configuration.

Full System Restore

This scenario assumes the following starting point:

  • The system where the restore is being performed is the same as, or identical to, the system that generated the backup.

  • All filesystems (or at least all files backed up) have been restored from the backup media and the path names at the operating system level are unchanged.

  • InterSystems IRIS is down and has not been started since the restore.

Full System Restore from External Backup or Cold Backup

If you used External Backup or Cold Backup procedures, your databases have been restored to a physically consistent state, but require at least transaction rollback to restore transactional consistently. You may also have journal files from after the time of the backup that you wish to apply before rolling back transactions. This section provides two recommended procedures, one of which you should use (depending on the details of the backup and restore you performed) for the required journal restore and transaction rollback.

If the image of the system that was restored is a snapshot of all elements of InterSystems IRIS, including the IRIS.WIJ file and journal files, from a single moment in time—that is, a crash-consistent image—and you have no newer journal files to apply, you can simply start InterSystems IRIS normally; InterSystems IRIS automatically performs journal recovery and transaction rollback. This is also true if you start InterSystems IRIS in maintenance mode, as described in Starting InterSystems IRIS for Maintenance.

Note:

The preceding recommendation applies after a crash-consistent snapshot of the entire system is restored even if normal external backup procedures (as described in External Backup and Cold Backup) were not used. In that case, the database files in the restored image may not be physically consistent, but are recovered automatically from the IRIS.WIJ file before automatic journal recovery and transaction rollback. For details on recovery, see Fundamental Data Integrity Protection and the sections that follow it.

If the restored image does not includes all elements of InterSystems IRIS — that is, the IRIS.WIJ file, the journal files, and other InterSystems IRIS files — from a single moment in time, or if you have newer journal files to apply, you must use the following procedure to perform journal restore manually, which includes transaction rollback.

Important:

This procedure assumes that the IRIS.WIJ file was backed up as part of the backup snapshot and restored along with the databases and other files and file systems, which is the recommended way to plan your backup and restore procedures. If the IRIS.WIJ file is not included in your backup, see Starting InterSystems IRIS Without Automatic WIJ and Journal Recovery for information about how to start InterSystems IRIS.

  1. Start InterSystems IRIS in maintenance mode as described in Starting InterSystems IRIS for Maintenance to perform a journal restore before users are allowed to access the system. If the instance is already running, you should stop it first and then start it again in maintenance mode.

    Note:

    If the system is down and you have auto-start configured, you may want to prevent the instance from starting automatically, so that you can start the instance in maintenance mode directly. This can only be done at the OS level and is dependent on your configuration.

  2. Restore the journals as described in Journal Restore Following Backup Restore.

  3. After the journal restore is complete, you can perform application validation or additional maintenance as needed.

  4. Restart InterSystems IRIS normally to allow users to access the system.

Full System Restore from Online Backup or Concurrent External Backup

The remainder of this section discusses the full system restore for users of Online Backup or concurrent external backup. You must perform an online backup restore to restore the databases from the backup output file. For online backup, the backup output file is written to the backup media as part of the full system backup, as described in Online Backup.

The online backup restore operation must be executed on a running instance, but the target of a full system restore cannot be running during the operation. Therefore, you must have a separate, secondary instance of InterSystems IRIS installed and available on which to execute the full system online backup restore operation. The databases being restored do not need database or namespace definitions in the secondary instance.

The secondary instance (IrisDB-2) can be installed as part of this restore procedure by running the installer and selecting an instance name and installation directory that is different from the target instance (IrisDB-1). Alternatively, to avoid this step at restore time, install the secondary “restore” instance when you decide to use the online backup strategy. This secondary instance should be shut down at all times and its installation directory backed up as part of the full system backup (that is, it would be a Cold Backup for the secondary instance). It could simply be started during a full system restore in order to run the online backup restore of the target instance.

To restore from an online backup or concurrent external backup after a full system restore:

  1. Using the secondary instance of the database (IrisDB-2), follow the instructions in Online Backup Restore Utility to:

    1. Restore the last full backup (if using concurrent external backup, the full backup was already restored externally during the filesystem restore) of the target instance.

    2. If you have done cumulative backups since the full backup, restore the last one; otherwise, continue with the next step.

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

  2. Using the secondary instance of the database (IrisDB-2), follow the instructions in Journal Restore Following Backup Restore.

  3. Shut down the secondary instance of the database (IrisDB-2).

  4. Start the target instance (IrisDB-1) as described in InterSystems IRIS Without Automatic WIJ and Journal Recovery. This step leaves the InterSystems IRIS database running in maintenance mode, which lets you perform application validation or additional maintenance.

  5. Restart the target instance (IrisDB-1) normally to allow users to access the system.

Important:

If you used concurrent external backup on a mirrored database on an async mirror member, you must activate the database once the mirror has started.

Database-Only Restore

This scenario assumes the following starting point:

  • The system where the restore is being performed is the system that generated the backup and the databases are to be restored to their original location.

  • You have identified the set of databases that require restoration.

  • InterSystems IRIS may be up and users may be accessing other databases normally; the databases requiring restoration may not be required for startup.

  • InterSystems IRIS may be unable to start fully; the databases requiring restoration may be required for startup, or damaged in a way that is preventing startup from completing.

Note:

If you used External Backup or Cold Backup and you have many database that need to be restored, a simpler procedure may be to shut down InterSystems IRIS, restore ALL IRIS.DAT files, and perform the restore procedures described in Full System Restore. This is especially true if the IRISSYS database must be restored.

To perform a database-only restore:

  1. If the database is not started already, start it as described in Starting InterSystems IRIS for Maintenance. Starting the database ensures that any pending automatic recovery to existing databases occurs immediately and does not conflict with the databases that you are about to restore on subsequent startup.

    If the system is already started and you are restoring databases that users may attempt to access during the restore process, InterSystems recommends that you shut down and restart as described in Starting InterSystems IRIS for Maintenance.

    The following table describes recommended procedures to resolve the problems that prevent a successful start of the database.

    Problem Solution
    1. InterSystems IRIS fails to start

    Starting InterSystems IRIS in maintenance mode allows the system to start even if a database that is required for startup cannot be mounted. However, if there is automatic journal recovery pending for a database that is marked as required for startup, the database does not skip it.

    Therefore, if damaged databases are still preventing the system from starting:

    1. Rename the IRIS.DAT files to make the database completely inaccessible.

    2. Change the configuration to mark those databases as not required for startup,

    3. Try again to start the system as described in Starting InterSystems IRIS for Maintenance.

    2. If InterSystems IRIS cannot start due to a damaged IRISSYS database

    Temporarily replace the IRISSYS database with a copy from an External Backup, or from a new install of the same version of InterSystems IRIS. This is temporary solution to get the system started to complete the restore procedure.

    3. InterSystems IRIS still does not start

    You may need to restore all databases following the procedure in Full System Restore.

    For additional help, contact InterSystems Worldwide Response Center (WRC)Opens in a new tab.

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

    For all databases except IRISSYS:

    1. Dismount the database from InterSystems IRIS.

    2. Copy the IRIS.DAT files from the backup media to their original locations.

    3. Remount the database.

    If you are restoring the IRISSYS database, restore it to an alternate directory temporarily.

    Online Backup

    Follow the instructions in theOnline Backup Restore Utility to:

    1. Restore the last full backup.

    2. If you have done cumulative backups since the full backup, restore the last one; otherwise, continue with the next step.

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

  3. Follow the instructions in Journal Restore Following Backup Restore.

  4. If you started InterSystems IRIS as described in Starting InterSystems IRIS for Maintenance, and you are ready to allow users on the system, stop and restart InterSystems IRIS normally. You can perform application validation or additional maintenance before restarting.

    Note:

    If you restored the IRISSYS database from External Backup or Cold Backup to a temporary alternate directory as described in the table in step 2 of this procedure, you must replace the existing IRISSYS database with the IRIS.DAT file from the temporary directory after shutting down (before restarting) InterSystems IRIS.

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.

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

  2. 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:

    1. Dismount any databases being restored if they are mounted on the target instance.

    2. Copy the IRIS.DAT files from the backup media to the desired locations.

    3. Add any new databases to the configuration.

    4. Remount the database that you dismounted.

    Online backup

    Follow the instructions in the Online Backup Restore Utility to:

    1. Restore the last full backup.

    2. If you have done cumulative backups since the full backup, restore the last one; otherwise, continue with the next step.

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

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

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

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

Starting InterSystems IRIS for Maintenance

During any restore procedure it is critical that no application activity occurs in the databases being restored until you are completely finished with the backup restore and journal restore, and you have completed any desired application-level validation. If you have in your application or operating environment, a mechanism to ensure that no user activity can occur when the database is started, then you can use that mechanism; for example, if your application is entirely web-based, shutting down the web servers may be sufficient to ensure that only administrators involved in the restore procedure have access to the system.

InterSystems IRIS provides a mechanism to let you start the system with limited access while maintenance is performed.

To start InterSystems IRIS for maintenance:

  1. Start InterSystems IRIS in emergency access mode, specifying a unique username and password to be used for all maintenance activity; this username and password should not match any existing user:

    • On Windows, invoke the following command as administrator from the bin directory of your installation:

      iris start <db-instance-name> /EmergencyId=<username>,<password>
      
    • On UNIX®/Linux and macOS platforms, invoke the following command:

      iris start <db-instance-name> EmergencyId=<username>,<password>
      

    For more information, see Emergency Access.

  2. Perform the remaining portions of the restore procedure as documented for your restore scenario.

  3. After completing the restore procedure — including any journal restore, application validation, or other maintenance activities — make the system available to users as follows:

    1. Shut down the database.

    2. Start the database without the EmergencyId switch.

Journal Restore Following Backup Restore

It is necessary to apply journal files following backup restore. As described in Importance of Journals, you usually have journal files available at restore time that are newer than the backup. Applying these journal files restores all journaled updates from the time of the backup to the time of the disaster.

Additionally, applying journals is necessary to restore the transactional integrity of your restored database (which may have partial transactions) by rolling back uncommitted transactions. This is required even if you only have journal files up to the moment of the backup and not newer.

Important:

If you do not have journal files at least up to the moment of the backup, do not apply any journal files.

When you start the restore, you must select a start point for journal restore. The journal restore may then need to look backwards in the journal stream to find the beginning of a transaction that began prior to the backup. When you use Online Backup, the backup stores a suggested start point; when you back up using the ^DBACK or ^BACKUP utilities, the utility displays information about the oldest journal file required for transaction rollback during restore at the beginning of the third and final pass.

For information about how to apply journals following the backup restore, see Restore All Databases Using ^DBREST and Restore Journal Files.

Starting InterSystems IRIS Without Automatic WIJ and Journal Recovery

Some of the restore procedures described on this page require starting InterSystems IRIS in a way that prevents the automatic recovery of databases at startup from occurring. This is specified when all of the recovery is to be done manually in the restore procedure and the automatic startup recovery may be incompatible with the manual recovery effort.

Caution:

The restore procedures documented on this page explicitly state when the following procedure is necessary. Performing the procedure at any other time is extremely dangerous and could damage database integrity.

To start InterSystems IRIS without automatic WIJ and Journal Recovery:

  1. Remove but do not delete the IRIS.WIJ file, so that it remains available for analysis, as follows:

    1. Check the startup.last file in the manager directory for the line wijlast=.

    2. Move or rename the IRIS.WIJ file in the directory specified in that line. If a null directory is specified, the IRIS.WIJ file is located in the manager directory.

  2. Start InterSystems IRIS in emergency access mode, specifying a unique username and password to be used for all maintenance activity; this username and password should not match any existing user:

    • On Windows, invoke the command from the bin directory of your InterSystems IRIS installation:

      iris start <iris-instance-name> /EmergencyId=<username>,<password>
      
    • On UNIX®/Linux and macOS platforms, invoke the command:

      iris start <iris-instance-name> EmergencyId=<username>,<password>
      

    For more information, see Emergency Access.

  3. In most cases, InterSystems IRIS does not start completely due to the missing journal recovery information in the WIJ. If InterSystems IRIS starts normally, skip the remainder of this procedure.

  4. Follow the instructions in the messages.log to enter InterSystems IRIS with the -B option and run do ^STURECOV:

    1. Select option 8 to reset InterSystems IRIS to start without journal recovery.

    2. Select option 9 to shut down InterSystems IRIS (using the displayed instructions).

  5. Start InterSystems IRIS in emergency access mode again, as described in step 2.

  6. Perform the remaining portions of the restore procedure as documented for your restore scenario.

  7. After completing the restore procedure — including any journal restore, application validation, or other maintenance activities — you can make the system available to users as follows:

    1. Shut down InterSystems IRIS.

    2. Start InterSystems IRIS without the EmergencyId (/EmergencyId on Windows platforms) switch.

Configuring Online Backup Settings

Online backup is one of the backup strategies that you can implement. For information about the supported strategies and the best practices for using them, see Backup Strategies.

You can configure the online backup settings using the choices in the System Administration > Configuration > Database Backup menu of the Management Portal. You can also perform some of these tasks using the methods in the Backup.GeneralOpens in a new tab class. This section points you to the appropriate method where it applies.

When an online backup is complete, your description of the backup is written to the backup history (see View Backup History). Note that this can trigger a journal purge, depending on the When to purge journal files > After this many successive backups setting on the Journal Settings page (the default is 2); for more information, see Configuring Journal Settings.

From the System Management portal you can perform the following configuration tasks:

Note:

The configuration tasks are in the management portion of the Management Portal application; you must have the appropriate manager-level security to configure the backup settings.

Define Database Backup List

InterSystems IRIS maintains a database list that specifies the databases to back up. You can display this list by navigating to the System Administration > Configuration > Database Backup > Database Backup List page of the Management Portal.

Use the arrow buttons to move the databases you do not want to back up to the Available list and the databases you do want to back up to the Selected list. Click Save. If you do not select any databases, the system backs up all databases.

When you add a new database to your system, the system automatically adds it to the database list. If you do not need to include the new database in your backup plan, be sure to remove it from the Backup Database List.

Note:

The defined database list is ignored by the FullAllDatabases backup task, which performs a backup of all databases excluding the IRISTEMP, IRISLIB, and IRISLOCALDATA databases.

You can also maintain the backup database list using the ^BACKUP routine or the Backup.General.AddDatabaseToList()Opens in a new tab and Backup.General.RemoveDatabaseFromList()Opens in a new tab methods. See Backup.GeneralOpens in a new tab for details on using these methods.

Configure Backup Tasks

InterSystems IRIS provides different types of backup tasks; each is listed as an item on the Database Backup Settings menu. The configuration backup tasks are:

  • Configure Full Backup of All Databases

  • Configure Full Backup of the Database List

  • Configure Incremental Backup of the Database List

  • Configure Cumulative Backup of the Database List

These are predefined backup tasks that you can run on-demand from the System Operation > Backup page of the portal. You can also schedule combinations of these backup tasks using the Task Manager. See Schedule Backup Tasks for details.

The process for configuring each of these tasks is the same. The Name, Description, and Type fields are read-only and reflect the menu choice as described in the following table.

Backup Task Descriptions
Name Description Type
FullAllDatabases Full backup of all commonly updated databases, whether or not they are in the Backup Database List. Full
FullDBList Full backup of the InterSystems IRIS databases listed in the Backup Database List. Full
IncrementalDBList Incremental backup of changes made to the data since the last backup, whether full or cumulative. Backup is performed on the databases currently listed in the Backup Database List. Incremental
CumuIncrDBList Cumulative and Incremental backup of all changes made to the data since the last full backup. Backup is performed on the databases currently listed in the Backup Database List. Cumulative

To send backup output to a directory on disk, specify the file pathname in the Device field. Click Browse to select a directory.:

Define Database Backup List describes how to maintain the Backup Database List.

Backup File Names

By default, backup files are stored in install-dir\Mgr\Backup. The backup log files are stored in the same directory. Backup files have the suffix .cbk. Backup log files have the suffix .log.

Backup files and backup log files use the same naming conventions:

  • The name of the backup task, followed by an underscore character (_)

  • The date of the backup, in yyyymmdd format, followed by an underscore character (_)

  • The numeric suffix, nnn, of the name of the new journal file following the journal switch triggered when the backup task begins (see Switch Journal Files

  • The .log or .cbk suffix

For example, if the new journal file after the switch triggered by the FullDBList backup task is named 20211031.003, the name of the backup file is FullDBList_20211031_003.cbk and the name of the backup log file is FullDBList_20211031_003.log.

Schedule Backup Tasks

You should ideally set up a schedule for running backups. Backups are best run at a time when there are the least amount of active users on the system.

In addition to the four on-demand backup tasks supplied by default, you can create additional definitions of these four backup tasks. For example, to alternate backups between two disk drives, you could create a backup task for each drive.

Use the InterSystems Task Manager to schedule these backup tasks:

  1. Navigate to the Task Scheduler wizard in the Management Portal (System Operation > Task Manager > New Task).

  2. Click Schedule New Task.

  3. Specify the Task name, Description, Task type, in addition to any changes to the defaults and click Next.

  4. Enter your desired scheduling information and click Finish.

You can now view your task on the View Task Schedule page (System Operation > Task Manager > View Task Schedule) and manage it as you do other tasks by clicking Details on its row.

Managing Online Backups

Online backup is one of the backup strategies that you can implement. For information about the supported strategies and the best practices for using them, see Backup Strategies.

You can manage online backups from both the Management Portal and the InterSystems ^BACKUP utility. This section focuses on the portal procedures and, where applicable, points to the section that describes the utility procedure.

You can run database backup tasks and view backup history from the System Operation > Backup page of the Management Portal. If you schedule additional backup tasks using the Task Manager, you can manage those from the System Operation > Task Manager > Task Schedule page of the Management Portal.

You can perform the following backup tasks from the System Management portal:

When you add a new database to your system, you must perform a full backup. You cannot perform an incremental backup until a full backup exists. If you intend to use the incremental and cumulative backup options, you must maintain the backup database list and run a full backup on that list.

After installation, InterSystems recommends that you perform a FullDBList backup to establish a complete backup for subsequent use by the other backup tasks.

Note:

These backup tasks are in the operations portion of the Management Portal application; you must have the appropriate operator-level security to run the backup tasks.

Run Backup Tasks

There are four types of backup tasks you can run from the Management Portal Backup menu options (System Operation > Backup), each having its own menu item:

  • Run Full Backup of All Databases

  • Run Full Backup of the Backup Database List

  • Run Incremental Backup of the Backup Database List

  • Run Cumulative Backup of the Backup Database List

You must have performed a full backup on a database before performing an incremental or cumulative backup on that database. Use the following procedure to run an online backup:

  1. Click the menu item of the appropriate backup type.

  2. Verify that the settings in the Run Backup Task box are correct.

  3. If the backup options are correct, click OK to start the backup.

    Otherwise, follow the procedures in Configuring Online Backup Settings to update them.

  4. While the backup is running, you can view the status of the running backup by clicking the text next to Backup started. See View Backup Status for details.

You can also run the last three of these backup tasks by choosing option 1) Backup from the ^BACKUP utility or running the ^DBACK utility. See Back Up Databases Using ^DBACK for details.

Multivolume Backups

A backup may require multiple disk files. Currently, there is no way to perform a multivolume backup using the Management Portal. If you require a multivolume backup, use the ^BACKUP utility. If a disk-full condition occurs, ^BACKUP prompts you for the name of another disk file on another disk.

In the event of an error during backup, you cannot restart the backup on a second or subsequent volume. You must restart the backup from the beginning.

See Estimate Backup Size Using ^DBSIZE for instructions on estimating the size of your backup before you run these tasks.

View Backup Status

Click View Backup Status from the System Operation > Backup page or click View on the running backup process to monitor the progress of the backup operation. The same information is recorded in the log file for that backup operation, which you can later view from the View Backup History page.

Starting a backup updates the Time and Status columns of the listing. The Time column records the date and time you initiate the backup, not when it completes. The Status column is updated to Running.

Completing a backup again updates the Status column to indicate the final status of the backup. For example:

  • Completed indicates the backup successfully completed.

  • Failed indicates the backup could not be performed or was aborted by the operator.

  • Warning indicates problems occurred during the backup, but it completed.

The associated backup log contains helpful information; click View next to the task to view the backup log.

Abort a Running Backup describes an additional option that appears for a backup that is running.

Abort a Running Backup

There are three ways for you to abort a running backup:

View Backup History

Every backup operation creates a separate backup log file. The logs follow the naming convention described in Backup File Names.

From the portal you can view a list of system backup logs from completed backup tasks:

  1. Navigate to the System Operation > Backup page of the Management Portal.

  2. Click View Backup History in the right-hand column to display the Backup History page, which lists information about the completed backups.

  3. To view the results of a particular backup, click View in the right-hand column of the appropriate row. You can view the contents of a backup log file and search for a string within that file.

Backup Errors

If a backup encounters any I/O errors, the backup aborts and logs a system error in the backup log file. Information in these log files allows you to quickly see where the problem occurred so that you can fix it.

One cause of backup failure is trying to perform a backup on a dismounted database. In the event of an error during backup, the backup utility allows you to retry the device on which the error occurred. Alternatively, you can abort the backup.

Online Backup Utilities

InterSystems IRIS provides utilities to perform backup tasks. The ^BACKUP routine provides menu choices to run common backup procedures, which you can also run independently and in some cases non-interactively using scripts.

The utility names are case-sensitive. Run all these utilities from the %SYS namespace:

InterSystems IRIS maintains a bitmap list of database blocks modified since the last backup; you can use this list to keep track of database updates during backup stages. The ^DBSIZE utility, which inspects these bitmaps, helps you calculate the size of a backup. The InterSystems IRIS ^BACKUP utility uses a multipass scan of these lists to back up only the blocks modified since the last pass.

Estimate Backup Size Using ^DBSIZE

Immediately before performing an InterSystems IRIS backup, you can estimate the size of its output using the ^DBSIZE utility. It is only an estimate, since there is no way of knowing how many blocks will be modified once the backup starts. You can obtain a more accurate estimate by preventing global updates while running ^DBSIZE, and then running your backup before resuming global updates.

You can estimate the size of backups in two ways:

Note:

A database must be in the database backup list before you can evaluate it with ^DBSIZE. See Define Database Backup List for details.

Run ^DBSIZE Interactively

The following procedure describes the steps necessary to run ^DBSIZE interactively:

  1. Open the Terminal and run the utility from the %SYS namespace:

    %SYS>Do ^DBSIZE
    
    
  2. InterSystems IRIS displays the ^DBSIZE main menu:

                   Incremental Backup Size Estimator
     
     
    What kind of backup:
       1. Full backup of all in-use blocks
       2. Incremental since last backup
       3. Cumulative incremental since last full backup
       4. Exit the backup program
    1 => 
    
    
  3. Enter the appropriate menu option to select the type of backup for which you want an estimate: full, incremental, or cumulative. The prompts are the same for each type.

  4. At the following prompt either press Enter to suspend updates so that you get a more accurate estimate or enter No to allow updates:

    Suspend Updates?  Yes=>
    

    If you choose to suspend updates, you receive the following message:

    WARNING: Switch is set and may affect production for up to 30 seconds.
    Waiting for disk cleanup to finish... ready.
    
  5. The output first shows you how many InterSystems IRIS blocks you need to do the type of backup you selected. It shows an estimate for each directory in the backup list and a total. The following is an example of the display for a full backup:

    
                                                         In-Use    Block
    Directory                                            Blocks    Size
    
    c:\iris-install\mgr\                                  19,963   (8KB)
    c:\iris-install\mgr\irisaudit\                           189   (8KB)
    c:\iris-install\mgr\user\                                 61   (8KB)
                                                          --------------
     Total number of database blocks:                     36,228
    
    

    The display for an incremental and cumulative backup looks similar to this:

    
                                                         Modified  Block
    Directory                                            Blocks    Size
     
    c:\iris-install\mgr\                                       5   (8KB)
    c:\iris-install\mgr\irisaudit\                             3   (8KB)
    c:\iris-install\mgr\user\                                  1   (8KB)
                                                        - --------------
    Total number of database blocks:                          10
    
    
  6. The utility then displays information about backup disk file space:

    Total backup size, including overhead of volume and pass labels:
     
         For a disk file:
              Number of 512-byte blocks:  598,092  (306,223,104 bytes)
    

Use the ^DBSIZE Function

You can also call ^DBSIZE from a routine. To do so, you use the following function:

$$INT^DBSIZE(backup_type)
Important:

The values of backup_type differ from the menu option numbers when running ^DBSIZE interactively.

backup_type Description
1 Incremental backup
2 Full backup
3 Cumulative incremental backup

For example, to see the size estimate for running a full backup:

%SYS>w $$INT^DBSIZE(2)
18950^5^160952320^2710^160309248^313104^313104

The returned value is seven numbers separated by a caret (^). In this example, the returned value 18950 is the total estimated size of the backup, in blocks; the returned value 5 indicates the number of database directories to back up. The following table shows what is contained in each piece of the output.

Position of output Description
Piece 1 Number of database blocks for backup

(-1 if error during processing or invalid parameter)

Piece 2 Number of directories to back up
Piece 3 Number of bytes for media (not including inter-record gaps)
Piece 4 Number of blocks for media
Piece 5 Number of bytes for a disk file
Piece 6 Number of 512-byte blocks for a disk file

The following shows the output of calling the ^DBSIZE function for each type of backup:

%SYS>w $$INT^DBSIZE(1)
466^5^4157440^70^4122624^8052^8052

%SYS>w $$INT^DBSIZE(2)
18950^5^160952320^2710^160309248^313104^313104

%SYS>w $$INT^DBSIZE(3)
466^5^4157440^70^4122624^8052^8052

Perform Backup and Restore Tasks Using ^BACKUP

The InterSystems IRIS ^BACKUP utility allows you to perform InterSystems IRIS backup and restore tasks from a central menu as shown in the following example:

%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
5) Abort Backup

6) Display Backup volume information
7) Monitor progress of backup or restore

Option?

Enter the appropriate menu option number to start the corresponding routine. Press Enter without entering an option number to exit the utility.

Subsequent sections in this document describe the utilities started by choosing the corresponding option:

  1. Back Up Databases Using ^DBACK

  2. Restore All Databases Using ^DBREST

  3. Restore Selected Databases Using ^DBREST

  4. Edit/Display List of Directories for Backup Using ^BACKUP

  5. Abort a Backup Using ^BACKUP

  6. Display Information About a Backup Volume Using ^BACKUP

  7. Monitor Backup or Restore Progress Using ^BACKUP

Back Up Databases Using ^DBACK

The InterSystems ^DBACK utility allows you to backup InterSystems IRIS databases. Running the ^DBACK utility is equivalent to choosing option 1 from the ^BACKUP utility menu. The following is an example of running the utility from the Terminal:

  1. First, make sure you have defined your database backup list and choose your output device for the backup file.

  2. From the %SYS namespace run the ^DBACK routine:

    %SYS>Do ^DBACK
     
     
                          Backup Utility
                  --------------------------
    What kind of backup:
       1. Full backup of all in-use blocks
       2. Incremental since last backup
       3. Cumulative incremental since last full backup
       4. Exit the backup program
    
    
  3. Select which backup type (full, incremental, or cumulative) to run by entering the appropriate menu option number. The procedure for running the backup is the same regardless of what type you run.

  4. Enter the output device and a description of the backup:

    Specify output device (type STOP to exit)
    Device: c:\iris-install\mgr\backup\FullDBList_20081201_003.cbk =>
    
    Backing up to device: c:\iris-install\mgr\backup\FullDBList_20081201_003.cbk
    Description: Full Backup using ^DBACK
    
    

    The device defaults to that of the last backup. This example uses the format of the online backup device.

  5. The utility then displays a list of the database directories to back up (those in your database backup list). For example:

     Backing up the following directories:
     c:\iris-install\mgr\
     c:\iris-install\mgr\irisaudit
     c:\iris-install\mgr\user\
     
    
    
  6. Answer Y to start the backup. The journal file switches and you see a display of the backup progress:

    Start the Backup =>  [answer Y or N] => y
    Journal file switched to:
    c:\iris-install\mgr\journal\20081201.004
    . 
    Starting backup pass 1
    
  7. At the beginning of the third and final pass, the utility displays information about the oldest journal file that will be required for transaction rollback when the backup is restored, for example:

    Starting backup pass 3
     
    Journal file 'c:\intersystems\test62\mgr\journal\20180919.003' and the subsequent ones
    are required for recovery purposes if the backup were to be restored
     
    Journal marker set at
    offset 197180 of c:\intersystems\test62\mgr\journal\20180919.003
    

    This information is available in the backup log.

  8. When the backup finishes successfully, you see the following:

    ***FINISHED BACKUP***
     
    Global references are enabled.
     
    Backup complete.
     
    %SYS>
    
    Note:

    Following successful completion of the backup, ^DBACK writes your description of the backup to the backup history (see View Backup History). Note that this can trigger a journal purge, depending on the When to purge journal files > After this many successive backups setting on the Journal Settings page (the default is 2); for more information, see Configuring Journal Settings.

External Entry Points for ^DBACK explains how to call this utility from your external backup procedures using the provided entry points.

External Entry Points for ^DBACK

The entry points provided for the ^DBACK utility are for you to use in your external backup procedures. You must use them as described to ensure the integrity of the backup. All of the entry points return 1 if they are successful or 0 if they fail. The following external entry points are available for the ^DBACK routine:

BACKUP^DBACK

This procedure invokes a backup using the passed arguments to satisfy the questions that are asked during the interactive execution of ^DBACK.

BACKUP^DBACK(argfile,TYPE,DESC,OUTDEV,kiljrn,LOGFILE,MODE,clrjrn,swjrn,
nwjrnfil,quietimeout,taskname)

The capitalized arguments are the ones most important to the backup procedure in this release of InterSystems IRIS. Due to changes in the journaling mechanism, you can no longer delete the current journal file, clear the current journal file, or specify a new journal file name in the backup utilities. As a result, this version of InterSystems IRIS ignores many of the arguments as described in the following tables.

Argument Description
argfile No longer used; always use a null value.
TYPE Type of backup (required)

Values:

I — Incremental

C — Cumulative

F — Full

E — External full backup using a third-party or operating system backup utility

DESC Description stored in the backup label and in the backup history global. Free form text string that can be empty.

External (type E) backups ignore the arguments in the following table. Whether they are ignored or required for other backup types is also indicated in the table.

Argument Description
OUTDEV Output filename for the backup (required).
kiljrn Indicates whether to switch the journal file:

Y — switch the journal file (recommended)

N — do not switch

(No longer allows deletion of the current journal file)

LOGFILE Indicates whether or not to log and where to write the output of the function:

File name — writes all messages that would be sent to the terminal to this file (recommended)

Null value — no log file

MODE Indicates what output to write to the terminal during the procedure; this does not control what is written to the log file.

Values:

“NOISY” — write all text on terminal (default)

“QUIET” — only write text related to abnormal conditions

“NOINPUT” — do not send any output as no terminal is attached to this process; if a read is required, the backup aborts

clrjrn Indicates whether to switch the journal file:

Y — switch the journal file (recommended)

N — do not switch

(No longer allows clearing of the current journal file)

swjrn Indicates whether or not to switch the journal file:

Y — switch the journal file (recommended)

N — do not switch (If the clrjrn or kiljrn arguments have a value of Y, swjrn converts to Y and the journal file is switched)

nwjrnfil (Ignored)

The following are two optional arguments:

Argument Description
quietimeout Number of seconds to wait for the system to quiesce before aborting the backup. A zero (0) or negative value indicates waiting indefinitely (default = 60).
taskname Task name used internally for backup types F, I, and C.

Using these external entry points requires read/write access to the ^SYS global for all modes. An external (type E) backup deletes the .IND, .INE, and .INF files in the directories in the ^SYS global. The routine also records this backup with the description in the backup history global as being the LASTFULL backup.

If you set switch 10 when you call this routine, it remains set throughout the backup. If you set switch 13, then the procedure converts it into a switch 10 while the backup performs necessary Set and Kill commands and then restores it to switch 13 upon exit.

The routine performs the New command on variables defined by this entry point, but does not on those defined within the body of the ^DBACK procedure. As a result, you must be careful to protect all other variables in any calling routine prior to calling ^DBACK.

Return values:

  • 0 — failed; check log file if specified.

  • 1 — success

  • 1,warning message string — success, but with warnings. The warnings are separated by a tilde character (~) in the string.

LISTDIRS^DBACK

This procedure opens an output file and writes a list to it of database directories included in a backup. If the list is empty, the procedure backs up all database directories (except IRISTEMP, IRISLIB, and IRISLOCALDATA). The format of the function is as follows:

LISTDIRS^DBACK(file,mode)
Argument Description
file Name of the output file name to which the function writes the list of database directories in the backup list.
mode Indicates what output to write to the terminal during the procedure.

“QUIET” — Only display return value and text related to abnormal conditions.

Any other value — Display the directory list at the terminal.

The following is an example of the output displayed on the terminal:

%SYS>w $$LISTDIRS^DBACK("c:\temp\listdirs.txt","NOISY")
 
List of directories to be backed up
     c:\iris-install\mgr\irisaudit\
     c:\iris-install\mgr\irislib\
     c:\iris-install\mgr\
     c:\iris-install\mgr\user\
1
%SYS>

Notes for this procedure:

  • Requires read access to the ^SYS global.

  • Does not set or clear any switches.

  • Issues a New command on all local variables.

CLRINC^DBACK (concurrent external backup Only)

This procedure is called to clear the incremental backup bitmaps that mark blocks as modified for the databases in the backup list. At the same time it also deletes the backup history as it is no longer possible to do any sort of a backup without first performing a full backup. This procedure is designed to be used prior to doing an external full backup with InterSystems IRIS running. If you perform an external backup with InterSystems IRIS down, then before shutting down the system, call this entry point. The format of the function is as follows:

CLRINC^DBACK(mode)
Argument Description
mode Indicates what output to write to the terminal during the procedure.

“QUIET” — Only display return value and text related to abnormal conditions.

Any other value — Display the directory names as they are processed.

For example:

%SYS>w $$CLRINC^DBACK("QUIET")
1
%SYS> 

%SYS>Do CLRINC^DBACK("NOISY")
 
     Cleared incremental backup bitmap in c:\iris-install\mgr\
     Cleared incremental backup bitmap in c:\iris-install\mgr\irisaudit\
     Cleared incremental backup bitmap in c:\iris-install\mgr\user\
%SYS>

Notes for this procedure:

  • Requires read and write access to the ^SYS global.

  • Records the state of switch 13, sets it if it is not already, and restores it to its original state upon exit.

  • Issues a New command on all local variables except those defined in the main backup procedure.

  • Leaves directories dismounted if they are dismounted when you call this routine.

Edit/Display List of Directories for Backup Using ^BACKUP

Important:

When editing the database list use the database name, not the directory name. This is consistent with the way the backup configuration works in the Management Portal.

Options of the InterSystems IRIS ^BACKUP utility allow you to backup InterSystems IRIS databases or to restore an already created backup. If you have not created a list of databases, then the utility includes all databases in the backup. When you create a list, it applies to all aspects of the InterSystems IRIS backup system including calls to the entry points of the ^DBACK utility in scripted backups.

The following examples show sample output from each option on the menu:

  1. From the ^BACKUP menu, choose option 4 to display the database backup list maintenance menu:

    %SYS>Do ^BACKUP
     
     
    1) Backup
    2) Restore ALL
    3) Restore Selected or Renamed Directories
    4) Edit/Display List of Directories for Backups
    5) Abort Backup
    6) Display Backup volume information
    7) Monitor progress of backup or restore
     
    Option? 4
     
    1) Add a database to the backup
    2) Remove a database from the backup
    3) Show current list of databases included in backups
    4) Show list of available databases
    5) Display last full backup information
    
    
  2. To add a database to the list choose option 1. This example also uses option 3 to show that the database is added to the current list.

    1) Add a database to the backup
    2) Remove a database from the backup
    3) Show current list of databases included in backups
    4) Show list of available databases
    5) Display last full backup information
     
    Option? 1
    Enter database to add? DATA
    Enter database to add?
    You've selected DATA to be added to the backups
    Are you sure you want to do this (yes/no)? y
    Completed.
     
    1) Add a database to the backup
    2) Remove a database from the backup
    3) Show current list of databases included in backups
    4) Show list of available databases
    5) Display last full backup information
     
    Option? 3
    The following 3 databases are included in backups
         IRISAUDIT               C:\iris-install\Mgr\irisaudit\
         IRISSYS                 C:\iris-install\Mgr\
         USER                    C:\iris-install\Mgr\User\
    
    
  3. To remove a database to the list choose option 2. This example also uses option 3 to show that the database is removed from the current list.

    1) Add a database to the backup
    2) Remove a database from the backup
    3) Show current list of databases included in backups
    4) Show list of available databases
    5) Display last full backup information
     
    Option? 2
    Enter database to remove (^ when done)?  DATA
    Enter database to remove (^ when done)?
    You've removed DATA from the backups
    Are you sure you want to do this? y
    Completed.
     
    1) Add a database to the backup
    2) Remove a database from the backup
    3) Show current list of databases included in backups
    4) Show list of available databases
    5) Display last full backup information
    
    Option? 3
    The following 3 databases are included in backups
         IRISAUDIT          C:\iris-install\Mgr\irisaudit\
         IRISSYS            C:\iris-install\Mgr\
         USER               C:\iris-install\Mgr\User\
    
    
  4. To display a list of all databases in this instance choose option 4:

    1) Add a database to the backup
    2) Remove a database from the backup
    3) Show current list of databases included in backups
    4) Show list of available databases
    5) Display last full backup information
     
    Option? 4
    The following is a list of all databases in the configuration.
    Databases which are part of the backup are marked with (*)
         (*) IRISAUDIT           c:\iris-install\mgr\irisaudit\
             IRISLIB (Read Only) c:\iris-install\mgr\irislib\
             IRISLOCALDATA       c:\iris-install\mgr\irislocaldata\
         (*) IRISSYS             c:\iris-install\mgr\
         (*) USER                c:\iris-install\mgr\user\
     
    
    
  5. To display information about the last full backup choose option 5:

    1) Add a database to the backup
    2) Remove a database from the backup
    3) Show current list of databases included in backups
    4) Show list of available databases
    5) Display last full backup information
     
    Option? 5
     
    =====Last Full Backup Information=====
     
    Date: 19 Jan 2018
    Description: Full backup of all databases that are in the backup database list.
    Device: c:\iris-install\mgr\backup\FullDBList_20180119_001.cbk
    
    

Abort a Running Backup Using ^BACKUP

You can abort a running backup using menu option 5 of the ^BACKUP utility.

%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
5) Abort Backup
6) Display Backup volume information
7) Monitor progress of backup or restore
 
Option? 5
Are you sure you want to abort the backup operation ? <No> Yes
Backup abortion succeed.

If no backup is running when you choose this option, you receive the following message:

No Backup operation is currently running.

Display Information About a Backup Volume Using ^BACKUP

When you select option 6 from the ^BACKUP menu, you are prompted for the pathname of a backup file, as shown in the following:

Enter the backup volume you want to display information from
 (Type STOP to exit)
Device: c:\131u1\mgr\backup\FullAllDatabases_20180802_001.cbk =>
 
This backup volume was created by:
InterSystems IRIS for Windows (x86-64) 2018.1.1 (Build 257U) Sun Jul 1 2018 23:35:31 EDT
 
The volume label contains:
   Volume number       1
   Volume backup       AUG 2 2018 12:27PM Full
   Previous backup     AUG 2 2018 11:35AM Cumulative Incremental
   Last FULL backup    AUG 2 2018 11:24AM
   Description         Full backup of ALL databases
   Buffer Count        0
   Mirror name         MIRROR122
   Failover member     NONNIE20/TEST2A   
   Journal File        c:\131u1\mgr\journal\20180802.005
   Log file            c:\131u1\mgr\Backup\FullAllDatabases_20180802_001.log
   Backup Status       Completed
 
Database                                Size(mb)  Mirror DB Name 
--------                                --------  --------------
c:\131u1\mgr\                                191
c:\131u1\mgr\irisaudit\                      11
c:\131u1\mgr\user\                          2113  MUSER
Total of 3 databases, totaling 2315 mb
Backup volume size is 2365 mb

Monitor Backup or Restore Progress Using ^BACKUP

To monitor the progress of a running backup or restore job started using ^BACKUP, select option 7 from the ^BACKUP menu. You can start the monitor in a separate Terminal window before starting the backup or restore job.

For a running backup job, the following information is displayed:

                                 Backup Status
                                 -------------
 
Status:                       Running
Backup process pid:           13052
Backup file:                  c:\132u1\mgr\stcfull.bck
Description:
Log file:                     c:\132u1\mgr\irisbackup.log
Type:                         Full
Start time:                   2018-09-05 14:09:02
Estimated finish time:        2018-09-05 14:09:45
Total time (hh:mm:ss):        00:00:18
Time remaining (hh:mm:ss):    00:00:25
Estimated backup size:        7.68GB
Current backup size:          3.12GB
Current Backup rate:          184MB/sec
% Completed                   41

For a running restore job, the following information is displayed:

                                 Restor Status
                                 -------------
 
Status:                       Running
Restore process pid:          13052
Restore file:                 c:\132u1\mgr\stcfull.bck
Description:
Type:                         Full
Start time:                   2018-09-05 14:10:49
Estimated finish time:        2018-09-05 14:12:07
Total time (hh:mm:ss):        00:00:34
Time remaining (hh:mm:ss):    00:00:44
Restore file size:            7.68GB
Restore size completed:       3.28GB
Current restore rate:         103MB/sec
% Completed                   43
Note:

When doing an incremental backup, some of the fields are not available and are displayed as N/A. This includes Time remaining, Estimated backup size, and % Completed.

A restore job cannot be monitored if switch 10 was set when starting the restore.

Online Backup Restore Utility

The Online Backup Restore Utility (^DBREST) utility performs the following actions:

  • Requires you to choose whether to restore all or selected directories.

  • Asks if you want to stop all other InterSystems IRIS processes from running during the restore. In most cases, answer Yes.

  • Asks for the name of the file that holds the backup you wish to restore. If your backup is on more than one volume, that information is in the volume header. After restoring the first volume, the utility prompts you for the next.

  • Displays the header of the volume. The header contains the following information determined during the backup: the date of the backup on this volume, the date of the previous backup, and the date of the last full backup.

  • Asks you to verify that this is the backup you wish to restore.

  • Lists the directories on the device to restore.

  • Allows you to specify another input device that contains the next backup to restore.

  • Lets you display information about a backup volume at any time.

The ^DBREST menu options 1, 2 and 3 are the same as options 2, 3 and 6 from the ^BACKUP menu.

When you select one of these restore options, the utility asks you to enter the name of the device holding the first backup to restore. The default the first time you enter a restore option is the device to which the last full backup was sent, if there was one.

Caution:

When you are restoring an incremental or cumulative backup, the target database must be in exactly the same state as when you restored it from the last full backup.

You must prevent all updates to the restored databases until you restore all subsequent incremental backups. Failure to heed this warning can result in the incremental or cumulative restore producing a degraded database.

The following is an example of running the utility from the Terminal:

%SYS>Do ^DBREST
 
                              DBREST Utility
         Restore database directories from a backup archive
 
Restore: 1. All directories
         2. Selected and/or renamed directories
         3. Display backup volume information
         4. Exit the restore program
    1 => 

The following sections describe the process of choosing each option:

  1. Restore All Databases Using ^DBREST

  2. Restore Selected or Renamed Databases Using ^DBREST

  3. Display Information About a Backup Volume Using ^BACKUP

  4. Restoring Databases Using the Backup History

  5. Unattended Restore Using ^DBREST

  6. Mirrored Database Considerations

You can also perform these functions non-interactively in a script. See External Entry Points of ^DBREST for details.

Restore All Databases Using ^DBREST

Choosing 1 from the ^DBREST menu is equivalent to choosing 2 from the ^BACKUP menu.

Note:

If you are restoring mirrored databases, review Mirrored Database Considerations before you perform this procedure.

The following procedure is an outline of an example that restores all directories. It shows the beginning prompts of the restore process. As it continues, the utility asks you very specific questions while stepping through the restore process.

  1. Select to restore all directories from the utility menu. This option restores all directories that are on the backup medium.

    %SYS>Do ^DBREST
     
                                  DBREST Utility
             Restore database directories from a backup archive
     
    Restore: 1. All directories
             2. Selected and/or renamed directories
             3. Display backup volume information
             4. Exit the restore program
        1 => 1
    
    
  2. Confirm that you want to restore all directories:

    Proceed with restoring ALL directories Yes=>
    
  3. Next you are asked to enter the top path you want all the databases to be restored to. The system prefixed it to the original path of the database to be restored. So all the databases are restored under this directory with their original directory as a subdirectory to this directory. Press Enter to ignore it and restore the databases to their original path.

    Top directory for all Databases to be restored to (? for Help)?
    
  4. Indicate whether you want to suspend InterSystems IRIS processes while restoring takes place. InterSystems recommends suspending processes.

    Do you want to set switch 10 so that other processes will be
    prevented from running during the restore? Yes =>
    
  5. Specify the first file from which to restore. You can press Enter to accept the default file, which is the last full backup.

    Specify input file for volume 1 of backup 1
     (Type STOP to exit)
    Device: c:\iris-install\mgr\backup\FullAllDatabases_20180323_001.cbk =>
    
    
  6. Check that the description of the backup is correct and verify that this is the file you want to restore.

    This backup volume was created by:
       InterSystems IRIS for Windows 2018.1.1
     
    The volume label contains:
       Volume number      1
       Volume backup      MAR 23 2018 09:52AM Full
       Previous backup    MAR 22 2018 11:00AM Incremental
       Last FULL backup   MAR 16 2018 11:00AM
       Description        Full backup of ALL databases, whether or not they are in
                          the backup database list.
       Buffer Count       0
    Is this the backup you want to start restoring? Yes =>
    
    
  7. The utility tells you which directories it will restore, and the restore proceeds.

    The following directories will be restored:
    c:\iris-install\mgr\
    c:\iris-install\mgr\irisaudit\
    c:\iris-install\mgr\test\
    c:\iris-install\mgr\user\
    
     
    ***Restoring c:\iris-install\mgr\ at 10:46:01
    146045 blocks restored in 241.3 seconds for this pass, 146045 total restored.
    
    
  8. Specify the input file for the next incremental backup to restore, or enter stop if there are no more input files to restore.

    Specify input file for volume 1 of backup following MAR 23 2018  09:52AM
     (Type STOP to exit)
    Device: stop
    
    
  9. Indicate whether you want to restore other backups. When you answer Yes, the procedure repeats. When you respond No, the system mounts the databases you have restored.

    Do you have any more backups to restore? Yes => No
    Mounting c:\iris-install\mgr\
        c:\iris-install\mgr\       ... (Mounted)
     
    Mounting c:\iris-install\mgr\irisaudit\
        c:\iris-install\mgr\irisaudit\  ... (Mounted)
      
    Mounting c:\iris-install\mgr\test\
        c:\iris-install\mgr\test\  ... (Mounted)
     
    Mounting c:\iris-install\mgr\user\
        c:\iris-install\mgr\user\  ... (Mounted)
     
    
    
  10. Specify which journal entries you want to apply to the restored databases and the name of the journal file you are restoring. Normally, you select option 1 and apply only those changes that affect the directories you have just restored.

    Note:

    For information about what happens when you restore all entries for all directories or selected directories and globals, see Restore Globals From Journal Files Using ^JRNRESTO.

    Restoring a directory restores the globals in it only up to the
    date of the backup.  If you have been journaling, you can apply
    journal entries to restore any changes that have been made in the
    globals since the backup was made.
     
    What journal entries do you wish to apply?
     
         1. All entries for the directories that you restored
         2. All entries for all directories
         3. Selected directories and globals
         4. No entries
     
    Apply: 1 =>
    
    
  11. Restore from the journal files begins after confirming several pieces of information:

    We know something about where journaling was at the time of the backup:
    0: offset 172940 in c:\iris-install\mgr\journal\20180323.002
     
    Use current journal filter (ZJRNFILT)? No
    Use journal marker filter (MARKER^ZJRNFILT)? No
    Updates will not be replicated
     
    The earliest journal entry since the backup was made is at
    offset 172940 in c:\iris-install\mgr\journal\20180323.002
     
    Do you want to start from that location? Yes => Yes
    Final file to process (name in YYYYMMDD.NNN format): <20180323.003> [?]
          =>
     
    Prompt for name of the next file to process? No => No
     
    Provide or confirm the following configuration settings:
     
    Journal File Prefix: =>
     
    Files to dejournal will be looked for in:
         c:\iris-install\mgr\journal\
         c:\journal\altdir\
    in addition to any directories you are going to specify below, UNLESS
    you enter a minus sign ('-' without quotes) at the prompt below,
    in which case ONLY directories given subsequently will be searched
     
    Directory to search: <return when done>
    Here is a list of directories in the order they will be searched for files:
         c:\iris-install\mgr\journal\
         c:\journal\altdir\
    The journal restore includes the current journal file.
    You cannot do that unless you stop journaling or switch
         journaling to another file.
    Do you want to switch journaling? Yes => Yes
    Journaling switched to c:\iris-install\mgr\journal\20180323.004
     
    You may disable journaling the updates for faster restore.
    Do you want to disable journaling the updates? Yes => yes
    Updates will NOT be journaled
    
    
  12. The utility displays its progress and indicates when it is complete:

     
     
    c:\iris-install\mgr\journal\20180323.002
      61.32%  65.03%  68.44%  72.21%  75.86%  79.26%  82.73%  86.08%  89.56%  
      92.99%  96.07%  98.87%100.00%
    ***Journal file finished at 11:03:31
     
     
    c:\iris-install\mgr\journal\20180323.003
      16.17%  17.10%  17.90%  18.90%  20.05%  21.33%  22.58%  23.81%  25.15%  
      26.32%  27.65%  28.85%  30.08%  31.37%  32.59%  33.98%  35.16%  36.25%  
      37.32%  38.41%  39.55%  40.72%  41.81%  42.83%  43.85%  44.89%  46.00%  
      47.15%  48.24%  49.28%  50.32%  51.41%  52.54%  53.71%  54.76%  55.80%  
      56.85%  57.97%  59.10%  60.16%  61.17%  62.19%  63.24%  64.32%  65.18%  
      66.02%  66.87%  67.71%  68.52%  69.34%  70.14%  70.96%  71.76%  72.60%  
      73.58%  74.51%  75.43%  76.35%  77.26%  78.17%  79.07%  79.69%  80.31%  
      80.93%  81.56%  82.20%  82.83%  83.47%  84.27%  87.00%  88.57%  91.65%  
      93.03%  96.09%  97.44%  99.04%100.00%
    ***Journal file finished at 11:03:32
     
    Journal reads completed. Applying changes to databases...
      14.29%  28.57%  42.86%  57.14%  71.43%  85.71% 100.00%
     
    [journal operation completed]
    
    

Restore Selected or Renamed Databases Using ^DBREST

Choosing 2 from the ^DBREST menu is equivalent to choosing 3 from the ^BACKUP menu. This option lets you select which directories to restore from the backup medium. It also allows you to restore a database to a different directory name or to a different device.

Note:

If you are restoring mirrored databases, review Mirrored Database Considerations before you perform this procedure.

The following example shows how to restore selected or renamed directories.

  1. Choose option 2 from the ^DBREST utility:

    %SYS>Do ^DBREST
     
                                  DBREST Utility
             Restore database directories from a backup archive
     
    Restore: 1. All directories
             2. Selected and/or renamed directories
             3. Display backup volume information
             4. Exit the restore program
        1 => 2
    
    
  2. Indicate whether you want to suspend InterSystems IRIS processes while restoring takes place. InterSystems recommends suspending processes.

    Do you want to set switch 10 so that other InterSystems IRIS processes
    will be prevented from running during the restore? Yes =>
    
  3. Specify the first file from which to restore. You can press <Enter> to accept the default file, which is the last full backup.

    Specify input file for volume 1 of backup 1
     (Type STOP to exit)
    Device: c:\iris-install\mgr\backup\IncrementalDBList_20180323_001.cbk =>
    
    
  4. Check that the description of the backup is correct and verify that this is the file you want to restore.

    This backup volume was created by:
       InterSystems IRIS for Windows (Intel) 5.1
     
    The volume label contains:
       Volume number      1
       Volume backup      MAR 23 2018 11:03AM Full
       Previous backup    MAR 23 2018 09:52AM Full
       Last FULL backup   MAR 23 2018 09:52AM
       Description        Incremental backup of all databases that are in the backup
                          database list.
       Buffer Count       0
    Is this the backup you want to start restoring? Yes =>
    
    
  5. As the utility prompts you with directory names, specify which databases you want to restore, and in which directories you want to restore them:

    For each database included in the backup file, you can:
     
     -- press RETURN to restore it to its original directory;
     -- type X, then press RETURN to skip it and not restore it at all.
     -- type a different directory name.  It will be restored to the directory
        you specify.  (If you specify a directory that already contains a
        database, the data it contains will be lost).
     
    c:\iris-install\mgr\ =>
    c:\iris-install\mgr\irisaudit\ =>
    c:\iris-install\mgr\test\ =>
    c:\iris-install\mgr\user\ =>
    
    
    
  6. After responding to each directory prompt, you see the prompt:

    Do you want to change this list of directories? No =>
    
    

    Answer Yes if you want to edit your choices, or press Enter to confirm them.

  7. The process then continues the same as the procedure for restoring all directories, as specified in the previous section.

You can use this procedure to restore a backup performed on different system from the one on which you are restoring it.

Restoring Databases Using the Backup History

The InterSystems IRIS backup utility maintains a backup history to help you restore backups in logical order. The restore utility prompts you for the backups to restore according to their type and order in the backup history.

After restoring the last full backup, the utility uses the information in the backup history to suggest the next logical backup for you to restore and continues through the history. It prompts you to restore subsequent backups in the following order:

  1. The most recent cumulative backup after the last full backup, if one exists.

  2. All incremental backups since the last cumulative backup (or if none exists, since the last full backup). It does so in order from the first to the most recent.

You can override the suggested backups in the restore process. Remember, however, that an incremental or cumulative backup does not represent a complete copy of the databases. You can restore an incremental backup only after restoring a full backup.

Important:

On InterSystems IRIS platforms that support access to a database from cluster, you should always back up a given database directory from the same node so that its complete backup history is available if you need to restore the directory.

Unattended Restore Using ^DBREST

The InterSystems IRIS restore utility, ^DBREST, provides a non-interactive execution option using external entry points.

Note:

If you are restoring mirrored databases, review Mirrored Database Considerations before you perform an unattended restore.

You can write a script to implement unattended restores by calling one of these two entry points:

  • EXTALL^DBREST — Restores all databases from the backup device (the unattended equivalent to the procedure described in Restore All Databases Using ^DBREST). The syntax to use the EXTALL entry point of the ^DBREST utility is as follows:

    EXTALL^DBREST(quietmode,allowupd,inpdev,dirlist,jrnopt,jrnfile,jdirglo)
    
    Note:

    If the target directory exists but the IRIS.DAT file does not, EXTALL^DBREST restores the IRIS.DAT file.

  • EXTSELCT^DBREST — Restores selected files from the backup device, or restores to a target directory that is different from the source directory (the unattended equivalent to the procedures described in Restore Selected or Renamed Databases Using ^DBREST). The syntax to use the EXTSELCT entry point of the ^DBREST utility is as follows:

    EXTSELCT^DBREST(quietmode,allowupd,inpdev,dirlist,jrnopt,jrnfile,jdirglo)
    

Both entry points are functions, which return the status of the call. All arguments are input only. The following table describes the input arguments used for both functions except where indicated.

Argument Description
allowupd Indicates whether or not to allow updates during the restore process:

1 — allow updates during the restore process

0 — do not allow updates

dirlist Name of file containing a list of directories to restore. One record for each directory to be restored has to be present. Ignored for the EXTALL entry point. See Directory List File Requirements.

When ^DBREST completes, it deletes the file specified by dirlist.

inpdev Input device that contains the backup.
jdirglo Only used when jrnopt is 3. This is the name of the file containing selection criteria for directories and globals for the journal restore. See Directory and Global Selection Criteria.
jrnfile Journal file. If null, the utility uses the current file, which is stored in the ^%SYS("JOURNAL“,”CURRENT") global.
jrnopt Options to restore the journal:

1 — All directories for which you just restored the backup

2 — All directories in the journal

3 — Selected directories and globals specified by the jdirglo argument

4 — No directories

quietmode A value indicates the operation is in quiet (non-interactive) mode; must be a non-null value for this external call, typically 1.

The following return codes are possible from calling these functions:

Return Code Description
3 No errors; successful completion
-1 Cannot open input device (device to restore from)
-2 Volume label does not match label in backup history
-3 Backup/Restore already in progress
-4 Invalid device for reading selection criteria (for selective restore of directories)
-5 Invalid journal restore option
-6 Invalid journal file or file for selection criteria for journal restore cannot be opened

Directory List File Requirements

Requirements of the file indicated by dirlist:

  • Contains one record for each directory to restore

  • Separate each field with a comma (,).

  • Format of each record is SourceDir,TargetDir,CreateDir; where:

    Argument Description
    SourceDir Name of the directory to restore.
    TargetDir Name of the directory to which to restore; omit if restoring to same as source directory.
    CreateDir Whether or not to create the target directory if it does not exist.

    Y — create the target directory

    N — do not create target directory

For example, assuming you have created a text file (RestoreList.txt) in the C:\Backup\ directory that contains the string:

C:\intersystems\iris\mgr\user\,C:\intersystems\iris\mgr\,Y

you could execute the following routine in the %SYS namespace to restore the database from C:\intersystems\iris\mgr\user\ to C:\intersystems\iris\mgr\:

set SourceDir = "C:\intersystems\iris\mgr\user\"
set BackupDir = "C:\Backup\"
set BackupListFile="C:\Backup\RestoreList.txt"
do EXTSELCT^DBREST(1,0,BackupDir_"back1.cbk",BackupListFile,4,"","")

Directory and Global Selection Criteria

Requirements of the file indicated by jdirglo:

  • Contains one record for each directory that you want to restore.

  • Separate each field with a comma (,).

  • Format of each record is DirName, RestAll, Globals; where:

Argument Description
DirName Name of the directory on which you want to restore the journal.
Globals A list of globals separated by commas for journal restore. Only used if RestAll is N. If the list of globals is large, you can enter the remaining global names on the next line but you must specify the directory name again followed by N and then the list of globals.
RestAll Whether or not to restore journal entries for all globals in the directory; not case-sensitive and required.

Y — restore journal on all globals in this directory

N — specify globals for journal restore in globals list

Examples of different records:

DUA0:[TEST1],Y
DUA1:[TEST2],N,GLO1,GLO2,GLO3
DUA1:[TEST2],N,GLO4,GLO5,GLO6
DUA1:[TEST3],n 

The last record could also be completely omitted if you do not want to restore the journal for that directory.

Mirrored Database Considerations

When a mirrored database is the target of an InterSystems IRIS backup restore, the source database must match the target (that is, it must be the same mirrored database).

Note:

Mirrored database backups created on a failover mirror member can be restored to any member of that mirror (that is, another failover member or an async member). If you are restoring from a backup created on an async mirror member, see Restoring from Async Mirror Members.

In this section, the term “active mirrored database” refers to a database that is currently included in a mirror to which its host system belongs, even if that mirror is not currently in operation. It does not include databases that were once mirrored, or that were included in a mirror to which the host system no longer belongs.

InterSystems IRIS backup restore in a mirror behaves differently depending on whether it is being restored on the mirror member where the backup was created or on a different system:

  • Primary Failover Member — ^DBREST does not let you restore an active mirrored database on the primary failover member. However, if the database must be restored, you can temporarily remove it from the mirror (see Removing Mirrored Databases from Mirrors). The database is restored as a mirrored database, however (since it was backed up as one), and the functionality described in the following sections applies, including automatic restore of the journal files required to activate the database in the mirror.

  • Backup Failover Member — On the backup failover member, restoring a mirrored database that is active, or newer than the copy in the backup, results in a warning message:

    • For a full backup restore, these databases are skipped.

    • For a selective restore, you are given a chance to overwrite the target if that is what you really want to do.

Full Backup Restores of Mirrored Databases

The following differences apply to full backup restores of mirrored databases, whether they are done interactively via the ^DBREST utility (see Online Backup Restore Utility) or non-interactively via the EXTALL entry point (see External Entry Points of ^DBREST):

  • A full backup restore on the system that created the backup works as it does for nonmirrored systems, except that local mirrored databases that are newer than the copies in the backup — which, by definition, includes databases that are currently active — are skipped; all databases are restored to their original locations.

  • A full backup restore on a mirror member other than the system that created the backup restores only mirrored databases that already exist on the system. However, mirrored databases on the target system that are newer than those in the backup are skipped.

  • A full backup restore that specifies a new top-level directory restores all the databases in the backup after generating the new path for the databases. If the user ends up with two copies of any of the mirrored databases after the restore, they are warned that the copy being restored cannot be activated because it is already active on the system.

Following a full backup restore the system attempts to:

  1. Activate the mirrored databases by restoring the required journal files.

  2. Link the mirrored databases into the active mirror (if the mirror exists and a copy of the database does not already exist).

Selective Backup Restores of Mirrored Databases

The following differences apply to selective backup restores of mirrored databases:

  • When a backup is being restored, you are asked whether to limit the restore to only mirrored databases; depending on your response:

    • yes — Only the mirrored databases are displayed.

    • no — You are prompted to select destinations for all the databases in the backup.

  • During the database selection phase of a selective restore, you are presented with a list of the databases in the backup and asked to specify a path where each should be restored. You can specify a path, enter an “X” or “x” to skip that directory, or press Enter to restore it to the path stored in the backup, if you are restoring on the source system.

    When restoring a backup on a mirror member other than the system that created the backup, the result of pressing Enter for a mirrored database directory varies depending on whether an active mirrored database with the same mirror database name exists on that system.

    • If the database exists, pressing Enter overwrites the existing database with the restored database, regardless of the existing database’s directory path, including whether that path is the same as on the source system.

    • If the database does not exist, the database is restored to the directory path it has on the source machine. If that path does not exist, you must confirm the creation of the needed directories. If a database already exists at that location, no action is taken.

  • If a selective backup restore detects that the restore is going to overwrite a mirrored databases in the following situations, you are warned that continuing will destroy the target database and asked if you want to continue:

    • The database from the backup is older than the current database.

    • The database from the backup is not a copy of the current database (for example, it could be a nonmirrored database or a database of the same mirror database name from a different mirror).

    If you continue, the target database is removed from the mirror and overwritten as requested.

  • If a selective backup restore is being done non-interactively via the EXTSELCT entry point (see External Entry Points of ^DBREST), the database selection file the source and target paths can be specified with either path names or mirror databases names.

    For a mirrored database, if the target is left blank it means restore to the corresponding mirror database on the local machine. If the target is not blank, then the database must be one of the following:

    • The correct, local copy of that mirrored database.

    • If a local copy of that mirrored database does not already exist on the system, a nonmirrored database (or a directory/database that does not exist) .

    • A mirror database name.

    Note:

    If the target is a mirror database name (or blank) and that mirrored database does not exist on the local system (or is dismounted), the target is created only if the backup is being restored on the system that created it. If the backup is being restored on another mirror member the database is skipped.

As with full backup restores, following a selective backup restore, the system attempts to:

  1. Activate the mirrored databases by restoring the required journal files.

  2. Link the mirrored databases into the active mirror (if the mirror exists).

Restoring from Async Mirror Members

The following considerations apply when restoring from mirrored databases created on async mirror members:

  • Mirrored databases backups created on a async mirror member can be restored to any async member of the same mirror.

  • Mirrored databases backups created on a async mirror member can only be used to create new copies of the mirrored database (that is, they cannot be restored over an existing mirrored database on a failover member).

FeedbackOpens in a new tab