Upgrade a Database

This article describes the procedure to upgrade a database in a DB system by using the Console and the API.

For Oracle Database release and software support timelines, see Release Schedule of Current Database Releases (Doc ID 742060.1) in the My Oracle Support portal.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment to work in.

For administrators: The policy in Let database admins manage Oracle Cloud database systems lets the specified group do everything with databases and related Database resources.

If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for databases, see Details for the Database Service.

Prerequisites

Review the following prerequisites to upgrade an Oracle Database in a DB system.

  • The DB system must use Oracle Linux 7 (OL7).
  • If your DB System uses Automatic Storage Management (ASM) storage management software, the system must use Oracle Grid Infrastructure (GI) 19c.
  • Upgrades to Oracle Database 23ai from earlier versions are currently not supported.

For databases on DB systems not meeting the minimum software version requirements, you can upgrade only after using the backup and restore operations to restore the database to a DB system that uses OL7 and GI 19c.

Note

Currently, the only option available for upgrade is to 19c.

Your Oracle Database must be configured with the following settings in order to upgrade:

  • The database must be in archivelog mode.
  • The database must have flashback enabled.

See the Oracle Database Documentation for your database's release version to learn more about these settings.

For more information, see:

About Upgrading Databases

Review the following information about database software version upgrades.

  • Database upgrades involve database downtime. Oracle recommends considering this when scheduling your database upgrade.
  • Oracle recommends that you back up your database and test the new software version on a test system before you upgrade.

    For more information about creating an on-demand manual backup, see On-Demand Full Backups.

  • Oracle recommends running an upgrade precheck operation for your database before you upgrade so that you can discover any issues that need mitigation before the time you plan to perform the upgrade. The precheck operation does not affect database availability. So you can perform it anytime.
  • An upgrade operation cannot take place while an automatic backup operation is underway. Before upgrading, Oracle recommends disabling automatic backups and performing a manual backup.

    For more information, see Configure Automatic Backups for a Database and Create an On-Demand Full Backup of a Database.

  • After upgrading, you cannot use automatic backups taken before the upgrade to restore the database to an earlier point in time.
  • If you are upgrading an database that uses version 11.2 software, the resulting version 19c database will be a non-container database (non-CDB). You can convert the resulting 19c database to a pluggable database (PDB) using the Console or APIs after your upgrade is complete.

    For more information about running a precheck and converting your non-CDB to a PDB, see Convert a Non-Container Database To an Oracle Database 19c PDB.

  • For upgrades using generally-available Oracle Database software releases, you cannot use the dbcli utility to perform the upgrade. Use the Console to perform your database upgrade. If your organization must upgrade using a customized software version, contact Oracle to receive a pre-authenticated URL that you can use with the dbcli to download your software. Performing upgrades using dbcli is only possible if Oracle has provided this pre-authenticated request URL (PAR URL).

Upgrading Databases that have Data Guard Association

For databases with a Data Guard association, you must always upgrade the standby database first and then the primary database. The upgrade options are available in the Console for Data Guard associations created using the Console. However, if you have a database that does not have a Data Guard association but is configured as a primary or standby database manually, then the following apply for upgrading such databases.

  • The database service will be able to detect and identify whether a database is a primary or standby.
  • For database versions 11.2 and 12.1, you must disable the Data Guard configuration before upgrading.
  • You must first upgrade the standby database and then the primary database.
  • The database service will set a Guaranteed Restore Point (GRP) on the database you are upgrading. After a successful upgrade, the GRP will be removed automatically from the primary database. However, on the standby database, you must manually remove the GRP.

  • While upgrading, the DB_HOME will be changed, the standby database will open in mount mode, and the primary will open in read/write mode.

After successful upgrade of both primary and standby databases, perform the following.

  1. For database versions 11.2 and 12.1, enable the Data Guard configuration you previously disabled before the upgrade.
  2. Check the open mode of the standby database.
  3. Drop the GRP created on standby.

How the Database Upgrade Operation is Performed by the Database Service

