Before You Begin

If you wish to replace your database using a backup from another currently operational Database Classic Cloud Service database deployment in the same identity domain, then you must specify the source database deployment by selecting from a list of the available deployments.

If you wish to replace your database using any other backup, you are prompted for the following information:

• The database ID of the backed-up database.

• The decryption method for the backup, which is the password associated with the backup for backups that use password encryption, or a zip file containing the source database’s wallet directory and contents for backups that use Transparent Data Encryption (TDE).

• The name of the Oracle Cloud Infrastructure Object Storage Classic container where the backup is stored.

• The user name and password of an Oracle Cloud user who has read access to the container.

Procedure

1. Open the Instances page of the Oracle Database Classic Cloud Service console.

   For detailed instructions, see Accessing the Oracle Database Classic Cloud Service Console.

2. Click the database deployment whose database you wish to replace.

   The Oracle Database Classic Cloud Service Overview page is displayed.

3. From the action menu () next to the database deployment name, choose Replace Database using Backup.

   The Replace Database using Backup window is displayed.

4. Specify attributes in the Replace Database using Backup window:

   On-Premises Backup? — use this option to indicate the origin of the source database backup.

   If you select this option you are indicating that the source database backup is not from another currently operational Database Classic Cloud Service database deployment in the same identify domain. In this case, the following fields and options are displayed:

   • Database ID — enter the database id of the database from which the existing backup was created. You can get this value by querying the backup source database as follows:

     SQL> SELECT dbid FROM v$database;

   • Decryption Method — provide the information necessary to decrypt the existing backup:

     • For a backup that uses Transparent Database Encryption (TDE), select Upload Wallet File then click Browse and specify a zip file containing the source database’s TDE wallet directory, and the contents of that directory.

       Note:

       If the source database is from another Database Classic Cloud Service database deployment, its TDE wallet directory is /u01/app/oracle/admin/dbname/tde_wallet.

     • For a backup that uses password encryption, select Paste RMAN Key Value and paste the password (key value) used to encrypt the backup.

     Note:

     For database deployments using Oracle Database 12c Release 2 (12.2), or later, only backups using TDE are supported.

   • Cloud Storage Container — enter the name of the Oracle Cloud Infrastructure Object Storage Classic container where the existing backup is stored; use this format:

     instance-id_domain/container

     where instance is the name of the Oracle Cloud Infrastructure Object Storage Classic instance, id_domain is the id of the identity domain, and container is the name of the container.

   • Username — enter the user name of an Oracle Cloud user who has read access to the container specified in Cloud Storage Container.

   • Password — enter the password of the user specified in Username.

   • Administration Password and Confirm Password — enter and then re-enter a password for the Oracle Database SYS and SYSTEM users in the newly replaced database.

   If you deselect On-Premises Backup? you are indicating that the source database backup is from another currently operational Database Classic Cloud Service database deployment in the same identity domain. In this case, the following fields are displayed:

   • Source Instance Name — specify the database deployment whose database backup you want to use.

   • Backup Tag — a list of backups available for the specified database deployment. The latest backup is selected by default, but you can choose an earlier backup.

   • Administration Password and Confirm Password — enter and then re-enter a password for the Oracle Database SYS and SYSTEM users in the newly replaced database.

5. Click Replace Database and confirm that you want to replace the database when prompted.

   The database deployment is put into Maintenance status and the operation begins. The process is fully automated and takes some time to complete. You should not access or manipulate the database deployment until the process is completed.

The dbaasapi utility operates by reading a json file containing instructions and other information and writing its results to a json file specified in the input file. In essence, it is a command-line utility that operates like a REST API endpoint, accepting a json "request body" and producing a json "response body". The dbaasapi utility checks that the operation being requested does not conflict with any operation already in progress and then runs the operation asynchronously: that is, it starts the requested operation and then returns terminal control to you.

Here are the tasks you perform to replace the database by using ibkup actions:

1. Copy the TDE wallet from the source database to the Database Classic Cloud Service deployment, if necessary.

2. Create dbaasapi input files for ibkup begin and ibkup status actions.

