onbar -r syntax: Restoring data

To run a complete restore, use onbar -r command.

To run ON-Bar commands, you must be user root, user informix, a member of the bargroup group on UNIX™, or a member of the HCL OneDB™-Admin group on Windows™.

Run a full or physical restore
>>-onbar-- -r--+-----+--+-----------+--+-----+------------------>
               '- -p-'  +- -e-------+  '- -w-'   
                        +- -encrypt-+            
                        '- -decrypt-'            

>—+-------------+-----+----------------------+------------------>
   +- -t--"time"-+    '- -pw-+------------+--'
   '- -n--log----'           '--filename--'

>--+----------------------------------------------------------------------------------+-->
   +- -O------------------------------------------------------------------------------+   
   '-+- -rename-- -f--filename------------------------------------------------------+-'   
     | .--------------------------------------------------------------------------. |     
     | V                                                                          | |     
     '--- -rename-- -p--old_path-- -o--old_offset-- -n--new_path-- -o--new_offset-+-'     

>--+---------------+--+----------------+-----------------------><
   +- -f--filename-+  '- -cf--+-yes--+-'   
   | .-------.     |          +-no---+     
   | V       |     |          '-only-'     
   '---space-+-----'
Figure 1: Run a logical restore

1  onbar  -r   -l
2.1  -C
2.1  -X
2.1   -t "time"
2.1  -n log
Figure 2: Run a tenant restore

1  onbar  -r   -T tenant_database
2.1   -encrypt
2.1   -decrypt
1   -t
1 "time"
1? -O
Table 1. Options for the onbar -r command.
Option Description
-r Specifies a restore. If the database server is offline, ON-Bar performs a cold restore. If the database server is in online, quiescent, or fast recovery mode, ON-Bar performs a warm restore.

In a cold restore, the -r option restores all storage spaces and salvages and restores the logical logs. In a warm restore, the -r option restores all storage spaces that are offline and restores the logical logs.

You must specify the -r option first.
space Specifies which storage spaces to back up as a list of one or more dbspace, blobspace, or sbspace names, separated by blank spaces.

ON-Bar restores only the storage spaces listed. If the database server is offline, you must list all the critical dbspaces. You cannot specify temporary spaces.
-C Continuously restores logical logs from the current logical log tape without sending prompts to mount the tape.

The server is placed in suspend log restore state, and the command exits after the last applicable log is restored. The server sends a prompt if a log spans tapes. The configuration parameter RESTARTABLE_RESTORE does not affect continuous log restoration.
-cf Specifies whether the critical files are restored during a cold restore.

The critical files are the onconfig file, the sqlhosts file (on UNIX), the oncfg_servername.servernum file, and the ixbar.servernum file.

Valid values are:

  • yes = Restores the critical files.
  • no = Default. Does not restore the critical files.
  • only = Restores only the critical files.
-decrypt Specifies to decrypt any encrypted storage spaces during the physical restore of the spaces.
-encrypt Specifies to encrypt storage spaces during the physical restore of the spaces. Storage space encryption must be enabled by the DISK_ENCRYPTION configuration parameter. Otherwise, the restore fails.

For more information about storage space encryption, see Changing storage space encryption during a restore.
-e Specifies an external restore. Run the onbar -r -e command after you externally restore the storage spaces. Marks storage spaces as physically restored, restores the logical logs, and brings the storage spaces online.
-f filename Specifies the path and file name of a text file that lists the storage spaces to restore or rename.

Use this option to avoid entering a long list of storage spaces.

For more information, see List of storage spaces in a file.
-l Specifies a logical restore only. Restores and rolls forward the logical logs. The logical restore applies only to those storage spaces that are already physically restored.
Important: To improve performance, replay logical-log transactions in parallel during a warm restore. Use the ON_RECVRY_THREADS configuration parameter to set the number of parallel threads. To replay logical-log transactions in parallel during a cold restore, use the OFF_RECVRY_THREADS configuration parameter. For more information, see your HCL OneDB Performance Guide.
-n log Indicates the unique ID of the last logical log to be restored in a cold restore. The database server must be offline.

To find the unique ID, use the onstat -l command.

