Product Documentation

Appearance

All platforms

ybrestore Examples ​

This section contains some simple examples of restore commands, using different options.

Restore an existing database under a new name ​

This example restores a database to the same system under a different name. Here is a breakdown of the ybrestore command options used in this example:

Command SyntaxExplanation
ybrestoreCall the ybrestore tool on the client.
-WPrompt for the user's password.
--username yb100Run as user yb100 (must be a superuser).
-d premdb_restoredRestore the database under the name premdb_restored. (You cannot use the name of the source database in the command unless it has been dropped from the target system or does not exist on the target system.)
--point October15Inc3Identify the restore point, which may be a valid backup name for the database you want to restore: October15Inc3 in this case. (You can also specify latest, oldest, or a timestamp; see ybrestore Options.
--chain October2019Name the backup chain October2019.
/home/brumsby/premdb_daily_backupsIdentify the location of the backup files, as specified when the ybbackup command was run. If the backup used multiple directories, make sure you name the first backup directory in the ybrestore command. This directory contains the metadata files (metaDB.*) for the backup. (You do not need to list the other directories.)An S3 storage path would look like this:


s3://ybbobr/premdb_bar


An Azure Blob storage path would look like this:


azure://premdb_bar


Tip: You can run the ybbackupctl --list command to verify backup information before running a restore command. See ybbackupctl Examples.

Here is the command line and the full output of the restore operation, which uses a sequence of four backups:

$ ybrestore -W --username yb100 -d premdb_restored --point October15Inc3 --chain October2019 /home/brumsby/premdb_daily_backups
Password for user yb100: 
17:44:56.066 [ INFO] ABOUT CLIENT:
   app.cli_args         = "-W" "--username" "yb100" "-d" "premdb_restored" "--point" "October15Inc3" "--chain" "October2019" "/home/brumsby/premdb_daily_backups"
   app.name_and_version = "Yellowbrick Backup and Restore version 4.0.0-1385"
   java.home            = "/usr/lib/jvm/java-8-oracle/jre"
   java.version         = "1.8.0_101"
   jvm.memory           = "512.00 MB (max=4.00 GB)"
   jvm.name_and_version = "Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)"
   jvm.options          = "-Xms512m, -Xmx4g, -XX:+UseG1GC, -Dapp.name=ybrestore2, -Dapp.pid=4240, -Dapp.repo=/opt/ybtools/lib, -Dapp.home=/opt/ybtools, -Dbasedir=/opt/ybtools"
   jvm.vendor           = "Oracle Corporation"
   os.name_and_version  = "Linux 4.4.0-31-generic (amd64)"

17:44:56.067 [ INFO] Running restore using input locations: [file:/home/brumsby/premdb_daily_backups/]
17:44:57.407 [ INFO] RestoreSession: Found candidate for restore : October15Inc3
17:44:57.585 [ INFO] Calculated restore sequence: 
17:44:57.585 [ INFO] 	1) October15Full
17:44:57.586 [ INFO] 	2) October15Inc1
17:44:57.586 [ INFO] 	3) October15Inc2
17:44:57.586 [ INFO] 	4) October15Inc3
17:44:57.947 [ INFO] Starting restore of 'October15Full' [15468]
ybrestore_meta | 100.0% |        Read: 21.00 KiB / 21.00 KiB        |      Write: 21509       |  0.00 B/s   |   2019-10-15 17:44:58  

ybrestore_data | 100.0% |       Read: 284.73 KiB / 284.73 KiB       |    Write: 284.59 KiB    | 28.10 KB/s  |   2019-10-15 17:45:14  
17:45:14.012 [ INFO] Validating restored objects
17:45:14.012 [ INFO] Committing
17:45:14.025 [ INFO] Completed restore of 'October15Full'

17:45:14.089 [ INFO] Starting restore of 'October15Inc1' [15767]
ybrestore_meta | 100.0% |         Read: 6.56 KiB / 6.56 KiB         |       Write: 6713       |  9.53 KB/s  |   2019-10-15 17:45:14  

ybrestore_data | 100.0% |         Read: 7.98 MiB / 7.98 MiB         |     Write: 7.97 MiB     |  1.58 MB/s  |   2019-10-15 17:45:17  
17:45:17.991 [ INFO] Validating restored objects
17:45:17.991 [ INFO] Committing
17:45:18.001 [ INFO] Completed restore of 'October15Inc1'

17:45:18.064 [ INFO] Starting restore of 'October15Inc2' [15828]
ybrestore_meta | 100.0% |         Read: 1.95 KiB / 1.95 KiB         |       Write: 2000       |  5.28 KB/s  |   2019-10-15 17:45:18  

ybrestore_data | 100.0% |       Read: 225.88 MiB / 225.88 MiB       |    Write: 225.82 MiB    | 32.21 MB/s  |   2019-10-15 17:45:24  
17:45:24.575 [ INFO] Validating restored objects
17:45:24.575 [ INFO] Committing
17:45:24.602 [ INFO] Completed restore of 'October15Inc2'

