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:

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.

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:

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:

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:

Considerations for RDS Custom for Oracle database upgrades

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

Considerations for RDS Custom for Oracle OS upgrades

When you plan an OS upgrade, consider the following:

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 Amazon Web Services Management Console.

You can also use the describe-db-engine-versions Amazon 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.

Before you begin, review Requirements for RDS Custom for Oracle upgrades and Considerations for RDS Custom for Oracle database upgrades.

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

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

aws rds modify-db-instance \
    --db-instance-identifier my-custom-instance \
    --engine-version 19.my_cev2 \
    --apply-immediately

aws rds modify-db-instance ^
    --db-instance-identifier my-custom-instance ^
    --engine-version 19.my_cev2 ^
    --apply-immediately

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

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

aws rds modify-db-instance \
    --db-instance-identifier my-custom-instance \
    --engine-version 19.my_cev3 \
    --apply-immediately

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

For more information, see Troubleshooting upgrades for RDS Custom for Oracle.