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.
Topics
- Requirements for RDS Custom for Oracle upgrades
- Considerations for RDS Custom for Oracle upgrades
- Viewing valid upgrade targets for RDS Custom for Oracle DB instances
- Upgrading an RDS Custom DB instance
- Viewing pending upgrades for RDS Custom DB instances
- Troubleshooting an upgrade failure for an RDS Custom for Oracle DB instance
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.
-
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.
-
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.
Considerations for RDS Custom for Oracle upgrades
When planning an upgrade, consider the following:
-
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" patch directly to the underlying Amazon EC2 instance directly using OPATCH. A valid use case might be a patch that you want to apply immediately, but the RDS Custom team is upgrading the CEV feature, causing a delay. To apply a patch manually, perform the following steps:
-
Pause RDS Custom automation.
-
Apply your patch to the database binaries on the Amazon EC2 instance.
-
Resume RDS Custom automation.
A disadvantage of the preceding technique is that you must apply the 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.
-
-
When you upgrade your primary DB instance, RDS Custom for Oracle upgrades your read replicas automatically. You don't have to upgrade read replicas manually.
-
When you upgrade your RDS Custom for Oracle DB instance to a new CEV, RDS Custom performs out-of-place patching that replaces the entire database volume with a new volume that uses your target database version. Thus, we strongly recommend that you don't use the
bin
volume for installations or for storing permanent data or files. -
When you upgrade a container database (CDB), 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 the patching process 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:
. If RDS Custom fails to patch the CDB root or any PDBs, the instance is put into thelist-of-PDBs
PATCH_DB_FAILED
state. -
You might want to perform a major version upgrade and a conversion of non-CDB to CDB at the same time. In this case, we recommend that you proceed as follows:
-
Create a new RDS Custom DB instance that uses the Oracle Multitenant architecture.
-
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.
-
Convert your PDB by running the
noncdb_to_pdb.sql
Oracle script. -
Validate your CDB instance.
-
Upgrade your CDB instance.
-
Viewing valid upgrade targets for RDS Custom for Oracle DB instances
You can see existing CEVs on the Custom engine versions page in the Amazon Web Services Management Console.
You can also use the describe-db-engine-versions Amazon CLI command to find valid upgrades for your DB instances, as shown in the following example. This example assumes that a DB instance was created using the 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.
{ "DBEngineVersions": [ { "Engine": "custom-oracle-ee", "EngineVersion": "19.my_cev1", ... "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 DB instance
To upgrade your RDS Custom DB instance, you modify it to use a new CEV.
Read replicas managed by RDS Custom are automatically upgraded after the primary DB instance is upgraded.
To upgrade an RDS Custom DB instance
Sign in to the Amazon Web Services Management Console and open the Amazon RDS console at https://console.amazonaws.cn/rds/
. -
In the navigation pane, choose Databases, and then choose the RDS Custom DB instance that you want to modify.
-
Choose Modify. The Modify DB instance page appears.
-
For DB engine version, choose the CEV to upgrade to, such as
19.my_cev3
. -
Choose Continue to check the summary of modifications.
Choose Apply immediately to apply the changes immediately.
-
If your changes are correct, choose Modify DB instance. Or choose Back to edit your changes or Cancel to cancel your changes.
To upgrade an RDS Custom DB instance, use the modify-db-instance Amazon CLI command with the following parameters:
-
--db-instance-identifier
– The DB instance to be upgraded -
--engine-version
– The new CEV -
--no-apply-immediately
|--apply-immediately
– Whether to perform the upgrade immediately or wait until the scheduled maintenance window
The following example upgrades my-custom-instance
to version 19.my_cev3
.
For Linux, macOS, or Unix:
aws rds modify-db-instance \ --db-instance-identifier
my-custom-instance
\ --engine-version19.my_cev3
\ --apply-immediately
For Windows:
aws rds modify-db-instance ^ --db-instance-identifier
my-custom-instance
^ --engine-version19.my_cev3
^ --apply-immediately
Viewing pending upgrades for RDS Custom DB instances
You can see pending upgrades for your Amazon RDS Custom DB instances by using the describe-db-instances or describe-pending-maintenance-actions Amazon 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 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" ... } } ] }
The following shows use of the describe-pending-maintenance-actions
command.
aws rds describe-pending-maintenance-actions
The output resembles the following.
{ "PendingMaintenanceActions": [ { "ResourceIdentifier": "arn:aws-cn:rds:
us-west-2
:123456789012
:instance:my-custom-instance", "PendingMaintenanceActionDetails": [ { "Action": "db-upgrade", "Description": "Upgrade to 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 Amazon 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.