3. Run the ibkup begin action.

4. Run the ibkup status action to monitor progress of the ibkup operation.

5. Upon completion of the ibkup operation, confirm that the source database now resides on the Database Classic Cloud Service deployment.

Copy the Source Database TDE Wallet

If the cloud backup you are using was created using Transparent Data Encryption (TDE) or dual-mode encryption, you need to copy the TDE wallet from the source database to the database deployment.

Here are high-level instructions:

1. Zip (or tar) up the source database's tde_wallet directory. (If the source database is from another Database Classic Cloud Service database deployment, its tde_wallet directory is /u01/app/oracle/admin/dbname/tde_wallet.)

2. On the database deployment you created, make a directory where you'll store the various files you'll create and use in the coming steps. For example:

   # mkdir –p /home/oracle/ibkup  

3. Use a secure copy utility like scp or WinSCP to copy the zip file to this directory.

4. Unzip (or untar) the file into the tde_wallet subdirectory.

Create dbaasapi Input Files

1. Use a secure shell utility like ssh or PuTTY to connect as the opc user to the compute node that is associated with your target database deployment. For instructions, see Connecting to a Compute Node Through Secure Shell (SSH).

2. The dbaasapi utility must be run as the root user. Start a root-user shell:

   $ sudo -s 
   # 

3. Navigate to the directory where you previously stored the source database TDE wallet.

   # cd /home/oracle/ibkup

   If you did not copy the source database TDE wallet, create a directory to store your request and response files and then navigate to it.

4. Create a begin-request.json file to pass to dbaasapi to perform the ibkup begin action.

   Here is an example that uses a password-encrypted backup:

   # cat begin-request.json 
   {
     "object": "db",
     "action": "begin",
     "operation": "ibkup",
     "params": {
       "dbname": "crmdb",
       "dbid": "1428538966",
       "oss_url": "https://mystore.storage.oraclecloud.com/v1/Storage-mystore/IBKUP",
       "oss_user": "storageadmin",
       "oss_passwd": "pa55word",
       "decrypt_key": "backup",
       "passwd": "Welcome-1",
       "dbsize": "30GB"
     },
     "outputfile": "/home/oracle/ibkup/begin-response.json",
     "FLAGS": ""
   }
   

   The json object for the ibkup begin action supports the following parameters. All parameters are required except those identified as optional.

   Parameter	Description
   object	The value "db".
   action	The value "begin".
   operation	The value "ibkup".
   params	An object containing parameters that provide details for the ibkup begin action. This object has the following parameters: dbname: The name of the target database that you are replacing. You can get this value by querying the target database: SQL> SELECT name FROM v$database; dbid: The database id of the source database. You can get this value by querying the source database: SQL> SELECT dbid FROM v$database; oss_url: The URL of the container where the source database's backup is stored. oss_user: The user name of an Oracle Cloud user who has read privileges for the container where the source database's backup is stored. oss_passwd: The password of the oss_user user. rman_handle: (Optional) The RMAN handle of a targeted backup that contains controlfile and spfile backups. The ibkup begin action will use the controlfile and spfile in this backup. Use the rman_tag parameter to specify the RMAN tag of a backup supported by this controlfile and spfile. If you do not specify an RMAN tag, the latest backup supported by this controlfile and spfile will be used. Oracle recommends that you provide both a handle and a tag to use a specific backup or provide neither a handle nor a tag to use the latest backup. You can view RMAN handles and tags by using the RMAN LIST BACKUP command. rman_tag: (Optional) The RMAN tag of a targeted full backup. The ibkup begin action will use this backup. Use the rman_handle parameter to specify the RMAN handle of a backup containing controlfile and spfile backups that support this RMAN tag. If you do not specify an RMAN handle, the latest controlfile and spfile will be used. If they do not support the specified RMAN tag, a “datafile not found” error will occur. Oracle recommends that you provide both a handle and a tag to use a specific backup or provide neither a handle nor a tag to use the latest backup. You can view RMAN handles and tags by using the RMAN LIST BACKUP command. decrypt_key: (Optional) The key (password) used to encrypt the backup. Provide this parameter if you created the backup using password encryption or dual-mode encryption. Note: you cannot use this option when replacing the database on a database deployment using Oracle Database 12c Release 2 (12.2) or later, because only backups using TDE are supported for such deployments. decrypt_wallet: (Optional) The fully qualified path of the wallet directory you copied from the source database to the DBCS deployment you created; for example: /home/oracle/ibkup/tde_wallet. Provide this parameter if you created the backup using Transparent Data Encryption (TDE) or dual-mode encryption. passwd: The administrator (SYS and SYSTEM) password to use for the target database after the replacement operation concludes. dbsize: The size of the source database.
   outputfile	The fully qualified name of the output file for dbaasapi to use; for example: "/home/oracle/ibkup/begin-response.json".
   FLAGS	The value "" (an empty string).