A point-in-log restore is a special point-in-time restore. You must restore all storage spaces in a point-in-log restore so that the data is consistent. If any logical logs exist after the specified log, ON-Bar does not restore them and their data is lost. If the specific logical log applies to more than one timeline, ON-Bar uses the latest one.

Cannot be combined with the -t option.
-n new_path Specifies the new path of the chunk. Use with the -rename option.
-O Overrides internal error checks. Allows the restore of online storage spaces. Forces the recreation of chunk files that no longer exist.

Used to override internal error checks to perform the following tasks:

  • Force the restore of online storage spaces. If a storage space in the list of storage spaces to restore is online, ON-Bar takes the storage space offline and then restores it. If this operation succeeds, ON-Bar completes with an exit code of 177.
  • Force the creation of nonexistent chunk files. If a chunk file for a storage space being restored no longer exists, ON-Bar recreates it. The newly created chunk file is cooked disk space, not raw disk space. If ON-Bar successfully recreates the missing chunk file, ON-Bar completes with an exit code of 179.
  • Force a cold restore to proceed if a critical storage space is missing. In a cold restore, ON-Bar checks whether every critical space is being restored. This check occasionally causes false warnings. If the warning was valid, the restore fails. If the warning was false and ON-Bar successfully restores the server, ON-Bar completes with an exit code of 115.

Use the -O option with a whole-system restore only to recreate missing chunk files. You cannot use the onbar -r -w -O command when the database server is online because the root dbspace cannot be taken offline during the whole-system restore. Cannot be combined with the -rename option.
-pw [file name]

The -pw option is required only when the storage space encryption feature is enabled and no stash file is in use. Supply an optional path to a file containing the keystore password, otherwise onbar will prompt for a password before performing the restore.
-o new_offset Specifies the offset of the renamed chunk. Use with the -rename option.
-o old_offset Specifies the offset of the chunk to be renamed. Use with the -rename option.
-p Specifies a physical restore only.

You must follow a physical restore with a logical restore before data is accessible unless you use a whole-system restore. This option turns off automatic log salvage before a cold restore. If the LTAPEDEV configuration parameter is set to /dev/null or NUL, you must use the -p option during a restore.
-p old_path Specifies the path of the chunk to be renamed. Use with the -rename option.
-rename Renames one or more chunks during a cold restore. The database server must be offline.

This option is useful if you need to restore storage spaces to a different disk from the one on which the backup was made. You can rename any type of chunk, including critical chunks and mirror chunks. You can rename chunks that have level-0 backups.

Cannot be combined with the -O option.
-T tenant_database Restores a tenant database. The database server must be online. No other warm restores or tenant restores can be in progress.

If you include the -t option, the data is restored to the specified point in time. If you do not include the -t option, the data is restored to the current time.

Include the -O option unless all of the permanent tenant storage spaces are marked as down. Temporary storage spaces are never backed up or restored.

For more information, see Restoring a tenant database to a point in time.
-t "time" Specifies the time of the last transaction to be restored from the logical logs in a cold restore. The database server must be offline.Specifies the time of the last transaction to be restored from the logical logs in a cold restore or a tenant database point-in-time restore. For a cold restore, the database server must be offline. For a tenant database point-in-time restore, the database server must be online.

All storage spaces specified are restored to the same point in time. However, for a cold restore, if you perform a physical restore followed by a logical restore, the logical restore can be to a later point in time. For example you might detect that your current backup is corrupted, and that you need to restore the previous backup. In this case, start your physical restore with the timestamp of your previous backup, and subsequently start the logical recovery to a more recent timestamp.

A point-in-time restore is typically used to recover from a mistake. For example, if you accidentally dropped a database, you can restore the server to a point in time just before you dropped the database.

To determine the appropriate date and time for the point-in-time restore, use the onlog utility. The onlog utility output shows the date and time of the committed transactions in the logical log. All data transactions that occurred after the time you specify in the restore command are lost.

Use quotation marks around the date and time. The format for the English locale is yyyy-mm-dd hh:mm:ss. If the GL_DATETIME environment variable is set, you must specify the date and time according to that variable.

Cannot be combined with the -n log option.
-w Performs a whole-system restore of all storage spaces and logical logs from the last whole-system backup. The database server must be offline.