17:45:24.664 [ INFO] Starting restore of 'October15Inc3' [15888]
ybrestore_meta | 100.0% |         Read: 1.94 KiB / 1.94 KiB         |       Write: 1991       |  5.40 KB/s  |   2019-10-15 17:45:25  

ybrestore_data | 100.0% |        Read: 34.64 MiB / 34.64 MiB        |    Write: 34.64 MiB     |  8.64 MB/s  |   2019-10-15 17:45:27  
17:45:27.665 [ INFO] Validating restored objects
17:45:27.665 [ INFO] Committing
17:45:27.678 [ INFO] Completed restore of 'October15Inc3'

17:45:27.690 [ INFO] Done

Restore a database with users, roles, grants, and ACLs ​

The following command restores a database with --security-mode all. Therefore, security-related objects and privileges are preserved.

$ ybrestore -W --username yb100 -d premdb_restored --point Dec18Full --chain December2019 
--security-mode all /home/brumsby/premdb_daily_backups
Password for user yb100: 
...

For details, see Restoring Users and Roles.

Attempt an incremental restore that is not needed ​

This example attempts an incremental restore, but the system detects that the target database is already in sync with the changes in the specified backup point.

$ ybrestore -W --username yb100 -d premdb_restored --all-security --point October15Inc3 --chain October2019 /home/brumsby/premdb_daily_backups
Password for user yb100: 
16:49:11.963 [ INFO] ABOUT CLIENT:
...
16:49:11.965 [ INFO] Running restore using input locations: [file:/home/brumsby/premdb_daily_backups/]
16:49:13.338 [ INFO] RestoreSession: Found candidate for restore : October15Inc3
16:49:13.498 [ INFO] RestoreSession - Last Backup Snapshot = October15Inc3
16:49:13.498 [ INFO] RestoreSession: Nothing to restore as desired snapshot 'October15Inc3' is already applied to YBD
16:49:13.498 [ INFO] System is up to date

Restore a database and disable HOT_STANDBY mode ​

Note the use of the --hot-standby off option in this example. When the restore completes, the database is not kept in HOT_STANDBY mode. Therefore, it cannot be used for incremental restores.

$ ybrestore -W --username yb100 -d premdb_restored --point Oct23Full --chain October2019 
/home/brumsby/premdb_daily_backups --hot-standby off
Password for user yb100: 
...
17:32:27.836 [ INFO] Running restore using input locations: [file:///home/brumsby/premdb_daily_backups/]
17:32:29.637 [ INFO] RestoreSession: Found candidate for restore : Oct23Full
17:32:29.786 [ INFO] Calculated restore sequence: 
17:32:29.787 [ INFO] 	1) Oct23Full
17:32:30.123 [ INFO] Starting restore of 'Oct23Full' [10880]
...
17:33:05.370 [ INFO] Completed restore of 'Oct23Full'

17:33:05.371 [ INFO] Disabling hot standby mode
17:33:05.374 [ INFO] Disabled hot standby mode
17:33:05.391 [ INFO] Done

Attempt an incremental restore to a database that is not in hot_standby mode ​

This example attempts to run an incremental restore on a database that has been taken out of HOT_STANDBY mode. Therefore, the restore fails.

$ ybrestore -W --username yb100 -d premdb_restored --point October16Inc4 --chain October2019 /home/brumsby/premdb_daily_backups
Password for user yb100: 
18:45:18.752 [ INFO] ABOUT CLIENT:
...
18:45:18.754 [ INFO] Running restore using input locations: [file:/home/brumsby/premdb_daily_backups/]
18:45:20.198 [ INFO] RestoreSession: Found candidate for restore : October16Inc4
18:45:20.347 [ INFO] RestoreSession - Last Backup Snapshot = October16Inc3
18:45:20.347 [ INFO] Calculated restore sequence: 
18:45:20.347 [ INFO] 	1) October16Inc4
18:45:20.444 [ERROR] Failed: Error starting restore session  CAUSED BY: Target database premdb_restored isn't a hot standby

Restore a single table to its original database, using a new name for the table ​

Restore a single table to its original source database, the same database on the same system where it was backed up. The table still exists on that database when the restore is run, so the --tt option is required. For example:

$ ybrestore -W --username yellowbrick -d premdb -t match -tt match_restored --chain premdb2021 --point latest /tmp/data
Password for user yellowbrick: 
13:52:31.409 [ INFO] ABOUT CLIENT:
...
13:52:31.410 [ INFO] Running restore using input locations: [file:///tmp/data/]
13:52:31.503 [ INFO] Session Key = ASiZUzoeEr3_5Cb9d__UaQDm6tLmYxhWDcCbziI1aMLO1j_i9OJQPSNynLvaYcaM
13:52:32.304 [ INFO] RestoreSession: Found candidate for restore : 10June2021
13:52:32.406 [ INFO] Restoring single object: public.match
13:52:32.412 [ INFO] RestoreSession: Found candidate for restore : 10June2021
13:52:32.892 [ INFO] Starting restore of '10June2021' [84675]
ybrestore_meta | 100.0% |          Read: 6.67 KiB / 0.00 B          |       Write: 6833       |  0.00 B/s   |   2021-06-10 13:52:33  

13:52:33.624 [ INFO] Skipping user data per user request
13:52:33.626 [ INFO] Committing
13:52:33.633 [ INFO] Completed restore of '10June2021'
13:52:33.681 [ INFO] Recreating DDL
13:52:33.769 [ INFO] Starting restore of '10June2021' [84691]
ybrestore_data | 100.0% |       Read: 276.91 KiB / 276.91 KiB       |    Write: 276.86 KiB    | 62.02 KB/s  |   2021-06-10 13:52:35  
13:52:35.877 [ INFO] Validating restored objects
13:52:35.877 [ INFO] Committing
13:52:35.880 [ INFO] Completed restore of '10June2021'
13:52:35.881 [ INFO] Successfully completed the restore of public.match as public.match_restored
13:52:36.198 [ INFO] Done

Restore a single table to a different schema ​

Restore a single table to a different schema in the original source database.

$ ybrestore -W --username yellowbrick -d premdb -t public.match -tt restored.match --chain premdb2021 --point latest /tmp/data
Password for user yellowbrick: 
...

Restore a single table to a different system and database ​

Restore a single table under the same name to a different database on a different system:

$ ybrestore -W --username yellowbrick -host yb100 -d db1 -t premdb.public.match -tt db1.public.match --chain premdb2021 --point latest /tmp/data
Password for user yellowbrick: 
...

Restore from object storage ​

Restore a database from object storage, using the appropriate credentials:

% ./ybrestore -d premdb_restored --point latest --chain Feb2023 
--object-store-region us-west-2 --object-store-identity ******************** --object-store-credential **************************************** 
--temp-workdir /Users/brumsby/tmp_backups 
s3://ybbobr/premdb_bar
15:26:35.864 [ INFO] ABOUT CLIENT:
...
15:26:35.866 [ INFO] Running restore using input locations: [s3://ybbobr/premdb_bar]
...
15:26:37.582 [ INFO] Loaded file handler for s3://
15:26:37.583 [ INFO] 
Configuration (S3 client):
   endpoint           : ********
   region             : us-west-2
   identity/credential: ********
15:26:40.867 [ INFO] RestoreSession: Found candidate for restore : Feb17Full
15:26:41.560 [ INFO] Calculated restore sequence: 
15:26:41.560 [ INFO] 	1) Feb17Full
15:26:42.189 [ INFO] Starting restore of 'Feb17Full' [4295109834]
ybrestore_meta | 100.0% |        Read: 12.65 KiB / 12.65 KiB        |      Write: 12953       |  0.00 B/s   |   2023-02-17 15:26:43  

ybrestore_data | 100.0% |         Read: 8.39 MiB / 8.39 MiB         |     Write: 8.39 MiB     | 899.00 B/s  |   2023-02-17 15:27:56  
15:27:56.639 [ INFO] Validating restored objects
15:27:56.639 [ INFO] Committing
15:27:56.902 [ INFO] Completed restore of 'Feb17Full'

15:27:57.477 [ INFO] Done

Validate restore locations (in object storage) ​

The following restore fails because --validate-locations-exist is specified, but the restore location cannot be found:

% ./ybrestore -d premdb_restored_feb21_all --point latest --chain Feb2023 
--object-store-region us-west-2 --object-store-identity ***************** --object-store-credential ************************ 
--security-mode all --temp-workdir /Users/brumsby/tmp_backups --validate-locations-exist s3://ybbobr/premdb_data
12:57:47.379 [ INFO] ABOUT CLIENT:
...
Configuration (S3 client):
   endpoint           : ********
   region             : us-west-2
   identity/credential: ********
12:57:53.512 [ERROR] Failed: --validate-locations-exist is enabled and invalid backup locations found.; Failed to access one or more backup locations: s3://ybbobr/premdb_data.

Restore to a new location after moving a backup ​

If you backed up a database to a single location and then moved it to another location, you can restore it from the new location by specifying the --use-relative-location option in the ybrestore command.

This example demonstrates a case where the original backup was taken as follows:

% ./ybbackup -d premdb --full --name apr3full --chain apr2023 /Users/bkadmin/premdb_apr_backups

Sometime later, the backup directory was moved:

% mv premdb_apr_backups premdb_full_backups

The restore operation now looks like this. Note the path to the new location and the INFO message that specifies how the new path overrides the original path:

% ./ybrestore -d premdb_restored --point latest --chain apr2023 --temp-workdir /Users/bkadmin/tmpbk --security-mode all 
--use-relative-location /Users/bkadmin/premdb_full_backups
...
11:46:11.158 [ INFO] Running restore using input locations: [file:///Users/bkadmin/premdb_full_backups/]
...
11:46:13.502 [ INFO] Overridden restore input location from: [file:///Users/bkadmin/premdb_apr_backups/] to: [file:///Users/bkadmin/premdb_full_backups/]
11:46:13.781 [ INFO] RestoreSession: Found candidate for restore : apr3full
...
11:46:45.153 [ INFO] Completed restore of 'apr3full'