5. Create a status-request.json file to pass to dbaasapi to perform the ibkup status action. Here is an example:

   # vim status-request.json
   {
     "object": "db",
     "action": "status",
     "operation": "ibkup",
     "id": "TBD",
     "params": {
       "dbname": "crmdb"
     },
     "outputfile": "/home/oracle/ibkup/status-response.json",
     "FLAGS": ""
   }

   In this example, the value of the id parameter is "TBD" because the ibkup begin action whose status this action will check has not been run yet.

   The json object for the ibkup status action supports the following parameters. All parameters are required.

   Parameter	Description
   object	The value "db".
   action	The value "status".
   operation	The value "ibkup".
   id	The ID number of the action you want status for.
   params	An object containing parameters that provide details for the ibkup status action. This object has the following parameters: dbname: The name of the database on the target database that is being replaced.
   outputfile	The fully qualified name of the output file for dbaasapi to use; for example: "/home/oracle/ibkup/status-response.json".
   FLAGS	The value "" (an empty string).

Run the ibkup begin Action

1. Use dbaasapi to run the ibkup begin action:

   # /var/opt/oracle/dbaasapi/dbaasapi -i begin-request.json 

   Note:

   The begin action deletes the input json file because it contains sensitive password information. If you are testing and want to save the file for debugging purposes, make a copy of it before you run the ibkup begin action; for example:

   # cp begin-request.json begin-request.json.keep 

2. View the output file to confirm that the action has started and note the id of the action; for example:

   # cat /home/oracle/ibkup/begin-response.json 
   {
      "msg" : "",
      "object" : "db",
      "status" : "Starting",
      "errmsg" : "",
      "outputfile" : "",
      "action" : "begin",
      "id" : "19",
      "operation" : "ibkup",
      "logfile" : "/var/opt/oracle/log/crmdb/dbaasapi/db/ibkup/19.log"
   }

   The key parameters in this response are as follows:

   Parameter	Description
   status	The status of the operation; one of: "Error", "Starting", "InProgress" or "Success".
   action	The value "begin", which is the ibkup action you requested.
   id	The ID number assigned to this action. Use this number in subsequent ibkup status actions to check the status of the overall ibkup operation.
   operation	The value "ibkup", which is the operation you requested.
   logfile	The log file for the ibkup operation. You can poll this log file to monitor progress of the operation. However, you should run the ibkup status action to monitor progress because this provides additional status information along with a definitive indication of when the operation is finished.

Run the ibkup status Action to Monitor Progress

1. Update the status-request.json input file with id value of the ibkup operation that you have started. Edit the status-request.json file, replacing the id parameter value of "TBD" with the ID number reported in the begin-response.json file.

2. Use dbaasapi to run the ibkup status action and view the response; for example:

   # /var/opt/oracle/dbaasapi/dbaasapi -i status-request.json
   # cat status-response.json
   {
      "msg" : "  -> 15 03 * * 6 oracle /var/opt/oracle/cleandb/cleandblogs.pl\\n\\n#### Completed OCDE Successfully ####",
      "object" : "db",
      "status" : "Success",
      "errmsg" : "",
      "outputfile" : "",
      "action" : "begin",
      "id" : "19",
      "operation" : "ibkup",
      "logfile" : "/var/opt/oracle/log/crmdb/dbaasapi/db/ibkup/19.log"
   }

