Restore from external backup (Performance Plan)

Prerequisites

Before starting the restore process, ensure you have the following:

• Access to your Db2 on Cloud console page

• At least one successful internal (snapshot) backup taken on the target instance before initiating external restore

• An existing DB2 backup stored in an IBM Cloud Object Storage or Amazon S3 bucket

• Your endpoint URL along with HMAC credentials (Access Key and Secret Access Key) to access the bucket and backup image

• Sufficient database storage space to accommodate the restored database

• A backup image that meets the following requirements:

  • Must be a full database backup. Incremental backups are not supported.
  • Must be compatible with the current Db2 system: created on a Linux-x86-64 system, unencrypted, and created on a single partition system.
  • Offline backups: no more than two major versions behind the current Db2 on Cloud version. Online backups: must be on the same major version as the Db2 on Cloud system.
  • If the backup was taken in an Oracle-compatible system, ensure the Db2 on Cloud system is provisioned with Oracle compatibility enabled before restoring.

  

The internal backup is required as a safety measure. If the external restore fails, you can recover the database by restoring from the internal backup.

Prerequisites

Before starting the restore process, ensure you have the following:

• An IAM API key with sufficient permissions
• At least one successful internal (snapshot) backup taken on the target instance before initiating external restore
• An existing DB2 backup stored in an IBM Cloud Object Storage or Amazon S3 bucket
• Your endpoint URL along with HMAC credentials (Access Key and Secret Access Key) to access the bucket and backup image
• Sufficient database storage space to accommodate the restored database
• A backup image that meets the following requirements:
  • Must be a full database backup. Incremental backups are not supported.
  • Must be compatible with the current Db2 system: created on a Linux-x86-64 system, unencrypted, and created on a single partition system.
  • Offline backups: no more than two major versions behind the current Db2 on Cloud version. Online backups: must be on the same major version as the Db2 on Cloud system.
  • If the backup was taken in an Oracle-compatible system, ensure the Db2 on Cloud system is provisioned with Oracle compatibility enabled before restoring.

The internal backup is required as a safety measure. If the external restore fails, you can recover the database by restoring from the internal backup.

Create internal backup (Prerequisite)

1. Navigate to the External restore tab. If no internal backup exists, you will see a message indicating that an internal backup file is required.

   

2. Click Go to internal backup page or navigate to the Backups tab.

3. Click the Run backup button and confirm by clicking Run in the dialog.

   

4. Wait for the backup to complete. You can monitor the progress on the Backups page.

   

Create internal backup (Prerequisite)

Ensure at least one successful internal (snapshot) backup has been taken on the target instance before initiating an external restore. You can trigger an internal backup through the Db2 on Cloud console before proceeding with the API calls.

Access external restore

1. Once the internal backup is complete, navigate to the External restore tab.

2. Click the External restore button to begin the restore wizard.

   

Access external restore

To initiate an external restore, use the Restore database from external storage endpoint. This single API call covers connecting to external storage, selecting the backup image, and confirming the restore.

curl -X POST \
  https://{HOSTNAME}/dbapi/v4/manage/backups/new_external_restore \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {AUTH_TOKEN}' \
  -H 'content-type: application/json' \
  -d '{"input_image":"<backup_image_path>","input_container":"<bucket_name>","archivelog_location":"<archive_log_path>","access_key":"<access_key>","secret_key":"<secret_key>","check_db_size":"false","complete_rollforward":"true","region":""}'

Where:

• input_image: Path of the backup image in object storage, excluding the part number suffix. For example, if the full backup image path is master/subdir/online/EUDB.0.db2inst1.DBPART000.20251018182026.001, the value should be master/subdir/online/EUDB.0.db2inst1.DBPART000.20251018182026.
• input_container: Name of the bucket in your object storage.
• archivelog_location: Path to the archive log location in object storage if rolling forward to end of logs. For end of backup restores, the value should be extrestore_endofbackup.
• access_key: HMAC access key for object storage authentication.
• secret_key: HMAC secret key for object storage authentication.
• check_db_size: Set to true to validate database size before restore, or false to skip validation.
• complete_rollforward: Set to true to complete rollforward and bring the database online, or false to leave the database in rollforward pending state.
• region: Region of the external object storage (optional).

