Online Backup Restore Utility

Restore All Databases Using ^DBREST

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

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.

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.

Unattended Restore Using ^DBREST

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

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.

The following return codes are possible from calling these functions:

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

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.