After the whole-system restore is complete, the server is in quiescent mode.

If you specify onbar -r -w without a whole-system backup, return code 147 is returned because ON-Bar cannot find any storage spaces backed up as part of a whole-system backup.
-X Stops continuous logical log restore. Leaves the server in quiescent mode in a logical restore suspend state without restoring additional logs.

Usage

You can restore storage spaces stored in both raw and cooked files. If your system contains primary and mirror storage spaces, ON-Bar writes to both chunks simultaneously during the restore, except for an external restore. You cannot specify to restore temporary spaces. When you restore the critical dbspaces (for example, the root dbspace), the database server recreates the temporary dbspaces, but they are empty.

ON-Bar restores the storage spaces in parallel if the BAR_MAX_BACKUP or BAR_MAX_RESTORE configuration parameter is set to a value greater than 1. To speed up restores, you can add additional CPU virtual processors.

You can restore noncritical storage spaces in a warm restore, when the database server is online, in the following circumstances:
  • The storage space is online, but one of its chunks is offline, recovering, or inconsistent.
  • The storage space is offline or down.

You cannot perform more than one warm restore simultaneously. If you need to restore multiple storage spaces, specify the set of storage spaces to restore to ON-Bar or allow ON-Bar to restore all down storage spaces by not explicitly specifying any spaces.

Tip: For faster performance in a restore, assign separate storage devices for backing up storage spaces and logical logs. If physical and logical backups are mixed together on the storage media, it takes longer to scan the media during a restore.

In certain situations, you might want to perform a restore in stages. If multiple devices are available for the restore, you can restore multiple storage spaces separately or concurrently, and then perform a single logical restore.

By default, ON-Bar restores the latest backup. If you do not want to restore the latest backup, you can restore from an older backup: for example, when backup verification failed or the backup media was lost. You can perform a point-in-time restore or a point-in-log restore. Alternatively, you can expire a bad backup in the storage manager, run the onsmsync command, and then restore from the older backup. If you accidentally drop a storage space, you can use a point-in-time restore or a point-in-log restore to recover it.

You can force a restore of online storage spaces (except critical dbspaces) by using the -O option. The database server automatically shuts down each storage space before it starts to restore it. Taking the storage space offline ensures that users do not try to update its tables during the restore process.

You can restore critical files during a cold restore by including the -cf yes option.

You can rename chunks by specifying new chunks paths and offsets during a cold restore with ON-Bar. This option is useful if you need to restore storage spaces to a different disk from the one on which the backup was made. You can rename any type of chunk, including critical chunks and mirror chunks.

When storage space encryption is enabled, by default storage spaces retain the same encryption state after a restore as during the back up. You can specify to encrypt or decrypt a storage space during a restore with the -encrypt or -decrypt options.

Example: Perform a whole-system restore

A whole-system restore is a cold restore and must be performed while the server is offline. The following command restores a whole-system backup:

onbar -r -w

Example: Restore specific storage spaces

The following example restores two specific storage spaces, fin_dbspace1 and fin_dbspace2: 
onbar -r fin_dbspace1 fin_dbspace2

Example: Perform a warm restore in stages

The following commands perform a physical restore, back up logical logs, and perform a logical restore:

onbar -r -p
onbar -b -l
onbar -r -l

Example: Point-in-time restore

The following command restores database server data to its state at a specific date and time:
onbar -r -t "2011-05-10 11:35:57"

In this example, the restore replays transactions that committed on or before the specified time, including any transactions with a commit time of 11:35:57. Transactions in progress but not committed by 11:35:57 are rolled back.

Example: Point-in-time restore in stages

The following commands perform a physical restore and a logical restore to the same point in time: 
onbar -r -p -t "2011-05-10 11:35:57"
onbar -r -l -t "2011-05-10 11:35:57"

Example: Restore a dropped storage space and chunks

Suppose that a transaction dropped a storage space named dbspace1 and deleted chunks at the time 2011-05-10 12:00:00. The following command restores the storage space and recreates the deleted chunks while the server is offline:

onbar -r -t "2011-05-10 11:59:59" -O

Example: Restore critical files

The following command restores data and the critical files during a cold restore:

onbar -r -cf yes