The database will be unavailable during the restore process. If you set complete_rollforward to false, the database will remain offline until you manually complete the rollforward.

Monitor restore progress

Once the restore is initiated, you can monitor its progress on the External restore page. The view you see depends on your login type:

For IAM Admins

IAM administrators will see the restore history page where they can monitor the restore status. Use the Refresh button to update the status.

For User Logins

Regular users will see a full-screen progress page during the restore.

During the restore process, console functionality is limited for all users. Regular users are directed to the full-screen progress page, while IAM admins can view the restore history page to monitor status. Restore times can vary depending on the size of the backup and system conditions, and may take anywhere from several hours to a few days.

Monitor restore progress

To monitor the progress of an external restore, use the Get the list of new external restores endpoint.

curl -X GET \
  https://{HOSTNAME}/dbapi/v4/manage/backups/new_external_restore/status/list \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {AUTH_TOKEN}' \
  -H 'content-type: application/json'

The response includes the restore status and the name field, which is used as the restore_crd parameter when triggering a rollforward.

Restore times can vary depending on the size of the backup and system conditions, and may take anywhere from several hours to a few days.

Complete rollforward

If you selected "Rollforward to end of logs" without enabling "Complete rollforward", the restore will finish in a "rollforward_pending" state:

1. Click the Rollforward button in the Available action column.

2. In the Rollforward dialog:

   • Enable Complete rollforward toggle to bring the database online after this rollforward.
   • Archive log location will be prefilled based on the selection in the previous external restore step. You can change the path if the new logs are in a different location.

3. Click Start rollforward to proceed.

   

4. The status will change to "rollforward_in_progress" and then "finalizing".

   

   

Complete rollforward

To trigger a rollforward, use the Trigger rollforward from an external restore backup endpoint.

curl -X POST \
  https://{HOSTNAME}/dbapi/v4/manage/backups/new_external_restore/rollforward \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {AUTH_TOKEN}' \
  -H 'content-type: application/json' \
  -d '{"restore_crd":"<restore_crd_id>","complete_rollforward":"true","archivelog_location":"<archive_log_path>"}'

Where:

• restore_crd: Identifier of the restore operation. This value can be found in the name field from the response of the Get the list of new external restores endpoint.
• complete_rollforward: Set to true to bring the database online after rollforward, or false to keep it in rollforward pending state for additional log application.
• archivelog_location: Path to the archive log location in object storage. If not provided, uses the location from the original restore request.

Verify completion

1. When the restore is complete, the status will show "Completed" with a green checkmark.

   

2. You can expand the restore entry to view the rollforward history, which shows details of each rollforward operation performed.

   

3. The database is now online and available for connections. The console will restore full functionality within a few minutes.

After the restore completes, it may take a few additional minutes for all console features to become fully available while the system completes post-restore setup tasks.

Verify completion

Use the Get the list of new external restores endpoint to check the status of the restore operation. The restore is complete when the status shows "completed".

curl -X GET \
  https://{HOSTNAME}/dbapi/v4/manage/backups/new_external_restore/status/list \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {AUTH_TOKEN}' \
  -H 'content-type: application/json'

After the restore completes, it may take a few additional minutes for all console features to become fully available while the system completes post-restore setup tasks.

External restore failure

In case of an external restore failure, there are a couple of options to recover the system:

1. Initiate a different external restore: Click the External restore button to start a new restore. For example, if you previously selected a backup image that is not compatible with the system, you can initiate a new external restore with the correct backup image.

2. Reset from internal backup: Click the Reset from last internal backup option to restore from the internal backup you created earlier. This will reset the system to its state before the external restore was attempted.

External restore failure

In case of an external restore failure, you can:

1. Initiate a different external restore: Call the Restore database from external storage endpoint again with the correct backup image.

2. Reset from internal backup: Use the console to click the Reset from last internal backup option to restore from the internal backup you created earlier. This will reset the system to its state before the external restore was attempted.