During the database upgrade process, the following steps are automatically performed:

  • Executes an automatic precheck. This enables the system to identify issues needing mitigation and to stop the upgrade operation.
  • Sets a GRP, enabling it to perform a flashback in the event of an upgrade failure.
  • Creates a new Database Home based on the specified Oracle-published or custom database software image.
  • Runs the Database Upgrade Assistant (DBUA) software to perform the upgrade on the database. For databases in Data Guard association, this step is executed only on the primary database.

Roll Back a Failed Database Upgrade

Note

The rollback operation is available for Oracle Database Enterprise Editions only.

If your database upgrade does not complete successfully, then you have the option of performing a rollback. Following an unsuccessful database upgrade operation, the rollback option is provided in a banner message displayed on the Database Details page.

Review the following information before you begin rollback.

  • Rollback resets your database to the state before the upgrade.
  • All changes to the database made during and after the upgrade will be lost.

For databases in Data Guard associations, the rollback must be performed according to the following steps.

  • If the standby database upgrade has failed and you want to rollback, perform the following steps.
    1. Rollback the standby database.
  • If the standby database upgrade has failed and you want to retry, perform the following steps.
    1. Rollback the standby database.
    2. Upgrade the standby database.
  • If the primary database upgrade has failed and you want to rollback, perform the following steps.
    1. Rollback the primary database.
    2. Rollback the standby database using the CLI. The Console does not provide an option to rollback a successful upgrade.

      For more information about CLI, see, Upgrade Rollback.

    3. Reenable Data Guard configuration on primary databases running on 11.2 and 12.1 database versions.
    4. After a successful rollback, verify the Data Guard configurations.
  • If the primary database upgrade has failed and you want to retry, perform the following steps.
    1. Rollback the primary database.
    2. Execute flashback to GRP on the standby database.

      For more information about GRP, see Managing Guaranteed Restore Points.

    3. Upgrade the primary database.
Note

You must always rollback the primary database first and then the standby database.

Generally, when you rollback the database using the rollback option in the Console, the following steps are taken care of by the database service automatically.

  1. Execute flashback.
  2. Change Database Home.
  3. Drop GRP.

You can rollback a successful standby database upgrade only using CLI.

For more information about the steps to perform a rollback using the Console, see Roll Back a Failed Database Upgrade.

After Your Database Upgrade is Complete

After a successful upgrade, note the following:

  • Oracle recommends that you remove the old Database Home using the dbcli ultility.

    For more information, see Dbhome Commands.

  • Check that automatic backups are enabled for the database if you disabled them prior to upgrading.
  • Edit the Oracle Database COMPATIBLE parameter to reflect the new Oracle Database version.

    For more information, see What Is Oracle Database Compatibility?.

  • Ensure that the .bashrc file in the home directory of the Oracle User has been updated to point to the 19c Database Home.
  • If you upgraded a database from Oracle Database 11.2 to Oracle Database 19c, you can convert the resulting non-container database to a pluggable database (PDB). You can perform a precheck prior to the conversion to identify problems prior to the conversion operation.
  • The GRP that was created on the standby database must be dropped.

Managing Guaranteed Restore Points

Listing Guaranteed Restore Points

You can use the following statement to list all the GRPs using the V$RESTORE_POINT View.

SELECT NAME FROM V$RESTORE_POINT WHERE GUARANTEE_FLASHBACK_DATABASE='YES';

For more information, see Listing Restore Points Using the V$RESTORE_POINT view in Oracle Database Backup and Recovery User's Guide.

Dropping Guaranteed Restore Points

You can use the following statement to drop a GRP using the DROP RESTORE POINT statement.

DROP RESTORE POINT <grp name>;

where, grp name is the name of the GRP that must be dropped.

For more information, see Dropping Restore Points in Oracle Database Backup and Recovery User's Guide.

Apply a Database Upgrade

View the Database Upgrade History

Roll Back a Failed Database Upgrade

Convert a Non-Container Database To an Oracle Database 19c PDB

