Upgrade a Database

This article describes the procedures to upgrade databases in bare metal and virtual machine DB systems by using the Console and the API. Currently, upgrades to Oracle Database 19c (Long Term Release) are available.


This topic is not applicable to Exadata Cloud Service instances.

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.


The following are required in order to upgrade a database on a bare metal or virtual machine DB system:

  • The DB system must use Oracle Linux 7 (OL7)
  • If your DB System uses ASM storage management software, the system must use Oracle Grid Infrastructure 19c

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 version 19c Grid Infrastructure. See the following topics for more information on restoring a database to another DB system by using an on-demand full backup:

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.

About Upgrading a Database

For database software version upgrades, note the following:

  • Database upgrades involve some database downtime. Keep this in mind when scheduling your upgrade.
  • Oracle recommends that you back up your database and test the new software version on a test system before you upgrade. For information on creating an on-demand manual backup, see Overview of Backing Up a Database.
  • Oracle recommends running an upgrade precheck operation for your database prior to attempting an upgrade so that you can discover any issues that need mitigation prior to the time you plan to perform the upgrade.
  • If your databases uses Data Guard, you will need to disable or remove the Data Guard association prior to upgrading.
  • 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 To configure automatic backups for a database and To create an on-demand full backup of a database in Back Up a Database to Object Storage.
  • After upgrading, you cannot use automatic backups taken prior to 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 details on 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 OCI Console to perform your database upgrade. If your organization needs to 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 PARL.

How the Upgrade Operation Is Performed by the Database Service

During the upgrade process, the Database service does the following:

  • Executes an automatic precheck. This allows the system to identify issues needing mitigation and to stop the upgrade operation.
  • Sets a guaranteed restore point, enabling it to perform a flashback in the event of an upgrade failure.
  • Creates a new Oracle Database Home based on the specified Oracle-published or custom database software image.
  • Runs the Database Upgrade Assistant (DBUA) software to perform the upgrade.

Roll Back an Unsuccessful Upgrade (Oracle Database Enterprise Editions Only)

If your upgrade does not complete successfully on a system using one of the Enterprise software editions, you have the option of performing a rollback. A rollback resets your database to the state prior to the upgrade. All changes to the database made during and after the upgrade will be lost. The rollback option is provided in a banner message displayed on the database details page of a database following an unsuccessful upgrade operation. For more information, see Roll Back a Failed Database Upgrade.

After Your Upgrade Is Complete

After a successful upgrade, note the following:

  • Oracle recommends that you remove the old Oracle Database Home using the dbcli ultility. For more information, see Dbhome Commands in Oracle Database CLI Reference.
  • 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 software version. For more information, see What Is Oracle Database Compatibility?.
  • On virtual machine DB Systems, 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.

Upgrade a Database

View the Upgrade History Of a Database

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 Upgrade a Database.

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 Overview of Backing Up a Database.
  • The Console allows 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.
  • For databases running in virtual machine DB systems, 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.

Using the Console to Convert a Non-CDB to a PDB

  1. Open the navigation menu. Select Bare Metal, VM, and Exadata, then select DB Systems.
  2. Choose your Compartment.

    A list of DB systems is displayed.

  3. Find the DB system where the database is located, and click the system name to display details about it.
  4. In the Databases list (located on the DB System Details page), find the database you want to convert and click its name to display details about it. Confirm that the database is a non-container database by checking the Database Architecture field in the Database Information section of the details page.
  5. On the Database Details page, click More Actions, then click Convert to PDB.
  6. 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: Re-enter 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: Re-enter the TDE wallet password.
  7. In the Non Container Database Details section, enter the existing TDE wallet password of the non-CDB that you are converting.
  8. Click Run Precheck to perform a precheck, or click Convert to PDB if you are ready to convert the database.

    After you run a precheck, you are returned to the Database Details page in the console. To initiate 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 on 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 pluggin process (when the new PDB is being plugged into the new CDB), you may need to Oracle Support for assistance in completing the conversion after the issue that caused the failure has been resolved.

For virtual machine DB systems, 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. Once 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


When using the UpgradeDatabase API to upgrade a database on a virtual machine or bare metal 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.