Upgrading a DB instance for Amazon RDS Custom for Oracle - Amazon Relational Database Service

Upgrading a DB instance for Amazon RDS Custom for Oracle

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.

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.

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.

  2. Apply your patch to the database binaries on the Amazon EC2 instance.

  3. 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.

  2. (Optional for database patching) Check available engine version upgrades by running describe-db-engine-versions.

  3. 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.

  4. 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

If you plan to upgrade your database, consider the following:

  • 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, 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.

    2. 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.

    3. Convert your PDB by running the noncdb_to_pdb.sql Oracle SQL script.

    4. Validate your CDB instance.

    5. Upgrade your CDB instance.

Considerations for RDS Custom for Oracle OS upgrades

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 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 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

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 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

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. If you want 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 and Considerations for RDS Custom for Oracle database upgrades.

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/.

  2. In the navigation pane, choose Databases, and then choose the RDS Custom for Oracle DB instance that you want to upgrade.

  3. Choose Modify. The Modify DB instance page appears.

  4. 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.

  5. Choose Continue to check the summary of modifications.

    Choose Apply immediately to apply the changes immediately.

  6. If your changes are correct, choose Modify DB instance. Or choose Back to edit your changes or Cancel to cancel your changes.

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 7.9 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.

Upgrading the OS

In this example, you want to upgrade ami-1234 to ami-2345, which is the latest service-provided AMI. Because this is an OS upgrade, 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.

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 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 | --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.

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, 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.

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.

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

You can see pending database upgrades for your Amazon RDS Custom DB instances by using the describe-db-instances or describe-pending-maintenance-actions 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

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 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.