3. Rerun the ibkup status action regularly until the response indicates that the operation is finished.

Confirm Successful Completion

1. Connect as the oracle user to the compute node that is associated with your target database deployment.

   See Connecting to a Compute Node Through Secure Shell (SSH).

2. Connect as SYSDBA to the database:

   $ sqlplus / as sysdba

3. Check the database status:

   SQL> select status from v$instance;
   STATUS
   ------------
   OPEN

4. Check the name and id of the database; for example:

   SQL> select name, dbid from v$database;
   
   NAME        DBID
   --------- ----------
   CRMDB      4023093732

5. If the Oracle Database version is 12c or later, view information about its PDBs; for example:

   SQL> select name,open_mode,restricted from v$pdbs;
   
   NAME                   OPEN_MODE  RES
   ---------------------- ---------- ---
   PDB$SEED               READ ONLY  NO
   PDBDBNOASM             READ WRITE NO

6. Exit SQL*Plus:

   SQL> exit
   $ 

7. Check that services provided by Oracle Net Listener include those from the source database; for example:

   $ lsnrctl status
   Services Summary...
   Service "crmdb.localdomain" has 1 instance(s).
     Instance "crmdb", status READY, has 1 handler(s) for this service...
   Service "dbnoasm.localdomain" has 1 instance(s).
     Instance "crmdb", status READY, has 1 handler(s) for this service...
   Service "dbnoasm.localdomainXDB" has 1 instance(s).
     Instance "crmdb", status READY, has 1 handler(s) for this service...
   Service "pdbdbnoasm.localdomain" has 1 instance(s).
     Instance "crmdb", status READY, has 1 handler(s) for this service...
   The command completed successfully

8. Disconnect from the compute node:

   $ exit

Use ibkup restore

The restore action takes an input file of the same format as the begin action, except that the value of the action parameter must be "restore".

If a begin operation fails, you can use the restore action to reset the database deployment's environment so that you can attempt the begin operation again, after determining the cause of the failure and correcting the problem.

If you successfully used ibkup to create a cloud database, but now want to replace the database from a different backup, you must use the restore action before using the begin action.

After you use the restore action, you need to reboot the database deployment's compute node to ensure that the environment is completely reset. For instructions, see Rebooting a Compute Node.

The restore action does as follows:

1. Validates the format and completeness of the input file.

2. Creates the output file, which includes an ID number for use in subsequent status actions.

3. Releases terminal control.

4. Terminates any begin action that is in progress.

5. Kills all processes related to the begin action. If it cannot kill one or more processes, it exits with an error status.

6. Restores the database deployment environment to its state before the first begin action.

More About ibkup Actions

The preceding instantiate-from-backup tasks showed the use of two ibkup actions; begin and status. Here is more information about what these two actions do, along with information about two other ibkup actions; prereqs and restore.

• The begin action:

  1. Validates the format and completeness of the input file.

  2. Creates the output file, which includes an ID number for use in subsequent status actions.

  3. Releases terminal control.

  4. Performs the same value-validation checks that the prereqs action performs.

  5. Takes a backup of the current database deployment environment, should the need arise to restore the environment after a failed ibkup operation.

  6. Replaces the current database using the backup of the source database.

• The status action:

  1. Validates the format and completeness of the input file.

  2. Retrieves the current status of operation whose ID number was provided in the input file.

  3. Creates the output file, which contains the retrieved status information.

• The prereqs action takes an input file of the same format as the begin and restore actions, except that the value of the action parameter must be "prereqs".

  You can use the prereqs action to test whether the input file you intend to use for either the begin action or the restore action is valid and that the backup specified in the file is available.

  The prereqs action does as follows:

  1. Validates the format and completeness of the input file.

  2. Creates the output file, which includes an ID number for use in subsequent status actions.

  3. Releases terminal control.

  4. Checks that the values provided in the input file would be valid if used in the input file for a begin or restore action. It confirms access to the backup, including use of the decryption key and wallet as necessary, and that the backup's database ID matches the provided dbid.