This topic applies to databases upgraded from Oracle Database 11.2 to Oracle Database 19c. As part of the conversion process, you create a new container database (CDB) to hold the pluggable database (PDB) created by the conversion of the non-CDB. To convert a non-container database to a PDB that uses a later version of Oracle Database than 19c, follow the steps in this topic, then upgrade the resulting 19c database to a later software version, as described in Apply a Database Upgrade.

Prerequisites and Recommended Practices

  • You must have the TDE wallet password of the non-CDB in order to convert it into a PDB.
  • Oracle recommends creating a manual backup of the database before attempting the conversion. For more information, see Back Up and Recovery in Base Database Service.
  • The Console enables you to perform a precheck for your conversion operation to ensure that the conversion can complete successfully. Oracle recommends running the precheck before performing the conversion. To perform the precheck, follow the steps in this procedure, and for the final step, click Run Precheck.
  • You can clone the DB system and test the conversion operation on the database in the cloned system before attempting the conversion on the source DB system. For more information, see Clone a DB System.

Convert a Non-CDB to a PDB Using the Console

  1. Open the navigation menu. Select Oracle Database, then select Oracle Base Database.
  2. Select your Compartment. A list of DB systems is displayed.
  3. In the list of DB systems, click the name of the DB system that contains the database you want to convert.
  4. The details of the DB system followed by a list of databases are displayed.
  5. In the list of databases, click the name of the database that you want to convert.
  6. On the Database Details page, in the Database information tab, check the Database architecture field to confirm that the database is a non-container database.
  7. On the Database Details page, click More actions, then click Convert to PDB.
  8. In the Convert non-CDB database to pluggable database panel, provide the following information in the Container database details section:
    • Container database name: Provide a name for the new CDB that will hold your converted PDB.
    • Password: Provide a password for the new CDB.
    • Confirm password: Reenter the CDB password.
    • Use the administrator password for the TDE wallet: Uncheck this option if you want to set a separate password for the TDE wallet. After you uncheck the option, the following fields display:
      • Enter TDE wallet password: Provide a TDE wallet password for the new CDB.
      • Confirm TDE wallet password: Reenter the TDE wallet password.
  9. In the Non container database details section, enter the existing TDE wallet password of the non-CDB that you are converting.
  10. Click Run precheck to perform a precheck, or click Convert to PDB if you are ready to convert the database.
    Note

    After you run a precheck, you are returned to the Database Details page in the Console. To start the conversion operation, follow all the steps in this topic again, and click the Convert to PDB option in the final step.

After the database has been successfully converted, the Database Details page in the Console displays Container database in the Database architecture field. This field is located in the Database information section of the Database Details page.

Troubleshooting Tips for Converting a Non-CDB to a PDB

If your conversion operation does not complete successfully, you can troubleshoot the issue using the database cli (dbcli) command line utility. For more information about database cli, see Oracle Database CLI Reference.

To troubleshoot:

  1. Login to the DB system as described in Overview of Connecting to a DB System.
  2. Use the dbcli list-jobs command to determine the job ID and status of the unsuccessful database conversion operation.
  3. Use the dbcli describe-job command to display details about the unsuccessful database conversion operation.

Based on the information retuned by the dbcli describe-job command, you can try to resolve the issue that caused the conversion operation to fail. For errors that occur during the plugging in process (when the new PDB is being plugged into the new CDB), contact Oracle Support for assistance in completing the conversion after the issue that caused the failure has been resolved.

If a conversion operation fails, the console might display either 2 databases in the DB system, or display only a terminated database. The DB system can take up to 2 hours to reset itself. If the Console no longer shows 2 databases or a single terminated database, you can try the conversion again. If the DB system does not reset itself and allow you to try again, contact Oracle Support.

Use the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following APIs to manage database upgrades:

  • ListDatabaseUpgradeHistoryEntries
  • UpgradeDatabase
Note

When using the UpgradeDatabase API to upgrade a database on a DB system, you must specify either DB_VERSION or DB_SOFTWARE_IMAGE as the upgrade source.

For the complete list of APIs for the Database service, see Database Service API.