# Upgrading a DB instance for Amazon RDS Custom for Oracle **Note** End of support notice: On March 31, 2027, AWS will end support for Amazon RDS Custom for Oracle. After March 31, 2027, you will no longer be able to access the RDS Custom for Oracle console or RDS Custom for Oracle resources. For more information, see [RDS Custom for Oracle end of support](RDS-Custom-for-Oracle-end-of-support.md). You can upgrade an Amazon RDS Custom DB instance by modifying it to use a new custom engine version (CEV). For general information about upgrades, see [Upgrading a DB instance engine version](USER_UpgradeDBInstance.Upgrading.md). **Topics** + [Overview of upgrades in RDS Custom for Oracle](#custom-upgrading.overview) + [Requirements for RDS Custom for Oracle upgrades](#custom-upgrading-reqs) + [Considerations for RDS Custom for Oracle database upgrades](custom-upgrading-considerations.md) + [Considerations for RDS Custom for Oracle OS upgrades](custom-upgrading-considerations-os.md) + [Viewing valid CEV upgrade targets for RDS Custom for Oracle DB instances](custom-upgrading-target.md) + [Upgrading an RDS Custom for Oracle DB instance](custom-upgrading-modify.md) + [Viewing pending database upgrades for RDS Custom DB instances](custom-upgrading-pending.md) + [Troubleshooting an upgrade failure for an RDS Custom for Oracle DB instance](custom-upgrading-failure.md) ## Overview of upgrades in RDS Custom for Oracle With RDS Custom for Oracle, you can patch either your Oracle database or your DB instance operating system (OS) by creating new CEVs and then modifying your instance to use the new CEV. **Topics** + [CEV upgrade options](#custom-upgrading.overview.cev-options) + [Patching without CEVs](#custom-upgrading.overview.no-cevs) + [General steps for patching your DB instance with a CEV](#custom-upgrading.overview.general-steps) ### CEV upgrade options When you create a CEV for an upgrade, you have the following mutually exclusive options: **Database only** Reuse the Amazon Machine Image (AMI) currently in use by your DB instance, but specify different database binaries. RDS Custom allocates a new binary volume and then attaches it to the existing Amazon EC2 instance. RDS Custom replaces the entire database volume with a new volume that uses your target database version. **OS only** Reuse the database binaries currently in use by your DB instance, but specify a different AMI. RDS Custom allocates a new Amazon EC2 instance, and then attaches the existing binary volume to the new instance. The existing database volume is retained. If you want to upgrade both the OS and database, you must upgrade the CEV twice. You can either upgrade the OS and then the database or upgrade the database and then the OS. **Warning** When you patch your OS, you lose your root volume data and any existing OS customization. Thus, we strongly recommend that you don't use the root volume for installations or for storing permanent data or files. We also recommend that you back up your data before the upgrade. ### Patching without CEVs We strongly recommend that you upgrade your RDS Custom for Oracle DB instance using CEVs. RDS Custom for Oracle automation synchronizes the patch metadata with the database binary on your DB instance. In special circumstances, RDS Custom supports applying a "one-off" database patch directly to the underlying Amazon EC2 instance directly using the OPatch utility. A valid use case might be a database patch that you want to apply immediately, but the RDS Custom team is upgrading the CEV feature, causing a delay. To apply a database patch manually, perform the following steps: 1. Pause RDS Custom automation. 1. Apply your patch to the database binaries on the Amazon EC2 instance. 1. Resume RDS Custom automation. A disadvantage of the preceding technique is that you must apply the database patch manually to every instance that you want to upgrade. In contrast, when you create a new CEV, you can create or upgrade multiple DB instances using the same CEV. ### General steps for patching your DB instance with a CEV Whether you patch the OS or your database, perform the following basic steps: 1. Create a CEV that contains either of the following, depending on whether you're patching the database or OS: + The Oracle Database RU that you want to apply to your DB instance + A different AMI–either the latest available or one that you specify–and an existing CEV to use as a source Follow the steps in [Creating a CEV](custom-cev.create.md). 1. (Optional for database patching) Check available engine version upgrades by running `describe-db-engine-versions`. 1. Start the patching process by running `modify-db-instance`. The status of the instance being patched differs as follows: + While RDS is patching the database, the status of the DB instance changes to **Upgrading**. + While RDS is patching the OS, the status of the DB instance changes to **Modifying**. When the DB instance has the status **Available**, patching is complete. 1. Confirm that your DB instance uses the new CEV by running `describe-db-instances`. ## Requirements for RDS Custom for Oracle upgrades When upgrading your RDS Custom for Oracle DB instance to a target CEV, make sure you meet the following requirements: + The target CEV to which you are upgrading must exist. + You must upgrade either the OS or the database in a single operation. Upgrading both the OS and the database in a single API call isn't supported. + The target CEV must use the installation parameter settings that are in the manifest of the current CEV. For example, you can't upgrade a database that uses the default Oracle home to a CEV that uses a nondefault Oracle home. + For database upgrades, the target CEV must use a new minor database version, not a new major version. For example, you can't upgrade from an Oracle Database 12c CEV to an Oracle Database 19c CEV. But you can upgrade from version 21.0.0.0.ru-2023-04.rur-2023-04.r1 to version 21.0.0.0.ru-2023-07.rur-2023-07.r1. + For OS upgrades, the target CEV must use a different AMI but have the same major version. # Considerations for RDS Custom for Oracle database upgrades **Note** End of support notice: On March 31, 2027, AWS will end support for Amazon RDS Custom for Oracle. After March 31, 2027, you will no longer be able to access the RDS Custom for Oracle console or RDS Custom for Oracle resources. For more information, see [RDS Custom for Oracle end of support](RDS-Custom-for-Oracle-end-of-support.md). If you plan to upgrade your database, consider the following: + The currently supported operating system (OS) version is Oracle Linux 8. To continue receiving the latest security updates and patches from RDS Custom for Oracle, upgrade your DB instances to Oracle Linux 8 by specifying a CEV based on this OS. Oracle Database 12c Release 1 (12.1), Oracle Database Release 2 (12.2), and Oracle Database 19c are the only releases that support Oracle Linux 8. To migrate to the latest Oracle Linux 8 AMI, upgrade your OS to the latest AMI. For more information, see [Upgrading an RDS Custom for Oracle DB instance](custom-upgrading-modify.md). Oracle Linux 7.9 ended support on Dec 31, 2024. To continue running Oracle Linux 7 after the end of support, purchase an Oracle Extended Support license. You're responsible for security updates and must patch your RDS Custom for Oracle instances manually. For more information, see [Lifetime Support Policy: Coverage for Oracle Open Source Service Offerings](https://www.oracle.com/a/ocom/docs/elsp-lifetime-069338.pdf). + When you upgrade the database binaries in your primary DB instance, RDS Custom for Oracle upgrades your read replicas automatically. When you upgrade the OS, however, you must upgrade the read replicas manually. + When you upgrade a container database (CDB) to a new database version, RDS Custom for Oracle checks that all PDBs are open or could be opened. If these conditions aren't met, RDS Custom stops the check and returns the database to its original state without attempting the upgrade. If the conditions are met, RDS Custom patches the CDB root first, and then patches all other PDBs (including `PDB$SEED`) in parallel. After patching completes, RDS Custom attempts to open all PDBs. If any PDBs fail to open, you receive the following event: `The following PDBs failed to open: list-of-PDBs`. If RDS Custom fails to patch the CDB root or any PDBs, the instance is put into the `PATCH_DB_FAILED` state. + You might want to perform a major database version upgrade and a conversion of non-CDB to CDB at the same time. In this case, we recommend that you proceed as follows: 1. Create a new RDS Custom for Oracle DB instance that uses the Oracle multitenant architecture. 1. Plug in a non-CDB into your CDB root, creating it as a PDB. Make sure that the non-CDB is the same major version as your CDB. 1. Convert your PDB by running the `noncdb_to_pdb.sql` Oracle SQL script. 1. Validate your CDB instance. 1. Upgrade your CDB instance. # Considerations for RDS Custom for Oracle OS upgrades **Note** End of support notice: On March 31, 2027, AWS will end support for Amazon RDS Custom for Oracle. After March 31, 2027, you will no longer be able to access the RDS Custom for Oracle console or RDS Custom for Oracle resources. For more information, see [RDS Custom for Oracle end of support](RDS-Custom-for-Oracle-end-of-support.md). When you plan an OS upgrade, consider the following: + You can't provide your own AMI for use in an RDS Custom for Oracle CEV. You can specify either the default AMI, which uses Oracle Linux 8, or an AMI that has been previously used by an RDS Custom for Oracle CEV. **Note** RDS Custom for Oracle releases a new default AMI when common vulnerabilities and exposures are discovered. No fixed schedule is available or guaranteed. RDS Custom for Oracle tends to publish a new default AMI every 30 days. + When you upgrade the OS in your primary DB instance, you must upgrade its associated read replicas manually. + Reserve sufficient Amazon EC2 compute capacity for your instance type in your AZ before you begin patching the OS. When you create a Capacity Reservation, you specify the AZ, number of instances, and instance attributes (including instance type). For example, if your DB instance uses the underlying EC2 instance type r5.large, we recommend that you reserve EC2 capacity for r5.large in your AZ. During OS patching, RDS Custom creates one new host of type db.r5.large, which can become stuck if the AZ lacks EC2 capacity for this instance type. If you reserve EC2 capacity, you lower the risk of blocked patching caused by capacity constraints. For more information, see [On-Demand Capacity Reservations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-capacity-reservations.html) in the *Amazon EC2 User Guide*. + Back up your DB instance before you upgrade its OS. The upgrade removes your root volume data and any existing OS customizations. + In the shared responsibility model, you're responsible for keeping your OS up to date. RDS Custom for Oracle doesn't mandate which patches you apply to your OS. If your RDS Custom for Oracle is functional, you can use the AMI associated with this CEV indefinitely. # Viewing valid CEV upgrade targets for RDS Custom for Oracle DB instances **Note** End of support notice: On March 31, 2027, AWS will end support for Amazon RDS Custom for Oracle. After March 31, 2027, you will no longer be able to access the RDS Custom for Oracle console or RDS Custom for Oracle resources. For more information, see [RDS Custom for Oracle end of support](RDS-Custom-for-Oracle-end-of-support.md). You can see existing CEVs on the **Custom engine versions** page in the AWS Management Console. You can also use the [describe-db-engine-versions](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-engine-versions.html) AWS CLI command to find valid CEVs to use when you upgrade your DB instances, as shown in the following example. This example assumes that you created a DB instance using the engine version `19.my_cev1`, and that the upgrade versions `19.my_cev2` and `19.my_cev` exist. ``` aws rds describe-db-engine-versions --engine custom-oracle-ee --engine-version 19.my_cev1 ``` The output resembles the following. The `ImageId` field shows the AMI ID. ``` { "DBEngineVersions": [ { "Engine": "custom-oracle-ee", "EngineVersion": "19.my_cev1", ... "Image": { "ImageId": "ami-2345", "Status": "active" }, "DBEngineVersionArn": "arn:aws:rds:us-west-2:123456789012:cev:custom-oracle-ee/19.my_cev1/12a34b5c-67d8-90e1-2f34-gh56ijk78lm9" "ValidUpgradeTarget": [ { "Engine": "custom-oracle-ee", "EngineVersion": "19.my_cev2", "Description": "19.my_cev2 description", "AutoUpgrade": false, "IsMajorVersionUpgrade": false }, { "Engine": "custom-oracle-ee", "EngineVersion": "19.my_cev3", "Description": "19.my_cev3 description", "AutoUpgrade": false, "IsMajorVersionUpgrade": false } ] ... ``` # Upgrading an RDS Custom for Oracle DB instance **Note** End of support notice: On March 31, 2027, AWS will end support for Amazon RDS Custom for Oracle. After March 31, 2027, you will no longer be able to access the RDS Custom for Oracle console or RDS Custom for Oracle resources. For more information, see [RDS Custom for Oracle end of support](RDS-Custom-for-Oracle-end-of-support.md). To upgrade your RDS Custom for Oracle DB instance, modify it to use a new CEV. This CEV can contain either new database binaries or a new AMI. For example, to upgrade your Oracle Linux 7.9 DB instance to Oracle Linux 8, specify the latest AMI, which uses Oracle Linux 8. To upgrade the database and OS, you must perform two separate upgrades. **Note** If you upgrade the database, RDS Custom automatically upgrades read replicas after it upgrades the primary DB instance. If you upgrade the OS, you must upgrade the replicas manually. Before you begin, review [Requirements for RDS Custom for Oracle upgrades](custom-upgrading.md#custom-upgrading-reqs) and [Considerations for RDS Custom for Oracle database upgrades](custom-upgrading-considerations.md). ## Console **To upgrade an RDS Custom for Oracle DB instance** 1. Sign in to the AWS Management Console and open the Amazon RDS console at [https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/). 1. In the navigation pane, choose **Databases**, and then choose the RDS Custom for Oracle DB instance that you want to upgrade. 1. Choose **Modify**. The **Modify DB instance** page appears. 1. For **DB engine version**, choose a new CEV. Do the following: + If you are patching the database, make sure that the CEV specifies database binaries that are different from those used by your DB instance, and doesn't specify an AMI that is different from the AMI currently used by your DB instance. + If you are patching the OS, make sure that the CEV specifies an AMI that is different from the AMI currently used by your DB instance, and doesn't specify different database binaries. **Warning** When you patch your OS, you lose your root volume data and any existing OS customization. 1. Choose **Continue** to check the summary of modifications. Choose **Apply immediately** to apply the changes immediately. 1. If your changes are correct, choose **Modify DB instance**. Or choose **Back** to edit your changes or **Cancel** to cancel your changes. ## AWS CLI The following examples show possible upgrade scenarios. The examples assume that you created an RDS Custom for Oracle DB instance with the following characteristics: + DB instance named `my-custom-instance` + CEV named `19.my_cev1` + Oracle Database 19c using the non-CDB architecture + Oracle Linux 8 using AMI `ami-1234` The latest service-provided AMI is `ami-2345`. You can find AMIs by running the CLI command `describe-db-engine-versions`. **Topics** + [Upgrading the OS](#custom-upgrading-modify.CLI.os) + [Upgrading the database](#custom-upgrading-modify.CLI.db) ### Upgrading the OS In this example, you want to upgrade `ami-1234` to `ami-2345`, which is the latest service-provided AMI. Because you are upgrading the OS, the database binaries for `ami-1234` and `ami-2345` must be the same. You create a new CEV named `19.my_cev2` based on `19.my_cev1`. **Example** For Linux, macOS, or Unix: ``` aws rds create-custom-db-engine-version \ --engine custom-oracle-ee \ --engine-version 19.my_cev2 \ --description "Non-CDB CEV based on ami-2345" \ --kms-key-id key-name \ --source-custom-db-engine-version-identifer arn:aws:rds:us-west-2:123456789012:cev:custom-oracle-ee/19.my_cev1/12345678-ab12-1234-cde1-abcde123456789 \ --image-id ami-2345 ``` For Windows: ``` aws rds create-custom-db-engine-version ^ --engine custom-oracle-ee ^ --engine-version 19.my_cev2 ^ --description "Non-CDB CEV based on ami-2345" ^ --kms-key-id key-name ^ --source-custom-db-engine-version-identifer arn:aws:rds:us-west-2:123456789012:cev:custom-oracle-ee/19.my_cev1/12345678-ab12-1234-cde1-abcde123456789 ^ --image-id ami-2345 ``` To upgrade an RDS Custom DB instance, use the [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) AWS CLI command with the following parameters: + `--db-instance-identifier` – Specify the RDS Custom for Oracle DB instance to be upgraded. + `--engine-version` – Specify the CEV that has the new AMI. + `--no-apply-immediately` \$1 `--apply-immediately` – Specify whether to perform the upgrade immediately or wait until the scheduled maintenance window. The following example upgrades `my-custom-instance` to version `19.my_cev2`. Only the OS is upgraded. **Example** For Linux, macOS, or Unix: ``` aws rds modify-db-instance \ --db-instance-identifier my-custom-instance \ --engine-version 19.my_cev2 \ --apply-immediately ``` For Windows: ``` aws rds modify-db-instance ^ --db-instance-identifier my-custom-instance ^ --engine-version 19.my_cev2 ^ --apply-immediately ``` ### Upgrading the database In this example, you want to apply Oracle patch p35042068 to your RDS for Oracle DB instance. Because you upgraded your OS in [Upgrading the OS](#custom-upgrading-modify.CLI.os), your DB instance is currently using `19.my_cev2`, which is based on `ami-2345`. You create a new CEV named `19.my_cev3` that also uses `ami-2345`, but you specify a new JSON manifest in the `$MANIFEST` environment variable. Thus, only the database binaries different in your new CEV and the CEV that your instance is currently using. **Example** For Linux, macOS, or Unix: ``` aws rds create-custom-db-engine-version \ --engine custom-oracle-ee \ --engine-version 19.my_cev3 \ --description "Non-CDB CEV with p35042068 based on ami-2345" \ --kms-key-id key-name \ --image-id ami-2345 \ --manifest $MANIFEST ``` For Windows: ``` aws rds create-custom-db-engine-version ^ --engine custom-oracle-ee ^ --engine-version 19.my_cev3 ^ --description "Non-CDB CEV with p35042068 based on ami-2345" ^ --kms-key-id key-name ^ --image-id ami-2345 ^ --manifest $MANIFEST ``` The following example upgrades `my-custom-instance` to engine version `19.my_cev3`. Only the database is upgraded. **Example** For Linux, macOS, or Unix: ``` aws rds modify-db-instance \ --db-instance-identifier my-custom-instance \ --engine-version 19.my_cev3 \ --apply-immediately ``` For Windows: ``` aws rds modify-db-instance ^ --db-instance-identifier my-custom-instance ^ --engine-version 19.my_cev3 ^ --apply-immediately ``` # Viewing pending database upgrades for RDS Custom DB instances **Note** End of support notice: On March 31, 2027, AWS will end support for Amazon RDS Custom for Oracle. After March 31, 2027, you will no longer be able to access the RDS Custom for Oracle console or RDS Custom for Oracle resources. For more information, see [RDS Custom for Oracle end of support](RDS-Custom-for-Oracle-end-of-support.md). You can see pending database upgrades for your Amazon RDS Custom DB instances by using the [describe-db-instances](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) or [describe-pending-maintenance-actions](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-pending-maintenance-actions.html) AWS CLI command. However, this approach doesn't work if you used the `--apply-immediately` option or if the upgrade is in progress. The following `describe-db-instances` command shows pending database upgrades for `my-custom-instance`. ``` aws rds describe-db-instances --db-instance-identifier my-custom-instance ``` The output resembles the following. ``` { "DBInstances": [ { "DBInstanceIdentifier": "my-custom-instance", "EngineVersion": "19.my_cev1", ... "PendingModifiedValues": { "EngineVersion": "19.my_cev3" ... } } ] } ``` # Troubleshooting an upgrade failure for an RDS Custom for Oracle DB instance **Note** End of support notice: On March 31, 2027, AWS will end support for Amazon RDS Custom for Oracle. After March 31, 2027, you will no longer be able to access the RDS Custom for Oracle console or RDS Custom for Oracle resources. For more information, see [RDS Custom for Oracle end of support](RDS-Custom-for-Oracle-end-of-support.md). If an RDS Custom DB instance upgrade fails, an RDS event is generated and the DB instance status becomes `upgrade-failed`. You can see this status by using the [describe-db-instances](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) AWS CLI command, as shown in the following example. ``` aws rds describe-db-instances --db-instance-identifier my-custom-instance ``` The output resembles the following. ``` { "DBInstances": [ { "DBInstanceIdentifier": "my-custom-instance", "EngineVersion": "19.my_cev1", ... "PendingModifiedValues": { "EngineVersion": "19.my_cev3" ... } "DBInstanceStatus": "upgrade-failed" } ] } ``` After an upgrade failure, all database actions are blocked except for modifying the DB instance to perform the following tasks: + Retrying the same upgrade + Pausing and resuming RDS Custom automation + Point-in-time recovery (PITR) + Deleting the DB instance **Note** If automation has been paused for the RDS Custom DB instance, you can't retry the upgrade until you resume automation. The same actions apply to an upgrade failure for an RDS-managed read replica as for the primary. For more information, see [Troubleshooting upgrades for RDS Custom for Oracle](custom-troubleshooting.md#custom-troubleshooting-upgrade).