";
public static void main(String[] args) throws SQLException {
final Properties properties = new Properties();
final String connectionString = String.format(
"jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=%s)(PORT=%d))(CONNECT_DATA=(SID=%s)))",
DB_SERVER_NAME, SSL_PORT, DB_SID);
properties.put("user", DB_USER);
properties.put("password", DB_PASSWORD);
properties.put("oracle.jdbc.J2EE13Compliant", "true");
properties.put("javax.net.ssl.trustStore", KEY_STORE_FILE_PATH);
properties.put("javax.net.ssl.trustStoreType", "JKS");
properties.put("javax.net.ssl.trustStorePassword", KEY_STORE_PASS);
final Connection connection = DriverManager.getConnection(connectionString, properties);
// If no exception, that means handshake has passed, and an SSL connection can be opened
}
}
```
**Important**
After you have determined that your database connections use SSL/TLS and have updated your application trust store, you can update your database to use the rds-ca-rsa2048-g1 certificates. For instructions, see step 3 in [Updating your CA certificate by modifying your DB instance or cluster](UsingWithRDS.SSL-certificate-rotation.md#UsingWithRDS.SSL-certificate-rotation-updating).
# Using native network encryption with an RDS for Oracle DB instance
Oracle Database offers two ways to encrypt data over the network: native network encryption (NNE) and Transport Layer Security (TLS). NNE is a proprietary Oracle security feature, whereas TLS is an industry standard. RDS for Oracle supports NNE for all editions of Oracle Database.
NNE has the following advantages over TLS:
+ You can control NNE on the client and server using settings in the NNE option:
+ `SQLNET.ALLOW_WEAK_CRYPTO_CLIENTS` and `SQLNET.ALLOW_WEAK_CRYPTO`
+ `SQLNET.CRYPTO_CHECKSUM_CLIENT` and `SQLNET.CRYPTO_CHECKSUM_SERVER`
+ `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT` and `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER`
+ `SQLNET.ENCRYPTION_CLIENT` and `SQLNET.ENCRYPTION_SERVER`
+ `SQLNET.ENCRYPTION_TYPES_CLIENT` and `SQLNET.ENCRYPTION_TYPES_SERVER`
+ In most cases, you don't need to configure your client or server. In contrast, TLS requires you to configure both client and server.
+ No certificates are required. In TLS, the server requires a certificate (which eventually expires), and the client requires a trusted root certificate for the certificate authority that issued the server’s certificate.
To enable NNE encryption for an Oracle DB instance, add the Oracle NNE option to the option group associated with the DB instance. For more information, see [Oracle native network encryption](Appendix.Oracle.Options.NetworkEncryption.md).
**Note**
You can't use both NNE and TLS on the same DB instance.
# Configuring Kerberos authentication for Amazon RDS for Oracle
You can use Kerberos authentication to authenticate users when they connect to your Amazon RDS for Oracle DB instance. In this configuration, your DB instance works with AWS Directory Service for Microsoft Active Directory, also called AWS Managed Microsoft AD. When users authenticate with an RDS for Oracle DB instance joined to the trusting domain, authentication requests are forwarded to the directory that you create with Directory Service.
Keeping all of your credentials in the same directory can save you time and effort. You have a centralized place for storing and managing credentials for multiple database instances. A directory can also improve your overall security profile.
# Region and version availability
Feature availability and support varies across specific versions of each database engine, and across AWS Regions. For more information on version and Region availability of RDS for Oracle with Kerberos authentication, see [Supported Regions and DB engines for Kerberos authentication in Amazon RDS](Concepts.RDS_Fea_Regions_DB-eng.Feature.KerberosAuthentication.md).
**Note**
Kerberos authentication isn't supported for DB instance classes that are deprecated for RDS for Oracle DB instances. For more information, see [RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md).
**Topics**
+ [
# Region and version availability
](oracle-kerberos-setting-up.RegionVersionAvailability.md)
+ [
# Setting up Kerberos for Oracle DB instances
](oracle-kerberos-setting-up.md)
+ [
# Managing a DB instance in a domain
](oracle-kerberos-managing.md)
+ [
# Connecting to Oracle with Kerberos authentication
](oracle-kerberos-connecting.md)
# Setting up Kerberos for Oracle DB instances
Use AWS Directory Service for Microsoft Active Directory, also called AWS Managed Microsoft AD, to set up Kerberos authentication for an Oracle DB instance. To set up Kerberos authentication, complete the following steps:
+ [Step 1: Create a directory using the AWS Managed Microsoft AD](#oracle-kerberos.setting-up.create-directory)
+ [Step 2: Create a trust](#oracle-kerberos.setting-up.create-forest-trust)
+ [Step 3: Configure IAM permissions for Amazon RDS](#oracle-kerberos.setting-up.CreateIAMRole)
+ [Step 4: Create and configure users](#oracle-kerberos.setting-up.create-users)
+ [Step 5: Enable cross-VPC traffic between the directory and the DB instance](#oracle-kerberos.setting-up.vpc-peering)
+ [Step 6: Create or modify an Oracle DB instance](#oracle-kerberos.setting-up.create-modify)
+ [Step 7: Create Kerberos authentication Oracle logins](#oracle-kerberos.setting-up.create-logins)
+ [Step 8: Configure an Oracle client](#oracle-kerberos.setting-up.configure-oracle-client)
**Note**
During the setup, RDS creates an Oracle database user named *managed\$1service\$1user*@*example.com* with the `CREATE SESSION` privilege, where *example.com* is your domain name. This user corresponds to the user that Directory Service creates inside your Managed Active Directory. Periodically, RDS uses the credentials provided by the Directory Service to log in to your Oracle database. Afterwards, RDS immediately destroys the ticket cache.
## Step 1: Create a directory using the AWS Managed Microsoft AD
Directory Service creates a fully managed Active Directory in the AWS Cloud. When you create an AWS Managed Microsoft AD directory, Directory Service creates two domain controllers and Domain Name System (DNS) servers on your behalf. The directory servers are created in different subnets in a VPC. This redundancy helps make sure that your directory remains accessible even if a failure occurs.
When you create an AWS Managed Microsoft AD directory, Directory Service performs the following tasks on your behalf:
+ Sets up an Active Directory within the VPC.
+ Creates a directory administrator account with the user name Admin and the specified password. You use this account to manage your directory.
**Note**
Be sure to save this password. Directory Service doesn't store it. You can reset it, but you can't retrieve it.
+ Creates a security group for the directory controllers.
When you launch an AWS Managed Microsoft AD, AWS creates an Organizational Unit (OU) that contains all of your directory's objects. This OU has the NetBIOS name that you typed when you created your directory and is located in the domain root. The domain root is owned and managed by AWS.
The Admin account that was created with your AWS Managed Microsoft AD directory has permissions for the most common administrative activities for your OU:
+ Create, update, or delete users
+ Add resources to your domain such as file or print servers, and then assign permissions for those resources to users in your OU
+ Create additional OUs and containers
+ Delegate authority
+ Restore deleted objects from the Active Directory Recycle Bin
+ Run AD and DNS Windows PowerShell modules on the Active Directory Web Service
The Admin account also has rights to perform the following domain-wide activities:
+ Manage DNS configurations (add, remove, or update records, zones, and forwarders)
+ View DNS event logs
+ View security event logs
To create the directory, use the AWS Management Console, the AWS CLI, or the Directory Service API. Make sure to open the relevant outbound ports on the directory security group so that the directory can communicate with the Oracle DB instance.
**To create a directory with AWS Managed Microsoft AD**
1. Sign in to the AWS Management Console and open the Directory Service console at [https://console.aws.amazon.com/directoryservicev2/](https://console.aws.amazon.com/directoryservicev2/).
1. In the navigation pane, choose **Directories** and choose **Set up Directory**.
1. Choose **AWS Managed Microsoft AD**. AWS Managed Microsoft AD is the only option that you can currently use with Amazon RDS.
1. Enter the following information:
**Directory DNS name**
The fully qualified name for the directory, such as **corp.example.com**.
**Directory NetBIOS name**
The short name for the directory, such as **CORP**.
**Directory description**
(Optional) A description for the directory.
**Admin password**
The password for the directory administrator. The directory creation process creates an administrator account with the user name Admin and this password.
The directory administrator password and can't include the word "admin." The password is case-sensitive and must be 8–64 characters in length. It must also contain at least one character from three of the following four categories:
+ Lowercase letters (a–z)
+ Uppercase letters (A–Z)
+ Numbers (0–9)
+ Non-alphanumeric characters (\$1\$1@\$1\$1%^&\$1\$1-\$1=`\$1\$1()\$1\$1[]:;"'<>,.?/)
**Confirm password**
The administrator password retyped.
1. Choose **Next**.
1. Enter the following information in the **Networking** section and then choose **Next**:
**VPC**
The VPC for the directory. Create the Oracle DB instance in this same VPC.
**Subnets**
Subnets for the directory servers. The two subnets must be in different Availability Zones.
1. Review the directory information and make any necessary changes. When the information is correct, choose **Create directory**.
![\[Directory details page during creation\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/WinAuth2.png)
It takes several minutes for the directory to be created. When it has been successfully created, the **Status** value changes to **Active**.
To see information about your directory, choose the directory name in the directory listing. Note the **Directory ID** value because you need this value when you create or modify your Oracle DB instance.
![\[Directory details page\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/WinAuth3.png)
## Step 2: Create a trust
If you plan to use AWS Managed Microsoft AD only, move on to [Step 3: Configure IAM permissions for Amazon RDS](#oracle-kerberos.setting-up.CreateIAMRole).
To enable Kerberos authentication using your self-managed Active Directory, you must create a forest trust relationship between your self-managed Active Directory and the AWS Managed Microsoft AD created in the previous step. The trust can be one-way, where the AWS Managed Microsoft AD trusts the self-managed Active Directory. The trust can also be two-way, where both Active Directories trust each other. For more information about setting up forest trusts using Directory Service, see [When to create a trust relationship](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_setup_trust.html) in the *Directory Service Administration Guide*.
## Step 3: Configure IAM permissions for Amazon RDS
To call Directory Service for you, Amazon RDS requires an IAM role that uses the managed IAM policy `AmazonRDSDirectoryServiceAccess`. This role allows Amazon RDS to make calls to the Directory Service.
**Note**
For the role to allow access, the AWS Security Token Service (AWS STS) endpoint must be activated in the correct AWS Region for your AWS account. AWS STS endpoints are active by default in all AWS Regions, and you can use them without any further actions. For more information, see [Activating and deactivating AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate) in the *IAM User Guide*.
### Creating an IAM role
When you create a DB instance using the AWS Management Console, and the console user has the `iam:CreateRole` permission, the console creates `rds-directoryservice-kerberos-access-role` automatically. Otherwise, you must create the IAM role manually. When you create an IAM role manually, choose `Directory Service`, and attach the AWS managed policy `AmazonRDSDirectoryServiceAccess` to it.
For more information about creating IAM roles for a service, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*.
**Note**
The IAM role used for Windows Authentication for RDS for Microsoft SQL Server can't be used for RDS for Oracle.
### Creating an IAM trust policy manually
Optionally, you can create resource policies with the required permissions instead of using the managed IAM policy `AmazonRDSDirectoryServiceAccess`. Specify both `directoryservice.rds.amazonaws.com` and `rds.amazonaws.com` as principals.
To limit the permissions that Amazon RDS gives another service for a specific resource, we recommend using the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context keys in resource policies. The most effective way to protect against the confused deputy problem is to use the `aws:SourceArn` global condition context key with the full ARN of an Amazon RDS resource. For more information, see [Preventing cross-service confused deputy problems](cross-service-confused-deputy-prevention.md).
The following example shows how you can use the `aws:SourceArn` and `aws:SourceAccount` global condition context keys in Amazon RDS to prevent the confused deputy problem.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"directoryservice.rds.amazonaws.com",
"rds.amazonaws.com"
]
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:rds:us-east-1:123456789012:db:mydbinstance"
},
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
------
For opt-in Regions, you must also include a service principal for that Region in the form of `directoryservice.rds.region_name.amazonaws.com`. For example, in the Africa (Cape Town) Region, use the following trust policy:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"directoryservice.rds.amazonaws.com",
"directoryservice.rds.af-south-1.amazonaws.com",
"rds.amazonaws.com"
]
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:rds:af-south-1:123456789012:db:mydbinstance"
},
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
------
The role must also have the following IAM policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"ds:DescribeDirectories",
"ds:AuthorizeApplication",
"ds:UnauthorizeApplication",
"ds:GetAuthorizedApplicationDetails"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
## Step 4: Create and configure users
You can create users with the Active Directory Users and Computers tool, which is one of the Active Directory Domain Services and Active Directory Lightweight Directory Services tools. In this case, *users* are individual people or entities that have access to your directory.
To create users in an Directory Service directory, you must be connected to a Windows-based Amazon EC2 instance that is a member of the Directory Service directory. At the same time, you must be logged in as a user that has privileges to create users. For more information about creating users in your Microsoft Active Directory, see [Manage users and groups in AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_manage_users_groups.html) in the *Directory Service Administration Guide*.
## Step 5: Enable cross-VPC traffic between the directory and the DB instance
If you plan to locate the directory and the DB instance in the same VPC, skip this step and move on to [Step 6: Create or modify an Oracle DB instance](#oracle-kerberos.setting-up.create-modify).
If you plan to locate the directory and the DB instance in different AWS accounts or VPCs, configure cross-VPC traffic using VPC peering or [AWS Transit Gateway](https://docs.aws.amazon.com/vpc/latest/tgw/what-is-transit-gateway.html). The following procedure enables traffic between VPCs using VPC peering. Follow the instructions in [What is VPC peering?](https://docs.aws.amazon.com/vpc/latest/peering/Welcome.html) in the *Amazon Virtual Private Cloud Peering Guide*.
**To enable cross-VPC traffic using VPC peering**
1. Set up appropriate VPC routing rules to ensure that network traffic can flow both ways.
1. Ensure that the DB instance's security group can receive inbound traffic from the directory's security group. For more information, see [ Best practices for AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_best_practices.html) in the *Directory Service Administration Guide*.
1. Ensure that there is no network access control list (ACL) rule to block traffic.
If a different AWS account owns the directory, you must share the directory.
**To share the directory between AWS accounts**
1. Start sharing the directory with the AWS account that the DB instance will be created in by following the instructions in [Tutorial: Sharing your AWS Managed Microsoft AD directory for seamless EC2 Domain-join](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_tutorial_directory_sharing.html) in the *Directory Service Administration Guide*.
1. Sign in to the Directory Service console using the account for the DB instance, and ensure that the domain has the `SHARED` status before proceeding.
1. While signed into the Directory Service console using the account for the DB instance, note the **Directory ID** value. You use this directory ID to join the DB instance to the domain.
## Step 6: Create or modify an Oracle DB instance
Create or modify an Oracle DB instance for use with your directory. You can use the console, CLI, or RDS API to associate a DB instance with a directory. You can do this in one of the following ways:
+ Create a new Oracle DB instance using the console, the [ create-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html) CLI command, or the [CreateDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html) RDS API operation.
For instructions, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ Modify an existing Oracle DB instance using the console, the [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) CLI command, or the [ModifyDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html) RDS API operation.
For instructions, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
+ Restore an Oracle DB instance from a DB snapshot using the console, the [ restore-db-instance-from-db-snapshot](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-instance-from-db-snapshot.html) CLI command, or the [ RestoreDBInstanceFromDBSnapshot](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceFromDBSnapshot.html) RDS API operation.
For instructions, see [Restoring to a DB instance](USER_RestoreFromSnapshot.md).
+ Restore an Oracle DB instance to a point-in-time using the console, the [ restore-db-instance-to-point-in-time](https://docs.aws.amazon.com/cli/latest/reference/rds/restore-db-instance-to-point-in-time.html) CLI command, or the [ RestoreDBInstanceToPointInTime](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RestoreDBInstanceToPointInTime.html) RDS API operation.
For instructions, see [Restoring a DB instance to a specified time for Amazon RDS](USER_PIT.md).
Kerberos authentication is only supported for Oracle DB instances in a VPC. The DB instance can be in the same VPC as the directory, or in a different VPC. When you create or modify the DB instance, do the following:
+ Provide the domain identifier (`d-*` identifier) that was generated when you created your directory.
+ Provide the name of the IAM role that you created.
+ Ensure that the DB instance security group can receive inbound traffic from the directory security group and send outbound traffic to the directory.
When you use the console to create a DB instance, choose **Password and Kerberos authentication** in the **Database authentication** section. Choose **Browse Directory** and then select the directory, or choose **Create a new directory**.
![\[Kerberos authentication setting when creating a DB instance\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/kerberos-authentication.png)
When you use the console to modify or restore a DB instance, choose the directory in the **Kerberos authentication** section, or choose **Create a new directory**.
![\[Kerberos authentication setting when modifying or restoring a DB instance\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/kerberos-auth-modify-restore.png)
When you use the AWS CLI, the following parameters are required for the DB instance to be able to use the directory that you created:
+ For the `--domain` parameter, use the domain identifier ("d-\$1" identifier) generated when you created the directory.
+ For the `--domain-iam-role-name` parameter, use the role you created that uses the managed IAM policy `AmazonRDSDirectoryServiceAccess`.
For example, the following CLI command modifies a DB instance to use a directory.
For Linux, macOS, or Unix:
```
aws rds modify-db-instance \
--db-instance-identifier mydbinstance \
--domain d-ID \
--domain-iam-role-name role-name
```
For Windows:
```
aws rds modify-db-instance ^
--db-instance-identifier mydbinstance ^
--domain d-ID ^
--domain-iam-role-name role-name
```
**Important**
If you modify a DB instance to enable Kerberos authentication, reboot the DB instance after making the change.
**Note**
*MANAGED\$1SERVICE\$1USER* is a service account whose name is randomly generated by Directory Service for RDS. During the Kerberos authentication setup, RDS for Oracle creates a user with the same name and assigns it the `CREATE SESSION` privilege. The Oracle DB user is identified externally as *MANAGED\$1SERVICE\$1USER@EXAMPLE.COM*, where *EXAMPLE.COM* is the name of your domain. Periodically, RDS uses the credentials provided by the Directory Service to log in to your Oracle database. Afterward, RDS immediately destroys the ticket cache.
## Step 7: Create Kerberos authentication Oracle logins
Use the Amazon RDS master user credentials to connect to the Oracle DB instance as you do any other DB instance. The DB instance is joined to the AWS Managed Microsoft AD domain. Thus, you can provision Oracle logins and users from the Microsoft Active Directory users in your domain. To manage database permissions, you grant and revoke standard Oracle permissions to these logins.
**To allow a Microsoft Active Directory user to authenticate with Oracle**
1. Connect to the Oracle DB instance using your Amazon RDS master user credentials.
1. Create an externally authenticated user in Oracle database.
In the following example, replace `KRBUSER@CORP.EXAMPLE.COM` with the user name and domain name.
```
CREATE USER "KRBUSER@CORP.EXAMPLE.COM" IDENTIFIED EXTERNALLY;
GRANT CREATE SESSION TO "KRBUSER@CORP.EXAMPLE.COM";
```
Users (both humans and applications) from your domain can now connect to the Oracle DB instance from a domain joined client machine using Kerberos authentication.
## Step 8: Configure an Oracle client
To configure an Oracle client, meet the following requirements:
+ Create a configuration file named krb5.conf (Linux) or krb5.ini (Windows) to point to the domain. Configure the Oracle client to use this configuration file.
+ Verify that traffic can flow between the client host and Directory Service over DNS port 53 over TCP/UDP, Kerberos ports (88 and 464 for managed Directory Service) over TCP, and LDAP port 389 over TCP.
+ Verify that traffic can flow between the client host and the DB instance over the database port.
Following is sample content for AWS Managed Microsoft AD.
```
[libdefaults]
default_realm = EXAMPLE.COM
[realms]
EXAMPLE.COM = {
kdc = example.com
admin_server = example.com
}
[domain_realm]
.example.com = CORP.EXAMPLE.COM
example.com = CORP.EXAMPLE.COM
```
Following is sample content for on-premise Microsoft AD. In your krb5.conf or krb5.ini file, replace *on-prem-ad-server-name* with the name of your on-premises AD server.
```
[libdefaults]
default_realm = ONPREM.COM
[realms]
AWSAD.COM = {
kdc = awsad.com
admin_server = awsad.com
}
ONPREM.COM = {
kdc = on-prem-ad-server-name
admin_server = on-prem-ad-server-name
}
[domain_realm]
.awsad.com = AWSAD.COM
awsad.com= AWSAD.COM
.onprem.com = ONPREM.COM
onprem.com= ONPREM.COM
```
**Note**
After you configure your krb5.ini or krb5.conf file, we recommend that you reboot the server.
The following is sample sqlnet.ora content for a SQL\$1Plus configuration:
```
SQLNET.AUTHENTICATION_SERVICES=(KERBEROS5PRE,KERBEROS5)
SQLNET.KERBEROS5_CONF=path_to_krb5.conf_file
```
For an example of a SQL Developer configuration, see [Document 1609359.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=1609359.1) from Oracle Support.
# Managing a DB instance in a domain
You can use the console, the CLI, or the RDS API to manage your DB instance and its relationship with your Microsoft Active Directory. For example, you can associate a Microsoft Active Directory to enable Kerberos authentication. You can also disassociate a Microsoft Active Directory to disable Kerberos authentication. You can also move a DB instance to be externally authenticated by one Microsoft Active Directory to another.
For example, using the CLI, you can do the following:
+ To reattempt enabling Kerberos authentication for a failed membership, use the [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) CLI command and specify the current membership's directory ID for the `--domain` option.
+ To disable Kerberos authentication on a DB instance, use the [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) CLI command and specify `none` for the `--domain` option.
+ To move a DB instance from one domain to another, use the [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) CLI command and specify the domain identifier of the new domain for the `--domain` option.
## Viewing the status of domain membership
After you create or modify your DB instance, the DB instance becomes a member of the domain. You can view the status of the domain membership for the DB instance in the console or by running the [describe-db-instances](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) CLI command. The status of the DB instance can be one of the following:
+ `kerberos-enabled` – The DB instance has Kerberos authentication enabled.
+ `enabling-kerberos` – AWS is in the process of enabling Kerberos authentication on this DB instance.
+ `pending-enable-kerberos` – Enabling Kerberos authentication is pending on this DB instance.
+ `pending-maintenance-enable-kerberos` – AWS will attempt to enable Kerberos authentication on the DB instance during the next scheduled maintenance window.
+ `pending-disable-kerberos` – Disabling Kerberos authentication is pending on this DB instance.
+ `pending-maintenance-disable-kerberos` – AWS will attempt to disable Kerberos authentication on the DB instance during the next scheduled maintenance window.
+ `enable-kerberos-failed` – A configuration problem has prevented AWS from enabling Kerberos authentication on the DB instance. Correct the configuration problem before reissuing the command to modify the DB instance.
+ `disabling-kerberos` – AWS is in the process of disabling Kerberos authentication on this DB instance.
A request to enable Kerberos authentication can fail because of a network connectivity issue or an incorrect IAM role. If the attempt to enable Kerberos authentication fails when you create or modify a DB instance, make sure that you're using the correct IAM role. Then modify the DB instance to join the domain.
**Note**
Only Kerberos authentication with Amazon RDS for Oracle sends traffic to the domain's DNS servers. All other DNS requests are treated as outbound network access on your DB instances running Oracle. For more information about outbound network access with Amazon RDS for Oracle, see [Setting up a custom DNS server](Appendix.Oracle.CommonDBATasks.System.md#Appendix.Oracle.CommonDBATasks.CustomDNS).
## Force-rotating Kerberos keys
A secret key is shared between AWS Managed Microsoft AD and Amazon RDS for Oracle DB instance. This key is rotated automatically every 45 days. You can use the following Amazon RDS procedure to force the rotation of this key.
```
SELECT rdsadmin.rdsadmin_kerberos_auth_tasks.rotate_kerberos_keytab AS TASK_ID FROM DUAL;
```
**Note**
In a read replica configuration, this procedure is available only on the source DB instance and not on the read replica.
The `SELECT` statement returns the ID of the task in a `VARCHAR2` data type. You can view the status of an ongoing task in a bdump file. The bdump files are located in the `/rdsdbdata/log/trace` directory. Each bdump file name is in the following format.
```
dbtask-task-id.log
```
You can view the result by displaying the task's output file.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Replace *`task-id`* with the task ID returned by the procedure.
**Note**
Tasks are executed asynchronously.
# Connecting to Oracle with Kerberos authentication
This section assumes that you have set up your Oracle client as described in [Step 8: Configure an Oracle client](oracle-kerberos-setting-up.md#oracle-kerberos.setting-up.configure-oracle-client). To connect to the Oracle DB with Kerberos authentication, log in using the Kerberos authentication type. For example, after launching Oracle SQL Developer, choose **Kerberos Authentication** as the authentication type, as shown in the following example.
![\[Shows the New/Select Database Connection dialog box in Oracle SQL Developer. The Kerberos Authentication checkbox is selected.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/ora-kerberos-auth.png)
To connect to Oracle with Kerberos authentication with SQL\$1Plus:
1. At a command prompt, run the following command:
```
kinit username
```
Replace *`username`* with the user name and, at the prompt, enter the password stored in the Microsoft Active Directory for the user.
1. Open SQL\$1Plus and connect using the DNS name and port number for the Oracle DB instance.
For more information about connecting to an Oracle DB instance in SQL\$1Plus, see [Connecting to your DB instance using SQL\$1Plus](USER_ConnectToOracleInstance.SQLPlus.md).
**Tip**
If you are using a native Windows cache, you can also set the `SQLNET.KERBEROS5_CC_NAME` parameter to `OSMSFT://` or `MSLSA` in the sqlnet.ora file to use the credentials stored in the Microsoft Active Directory.
# Configuring UTL\$1HTTP access using certificates and an Oracle wallet
Amazon RDS supports outbound network access on your RDS for Oracle DB instances. To connect your DB instance to the network, you can use the following PL/SQL packages:
`UTL_HTTP`
This package makes HTTP calls from SQL and PL/SQL. You can use it to access data on the Internet over HTTP. For more information, see [UTL\$1HTTP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_HTTP.html#GUID-A85D2D1F-90FC-45F1-967F-34368A23C9BB) in the Oracle documentation.
`UTL_TCP`
This package provides TCP/IP client-side access functionality in PL/SQL. This package is useful to PL/SQL applications that use Internet protocols and email. For more information, see [UTL\$1TCP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_TCP.html#GUID-348AFFE8-78B2-4217-AE73-384F46A1D292) in the Oracle documentation.
`UTL_SMTP`
This package provides interfaces to the SMTP commands that enable a client to dispatch emails to an SMTP server. For more information, see [UTL\$1SMTP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_SMTP.html#GUID-F0065C52-D618-4F8A-A361-7B742D44C520) in the Oracle documentation.
By completing the following tasks, you can configure `UTL_HTTP.REQUEST` to work with websites that require client authentication certificates during the SSL handshake. You can also configure password authentication for `UTL_HTTP` access to websites by modifying the Oracle wallet generation commands and the `DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACE` procedure. For more information, see [ DBMS\$1NETWORK\$1ACL\$1ADMIN](https://docs.oracle.com/en/database/oracle/oracle-database/21/arpls/DBMS_NETWORK_ACL_ADMIN.html) in the Oracle Database documentation.
**Note**
You can adapt the following tasks for `UTL_SMTP`, which enables you to send emails over SSL/TLS (including [Amazon Simple Email Service](https://aws.amazon.com/ses/)).
**Topics**
+ [
## Considerations when configuring UTL\$1HTTP access
](#utl_http-considerations)
+ [
## Step 1: Get the root certificate for a website
](#website-root-certificate)
+ [
## Step 2: Create an Oracle wallet
](#create-oracle-wallet)
+ [
## Step 3: Download your Oracle wallet to your RDS for Oracle instance
](#upload-wallet-to-instance)
+ [
## Step 4: Grant user permissions for the Oracle wallet
](#config-oracle-wallet-user)
+ [
## Step 5: Configure access to a website from your DB instance
](#config-website-access)
+ [
## Step 6: Test connections from your DB instance to a website
](#test_utl_http)
## Considerations when configuring UTL\$1HTTP access
Before configuring access, consider the following:
+ You can use SMTP with the UTL\$1MAIL option. For more information, see [Oracle UTL\$1MAIL](Oracle.Options.UTLMAIL.md).
+ The Domain Name Server (DNS) name of the remote host can be any of the following:
+ Publicly resolvable.
+ The endpoint of an Amazon RDS DB instance.
+ Resolvable through a custom DNS server. For more information, see [Setting up a custom DNS server](Appendix.Oracle.CommonDBATasks.System.md#Appendix.Oracle.CommonDBATasks.CustomDNS).
+ The private DNS name of an Amazon EC2 instance in the same VPC or a peered VPC. In this case, make sure that the name is resolvable through a custom DNS server. Alternatively, to use the DNS provided by Amazon, you can enable the `enableDnsSupport` attribute in the VPC settings and enable DNS resolution support for the VPC peering connection. For more information, see [DNS support in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support) and [Modifying your VPC peering connection](https://docs.aws.amazon.com/vpc/latest/peering/working-with-vpc-peering.html#modify-peering-connections).
+ To connect securely to remote SSL/TLS resources, we recommend that you create and upload customized Oracle wallets. By using the Amazon S3 integration with Amazon RDS for Oracle feature, you can download a wallet from Amazon S3 into Oracle DB instances. For information about Amazon S3 integration for Oracle, see [Amazon S3 integration](oracle-s3-integration.md).
+ You can establish database links between Oracle DB instances over an SSL/TLS endpoint if the Oracle SSL option is configured for each instance. No further configuration is required. For more information, see [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md).
## Step 1: Get the root certificate for a website
For the RDS for Oracle DB instance to make secure connections to a website, add the root CA certificate. Amazon RDS uses the root certificate to sign the website certificate to the Oracle wallet.
You can get the root certificate in various ways. For example, you can do the following:
1. Use a web server to visit the website secured by the certificate.
1. Download the root certificate that was used for signing.
For AWS services, root certificates typically reside in the [Amazon trust services repository](https://www.amazontrust.com/repository/).
## Step 2: Create an Oracle wallet
Create an Oracle wallet that contains both the web server certificates and the client authentication certificates. The RDS Oracle instance uses the web server certificate to establish a secure connection to the website. The website needs the client certificate to authenticate the Oracle database user.
You might want to configure secure connections without using client certificates for authentication. In this case, you can skip the Java keystore steps in the following procedure.
**To create an Oracle wallet**
1. Place the root and client certificates in a single directory, and then change into this directory.
1. Convert the .p12 client certificate to the Java keystore.
**Note**
If you're not using client certificates for authentication, you can skip this step.
The following example converts the client certificate named *client\$1certificate.p12* to the Java keystore named *client\$1keystore.jks*. The keystore is then included in the Oracle wallet. The keystore password is *P12PASSWORD*.
```
orapki wallet pkcs12_to_jks -wallet ./client_certificate.p12 -jksKeyStoreLoc ./client_keystore.jks -jksKeyStorepwd P12PASSWORD
```
1. Create a directory for your Oracle wallet that is different from the certificate directory.
The following example creates the directory `/tmp/wallet`.
```
mkdir -p /tmp/wallet
```
1. Create an Oracle wallet in your wallet directory.
The following example sets the Oracle wallet password to *P12PASSWORD*, which is the same password used by the Java keystore in a previous step. Using the same password is convenient, but not necessary. The `-auto_login` parameter turns on the automatic login feature, so that you don’t need to specify a password every time you want to access it.
**Note**
Specify a password other than the prompt shown here as a security best practice.
```
orapki wallet create -wallet /tmp/wallet -pwd P12PASSWORD -auto_login
```
1. Add the Java keystore to your Oracle wallet.
**Note**
If you're not using client certificates for authentication, you can skip this step.
The following example adds the keystore *client\$1keystore.jks* to the Oracle wallet named */tmp/wallet*. In this example, you specify the same password for the Java keystore and the Oracle wallet.
```
orapki wallet jks_to_pkcs12 -wallet /tmp/wallet -pwd P12PASSWORD -keystore ./client_keystore.jks -jkspwd P12PASSWORD
```
1. Add the root certificate for your target website to the Oracle wallet.
The following example adds a certificate named *Root\$1CA.cer*.
```
orapki wallet add -wallet /tmp/wallet -trusted_cert -cert ./Root_CA.cer -pwd P12PASSWORD
```
1. Add any intermediate certificates.
The following example adds a certificate named *Intermediate.cer*. Repeat this step as many times as need to load all intermediate certificates.
```
orapki wallet add -wallet /tmp/wallet -trusted_cert -cert ./Intermediate.cer -pwd P12PASSWORD
```
1. Confirm that your newly created Oracle wallet has the required certificates.
```
orapki wallet display -wallet /tmp/wallet -pwd P12PASSWORD
```
## Step 3: Download your Oracle wallet to your RDS for Oracle instance
In this step, you upload your Oracle wallet to Amazon S3, and then download the wallet from Amazon S3 to your RDS for Oracle instance.
**To download your Oracle wallet to your RDS for Oracle DB instance**
1. Complete the prerequisites for Amazon S3 integration with Oracle, and add the `S3_INTEGRATION` option to your Oracle DB instance. Ensure that the IAM role for the option has access to the Amazon S3 bucket you are using.
For more information, see [Amazon S3 integration](oracle-s3-integration.md).
1. Log in to your DB instance as the master user, and then create an Oracle directory to hold the Oracle wallet.
The following example creates an Oracle directory named *WALLET\$1DIR*.
```
EXEC rdsadmin.rdsadmin_util.create_directory('WALLET_DIR');
```
For more information, see [Creating and dropping directories in the main data storage space](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.NewDirectories).
1. Upload the Oracle wallet to your Amazon S3 bucket.
You can use any supported upload technique.
1. If you're re-uploading an Oracle wallet, delete the existing wallet. Otherwise, skip to the next step.
The following example removes the existing wallet, which is named *cwallet.sso*.
```
EXEC UTL_FILE.FREMOVE ('WALLET_DIR','cwallet.sso');
```
1. Download the Oracle wallet from your Amazon S3 bucket to the Oracle DB instance.
The following example downloads the wallet named *cwallet.sso* from the Amazon S3 bucket named *my\$1s3\$1bucket* to the DB instance directory named *WALLET\$1DIR*.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'my_s3_bucket',
p_s3_prefix => 'cwallet.sso',
p_directory_name => 'WALLET_DIR')
AS TASK_ID FROM DUAL;
```
1. (Optional) Download a password-protected Oracle wallet.
Download this wallet only if you want to require a password for every use of the wallet. The following example downloads password-protected wallet *ewallet.p12*.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'my_s3_bucket',
p_s3_prefix => 'ewallet.p12',
p_directory_name => 'WALLET_DIR')
AS TASK_ID FROM DUAL;
```
1. Check the status of your DB task.
Substitute the task ID returned from the preceding steps for *dbtask-1234567890123-4567.log* in the following example.
```
SELECT TEXT FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-4567.log'));
```
1. Check the contents of the directory that you're using to store the Oracle wallet.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir(p_directory => 'WALLET_DIR'));
```
For more information, see [Listing files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ListDirectories).
## Step 4: Grant user permissions for the Oracle wallet
You can either create a new database user or configure an existing user. In either case, you must configure the user to access the Oracle wallet for secure connections and client authentication using certificates.
**To grant user permissions for the Oracle wallet**
1. Log in your RDS for Oracle DB instance as the master user.
1. If you don't want to configure an existing database user, create a new user. Otherwise, skip to the next step.
The following example creates a database user named *my-user*.
```
CREATE USER my-user IDENTIFIED BY my-user-pwd;
GRANT CONNECT TO my-user;
```
1. Grant permission to your database user on the directory containing your Oracle wallet.
The following example grants read access to user *my-user* on directory *WALLET\$1DIR*.
```
GRANT READ ON DIRECTORY WALLET_DIR TO my-user;
```
1. Grant permission to your database user to use the `UTL_HTTP` package.
The following PL/SQL program grants `UTL_HTTP` access to user *my-user*.
```
BEGIN
rdsadmin.rdsadmin_util.grant_sys_object('UTL_HTTP', UPPER('my-user'));
END;
/
```
1. Grant permission to your database user to use the `UTL_FILE` package.
The following PL/SQL program grants `UTL_FILE` access to user *my-user*.
```
BEGIN
rdsadmin.rdsadmin_util.grant_sys_object('UTL_FILE', UPPER('my-user'));
END;
/
```
## Step 5: Configure access to a website from your DB instance
In this step, you configure your Oracle database user so that it can connect to your target website using `UTL_HTTP`, your uploaded Oracle Wallet, and the client certificate. For more information, see [Configuring Access Control to an Oracle Wallet ](https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/managing-fine-grained-access-in-pl-sql-packages-and-types.html#GUID-0BCB5925-A40F-4507-95F9-5DA4A1919EBD) in the Oracle Database documentation.
**To configure access to a website from your RDS for Oracle DB instance**
1. Log in your RDS for Oracle DB instance as the master user.
1. Create a Host Access Control Entry (ACE) for your user and the target website on a secure port.
The following example configures *my-user* to access *secret.encrypted-website.com* on secure port 443.
```
BEGIN
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
host => 'secret.encrypted-website.com',
lower_port => 443,
upper_port => 443,
ace => xs$ace_type(privilege_list => xs$name_list('http'),
principal_name => 'my-user',
principal_type => xs_acl.ptype_db));
-- If the program unit results in PLS-00201, set
-- the principal_type parameter to 2 as follows:
-- principal_type => 2));
END;
/
```
**Important**
The preceding program unit can result in the following error: `PLS-00201: identifier 'XS_ACL' must be declared`. If this error is returned, replace the line that assigns a value to `principal_type` with the following line, and then rerun the program unit:
```
principal_type => 2));
```
For more information about constants in the PL/SQL package `XS_ACL`, see [https://docs.oracle.com/en/database/oracle/oracle-database/19/dbfsg/XS_ACL-package.html#GUID-A157FB28-FE23-4D30-AAEB-8224230517E7](https://docs.oracle.com/en/database/oracle/oracle-database/19/dbfsg/XS_ACL-package.html#GUID-A157FB28-FE23-4D30-AAEB-8224230517E7) in the Oracle Database documentation.
For more information, see [Configuring Access Control for External Network Services ](https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/managing-fine-grained-access-in-pl-sql-packages-and-types.html#GUID-3D5B66BC-0277-4887-9CD1-97DB44EB5213) in the Oracle Database documentation.
1. (Optional) Create an ACE for your user and target website on the standard port.
You might need to use the standard port if some web pages are served from the standard web server port (80) instead of the secure port (443).
```
BEGIN
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
host => 'secret.encrypted-website.com',
lower_port => 80,
upper_port => 80,
ace => xs$ace_type(privilege_list => xs$name_list('http'),
principal_name => 'my-user',
principal_type => xs_acl.ptype_db));
-- If the program unit results in PLS-00201, set
-- the principal_type parameter to 2 as follows:
-- principal_type => 2));
END;
/
```
1. Confirm that the access control entries exist.
```
SET LINESIZE 150
COLUMN HOST FORMAT A40
COLUMN ACL FORMAT A50
SELECT HOST, LOWER_PORT, UPPER_PORT, ACL
FROM DBA_NETWORK_ACLS
ORDER BY HOST;
```
1. Grant permission to your database user to use the `UTL_HTTP` package.
The following PL/SQL program grants `UTL_HTTP` access to user *my-user*.
```
BEGIN
rdsadmin.rdsadmin_util.grant_sys_object('UTL_HTTP', UPPER('my-user'));
END;
/
```
1. Confirm that related access control lists exist.
```
SET LINESIZE 150
COLUMN ACL FORMAT A50
COLUMN PRINCIPAL FORMAT A20
COLUMN PRIVILEGE FORMAT A10
SELECT ACL, PRINCIPAL, PRIVILEGE, IS_GRANT,
TO_CHAR(START_DATE, 'DD-MON-YYYY') AS START_DATE,
TO_CHAR(END_DATE, 'DD-MON-YYYY') AS END_DATE
FROM DBA_NETWORK_ACL_PRIVILEGES
ORDER BY ACL, PRINCIPAL, PRIVILEGE;
```
1. Grant permission to your database user to use certificates for client authentication and your Oracle wallet for connections.
**Note**
If you're not using client certificates for authentication, you can skip this step.
```
DECLARE
l_wallet_path all_directories.directory_path%type;
BEGIN
SELECT DIRECTORY_PATH
INTO l_wallet_path
FROM ALL_DIRECTORIES
WHERE UPPER(DIRECTORY_NAME)='WALLET_DIR';
DBMS_NETWORK_ACL_ADMIN.APPEND_WALLET_ACE(
wallet_path => 'file:/' || l_wallet_path,
ace => xs$ace_type(privilege_list => xs$name_list('use_client_certificates'),
principal_name => 'my-user',
principal_type => xs_acl.ptype_db));
END;
/
```
## Step 6: Test connections from your DB instance to a website
In this step, you configure your database user so that it can connect to the website using `UTL_HTTP`, your uploaded Oracle Wallet, and the client certificate.
**To configure access to a website from your RDS for Oracle DB instance**
1. Log in your RDS for Oracle DB instance as a database user with `UTL_HTTP` permissions.
1. Confirm that a connection to your target website can resolve the host address.
The following example gets the host address from *secret.encrypted-website.com*.
```
SELECT UTL_INADDR.GET_HOST_ADDRESS(host => 'secret.encrypted-website.com')
FROM DUAL;
```
1. Test a failed connection.
The following query fails because `UTL_HTTP` requires the location of the Oracle wallet with the certificates.
```
SELECT UTL_HTTP.REQUEST('secret.encrypted-website.com') FROM DUAL;
```
1. Test website access by using `UTL_HTTP.SET_WALLET` and selecting from `DUAL`.
```
DECLARE
l_wallet_path all_directories.directory_path%type;
BEGIN
SELECT DIRECTORY_PATH
INTO l_wallet_path
FROM ALL_DIRECTORIES
WHERE UPPER(DIRECTORY_NAME)='WALLET_DIR';
UTL_HTTP.SET_WALLET('file:/' || l_wallet_path);
END;
/
SELECT UTL_HTTP.REQUEST('secret.encrypted-website.com') FROM DUAL;
```
1. (Optional) Test website access by storing your query in a variable and using `EXECUTE IMMEDIATE`.
```
DECLARE
l_wallet_path all_directories.directory_path%type;
v_webpage_sql VARCHAR2(1000);
v_results VARCHAR2(32767);
BEGIN
SELECT DIRECTORY_PATH
INTO l_wallet_path
FROM ALL_DIRECTORIES
WHERE UPPER(DIRECTORY_NAME)='WALLET_DIR';
v_webpage_sql := 'SELECT UTL_HTTP.REQUEST(''secret.encrypted-website.com'', '''', ''file:/' ||l_wallet_path||''') FROM DUAL';
DBMS_OUTPUT.PUT_LINE(v_webpage_sql);
EXECUTE IMMEDIATE v_webpage_sql INTO v_results;
DBMS_OUTPUT.PUT_LINE(v_results);
END;
/
```
1. (Optional) Find the file system location of your Oracle wallet directory.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir(p_directory => 'WALLET_DIR'));
```
Use the output from the previous command to make an HTTP request. For example, if the directory is *rdsdbdata/userdirs/01*, run the following query.
```
SELECT UTL_HTTP.REQUEST('https://secret.encrypted-website.com/', '', 'file://rdsdbdata/userdirs/01')
FROM DUAL;
```
# Working with CDBs in RDS for Oracle
In the Oracle multitenant architecture, a container database (CDB) can include customer-created pluggable databases (PDBs). For more information about CDBs, see [Introduction to the Multitenant Architecture ](https://docs.oracle.com/en/database/oracle/oracle-database/19/multi/introduction-to-the-multitenant-architecture.html#GUID-267F7D12-D33F-4AC9-AA45-E9CD671B6F22) in the Oracle Database documentation.
**Topics**
+ [
# Overview of RDS for Oracle CDBs
](Oracle.Concepts.CDBs.md)
+ [
# Configuring an RDS for Oracle CDB
](oracle-cdb.configuring.md)
+ [
# Backing up and restoring a CDB
](Oracle.Concepts.single-tenant.snapshots.md)
+ [
# Converting an RDS for Oracle non-CDB to a CDB
](oracle-cdb-converting.md)
+ [
# Converting the single-tenant configuration to multi-tenant
](oracle-single-tenant-converting.md)
+ [
# Adding an RDS for Oracle tenant database to your CDB instance
](oracle-cdb-configuring.adding.pdb.md)
+ [
# Modifying an RDS for Oracle tenant database
](oracle-cdb-configuring.modifying.pdb.md)
+ [
# Deleting an RDS for Oracle tenant database from your CDB
](oracle-cdb-configuring.deleting.pdb.md)
+ [
# Viewing tenant database details
](oracle-cdb-configuring.describing.pdb.md)
+ [
# Upgrading your CDB
](Oracle.Concepts.single-tenant.upgrades.md)
# Overview of RDS for Oracle CDBs
You can create an RDS for Oracle DB instance as a container database (CDB) when you run Oracle Database 19c or higher. Starting with Oracle Database 21c, all databases are CDBs. A CDB differs from a non-CDB because it can contain pluggable databases (PDBs), which are called tenant databases in RDS for Oracle. A PDB is a portable collection of schemas and objects that appears to an application as a separate database.
You create your initial tenant database (PDB) when you create your CDB instance. In RDS for Oracle, your client application interacts with a PDB rather than the CDB. Your experience with a PDB is mostly identical to your experience with a non-CDB.
**Topics**
+ [
## Multi-tenant configuration of the CDB architecture
](#multi-tenant-configuration)
+ [
## Single-tenant configuration of the CDB architecture
](#Oracle.Concepts.single-tenant)
+ [
## Creation and conversion options for CDBs
](#oracle-cdb-creation-conversion)
+ [
## User accounts and privileges in a CDB
](#Oracle.Concepts.single-tenant.users)
+ [
## Parameter group families in a CDB
](#Oracle.Concepts.single-tenant.parameters)
+ [
## Limitations of RDS for Oracle CDBs
](#Oracle.Concepts.single-tenant-limitations)
## Multi-tenant configuration of the CDB architecture
RDS for Oracle supports the multi-tenant configuration of the Oracle multitenant architecture, also called the *CDB architecture*. In this configuration, your RDS for Oracle CDB instance can contain 1–30 tenant databases, depending on the database edition and any required option licenses. In Oracle database, a tenant database is a PDB. Your DB instance must use Oracle database release 19.0.0.0.ru-2022-01.rur-2022.r1 or higher.
**Note**
The Amazon RDS configuration is called "multi-tenant" rather than "multitenant" because it is a capability of Amazon RDS, not just the Oracle DB engine. Similarly, the RDS term "tenant" refers to any tenant in an RDS configuration, not just Oracle PDBs. In the RDS documentation, the unhyphenated term "Oracle multitenant" refers exclusively to the Oracle database CDB architecture, which is compatible with both on-premises and RDS deployments.
You can configure the following settings:
+ Tenant database name
+ Tenant database master username
+ Tenant database master password (optionally integrated with Secrets Manager)
+ Tenant database character set
+ Tenant database national character set
The tenant database character set can be different from the CDB character set. The same applies to the national character set. After you create your initial tenant database, you can create, modify, or delete tenant databases using RDS APIs. The CDB name defaults to `RDSCDB` and can't be changed. For more information, see [Settings for DB instances](USER_CreateDBInstance.Settings.md) and [Modifying an RDS for Oracle tenant database](oracle-cdb-configuring.modifying.pdb.md).
## Single-tenant configuration of the CDB architecture
RDS for Oracle supports a legacy configuration of the Oracle multitenant architecture called the single-tenant configuration. In this configuration, an RDS for Oracle CDB instance can contain only one tenant (PDB). You can't create more PDBs later.
## Creation and conversion options for CDBs
Oracle Database 21c supports only CDBs, whereas Oracle Database 19c supports both CDBs and non-CDBs. All RDS for Oracle CDB instances support both the multi-tenant and single-tenant configurations.
### Creation, conversion, and upgrade options for the Oracle database architecture
The following table shows the different architecture options for creating and upgrading RDS for Oracle databases.
| Release | Database creation options | Architecture conversion options | Major version upgrade targets |
| --- | --- | --- | --- |
| Oracle Database 21c | CDB architecture only | N/A | N/A |
| Oracle Database 19c | CDB or non-CDB architecture | Non-CDB to CDB architecture (April 2021 RU or higher) | Oracle Database 21c CDB |
As shown in the preceding table, you can't directly upgrade a non-CDB to a CDB in a new major database version. But you can convert an Oracle Database 19c non-CDB to an Oracle Database 19c CDB, and then upgrade the Oracle Database 19c CDB to an Oracle Database 21c CDB. For more information, see [Converting an RDS for Oracle non-CDB to a CDB](oracle-cdb-converting.md).
### Conversion options for CDB architecture configurations
The following table shows the different options for converting the architecture configuration of an RDS for Oracle DB instance.
| Current architecture and configuration | Conversion to the single-tenant configuration of the CDB architecture | Conversion to the multi-tenant configuration of the CDB architecture | Conversion to the non-CDB architecture |
| --- | --- | --- | --- |
| Non-CDB | Supported | Supported\$1 | N/A |
| CDB using the single-tenant configuration | N/A | Supported | Not supported |
| CDB using the multi-tenant configuration | Not supported | N/A | Not supported |
\$1 You can't convert a non-CDB to the multi-tenant configuration in a single operation. When you convert a non-CDB to a CDB, the CDB is in the single-tenant configuration. You can then convert the single-tenant to the multi-tenant configuration in a separate operation.
## User accounts and privileges in a CDB
In the Oracle multitenant architecture, all user accounts are either common users or local users. A CDB common user is a database user whose single identity and password are known in the CDB root and in every existing and future PDB. In contrast, a local user exists only in a single PDB.
The RDS master user is a local user account in the PDB, which you name when you create your DB instance. If you create new user accounts, these users will also be local users residing in the PDB. You can't use any user accounts to create new PDBs or modify the state of the existing PDB.
The `rdsadmin` user is a common user account. You can run RDS for Oracle packages that exist in this account, but you can't log in as `rdsadmin`. For more information, see [About Common Users and Local Users](https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/managing-security-for-oracle-database-users.html#GUID-BBBD9904-F2F3-442B-9AFC-8ACDD9A588D8) in the Oracle documentation.
For master users in both the multi-tenant and single-tenant configurations, you can use credentials that are self-managed or managed by AWS Secrets Manager. In the single-tenant configuration, you use instance-level CLI commands such as `create-db-instance` for managed master passwords. In the multi-tenant configuration, you use tenant database commands such as `create-tenant-database` for managed master passwords. For more information about Secrets Manager integration, see [Managing the master user password for an RDS for Oracle tenant database with Secrets Manager](rds-secrets-manager.md#rds-secrets-manager-tenant).
## Parameter group families in a CDB
CDBs have their own parameter group families and default parameter values. The CDB parameter group families are as follows:
+ oracle-ee-cdb-21
+ oracle-se2-cdb-21
+ oracle-ee-cdb-19
+ oracle-se2-cdb-19
## Limitations of RDS for Oracle CDBs
RDS for Oracle supports a subset of features available in an on-premises CDB.
### CDB limitations
The following limitations apply to RDS for Oracle at the CDB level:
+ You can’t connect to a CDB. You always connect to the tenant database (PDB) rather than the CDB. Specify the endpoint for the PDB just as for a non-CDB. The only difference is that you specify *pdb\$1name* for the database name, where *pdb\$1name* is the name you chose for your PDB.
+ You can't convert a CDB in the multi-tenant configuration to a CDB in the single-tenant conversion. Conversion to the multi-tenant configuration is one-way and irreversible.
+ You can't enable or convert to the multi-tenant configuration if your DB instance uses an Oracle database release lower than 19.0.0.0.ru-2022-01.rur-2022.r1.
+ You can't use Database Activity Streams in a CDB.
+ You can't enable auditing from within `CDB$ROOT`. You must enable auditing within each PDB individually.
### Tenant database (PDB) limitations
The following limitations apply to tenant databases in the RDS for Oracle multi-tenant configuration:
+ You can't defer tenant database operations to the maintenance window. All changes occur immediately.
+ You can't add a tenant database to a CDB that uses the single-tenant configuration.
+ You can't add or modify multiple tenant databases in a single operation. You can only add or modify them one at a time.
+ You can't modify a tenant database to be named `CDB$ROOT` or `PDB$SEED`.
+ You can't delete a tenant database if it is the only tenant in the CDB.
+ Not all DB instance class types have sufficient resources to support multiple PDBs in an RDS for Oracle CDB instance. An increased PDB count affects the performance and stability of the smaller instance classes and increases the time of most instance-level operations, for example, database upgrades.
+ You cannot rename a PDB using `rdsadmin.rdsadmin_util.rename_global_name`, You must use the `modify-tenant-database` API instead.
+ You can't use multiple AWS accounts to create PDBs in the same CDB. PDBs must be owned by the same account as the DB instance that the PDBs are hosted on.
+ All PDBs in a CDB use the same endpoint and database listener.
+ The following operations aren't supported at the PDB level but are supported at the CDB level:
+ Backup and recovery
+ Database upgrades
+ Maintenance actions
+ The following features aren't supported at the PDB level but are supported at the CDB level:
+ Option groups (options are installed on all PDBs on your CDB instance)
+ Parameter groups (all parameters are derived from the parameter group associated with your CDB instance)
+ PDB-level operations that are supported in the on-premises CDB architecture but aren't supported in an RDS for Oracle CDB include the following:
**Note**
The following list is not exhaustive.
+ Application PDBs
+ Proxy PDBs
+ Starting and stopping a PDB
+ Unplugging and plugging in PDBs
To move data into or out of your CDB, use the same techniques as for a non-CDB. For more information about migrating data, see [Importing data into Oracle on Amazon RDS](Oracle.Procedural.Importing.md).
+ Setting options at the PDB level
The PDB inherits options settings from the CDB option group. For more information about setting options, see [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md). For best practices, see [Working with DB parameter groups](CHAP_BestPractices.md#CHAP_BestPractices.DBParameterGroup).
+ Configuring parameters in a PDB
The PDB inherits parameter settings from the CDB. For more information about setting option, see [Adding options to Oracle DB instances](Appendix.Oracle.Options.md).
+ Configuring different listeners for PDBs in the same CDB
+ Oracle Flashback features
# Configuring an RDS for Oracle CDB
Configuring a CDB is similar to configuring a non-CDB.
**Topics**
+ [
## Creating an RDS for Oracle CDB instance
](#Oracle.Concepts.single-tenant.creation)
+ [
## Connecting to a PDB in your RDS for Oracle CDB
](#Oracle.Concepts.connecting.pdb)
## Creating an RDS for Oracle CDB instance
In RDS for Oracle, creating a CDB instance is almost identical to creating a non-CDB instance. The difference is that you choose the Oracle multitenant architecture when creating your DB instance and also choose an architecture configuration: multi-tenant or single-tenant. If you create tags when you create a CDB in the multi-tenant configuration, RDS propagates the tags to the initial tenant database. To create a CDB, use the AWS Management Console, the AWS CLI, or the RDS API.
### Console
**To create a CDB 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 upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to create the CDB instance.
1. In the navigation pane, choose **Databases**.
1. Choose **Create database**.
1. In **Choose a database creation method**, select **Standard Create**.
1. In **Engine options**, choose **Oracle**.
1. For **Database management type**, choose **Amazon RDS**.
1. For **Architecture settings**, choose **Oracle multitenant architecture**.
1. For **Architecture configuration**, do either of the following:
+ Choose **Multi-tenant configuration** and proceed to the next step.
+ Choose **Single-tenant configuration** and skip to Step 11.
1. (Multi-tenant configuration) For **Tenant database settings**, make the following changes:
+ For **Tenant database name**, enter the name of your initial PDB. The PDB name must be different from the CDB name, which defaults to `RDSCDB`.
+ For **Tenant database master username**, enter the master username of your PDB. You can't use the tenant database master username to log in to the CDB itself.
+ For **Credentials management**, choose either of the following credentials management options:
+ **Managed in AWS Secrets Manager**
The managed password is for the initial tenant database rather than for the instance. In **Select the encryption key**, choose either a KMS key that Secrets Manager creates or a key that you have created.
**Note**
We recommend AWS Secrets Manager as the most secure technique for managing credentials. Additional charges apply. For more information, see [Password management with Amazon RDS and AWS Secrets Manager](rds-secrets-manager.md).
+ **Self managed**
To specify a password, clear the **Auto generate a password** check box if it is selected. Enter the same password in **Master password** and **Confirm master password**.
+ For **Tenant database character set**, choose a character set for the PDB. You can choose a tenant database character set that is different from the CDB character set.
The default PDB character set is **AL32UTF8**. If you choose a nondefault PDB character set, CDB creation might be slower.
**Note**
You can't specify multiple tenant databases in the create operation. The CDB has one PDB when it is created. You can add PDBs to an existing CDB in a separate operation.
1. (Single-tenant configuration) Choose the settings that you want based on the options listed in [Settings for DB instances](USER_CreateDBInstance.Settings.md):
1. In the **Settings** section, open **Credential Settings**. Then do the following:
1. For **Master username**, enter the name for a local user in your PDB. You can't use the master username to log in to the CDB root.
1. For **Credentials management**, choose either of the following credentials management options:
+ **Managed in AWS Secrets Manager**
In **Select the encryption key**, choose either a KMS key that Secrets Manager creates or a key that you have created.
**Note**
We recommend AWS Secrets Manager as the most secure technique for managing credentials. Additional charges apply. For more information, see [Password management with Amazon RDS and AWS Secrets Manager](rds-secrets-manager.md).
+ **Self managed**
To specify a password, clear the **Auto generate a password** check box if it is selected. Enter the same password in **Master password** and **Confirm master password**.
1. For the remaining sections, specify your DB instance settings. For information about each setting, see [Settings for DB instances](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.Settings.html).
1. Choose **Create database**.
### AWS CLI
To create a CDB in the multi-tenant configuration, use the [create-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance.html) command with the following parameters:
+ `--db-instance-identifier`
+ `--db-instance-class`
+ `--engine { oracle-ee-cdb | oracle-se2-cdb }`
+ `--master-username`
+ `--master-user-password` or `--manage-master-user-password`
+ `--multi-tenant` (for the single-tenant configuration, either don't specify `multi-tenant` or specify `--no-multi-tenant`)
+ `--allocated-storage`
+ `--backup-retention-period`
For information about each setting, see [Settings for DB instances](USER_CreateDBInstance.Settings.md).
This following example creates an RDS for Oracle DB instance named *my-cdb-inst* in the multi-tenant configuration. If you specify `--no-multi-tenant` or don't specify `--multi-tenant`, the default CDB configuration is single-tenant. The engine is `oracle-ee-cdb`: a command that specifies `oracle-ee` and `--multi-tenant` fails with an error. The initial tenant database is named *mypdb*.
**Example**
For Linux, macOS, or Unix:
```
1. aws rds create-db-instance \
2. --engine oracle-ee-cdb \
3. --db-instance-identifier my-cdb-inst \
4. --multi-tenant \
5. --db-name mypdb \
6. --allocated-storage 250 \
7. --db-instance-class db.t3.large \
8. --master-username pdb_admin \
9. --manage-master-user-password \
10. --backup-retention-period 3
```
For Windows:
```
1. aws rds create-db-instance ^
2. --engine oracle-ee-cdb ^
3. --db-instance-identifier my-cdb-inst ^
4. --multi-tenant ^
5. --db-name mypdb ^
6. --allocated-storage 250 ^
7. --db-instance-class db.t3.large ^
8. --master-username pdb_admin ^
9. --manage-master-user-password \ ^
10. --backup-retention-period 3
```
Specify a password other than the prompt shown here as a security best practice.
This command produces output similar to the following. The database name, character set, national character set, master user, and master user secret aren't included in the output. You can view this information by using the CLI command `describe-tenant-databases`.
```
1. {
2. "DBInstance": {
3. "DBInstanceIdentifier": "my-cdb-inst",
4. "DBInstanceClass": "db.t3.large",
5. "MultiTenant": true,
6. "Engine": "oracle-ee-cdb",
7. "DBResourceId": "db-ABCDEFGJIJKLMNOPQRSTUVWXYZ",
8. "DBInstanceStatus": "creating",
9. "AllocatedStorage": 250,
10. "PreferredBackupWindow": "04:59-05:29",
11. "BackupRetentionPeriod": 3,
12. "DBSecurityGroups": [],
13. "VpcSecurityGroups": [
14. {
15. "VpcSecurityGroupId": "sg-0a1bcd2e",
16. "Status": "active"
17. }
18. ],
19. "DBParameterGroups": [
20. {
21. "DBParameterGroupName": "default.oracle-ee-cdb-19",
22. "ParameterApplyStatus": "in-sync"
23. }
24. ],
25. "DBSubnetGroup": {
26. "DBSubnetGroupName": "default",
27. "DBSubnetGroupDescription": "default",
28. "VpcId": "vpc-1234567a",
29. "SubnetGroupStatus": "Complete",
30. ...
```
### RDS API
To create a DB instance by using the Amazon RDS API, call the [CreateDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html) operation.
For information about each setting, see [Settings for DB instances](USER_CreateDBInstance.Settings.md).
## Connecting to a PDB in your RDS for Oracle CDB
You can use a utility like SQL\$1Plus to connect to a PDB. To download Oracle Instant Client, which includes a standalone version of SQL\$1Plus, see [ Oracle Instant Client Downloads](https://www.oracle.com/database/technologies/instant-client/downloads.html).
To connect SQL\$1Plus to your PDB, you need the following information:
+ PDB name
+ Database user name and password
+ Endpoint for your DB instance
+ Port number
For information about finding the preceding information, see [Finding the endpoint of your RDS for Oracle DB instance](USER_Endpoint.md).
**Example To connect to your PDB using SQL\$1Plus**
In the following examples, substitute your master user for *master\$1user\$1name*. Also, substitute the endpoint for your DB instance, and then include the port number and the Oracle SID. The SID value is the name of the PDB that you specified when you created your DB instance, and not the DB instance identifier.
For Linux, macOS, or Unix:
```
1. sqlplus 'master_user_name@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=endpoint)(PORT=port))(CONNECT_DATA=(SID=pdb_name)))'
```
For Windows:
```
1. sqlplus master_user_name@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=endpoint)(PORT=port))(CONNECT_DATA=(SID=pdb_name)))
```
You should see output similar to the following.
```
SQL*Plus: Release 19.0.0.0.0 Production on Mon Aug 21 09:42:20 2021
```
After you enter the password for the user, the SQL prompt appears.
```
SQL>
```
**Note**
The shorter format connection string (Easy connect or EZCONNECT), such as `sqlplus username/password@LONGER-THAN-63-CHARS-RDS-ENDPOINT-HERE:1521/database-identifier`, might encounter a maximum character limit and should not be used to connect.
# Backing up and restoring a CDB
You can back up and restore your CDB using either RDS DB snapshots or Recovery Manager (RMAN).
## Backing up and restoring a CDB using DB snapshots
DB snapshots work similarly in the CDB and non-CDB architectures. The principal differences are as follows:
+ When you restore a DB snapshot of a CDB, you can't rename the CDB. The CDB is named `RDSCDB` and can't be changed.
+ When you restore a DB snapshot of a CDB, you can't rename PDBs. You can modify the PDB name by using the [modify-tenant-database](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyTenantDatabase.html) command.
+ To find tenant databases in a snapshot, use the CLI command [describe-db-snapshot-tenant-databases](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBSnapshotTenantDatabases.html).
+ You can't directly interact with the tenant databases in a CDB snapshot that uses the multi-tenant architecture configuration. If you restore the DB snapshot, you restore all its tenant databases.
+ RDS for Oracle implicitly copies tags on a tenant database to the tenant database in a DB snapshot. When you restore a tenant database, the tags appear in the restored database.
+ If you restore a DB snapshot and specify new tags using the `--tags` parameter, the new tags overwrite all existing tags.
+ If you take a DB snapshot of a CDB instance that has tags, and you specify `--copy-tags-to-snapshot`, RDS for Oracle copies tags from the tenant databases to the tenant databases in the snapshot.
For more information, see [Oracle Database considerations](USER_RestoreFromSnapshot.md#USER_RestoreFromSnapshot.Oracle).
## Backing up and restoring a CDB using RMAN
To learn how to back up and restore a CDB or individual tenant database using RMAN, see [Performing common RMAN tasks for Oracle DB instances](Appendix.Oracle.CommonDBATasks.RMAN.md).
# Converting an RDS for Oracle non-CDB to a CDB
You can change the architecture of an Oracle database from the non-CDB architecture to the Oracle multitenant architecture, also called the *CDB architecture*, with the `modify-db-instance` command. In most cases, this technique is preferable to creating a new CDB and importing data. The conversion operation incurs downtime.
When you upgrade your database engine version, you can't change the database architecture in the same operation. Therefore, to upgrade an Oracle Database 19c non-CDB to an Oracle Database 21c CDB, you first need to convert the non-CDB to a CDB in one step, and then upgrade the 19c CDB to a 21c CDB in a separate step.
The non-CDB conversion operation has the following requirements:
+ You must specify `oracle-ee-cdb` or `oracle-se2-cdb` for the DB engine type. These are the only supported values.
+ Your DB engine must use Oracle Database 19c with an April 2021 or later release update (RU).
The operation has the following limitations:
+ You can't convert a CDB to a non-CDB. You can only convert a non-CDB to a CDB.
+ You can't convert a non-CDB to the multi-tenant configuration in a single `modify-db-instance` call. After you convert a non-CDB to a CDB, your CDB is in the single-tenant configuration. To convert the single-tenant configuration to the multi-tenant configuration, run `modify-db-instance` again. For more information, see [Converting the single-tenant configuration to multi-tenant](oracle-single-tenant-converting.md).
+ You can't convert a primary or replica database that has Oracle Data Guard enabled. To convert a non-CDB that has read replicas, first delete all read replicas.
+ You can't upgrade the DB engine version and convert a non-CDB to a CDB in the same operation.
Before converting your non-CDB, consider the following:
+ The considerations for option and parameter groups are the same as for upgrading the DB engine. For more information, see [Considerations for Oracle database upgrades](USER_UpgradeDBInstance.Oracle.OGPG.md).
+ You can convert existing non-CDB instances that uses managed master passwords to single-tenant instances in a single operation. The single-tenant instances inherit the managed passwords.
+ If your DB instance has the `OEMAGENT` option installed, a best practice is to remove this option before you convert your non-CDB. After your non-CDB is converted to a CDB, reinstall the option. For more information, see [Oracle Management Agent for Enterprise Manager Cloud Control](Oracle.Options.OEMAgent.md).
+ During the conversion process, RDS resets the online redo log size to the default 128M.
## Console
**To convert a non-CDB to a CDB**
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 upper-right corner of the Amazon RDS console, choose the AWS Region where your DB instance resides.
1. In the navigation pane, choose **Databases**, and then choose the non-CDB instance that you want to convert to a CDB instance.
1. Choose **Modify**.
1. For **Architecture settings**, select **Oracle multitenant architecture**. After conversion, your CDB will be in the single-tenant configuration.
1. (Optional) For **DB parameter group**, choose a new parameter group for your CDB instance. The same parameter group considerations apply when converting a DB instance as when upgrading a DB instance. For more information, see [Parameter group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.PG).
1. (Optional) For **Option group**, choose a new option group for your CDB instance. The same option group considerations apply when converting a DB instance as when upgrading a DB instance. For more information, see [Option group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.OG).
1. (Optional) For **Credentials management**, choose **Managed in AWS Secrets Manager** or **Self-managed**. For more information, see [Managing the master user password for a DB instance with Secrets Manager](rds-secrets-manager.md#rds-secrets-manager-db-instance).
1. When all the changes are as you want them, choose **Continue** and check the summary of modifications.
1. (Optional) Choose **Apply immediately** to apply the changes immediately. Choosing this option can cause downtime in some cases. For more information, see [Using the schedule modifications setting](USER_ModifyInstance.ApplyImmediately.md).
1. On the confirmation page, review your changes. If they are correct, choose **Modify DB instance**.
Or choose **Back** to edit your changes or **Cancel** to cancel your changes.
## AWS CLI
To convert the non-CDB on your DB instance to a CDB in the single-tenant configuration, set `--engine` to `oracle-ee-cdb` or `oracle-se2-cdb` in the AWS CLI command [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html). For more information, see [Settings for DB instances](USER_ModifyInstance.Settings.md).
The following example converts the DB instance named *my-non-cdb* and specifies a custom option group and parameter group. The command also enables password management with Secrets Manager.
**Example**
For Linux, macOS, or Unix:
```
aws rds modify-db-instance \
--db-instance-identifier my-non-cdb \
--engine oracle-ee-cdb \
--option-group-name custom-option-group \
--db-parameter-group-name custom-parameter-group \
--manage-master-user-password
```
For Windows:
```
aws rds modify-db-instance ^
--db-instance-identifier my-non-cdb ^
--engine oracle-ee-cdb ^
--option-group-name custom-option-group ^
--db-parameter-group-name custom-parameter-group ^
--manage-master-user-password
```
## RDS API
To convert a non-CDB to a CDB, specify `Engine` in the RDS API operation [ModifyDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html).
# Converting the single-tenant configuration to multi-tenant
You can modify the architecture of an RDS for Oracle CDB from the single-tenant configuration to the multi-tenant configuration. Before and after the conversion, your CDB contains a single tenant database (PDB). Tags for the DB instance propagate to the initial tenant database created during the conversion.
Before you begin, make sure that your IAM policy has permission to create a tenant database. During the conversion, RDS for Oracle migrates the following metadata to the new tenant database:
+ The master username
+ The managed master password (if the source CDB integrates with Secrets Manager)
+ The database name
+ The character set
+ The national character set
Before the conversion, you view the preceding information by using the `describe-db-instances` command. After the conversion, you view the information by using the `describe-tenant-database` command.
The conversion from single-tenant to multi-tenant has the following limitations:
+ You can't later convert back to the single-tenant configuration after you convert to the multi-tenant configuration. The conversion is irreversible.
+ You can't convert a primary or replica database that has Oracle Data Guard enabled.
+ You can't upgrade the DB engine version and convert to the multi-tenant configuration in the same operation.
+ You can't enable or disable managed master user passwords during the conversion.
## Console
**To convert a CDB using the single-tenant configuration to the multi-tenant configuration**
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 upper-right corner of the Amazon RDS console, choose the AWS Region where your DB instance resides.
1. In the navigation pane, choose **Databases**, and then choose the non-CDB instance that you want to convert to a CDB instance.
1. Choose **Modify**.
1. For **Architecture settings**, select **Oracle multitenant architecture**.
1. For **Architecture configuration**, select **Multi-tenant configuration**.
1. (Optional) For **DB parameter group**, choose a new parameter group for your CDB instance. The same parameter group considerations apply when converting a DB instance as when upgrading a DB instance.
1. (Optional) For **Option group**, choose a new option group for your CDB instance. The same option group considerations apply when converting a DB instance as when upgrading a DB instance.
1. When all the changes are as you want them, choose **Continue** and check the summary of modifications.
1. Choose **Apply immediately**. This option is required when you switch to a multi-tenant configuration. Note that this option can cause downtime in some cases.
1. On the confirmation page, review your changes. If they are correct, choose **Modify DB instance**.
Or choose **Back** to edit your changes or **Cancel** to cancel your changes.
## AWS CLI
To convert a CDB using the single-tenant configuration to the multi-tenant configuration, specify `--multi-tenant` in the AWS CLI command [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html).
The following example converts the DB instance named `my-st-cdb` from the single-tenant configuration to the multi-tenant configuration. The `--apply-immediately` option is required.
**Example**
For Linux, macOS, or Unix:
```
aws rds modify-db-instance --region us-east-1\
--db-instance-identifier my-st-cdb \
--multi-tenant \
--apply-immediately
```
For Windows:
```
aws rds modify-db-instance --region us-east-1 ^
--db-instance-identifier my-st-cdb ^
--multi-tenant ^
--apply-immediately
```
The output looks something like the following.
```
{
"DBInstance": {
"DBInstanceIdentifier": "my-st-cdb",
"DBInstanceClass": "db.r5.large",
"MultiTenant": false,
"Engine": "oracle-ee-cdb",
"DBResourceId": "db-AB1CDE2FGHIJK34LMNOPRLXTXU",
"DBInstanceStatus": "modifying",
"MasterUsername": "admin",
"DBName": "ORCL",
...
"EngineVersion": "19.0.0.0.ru-2022-01.rur-2022-01.r1",
"AutoMinorVersionUpgrade": true,
"ReadReplicaDBInstanceIdentifiers": [],
"LicenseModel": "bring-your-own-license",
"OptionGroupMemberships": [
{
"OptionGroupName": "default:oracle-ee-cdb-19",
"Status": "in-sync"
}
],
...
"PendingModifiedValues": {
"MultiTenant": "true"
}
}
}
```
# Adding an RDS for Oracle tenant database to your CDB instance
In the RDS for Oracle multi-tenant configuration, a tenant database is a PDB. To add a tenant database, make sure you meet the following prerequisites:
+ Your CDB has the multi-tenant configuration enabled. For more information, see [Multi-tenant configuration of the CDB architecture](Oracle.Concepts.CDBs.md#multi-tenant-configuration).
+ You have the necessary IAM permissions to create the tenant database.
You can add a tenant database using the AWS Management Console, the AWS CLI, or the RDS API. You can't add multiple tenant databases in a single operation: you must add them one at a time. If the CDB has backup retention enabled, Amazon RDS backs up the DB instance before and after it adds a new tenant database. If the CDB has read replicas, you can only add a tenant database to the primary DB instance; Amazon RDS automatically creates the tenant database on the replicas. Replication health is also validated, ensuring all replicas are available and replication lag is less than 5 minutes before the tenant is created.
## Console
**To add a tenant database to your 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 upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to create the tenant database.
1. In the navigation pane, choose **Databases**.
1. Choose the CDB instance to which you want to add a tenant database. Your DB instance must use the multi-tenant configuration of the CDB architecture.
1. Choose **Actions** and then **Add tenant database**.
1. For **Tenant database settings**, do the following:
+ For **Tenant database name**, enter the name of your new PDB.
+ For **Tenant database master username**, enter the name of the master user for your PDB.
+ Choose either of the following credentials management options:
+ **Managed in AWS Secrets Manager**
In **Select the encryption key**, choose either a KMS key that Secrets Manager creates or a key that you have created.
**Note**
We recommend AWS Secrets Manager as the most secure technique for managing credentials. Additional charges apply. AWS Secrets Manager is not supported for instances using read replicas. For more information, see [Password management with Amazon RDS and AWS Secrets Manager](rds-secrets-manager.md).
+ **Self managed**
To specify a password, clear the **Auto generate a password** check box if it is selected. Enter the same password in **Master password** and **Confirm master password**.
+ Under **Additional configuration**, enter the name of your PDB for **Initial database name**. You can't name the CDB, which has the default name `RDSCDB`.
+ For **Tenant database character set**, choose a character set for the PDB. The default is **AL32UTF8**. You can choose a PDB character set that is different from the CDB character set. If the instance has read replicas, tenants cannot be created with a custom character set. You can create your tenants with a custom character set before creating a read replica if needed.
+ For **Tenant database national character set**, choose a national character set for the PDB. The default is **AL32UTF8**. The national character set specifies the encoding only for columns that use the `NCHAR` data type (`NCHAR`, `NVARCHAR2`, and `NCLOB`) and doesn't affect database metadata.
For more information about the preceding settings, see [Settings for DB instances](USER_CreateDBInstance.Settings.md).
1. Choose **Add tenant**.
## AWS CLI
To add a tenant database to your CDB with the AWS CLI, use the command [create-tenant-database](https://docs.aws.amazon.com/cli/latest/reference/rds/create-tenant-database.html) with the following required parameters:
+ `--db-instance-identifier`
+ `--tenant-db-name`
+ `--master-username`
+ `--master-user-password`
This following example creates a tenant database named *mypdb2* in the RDS for Oracle CDB instance named *my-cdb-inst*. The PDB character set is `UTF-16`.
**Example**
For Linux, macOS, or Unix:
```
1. aws rds create-tenant-database --region us-east-1 \
2. --db-instance-identifier my-cdb-inst \
3. --tenant-db-name mypdb2 \
4. --master-username mypdb2-admin \
5. --master-user-password mypdb2-pwd \
6. --character-set-name UTF-16
```
For Windows:
```
1. aws rds create-tenant-database --region us-east-1 \
2. --db-instance-identifier my-cdb-inst ^
3. --tenant-db-name mypdb2 ^
4. --master-username mypdb2-admin ^
5. --master-user-password mypdb2-pwd ^
6. --character-set-name UTF-16
```
The output looks similar to the following.
```
...}
"TenantDatabase" :
{
"DbiResourceId" : "db-abc123",
"TenantDatabaseResourceId" : "tdb-bac567",
"TenantDatabaseArn" : "arn:aws:rds:us-east-1:123456789012:db:my-cdb-inst:mypdb2",
"DBInstanceIdentifier" : "my-cdb-inst",
"TenantDBName" : "mypdb2",
"Status" : "creating",
"MasterUsername" : "mypdb2",
"CharacterSetName" : "UTF-16",
...
}
}...
```
# Modifying an RDS for Oracle tenant database
You can modify only the PDB name and the master user password of a tenant database in your CDB. Note the following requirements and limitations:
+ To modify the settings of a tenant database in your DB instance, the tenant database must exist.
+ You can't modify multiple tenant databases in a single operation. You can only modify one tenant database at a time.
+ You can't change the name of a tenant database to `CDB$ROOT` or `PDB$SEED`.
+ If your DB instance has read replicas, you can only modify tenants on the primary DB instance. Replication health is also validated, ensuring the replicas are available and replication lag is less than 5 minutes before the tenant is modified.
You can modify PDBs using the AWS Management Console, the AWS CLI, or the RDS API.
## Console
**To modify the PDB name or master password of a tenant database**
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 upper-right corner of the Amazon RDS console, choose the AWS Region in which you want to create the tenant database.
1. In the navigation pane, choose **Databases**.
1. Choose the tenant database whose database name or master user password you want to modify.
1. Choose **Modify**.
1. For **Tenant database settings**, do any of the following:
+ For **Tenant database name**, enter the new name of your new PDB.
+ For **Tenant database master password**, enter a new password.
1. Choose **Modify tenant**.
## AWS CLI
To modify a tenant database using the AWS CLI, call the [modify-tenant-database](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-tenant-database.html) command with the following parameters:
+ `--db-instance-identifier` *value*
+ `--tenant-db-name value`
+ `[--new-tenant-db-name value]`
+ `[--master-user-password value]`
The following example renames tenant database `pdb1` to `pdb-hr` on DB instance `my-cdb-inst`.
**Example**
For Linux, macOS, or Unix:
```
1. aws rds modify-tenant-database --region us-east-1 \
2. --db-instance-identifier my-cdb-inst \
3. --tenant-db-name pdb1 \
4. --new-tenant-db-name pdb-hr
```
For Windows:
```
1. aws rds modify-tenant-database --region us-east-1 ^
2. --db-instance-identifier my-cdb-inst ^
3. --tenant-db-name pdb1 ^
4. --new-tenant-db-name pdb-hr
```
This command produces output similar to the following.
```
{
"TenantDatabase" : {
"DbiResourceId" : "db-abc123",
"TenantDatabaseResourceId" : "tdb-bac567",
"TenantDatabaseArn" : "arn:aws:rds:us-east-1:123456789012:db:my-cdb-inst:pdb1",
"DBInstanceIdentifier" : "my-cdb-inst",
"TenantDBName" : "pdb1",
"Status" : "modifying",
"MasterUsername" : "tenant-admin-user"
"Port" : "6555",
"CharacterSetName" : "UTF-16",
"MaxAllocatedStorage" : "1000",
"ParameterGroups": [
{
"ParameterGroupName": "pdb1-params",
"ParameterApplyStatus": "in-sync"
}
],
"OptionGroupMemberships": [
{
"OptionGroupName": "pdb1-options",
"Status": "in-sync"
}
],
"PendingModifiedValues": {
"TenantDBName": "pdb-hr"
}
}
}
```
# Deleting an RDS for Oracle tenant database from your CDB
You can delete a tenant database (PDB) using the AWS Management Console, the AWS CLI, or the RDS API. Consider the following prerequisites and limitations:
+ The tenant database and DB instance must exist.
+ For the deletion to succeed, one of the following situations must exist:
+ The tenant database and DB instance are available.
**Note**
You can take a final snapshot, but only if the tenant database and DB instance were in an available state before you issued the `delete-tenant-database` command. This snapshot will only be taken on the primary instance if the DB instance has read replicas.
+ The tenant database is being created.
+ The DB instance is modifying the tenant database.
+ If the DB instance has read replicas these constraints apply to all replicas.
+ You can't delete multiple tenant databases in a single operation.
+ You can't delete a tenant database if it is the only tenant in the CDB.
+ You can't delete a tenant database on a read replica, you can only delete a tenant on the primary DB instance. Replication health is also validated, ensuring the replication lag is less than 5 minutes before the tenant is deleted.
## Console
**To delete a tenant database**
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 tenant database that you want to delete.
1. For **Actions**, choose **Delete**.
1. To create a final DB snapshot for the DB instance, choose **Create final snapshot?**.
1. If you chose to create a final snapshot, enter the **Final snapshot name**.
1. Enter **delete me** in the box.
1. Choose **Delete**.
## AWS CLI
To delete a tenant database using the AWS CLI, call the [delete-tenant-database](https://docs.aws.amazon.com/cli/latest/reference/rds/delete-tenant-database.html) command with the following parameters:
+ `--db-instance-identifier value`
+ `--tenant-db-name value`
+ `[--skip-final-snapshot | --no-skip-final-snapshot]`
+ `[--final-snapshot-identifier value]`
This following example deletes the tenant database named *pdb-test* from the CDB named *my-cdb-inst*. By default, the operation creates a final snapshot.
**Example**
For Linux, macOS, or Unix:
```
1. aws rds delete-tenant-database --region us-east-1 \
2. --db-instance-identifier my-cdb-inst \
3. --tenant-db-name pdb-test \
4. --final-snapshot-identifier final-snap-pdb-test
```
For Windows:
```
1. aws rds delete-tenant-database --region us-east-1 ^
2. --db-instance-identifier my-cdb-inst ^
3. --tenant-db-name pdb-test ^
4. --final-snapshot-identifier final-snap-pdb-test
```
This command produces output similar to the following.
```
{
"TenantDatabase" : {
"DbiResourceId" : "db-abc123",
"TenantDatabaseResourceId" : "tdb-bac456",
"TenantDatabaseArn" : "arn:aws:rds:us-east-1:123456789012:db:my-cdb-inst:pdb-test",
"DBInstanceIdentifier" : "my-cdb-inst",
"TenantDBName" : "pdb-test",
"Status" : "deleting",
"MasterUsername" : "pdb-test-admin"
"Port" : "6555",
"CharacterSetName" : "UTF-16",
"MaxAllocatedStorage" : "1000",
"ParameterGroups": [
{
"ParameterGroupName": "tenant-1-params",
"ParameterApplyStatus": "in-sync"
}
],
"OptionGroupMemberships": [
{
"OptionGroupName": "tenant-1-options",
"Status": "in-sync"
}
]
}
}
```
# Viewing tenant database details
You can view details about a tenant database in the same way that you can for a non-CDB or CDB.
## Console
**To view details about a tenant database**
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 upper-right corner of the Amazon RDS console, choose the AWS Region where your DB instance resides.
1. In the navigation pane, choose **Databases**.
![\[View details about a CDB\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/cdb-list.png)
In the preceding image, the sole tenant database (PDB) appears as a child of the DB instance.
1. Choose the name of a tenant database.
![\[View details about a PDB\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/pdb-details.png)
## AWS CLI
To see details about your PDBs, use the AWS CLI command [describe-tenant-databases](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-tenant-databases.html).
This following example describes all tenant databases in the specified Region.
**Example**
For Linux, macOS, or Unix:
```
1. aws rds describe-tenant-databases --region us-east-1
```
For Windows:
```
1. aws rds describe-tenant-databases --region us-east-1
```
This command produces output similar to the following.
```
"TenantDatabases" : [
{
"DBInstanceIdentifier" : "my-cdb-inst",
"TenantDBName" : "pdb-test",
"Status" : "available",
"MasterUsername" : "pdb-test-admin",
"DbiResourceId" : "db-abc123",
"TenantDatabaseResourceId" : "tdb-bac456",
"TenantDatabaseArn" : "arn:aws:rds:us-east-1:123456789012:db:my-cdb-inst:pdb-test",
"CharacterSetName": "AL32UTF8",
"NcharCharacterSetName": "AL16UTF16",
"DeletionProtection": false,
"PendingModifiedValues": {
"MasterUserPassword": "****"
},
"TagList": []
},
{
"DBInstanceIdentifier" : "my-cdb-inst2",
"TenantDBName" : "pdb-dev",
"Status" : "modifying",
"MasterUsername" : "masterrdsuser"
"DbiResourceId" : "db-xyz789",
"TenantDatabaseResourceId" : "tdb-ghp890",
"TenantDatabaseArn" : "arn:aws:rds:us-east-1:123456789012:db:my-cdb-inst2:pdb-dev",
"CharacterSetName": "AL32UTF8",
"NcharCharacterSetName": "AL16UTF16",
"DeletionProtection": false,
"PendingModifiedValues": {
"MasterUserPassword": "****"
},
"TagList": []
},
... other truncated data
```
The following example describes the tenant databases on DB instance `my-cdb-inst` in the specified Region.
**Example**
For Linux, macOS, or Unix:
```
1. aws rds describe-tenant-databases --region us-east-1 \
2. --db-instance-identifier my-cdb-inst
```
For Windows:
```
1. aws rds describe-tenant-databases --region us-east-1 ^
2. --db-instance-identifier my-cdb-inst
```
This command produces output similar to the following.
```
{
"TenantDatabase": {
"TenantDatabaseCreateTime": "2023-10-19T23:55:30.046Z",
"DBInstanceIdentifier": "my-cdb-inst",
"TenantDBName": "pdb-hr",
"Status": "creating",
"MasterUsername": "tenant-admin-user",
"DbiResourceId": "db-abc123",
"TenantDatabaseResourceId": "tdb-bac567",
"TenantDatabaseARN": "arn:aws:rds:us-west-2:579508833180:pdb-hr:tdb-abcdefghi1jklmno2p3qrst4uvw5xy6zabc7defghi8jklmn90op",
"CharacterSetName": "AL32UTF8",
"NcharCharacterSetName": "AL16UTF16",
"DeletionProtection": false,
"PendingModifiedValues": {
"MasterUserPassword": "****"
},
"TagList": [
{
"Key": "TEST",
"Value": "testValue"
}
]
}
}
```
The following example describes tenant database `pdb1` on DB instance `my-cdb-inst` in the US East (N. Virginia) Region.
**Example**
For Linux, macOS, or Unix:
```
1. aws rds describe-tenant-databases --region us-east-1 \
2. --db-instance-identifier my-cdb-inst \
3. --tenant-db-name pdb1
```
For Windows:
```
1. aws rds describe-tenant-databases --region us-east-1 ^
2. --db-instance-identifier my-cdb-inst ^
3. --tenant-db-name pdb1
```
This command produces output similar to the following.
```
{
"TenantDatabases" : [
{
"DbiResourceId" : "db-abc123",
"TenantDatabaseResourceId" : "tdb-bac567",
"TenantDatabaseArn" : "arn:aws:rds:us-east-1:123456789012:db:my-cdb-inst:pdb1"
"DBInstanceIdentifier" : "my-cdb-inst",
"TenantDBName" : "pdb1",
"Status" : "ACTIVE",
"MasterUsername" : "masterawsuser"
"Port" : "1234",
"CharacterSetName": "UTF-8",
"ParameterGroups": [
{
"ParameterGroupName": "tenant-custom-pg",
"ParameterApplyStatus": "in-sync"
}
],
{
"OptionGroupMemberships": [
{
"OptionGroupName": "tenant-custom-og",
"Status": "in-sync"
}
]
}
]
}
```
# Upgrading your CDB
You can upgrade a CDB to a different Oracle Database release. For example, you can upgrade an Oracle Database 19c CDB to an Oracle Database 21c CDB. You can't change the database architecture during an upgrade. Thus, you can't upgrade a non-CDB to a CDB or upgrade a CDB to a non-CDB.
The procedure for upgrading a CDB to a CDB is the same as for upgrading a non-CDB to a non-CDB. For more information, see [Upgrading the RDS for Oracle DB engine](USER_UpgradeDBInstance.Oracle.md).
# Administering your RDS for Oracle DB instance
Following are the common management tasks that you perform with an RDS for Oracle DB instance. Some tasks are the same for all RDS DB instances. Other tasks are specific to RDS for Oracle.
The following tasks are common to all RDS databases, but Oracle Database has special considerations. For example, you connect to an Oracle database using the Oracle clients SQL\$1Plus and SQL Developer.
****
| Task area | Relevant documentation |
| --- | --- |
| **Instance classes, storage, and PIOPS** If you are creating a production instance, learn how instance classes, storage types, and Provisioned IOPS work in Amazon RDS. | [RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md) [Amazon RDS storage types](CHAP_Storage.md#Concepts.Storage) |
| **Multi-AZ deployments** A production DB instance should use Multi-AZ deployments. Multi-AZ deployments provide increased availability, data durability, and fault tolerance for DB instances. | [Configuring and managing a Multi-AZ deployment for Amazon RDS](Concepts.MultiAZ.md) |
| **Amazon VPC** If your AWS account has a default virtual private cloud (VPC), then your DB instance is automatically created inside the default VPC. If your account doesn't have a default VPC, and you want the DB instance in a VPC, create the VPC and subnet groups before you create the instance. | [Working with a DB instance in a VPC](USER_VPC.WorkingWithRDSInstanceinaVPC.md) |
| **Security groups** By default, DB instances use a firewall that prevents access. Make sure that you create a security group with the correct IP addresses and network configuration to access the DB instance. | [Controlling access with security groups](Overview.RDSSecurityGroups.md) |
| **Parameter groups** If your DB instance is going to require specific database parameters, create a parameter group before you create the DB instance. | [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md) |
| **Option groups** If your DB instance requires specific database options, create an option group before you create the DB instance. | [Adding options to Oracle DB instances](Appendix.Oracle.Options.md) |
| **Connecting to your DB instance** After creating a security group and associating it to a DB instance, you can connect to the DB instance using any standard SQL client application such as Oracle SQL\$1Plus. | [Connecting to your Oracle DB instance](USER_ConnectToOracleInstance.md) |
| **Backup and restore** You can configure your DB instance to take automated backups, or take manual snapshots, and then restore instances from the backups or snapshots. | [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md) |
| **Monitoring** You can monitor an Oracle DB instance by using CloudWatch Amazon RDS metrics, events, and enhanced monitoring. | [Viewing metrics in the Amazon RDS console](USER_Monitoring.md) [Viewing Amazon RDS events](USER_ListEvents.md) |
| **Log files** You can access the log files for your Oracle DB instance. | [Monitoring Amazon RDS log files](USER_LogAccess.md) |
Following, you can find a description for Amazon RDS–specific implementations of common DBA tasks for RDS Oracle. To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances. Also, RDS restricts access to certain system procedures and tables that require advanced privileges. In many of the tasks, you run the `rdsadmin` package, which is an Amazon RDS–specific tool that enables you to administer your database.
The following are common DBA tasks for DB instances running Oracle:
+ [System tasks](Appendix.Oracle.CommonDBATasks.System.md)
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.html)
+ [Database tasks](Appendix.Oracle.CommonDBATasks.Database.md)
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.html)
+ [Log tasks](Appendix.Oracle.CommonDBATasks.Log.md)
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.html)
+ [RMAN tasks](Appendix.Oracle.CommonDBATasks.RMAN.md)
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.html)
+ [Oracle Scheduler tasks](Appendix.Oracle.CommonDBATasks.Scheduler.md)
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.html)
+ [Diagnosing problems](Appendix.Oracle.CommonDBATasks.Diagnostics.md)
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.html)
+ [Other tasks](Appendix.Oracle.CommonDBATasks.Misc.md)
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.html)
You can also use Amazon RDS procedures for Amazon S3 integration with Oracle and for running OEM Management Agent database tasks. For more information, see [Amazon S3 integration](oracle-s3-integration.md) and [Performing database tasks with the Management Agent](Oracle.Options.OEMAgent.md#Oracle.Options.OEMAgent.DBTasks).
# Performing common system tasks for Oracle DB instances
Following, you can find how to perform certain common DBA tasks related to the system on your Amazon RDS DB instances running Oracle. To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances, and restricts access to certain system procedures and tables that require advanced privileges.
**Topics**
+ [
# Disconnecting a session
](Appendix.Oracle.CommonDBATasks.DisconnectingSession.md)
+ [
# Terminating a session
](Appendix.Oracle.CommonDBATasks.KillingSession.md)
+ [
# Canceling a SQL statement in a session
](Appendix.Oracle.CommonDBATasks.CancellingSQL.md)
+ [
# Enabling and disabling restricted sessions
](Appendix.Oracle.CommonDBATasks.RestrictedSession.md)
+ [
# Flushing the shared pool
](Appendix.Oracle.CommonDBATasks.FlushingSharedPool.md)
+ [
# Granting SELECT or EXECUTE privileges to SYS objects
](Appendix.Oracle.CommonDBATasks.TransferPrivileges.md)
+ [
# Revoking SELECT or EXECUTE privileges on SYS objects
](Appendix.Oracle.CommonDBATasks.RevokePrivileges.md)
+ [
# Managing RDS\$1X\$1 views for Oracle DB instances
](Appendix.Oracle.CommonDBATasks.X-dollar.md)
+ [
# Granting privileges to non-master users
](Appendix.Oracle.CommonDBATasks.PermissionsNonMasters.md)
+ [
# Creating custom functions to verify passwords
](Appendix.Oracle.CommonDBATasks.CustomPassword.md)
+ [
## Setting up a custom DNS server
](#Appendix.Oracle.CommonDBATasks.CustomDNS)
+ [
# Setting and unsetting system diagnostic events
](Appendix.Oracle.CommonDBATasks.SystemEvents.md)
# Disconnecting a session
To disconnect the current session by ending the dedicated server process, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.disconnect`. The `disconnect` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `sid` | number | — | Yes | The session identifier. |
| `serial` | number | — | Yes | The serial number of the session. |
| `method` | varchar | 'IMMEDIATE' | No | Valid values are `'IMMEDIATE'` or `'POST_TRANSACTION'`. |
The following example disconnects a session.
```
begin
rdsadmin.rdsadmin_util.disconnect(
sid => sid,
serial => serial_number);
end;
/
```
To get the session identifier and the session serial number, query the `V$SESSION` view. The following example gets all sessions for the user `AWSUSER`.
```
SELECT SID, SERIAL#, STATUS FROM V$SESSION WHERE USERNAME = 'AWSUSER';
```
The database must be open to use this method. For more information about disconnecting a session, see [ALTER SYSTEM](http://docs.oracle.com/cd/E11882_01/server.112/e41084/statements_2014.htm#SQLRF53166) in the Oracle documentation.
# Terminating a session
To terminate a session, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.kill`. The `kill` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `sid` | number | — | Yes | The session identifier. |
| `serial` | number | — | Yes | The serial number of the session. |
| `method` | varchar | null | No | Valid values are `'IMMEDIATE'` or `'PROCESS'`. If you specify `IMMEDIATE`, it has the same effect as running the following statement: ALTER SYSTEM KILL SESSION 'sid,serial#' IMMEDIATE
If you specify `PROCESS`, you terminate the processes associated with a session. Only specify `PROCESS` if terminating the session using `IMMEDIATE` was unsuccessful. |
To get the session identifier and the session serial number, query the `V$SESSION` view. The following example gets all sessions for the user *AWSUSER*.
```
SELECT SID, SERIAL#, STATUS FROM V$SESSION WHERE USERNAME = 'AWSUSER';
```
The following example terminates a session.
```
BEGIN
rdsadmin.rdsadmin_util.kill(
sid => sid,
serial => serial_number,
method => 'IMMEDIATE');
END;
/
```
The following example terminates the processes associated with a session.
```
BEGIN
rdsadmin.rdsadmin_util.kill(
sid => sid,
serial => serial_number,
method => 'PROCESS');
END;
/
```
# Canceling a SQL statement in a session
To cancel a SQL statement in a session, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.cancel`.
**Note**
This procedure is supported for Oracle Database 19c (19.0.0) and all higher major and minor versions of RDS for Oracle.
The `cancel` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `sid` | number | — | Yes | The session identifier. |
| `serial` | number | — | Yes | The serial number of the session. |
| `sql_id` | varchar2 | null | No | The SQL identifier of the SQL statement. |
The following example cancels a SQL statement in a session.
```
begin
rdsadmin.rdsadmin_util.cancel(
sid => sid,
serial => serial_number,
sql_id => sql_id);
end;
/
```
To get the session identifier, the session serial number, and the SQL identifier of a SQL statement, query the `V$SESSION` view. The following example gets all sessions and SQL identifiers for the user `AWSUSER`.
```
select SID, SERIAL#, SQL_ID, STATUS from V$SESSION where USERNAME = 'AWSUSER';
```
# Enabling and disabling restricted sessions
To enable and disable restricted sessions, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.restricted_session`. The `restricted_session` procedure has the following parameters.
****
| Parameter name | Data type | Default | Yes | Description |
| --- | --- | --- | --- | --- |
| `p_enable` | boolean | true | No | Set to `true` to enable restricted sessions, `false` to disable restricted sessions. |
The following example shows how to enable and disable restricted sessions.
```
/* Verify that the database is currently unrestricted. */
SELECT LOGINS FROM V$INSTANCE;
LOGINS
-------
ALLOWED
/* Enable restricted sessions */
EXEC rdsadmin.rdsadmin_util.restricted_session(p_enable => true);
/* Verify that the database is now restricted. */
SELECT LOGINS FROM V$INSTANCE;
LOGINS
----------
RESTRICTED
/* Disable restricted sessions */
EXEC rdsadmin.rdsadmin_util.restricted_session(p_enable => false);
/* Verify that the database is now unrestricted again. */
SELECT LOGINS FROM V$INSTANCE;
LOGINS
-------
ALLOWED
```
# Flushing the shared pool
To flush the shared pool, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.flush_shared_pool`. The `flush_shared_pool` procedure has no parameters.
The following example flushes the shared pool.
```
EXEC rdsadmin.rdsadmin_util.flush_shared_pool;
```
## Flushing the buffer cache
To flush the buffer cache, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.flush_buffer_cache`. The `flush_buffer_cache` procedure has no parameters.
The following example flushes the buffer cache.
```
EXEC rdsadmin.rdsadmin_util.flush_buffer_cache;
```
## Flushing the database smart flash cache
To flush the database smart flash cache, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.flush_flash_cache`. The `flush_flash_cache` procedure has no parameters. The following example flushes the database smart flash cache.
```
EXEC rdsadmin.rdsadmin_util.flush_flash_cache;
```
For more information about using the database smart flash cache with RDS for Oracle, see [Storing temporary data in an RDS for Oracle instance store](CHAP_Oracle.advanced-features.instance-store.md).
# Granting SELECT or EXECUTE privileges to SYS objects
Usually you transfer privileges by using roles, which can contain many objects. To grant privileges to a single object, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.grant_sys_object`. The procedure grants only privileges that the master user has already been granted through a role or direct grant.
The `grant_sys_object` procedure has the following parameters.
**Important**
For all parameter values, use uppercase unless you created the user with a case-sensitive identifier. For example, if you run `CREATE USER myuser` or `CREATE USER MYUSER`, the data dictionary stores `MYUSER`. However, if you use double quotes in `CREATE USER "MyUser"`, the data dictionary stores `MyUser`.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_obj_name` | varchar2 | — | Yes | The name of the object to grant privileges for. The object can be a directory, function, package, procedure, sequence, table, or view. Object names must be spelled exactly as they appear in `DBA_OBJECTS`. Most system objects are defined in uppercase, so we recommend that you try that first. |
| `p_grantee` | varchar2 | — | Yes | The name of the object to grant privileges to. The object can be a schema or a role. |
| `p_privilege` | varchar2 | null | Yes | — |
| `p_grant_option` | boolean | false | No | Set to `true` to use the with grant option. |
The following example grants select privileges on an object named `V_$SESSION` to a user named `USER1`.
```
begin
rdsadmin.rdsadmin_util.grant_sys_object(
p_obj_name => 'V_$SESSION',
p_grantee => 'USER1',
p_privilege => 'SELECT');
end;
/
```
The following example grants select privileges on an object named `V_$SESSION` to a user named `USER1` with the grant option.
```
begin
rdsadmin.rdsadmin_util.grant_sys_object(
p_obj_name => 'V_$SESSION',
p_grantee => 'USER1',
p_privilege => 'SELECT',
p_grant_option => true);
end;
/
```
To be able to grant privileges on an object, your account must have those privileges granted to it directly with the grant option, or via a role granted using `with admin option`. In the most common case, you may want to grant `SELECT` on a DBA view that has been granted to the `SELECT_CATALOG_ROLE` role. If that role isn't already directly granted to your user using `with admin option`, then you can't transfer the privilege. If you have the DBA privilege, then you can grant the role directly to another user.
The following example grants the `SELECT_CATALOG_ROLE` and `EXECUTE_CATALOG_ROLE` to `USER1`. Since the `with admin option` is used, `USER1` can now grant access to SYS objects that have been granted to `SELECT_CATALOG_ROLE`.
```
GRANT SELECT_CATALOG_ROLE TO USER1 WITH ADMIN OPTION;
GRANT EXECUTE_CATALOG_ROLE to USER1 WITH ADMIN OPTION;
```
Objects already granted to `PUBLIC` do not need to be re-granted. If you use the `grant_sys_object` procedure to re-grant access, the procedure call succeeds.
# Revoking SELECT or EXECUTE privileges on SYS objects
To revoke privileges on a single object, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.revoke_sys_object`. The procedure only revokes privileges that the master account has already been granted through a role or direct grant.
The `revoke_sys_object` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_obj_name` | varchar2 | — | Yes | The name of the object to revoke privileges for. The object can be a directory, function, package, procedure, sequence, table, or view. Object names must be spelled exactly as they appear in `DBA_OBJECTS`. Most system objects are defined in upper case, so we recommend you try that first. |
| `p_revokee` | varchar2 | — | Yes | The name of the object to revoke privileges for. The object can be a schema or a role. |
| `p_privilege` | varchar2 | null | Yes | — |
The following example revokes select privileges on an object named `V_$SESSION` from a user named `USER1`.
```
begin
rdsadmin.rdsadmin_util.revoke_sys_object(
p_obj_name => 'V_$SESSION',
p_revokee => 'USER1',
p_privilege => 'SELECT');
end;
/
```
# Managing RDS\$1X\$1 views for Oracle DB instances
You might need to access `SYS.X$` fixed tables, which are only accessible by `SYS`. To create `SYS.RDS_X$` views on eligible `X$` tables, use the procedures in the `rdsadmin.rdsadmin_util` package. Your master user is automatically granted the privilege `SELECT … WITH GRANT OPTION` on the `RDS_X$` views.
The `rdsadmin.rdsadmin_util` procedures are available in the following cases:
+ Existing DB instances that have never been upgraded and use the following releases:
+ `21.0.0.0.ru-2023-10.rur-2023-10.r1` and higher 21c releases
+ `19.0.0.0.ru-2023-10.rur-2023-10.r1` and higher 19c releases
+ Any new DB instance that you create
+ Any existing DB instance that you have upgraded
**Important**
Internally, the `rdsadmin.rdsadmin_util` package creates views on `X$` tables. The `X$` tables are internal system objects that aren’t described in the Oracle Database documentation. We recommend that you test specific views in your non-production database and only create views in your production database under the guidance of Oracle Support.
## List X\$1 fixed tables eligible for use in RDS\$1X\$1 views
To list X\$1 tables that are eligible for use in `RDS_X$` views, use the RDS procedure `rdsadmin.rdsadmin_util.list_allowed_sys_x$_views`. This procedure accepts no parameters. The following statements lists all eligible `X$` tables (sample output included).
```
SQL> SET SERVEROUTPUT ON
SQL> SELECT * FROM TABLE(rdsadmin.rdsadmin_util.list_allowed_sys_x$_views);
'X$BH'
'X$K2GTE'
'X$KCBWBPD'
'X$KCBWDS'
'X$KGLLK'
'X$KGLOB'
'X$KGLPN'
'X$KSLHOT'
'X$KSMSP'
'X$KSPPCV'
'X$KSPPI'
'X$KSPPSV'
'X$KSQEQ'
'X$KSQRS'
'X$KTUXE'
'X$KQRFP'
```
The list of eligible `X$` tables can change over time. To make sure that your list of eligible `X$` fixed tables is current, rerun `list_allowed_sys_x$_views` periodically.
## Creating SYS.RDS\$1X\$1 views
To create an `RDS_X$` view on an eligible `X$` table, use the RDS procedure `rdsadmin.rdsadmin_util.create_sys_x$_view`. You can only create views for the tables listed in the output of `rdsadmin.rdsadmin_util.list_allowed_sys_x$_views`. The `create_sys_x$_view` procedure accepts the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_x$_tbl` | varchar2 | Null | Yes | A valid `X$` table name. The value must be one of the `X$` tables reported by `list_allowed_sys_x$_views`. |
| `p_force_creation` | Boolean | FALSE | No | A value indicating whether to force creation of an `RDS_X$` view that already exists for an `X$` table. By default, RDS won't create a view if it already exists. To force creation, set this parameter to `TRUE`. |
The following example creates the `SYS.RDS_X$KGLOB` view on the table `X$KGLOB`. The format for the view name is `RDS_X$tablename`.
```
SQL> SET SERVEROUTPUT ON
SQL> EXEC rdsadmin.rdsadmin_util.create_sys_x$_view('X$KGLOB');
PL/SQL procedure successfully completed.
```
The following data dictionary query lists the view `SYS.RDS_X$KGLOB` and shows its status. Your master user is automatically granted the privilege `SELECT ... WITH GRANT OPTION` on this view.
```
SQL> SET SERVEROUTPUT ON
SQL> COL OWNER FORMAT A30
SQL> COL OBJECT_NAME FORMAT A30
SQL> COL STATUS FORMAT A30
SQL> SET LINESIZE 200
SQL> SELECT OWNER, OBJECT_NAME, STATUS
FROM DBA_OBJECTS
WHERE OWNER = 'SYS' AND OBJECT_NAME = 'RDS_X$KGLOB';
OWNER OBJECT_NAME STATUS
------------------------------ ------------------------------ ------------------------------
SYS RDS_X$KGLOB VALID
```
**Important**
`X$` tables aren't guaranteed to stay the same before and after an upgrade. RDS for Oracle drops and recreates the `RDS_X$` views on `X$` tables during an engine upgrade. Then it grants the `SELECT ... WITH GRANT OPTION` privilege to the master user. After an upgrade, grant privileges to database users as needed on the corresponding `RDS_X$` views.
## Listing SYS.RDS\$1X\$1 views
To list existing `RDS_X$` views, use the RDS procedure `rdsadmin.rdsadmin_util.list_created_sys_x$_views`. The procedure lists only views that were created by the procedure `create_sys_x$_view`. The following example lists `X$` tables that have corresponding `RDS_X$` views (sample output included).
```
SQL> SET SERVEROUTPUT ON
SQL> COL XD_TBL_NAME FORMAT A30
SQL> COL STATUS FORMAT A30
SQL> SET LINESIZE 200
SQL> SELECT * FROM TABLE(rdsadmin.rdsadmin_util.list_created_sys_x$_views);
XD_TBL_NAME STATUS
------------------------------ ------------------------------
X$BH VALID
X$K2GTE VALID
X$KCBWBPD VALID
3 rows selected.
```
## Dropping RDS\$1X\$1 views
To drop a `SYS.RDS_X$` view, use the RDS procedure `rdsadmin.rdsadmin_util.drop_sys_x$_view`. You can only drop views listed in the output of `rdsadmin.rdsadmin_util.list_allowed_sys_x$_views`. The `drop_sys_x$_view` procedure accepts the following parameter.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_x$_tbl` | varchar2 | Null | Yes | A valid `X$` fixed table name. The value must be one of the `X$` fixed tables reported by `list_created_sys_x$_views`. |
The following example drops the `RDS_X$KGLOB` view, which was created on the table `X$KGLOB`.
```
SQL> SET SERVEROUTPUT ON
SQL> EXEC rdsadmin.rdsadmin_util.drop_sys_x$_view('X$KGLOB');
PL/SQL procedure successfully completed.
```
The following example shows that the view `SYS.RDS_X$KGLOB` has been dropped (sample output included).
```
SQL> SET SERVEROUTPUT ON
SQL> COL OWNER FORMAT A30
SQL> COL OBJECT_NAME FORMAT A30
SQL> COL STATUS FORMAT A30
SQL> SET LINESIZE 200
SQL> SELECT OWNER, OBJECT_NAME, STATUS
FROM DBA_OBJECTS
WHERE OWNER = 'SYS' AND OBJECT_NAME = 'RDS_X$KGLOB';
no rows selected
```
# Granting privileges to non-master users
You can grant select privileges for many objects in the `SYS` schema by using the `SELECT_CATALOG_ROLE` role. The `SELECT_CATALOG_ROLE` role gives users `SELECT` privileges on data dictionary views. The following example grants the role `SELECT_CATALOG_ROLE` to a user named `user1`.
```
GRANT SELECT_CATALOG_ROLE TO user1;
```
You can grant `EXECUTE` privileges for many objects in the `SYS` schema by using the `EXECUTE_CATALOG_ROLE` role. The `EXECUTE_CATALOG_ROLE` role gives users `EXECUTE` privileges for packages and procedures in the data dictionary. The following example grants the role `EXECUTE_CATALOG_ROLE` to a user named *user1*.
```
GRANT EXECUTE_CATALOG_ROLE TO user1;
```
The following example gets the permissions that the roles `SELECT_CATALOG_ROLE` and `EXECUTE_CATALOG_ROLE` allow.
```
SELECT *
FROM ROLE_TAB_PRIVS
WHERE ROLE IN ('SELECT_CATALOG_ROLE','EXECUTE_CATALOG_ROLE')
ORDER BY ROLE, TABLE_NAME ASC;
```
The following example creates a non-master user named `user1`, grants the `CREATE SESSION` privilege, and grants the `SELECT` privilege on a database named *sh.sales*.
```
CREATE USER user1 IDENTIFIED BY PASSWORD;
GRANT CREATE SESSION TO user1;
GRANT SELECT ON sh.sales TO user1;
```
# Creating custom functions to verify passwords
You can create a custom password verification function in the following ways:
+ To use standard verification logic, and to store your function in the `SYS` schema, use the `create_verify_function` procedure.
+ To use custom verification logic, or to avoid storing your function in the `SYS` schema, use the `create_passthrough_verify_fcn` procedure.
# The create\$1verify\$1function procedure
You can create a custom function to verify passwords by using the Amazon RDS procedure `rdsadmin.rdsadmin_password_verify.create_verify_function`. The `create_verify_function` procedure is supported for all versions of RDS for Oracle.
The `create_verify_function` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_verify_function_name` | varchar2 | — | Yes | The name for your custom function. This function is created for you in the SYS schema. You assign this function to user profiles. |
| `p_min_length` | number | 8 | No | The minimum number of characters required. |
| `p_max_length` | number | 256 | No | The maximum number of characters allowed. |
| `p_min_letters` | number | 1 | No | The minimum number of letters required. |
| `p_min_uppercase` | number | 0 | No | The minimum number of uppercase letters required. |
| `p_min_lowercase` | number | 0 | No | The minimum number of lowercase letters required. |
| `p_min_digits` | number | 1 | No | The minimum number of digits required. |
| `p_min_special` | number | 0 | No | The minimum number of special characters required. |
| `p_min_different_chars` | number | 3 | No | The minimum number of different characters required between the old and new password. |
| `p_disallow_username` | boolean | true | No | Set to `true` to disallow the user name in the password. |
| `p_disallow_reverse` | boolean | true | No | Set to `true` to disallow the reverse of the user name in the password. |
| `p_disallow_db_name` | boolean | true | No | Set to `true` to disallow the database or server name in the password. |
| `p_disallow_simple_strings` | boolean | true | No | Set to `true` to disallow simple strings as the password. |
| `p_disallow_whitespace` | boolean | false | No | Set to `true` to disallow white space characters in the password. |
| `p_disallow_at_sign` | boolean | false | No | Set to `true` to disallow the @ character in the password. |
You can create multiple password verification functions.
There are restrictions on the name of your custom function. Your custom function can't have the same name as an existing system object. The name can be no more than 30 characters long. Also, the name must include one of the following strings: `PASSWORD`, `VERIFY`, `COMPLEXITY`, `ENFORCE`, or `STRENGTH`.
The following example creates a function named `CUSTOM_PASSWORD_FUNCTION`. The function requires that a password has at least 12 characters, 2 uppercase characters, 1 digit, and 1 special character, and that the password disallows the @ character.
```
begin
rdsadmin.rdsadmin_password_verify.create_verify_function(
p_verify_function_name => 'CUSTOM_PASSWORD_FUNCTION',
p_min_length => 12,
p_min_uppercase => 2,
p_min_digits => 1,
p_min_special => 1,
p_disallow_at_sign => true);
end;
/
```
To see the text of your verification function, query `DBA_SOURCE`. The following example gets the text of a custom password function named `CUSTOM_PASSWORD_FUNCTION`.
```
COL TEXT FORMAT a150
SELECT TEXT
FROM DBA_SOURCE
WHERE OWNER = 'SYS'
AND NAME = 'CUSTOM_PASSWORD_FUNCTION'
ORDER BY LINE;
```
To associate your verification function with a user profile, use `ALTER PROFILE`. The following example associates a verification PL/SQL function named `CUSTOM_PASSWORD_FUNCTION` with the `DEFAULT` user profile. `PASSWORD_VERIFY_FUNCTION` is the Oracle profile resource name.
```
ALTER PROFILE DEFAULT LIMIT PASSWORD_VERIFY_FUNCTION CUSTOM_PASSWORD_FUNCTION;
```
To see which user profiles are associated with which verification functions, query `DBA_PROFILES`. The following example gets the profiles that are associated with the custom verification function named `CUSTOM_PASSWORD_FUNCTION`.
```
SELECT * FROM DBA_PROFILES WHERE RESOURCE_NAME = 'PASSWORD_VERIFY_FUNCTION' AND LIMIT = 'CUSTOM_PASSWORD_FUNCTION';
PROFILE RESOURCE_NAME RESOURCE LIMIT
------------------------- -------------------------------- -------- ------------------------
DEFAULT PASSWORD_VERIFY_FUNCTION PASSWORD CUSTOM_PASSWORD_FUNCTION
```
The following example gets all profiles and the password verification functions that they are associated with.
```
SELECT * FROM DBA_PROFILES WHERE RESOURCE_NAME = 'PASSWORD_VERIFY_FUNCTION';
PROFILE RESOURCE_NAME RESOURCE LIMIT
------------------------- -------------------------------- -------- ------------------------
DEFAULT PASSWORD_VERIFY_FUNCTION PASSWORD CUSTOM_PASSWORD_FUNCTION
RDSADMIN PASSWORD_VERIFY_FUNCTION PASSWORD NULL
```
# The create\$1passthrough\$1verify\$1fcn procedure
The `create_passthrough_verify_fcn` procedure is supported for all versions of RDS for Oracle.
You can create a custom function to verify passwords by using the Amazon RDS procedure `rdsadmin.rdsadmin_password_verify.create_passthrough_verify_fcn`. The `create_passthrough_verify_fcn` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_verify_function_name` | varchar2 | — | Yes | The name for your custom verification function. This is a wrapper function that is created for you in the SYS schema, and it doesn't contain any verification logic. You assign this function to user profiles. |
| `p_target_owner` | varchar2 | — | Yes | The schema owner for your custom verification function. |
| `p_target_function_name` | varchar2 | — | Yes | The name of your existing custom function that contains the verification logic. Your custom function must return a boolean. Your function should return `true` if the password is valid and `false` if the password is invalid. |
The following example creates a password verification function that uses the logic from the function named `PASSWORD_LOGIC_EXTRA_STRONG`.
```
begin
rdsadmin.rdsadmin_password_verify.create_passthrough_verify_fcn(
p_verify_function_name => 'CUSTOM_PASSWORD_FUNCTION',
p_target_owner => 'TEST_USER',
p_target_function_name => 'PASSWORD_LOGIC_EXTRA_STRONG');
end;
/
```
To associate the verification function with a user profile, use `alter profile`. The following example associates the verification function with the `DEFAULT` user profile.
```
ALTER PROFILE DEFAULT LIMIT PASSWORD_VERIFY_FUNCTION CUSTOM_PASSWORD_FUNCTION;
```
## Setting up a custom DNS server
Amazon RDS supports outbound network access on your DB instances running Oracle. For more information about outbound network access, including prerequisites, see [Configuring UTL\$1HTTP access using certificates and an Oracle wallet](Oracle.Concepts.ONA.md).
Amazon RDS Oracle allows Domain Name Service (DNS) resolution from a custom DNS server owned by the customer. You can resolve only fully qualified domain names from your Amazon RDS DB instance through your custom DNS server.
After you set up your custom DNS name server, it takes up to 30 minutes to propagate the changes to your DB instance. After the changes are propagated to your DB instance, all outbound network traffic requiring a DNS lookup queries your DNS server over port 53.
To set up a custom DNS server for your Amazon RDS for Oracle DB instance, do the following:
+ From the DHCP options set attached to your virtual private cloud (VPC), set the `domain-name-servers` option to the IP address of your DNS name server. For more information, see [DHCP options sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html).
**Note**
The `domain-name-servers` option accepts up to four values, but your Amazon RDS DB instance uses only the first value.
+ Ensure that your DNS server can resolve all lookup queries, including public DNS names, Amazon EC2 private DNS names, and customer-specific DNS names. If the outbound network traffic contains any DNS lookups that your DNS server can't handle, your DNS server must have appropriate upstream DNS providers configured.
+ Configure your DNS server to produce User Datagram Protocol (UDP) responses of 512 bytes or less.
+ Configure your DNS server to produce Transmission Control Protocol (TCP) responses of 1024 bytes or less.
+ Configure your DNS server to allow inbound traffic from your Amazon RDS DB instances over port 53. If your DNS server is in an Amazon VPC, the VPC must have a security group that contains inbound rules that permit UDP and TCP traffic on port 53. If your DNS server is not in an Amazon VPC, it must have appropriate firewall allow-listing to permit UDP and TCP inbound traffic on port 53.
For more information, see [Security groups for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) and [Adding and removing rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#AddRemoveRules).
+ Configure the VPC of your Amazon RDS DB instance to allow outbound traffic over port 53. Your VPC must have a security group that contains outbound rules that allow UDP and TCP traffic on port 53.
For more information, see [Security groups for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) and [Adding and removing rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#AddRemoveRules).
+ The routing path between the Amazon RDS DB instance and the DNS server has to be configured correctly to allow DNS traffic.
+ If the Amazon RDS DB instance and the DNS server are not in the same VPC, a peering connection has to be set up between them. For more information, see [What is VPC peering?](https://docs.aws.amazon.com/vpc/latest/peering/Welcome.html)
# Setting and unsetting system diagnostic events
To set and unset diagnostic events at the session level, you can use the Oracle SQL statement `ALTER SESSION SET EVENTS`. However, to set events at the system level you can't use Oracle SQL. Instead, use the system event procedures in the `rdsadmin.rdsadmin_util` package. The system event procedures are available in the following engine versions:
+ All Oracle Database 21c versions
+ 19.0.0.0.ru-2020-10.rur-2020-10.r1 and higher Oracle Database 19c versions
For more information, see [Version 19.0.0.0.ru-2020-10.rur-2020-10.r1](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/oracle-version-19-0.html#oracle-version-RU-RUR.19.0.0.0.ru-2020-10.rur-2020-10.r1) in the *Amazon RDS for Oracle Release Notes*
**Important**
Internally, the `rdsadmin.rdsadmin_util` package sets events by using the `ALTER SYSTEM SET EVENTS` statement. This `ALTER SYSTEM` statement isn't documented in the Oracle Database documentation. Some system diagnostic events can generate large amounts of tracing information, cause contention, or affect database availability. We recommend that you test specific diagnostic events in your nonproduction database, and only set events in your production database under guidance of Oracle Support.
## Listing allowed system diagnostic events
To list the system events that you can set, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.list_allowed_system_events`. This procedure accepts no parameters.
The following example lists all system events that you can set.
```
SET SERVEROUTPUT ON
EXEC rdsadmin.rdsadmin_util.list_allowed_system_events;
```
The following sample output lists event numbers and their descriptions. Use the Amazon RDS procedures `set_system_event` to set these events and `unset_system_event` to unset them.
```
604 - error occurred at recursive SQL level
942 - table or view does not exist
1401 - inserted value too large for column
1403 - no data found
1410 - invalid ROWID
1422 - exact fetch returns more than requested number of rows
1426 - numeric overflow
1427 - single-row subquery returns more than one row
1476 - divisor is equal to zero
1483 - invalid length for DATE or NUMBER bind variable
1489 - result of string concatenation is too long
1652 - unable to extend temp segment by in tablespace
1858 - a non-numeric character was found where a numeric was expected
4031 - unable to allocate bytes of shared memory ("","","","")
6502 - PL/SQL: numeric or value error
10027 - Specify Deadlock Trace Information to be Dumped
10046 - enable SQL statement timing
10053 - CBO Enable optimizer trace
10173 - Dynamic Sampling time-out error
10442 - enable trace of kst for ORA-01555 diagnostics
12008 - error in materialized view refresh path
12012 - error on auto execute of job
12504 - TNS:listener was not given the SERVICE_NAME in CONNECT_DATA
14400 - inserted partition key does not map to any partition
31693 - Table data object failed to load/unload and is being skipped due to error:
```
**Note**
The list of the allowed system events can change over time. To make sure that you have the most recent list of eligible events, use `rdsadmin.rdsadmin_util.list_allowed_system_events`.
## Setting system diagnostic events
To set a system event, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.set_system_event`. You can only set events listed in the output of `rdsadmin.rdsadmin_util.list_allowed_system_events`. The `set_system_event` procedure accepts the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_event` | number | — | Yes | The system event number. The value must be one of the event numbers reported by `list_allowed_system_events`. |
| `p_level` | number | — | Yes | The event level. See the Oracle Database documentation or Oracle Support for descriptions of different level values. |
The procedure `set_system_event` constructs and runs the required `ALTER SYSTEM SET EVENTS` statements according to the following principles:
+ The event type (`context` or `errorstack`) is determined automatically.
+ A statement in the form `ALTER SYSTEM SET EVENTS 'event LEVEL event_level'` sets the context events. This notation is equivalent to `ALTER SYSTEM SET EVENTS 'event TRACE NAME CONTEXT FOREVER, LEVEL event_level'`.
+ A statement in the form `ALTER SYSTEM SET EVENTS 'event ERRORSTACK (event_level)'` sets the error stack events. This notation is equivalent to `ALTER SYSTEM SET EVENTS 'event TRACE NAME ERRORSTACK LEVEL event_level'`.
The following example sets event 942 at level 3, and event 10442 at level 10. Sample output is included.
```
SQL> SET SERVEROUTPUT ON
SQL> EXEC rdsadmin.rdsadmin_util.set_system_event(942,3);
Setting system event 942 with: alter system set events '942 errorstack (3)'
PL/SQL procedure successfully completed.
SQL> EXEC rdsadmin.rdsadmin_util.set_system_event(10442,10);
Setting system event 10442 with: alter system set events '10442 level 10'
PL/SQL procedure successfully completed.
```
## Listing system diagnostic events that are set
To list the system events that are currently set, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.list_set_system_events`. This procedure reports only events set at system level by `set_system_event`.
The following example lists the active system events.
```
SET SERVEROUTPUT ON
EXEC rdsadmin.rdsadmin_util.list_set_system_events;
```
The following sample output shows the list of events, the event type, the level at which the events are currently set, and the time when the event was set.
```
942 errorstack (3) - set at 2020-11-03 11:42:27
10442 level 10 - set at 2020-11-03 11:42:41
PL/SQL procedure successfully completed.
```
## Unsetting system diagnostic events
To unset a system event, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.unset_system_event`. You can only unset events listed in the output of `rdsadmin.rdsadmin_util.list_allowed_system_events`. The `unset_system_event` procedure accepts the following parameter.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_event` | number | — | Yes | The system event number. The value must be one of the event numbers reported by `list_allowed_system_events`. |
The following example unsets events 942 and 10442. Sample output is included.
```
SQL> SET SERVEROUTPUT ON
SQL> EXEC rdsadmin.rdsadmin_util.unset_system_event(942);
Unsetting system event 942 with: alter system set events '942 off'
PL/SQL procedure successfully completed.
SQL> EXEC rdsadmin.rdsadmin_util.unset_system_event(10442);
Unsetting system event 10442 with: alter system set events '10442 off'
PL/SQL procedure successfully completed.
```
# Performing common database tasks for Oracle DB instances
Following, you can find how to perform certain common DBA tasks related to databases on your Amazon RDS DB instances running Oracle. To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances. Amazon RDS also restricts access to some system procedures and tables that require advanced privileges.
**Topics**
+ [
# Changing the global name of a database
](Appendix.Oracle.CommonDBATasks.RenamingGlobalName.md)
+ [
# Working with tablespaces in RDS for Oracle
](Appendix.Oracle.CommonDBATasks.TablespacesAndDatafiles.md)
+ [
# Working with tempfiles in RDS for Oracle
](Appendix.Oracle.CommonDBATasks.using-tempfiles.md)
+ [
# Resizing tablespaces, data files, and tempfiles in RDS for Oracle
](Appendix.Oracle.CommonDBATasks.ResizeTempSpaceReadReplica.md)
+ [
# Moving data between storage volumes in RDS for Oracle
](Appendix.Oracle.CommonDBATasks.MovingDataBetweenVolumes.md)
+ [
# Working with external tables in RDS for Oracle
](Appendix.Oracle.CommonDBATasks.External_Tables.md)
# Changing the global name of a database
To change the global name of a database, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.rename_global_name`. The `rename_global_name` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_new_global_name` | varchar2 | — | Yes | The new global name for the database. |
The database must be open for the name change to occur. For more information about changing the global name of a database, see [ALTER DATABASE](http://docs.oracle.com/cd/E11882_01/server.112/e41084/statements_1004.htm#SQLRF52547) in the Oracle documentation.
The following example changes the global name of a database to `new_global_name`.
```
EXEC rdsadmin.rdsadmin_util.rename_global_name(p_new_global_name => 'new_global_name');
```
# Working with tablespaces in RDS for Oracle
You can use tablespaces with RDS for Oracle, which is a logical storage unit that stores the database's data.
**Important**
If your DB instance has replicas, we recommend using parameter group settings instead of session-level changes to manage default file locations. Session-level changes to default file locations in the primary instance are not automatically reflected in the replicas. Using parameter group settings ensures consistent file locations across your primary and replica instances.
**Topics**
+ [
## Specifying database file locations in RDS for Oracle
](#Appendix.Oracle.CommonDBATasks.DatabaseFileLocations)
+ [
## Creating and sizing tablespaces in RDS for Oracle
](#Appendix.Oracle.CommonDBATasks.CreatingTablespacesAndDatafiles)
+ [
## Creating tablespaces on additional storage volumes in RDS for Oracle
](#Appendix.Oracle.CommonDBATasks.CreatingTablespacesWithFileLocations)
+ [
## Setting the default tablespace in RDS for Oracle
](#Appendix.Oracle.CommonDBATasks.SettingDefaultTablespace)
+ [
## Setting the default temporary tablespace in RDS for Oracle
](#Appendix.Oracle.CommonDBATasks.SettingDefTempTablespace)
+ [
## Creating a temporary tablespace on the instance store
](#Appendix.Oracle.CommonDBATasks.creating-tts-instance-store)
## Specifying database file locations in RDS for Oracle
RDS for Oracle uses Oracle Managed Files (OMF) to name database files. When you create database files the database derives the setting based on the current setting of the `DB_CREATE_FILE_DEST` initialization parameter.
The default value of the `DB_CREATE_FILE_DEST` initialization parameter is `/rdsdbdata/db` for standalone databases and `/rdsdbdata/db/pdb` for containerized (CDB/MT) architecture. If your DB instance has additional storage volumes, then you can set `DB_CREATE_FILE_DEST` to your volume locations. For example, if your instance has a volume mounted on `/rdsdbdata/db`, you can set `DB_CREATE_FILE_DEST` to this value.
You can modify the `DB_CREATE_FILE_DEST` parameter at either the session level or Oracle database instance level.
### Modifying DB\$1CREATE\$1FILE\$1SET at the instance level
To modify the parameter at the instance level, update the parameter in the parameter group assigned to your DB instance and apply it. For more information, see [RDS for Oracle initialization parameters](Oracle.Concepts.FeatureSupport.Parameters.md) and [Modifying parameters in a DB parameter group in Amazon RDS](USER_WorkingWithParamGroups.Modifying.md).
### Modifying DB\$1CREATE\$1FILE\$1DEST at the session level
You can modify the parameter at the session level by executing an `ALTER SESSION` statement. This approach is useful when you want to create database files in a specific location for a particular session without affecting the entire instance.
The following example shows how to check the current parameter value and modify it for the session:
```
SHOW PARAMETER db_create_file_dest
NAME TYPE VALUE
------------------------------------ ----------- ------------------------------
db_create_file_dest string /rdsdbdata/db
ALTER SESSION SET db_create_file_dest = '/rdsdbdata2/db';
Session altered.
SHOW PARAMETER db_create_file_dest
NAME TYPE VALUE
------------------------------------ ----------- ------------------------------
db_create_file_dest string /rdsdbdata2/db
```
## Creating and sizing tablespaces in RDS for Oracle
When you create tablespaces, the database creates the data files in the storage volume specified by the `DB_CREATE_FILE_DEST` initialization parameter at the time of creation. By default, if you don't specify a data file size, tablespaces are created with the default of `AUTOEXTEND ON`, and no maximum size. In the following example, the tablespace *users1* is autoextensible.
```
CREATE TABLESPACE users1;
```
Because of these default settings, tablespaces can grow to consume all allocated storage. We recommend that you specify an appropriate maximum size on permanent and temporary tablespaces, and that you carefully monitor space usage.
The following example creates a tablespace named *users2* with a starting size of 1 gigabyte. Because a data file size is specified, but `AUTOEXTEND ON` isn't specified, the tablespace isn't autoextensible.
```
CREATE TABLESPACE users2 DATAFILE SIZE 1G;
```
The following example creates a tablespace named *users3* with a starting size of 1 gigabyte, autoextend turned on, and a maximum size of 10 gigabytes.
```
CREATE TABLESPACE users3 DATAFILE SIZE 1G AUTOEXTEND ON MAXSIZE 10G;
```
The following example creates a temporary tablespace named *temp01*.
```
CREATE TEMPORARY TABLESPACE temp01;
```
You can resize a bigfile tablespace by using `ALTER TABLESPACE`. You can specify the size in kilobytes (K), megabytes (M), gigabytes (G), or terabytes (T). The following example resizes a bigfile tablespace named *users\$1bf* to 200 MB.
```
ALTER TABLESPACE users_bf RESIZE 200M;
```
The following example adds an additional data file to a smallfile tablespace named *users\$1sf*.
```
ALTER TABLESPACE users_sf ADD DATAFILE SIZE 100000M AUTOEXTEND ON NEXT 250m MAXSIZE UNLIMITED;
```
## Creating tablespaces on additional storage volumes in RDS for Oracle
To create a tablespace on an additional storage volume, modify the `DB_CREATE_FILE_DEST` parameter to the volume location. The following example sets the file location to `/rdsdbdata2/db`.
```
ALTER SESSION SET db_create_file_dest = '/rdsdbdata2/db';
Session altered.
```
In the following example, you create a tablespace on the additional volume `/rdsdbdata2/db`.
```
CREATE TABLESPACE new_tablespace DATAFILE SIZE 10G;
Tablespace created.
SELECT tablespace_name,file_id,file_name FROM dba_data_files
WHERE tablespace_name = 'NEW_TABLESPACE';
TABLESPACE_NAME FILE_ID FILE_NAME
------------------------- ---------- --------------------------------------------------------------------------------
NEW_TABLESPACE 7 /rdsdbdata2/db/ORCL_A/datafile/o1_mf_newtable_a123b4c5_.dbf
```
To create a smallfile tablespace and spread its data files across different storage volumes, add data files to the tablespace after you create it. In the following example, you create a tablespace with the data files in the default location of `/rdsdbdata/db`. Then you set the default destination to `/rdsdbdata/db2`. When you add a data file to your newly created tablespace, the database stores the file in `/rdsdbdata/db2`.
```
ALTER SESSION SET db_create_file_dest = '/rdsdbdata/db';
Session altered.
CREATE SMALLFILE TABLESPACE smalltbs DATAFILE SIZE 10G;
Tablespace created.
SELECT tablespace_name,file_id,file_name FROM dba_data_files
WHERE tablespace_name = 'SMALLTBS';
TABLESPACE_NAME FILE_ID FILE_NAME
------------------------- ---------- --------------------------------------------------------------------------------
SMALLTBS 8 /rdsdbdata/db/ORCL_A/datafile/o1_mf_smalltbs_n563yryk_.dbf
ALTER SESSION SET db_create_file_dest = '/rdsdbdata2/db';
Session altered.
ALTER TABLESPACE smalltbs ADD DATAFILE SIZE 10G;
Tablespace altered.
SELECT tablespace_name,file_id,file_name FROM dba_data_files
WHERE tablespace_name = 'SMALLTBS';
TABLESPACE_NAME FILE_ID FILE_NAME
------------------------- ---------- --------------------------------------------------------------------------------
SMALLTBS 8 /rdsdbdata/db/ORCL_A/datafile/o1_mf_smalltbs_n563yryk_.dbf
SMALLTBS 9 /rdsdbdata2/db/ORCL_A/datafile/o1_mf_smalltbs_n564004g_.dbf
```
## Setting the default tablespace in RDS for Oracle
To set the default tablespace, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.alter_default_tablespace`. The `alter_default_tablespace` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tablespace_name` | varchar | — | Yes | The name of the default tablespace. |
The following example sets the default tablespace to *users2*:
```
EXEC rdsadmin.rdsadmin_util.alter_default_tablespace(tablespace_name => 'users2');
```
## Setting the default temporary tablespace in RDS for Oracle
To set the default temporary tablespace, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.alter_default_temp_tablespace`. The `alter_default_temp_tablespace` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tablespace_name` | varchar | — | Yes | The name of the default temporary tablespace. |
The following example sets the default temporary tablespace to *temp01*.
```
EXEC rdsadmin.rdsadmin_util.alter_default_temp_tablespace(tablespace_name => 'temp01');
```
## Creating a temporary tablespace on the instance store
To create a temporary tablespace on the instance store, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.create_inst_store_tmp_tblspace`. The `create_inst_store_tmp_tblspace` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_tablespace_name` | varchar | — | Yes | The name of the temporary tablespace. |
The following example creates the temporary tablespace *temp01* in the instance store.
```
EXEC rdsadmin.rdsadmin_util.create_inst_store_tmp_tblspace(p_tablespace_name => 'temp01');
```
**Important**
When you run `rdsadmin_util.create_inst_store_tmp_tblspace`, the newly created temporary tablespace is not automatically set as the default temporary tablespace. To set it as the default, see [Setting the default temporary tablespace in RDS for Oracle](#Appendix.Oracle.CommonDBATasks.SettingDefTempTablespace).
For more information, see [Storing temporary data in an RDS for Oracle instance store](CHAP_Oracle.advanced-features.instance-store.md).
# Working with tempfiles in RDS for Oracle
## Adding a tempfile to the instance store on a read replica
When you create a temporary tablespace on a primary DB instance, the read replica doesn't create tempfiles. Assume that an empty temporary tablespace exists on your read replica for either of the following reasons:
+ You dropped a tempfile from the tablespace on your read replica. For more information, see [Dropping tempfiles on a read replica](Appendix.Oracle.CommonDBATasks.dropping-tempfiles-replica.md).
+ You created a new temporary tablespace on the primary DB instance. In this case, RDS for Oracle synchronizes the metadata to the read replica.
You can add a tempfile to the empty temporary tablespace, and store the tempfile in the instance store. To create a tempfile in the instance store, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.add_inst_store_tempfile`. You can use this procedure only on a read replica. The procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_tablespace_name` | varchar | — | Yes | The name of the temporary tablespace on your read replica. |
In the following example, the empty temporary tablespace *temp01* exists on your read replica. Run the following command to create a tempfile for this tablespace, and store it in the instance store.
```
EXEC rdsadmin.rdsadmin_util.add_inst_store_tempfile(p_tablespace_name => 'temp01');
```
For more information, see [Storing temporary data in an RDS for Oracle instance store](CHAP_Oracle.advanced-features.instance-store.md).
# Dropping tempfiles on a read replica
You can't drop an existing temporary tablespace on a read replica. You can change the tempfile storage on a read replica from Amazon EBS to the instance store, or from the instance store to Amazon EBS. To achieve these goals, do the following:
1. Drop the current tempfiles in the temporary tablespace on the read replica.
1. Create new tempfiles on different storage.
To drop the tempfiles, use the Amazon RDS procedure `rdsadmin.rdsadmin_util. drop_replica_tempfiles`. You can use this procedure only on read replicas. The `drop_replica_tempfiles` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_tablespace_name` | varchar | — | Yes | The name of the temporary tablespace on your read replica. |
Assume that a temporary tablespace named *temp01* resides in the instance store on your read replica. Drop all tempfiles in this tablespace by running the following command.
```
EXEC rdsadmin.rdsadmin_util.drop_replica_tempfiles(p_tablespace_name => 'temp01');
```
For more information, see [Storing temporary data in an RDS for Oracle instance store](CHAP_Oracle.advanced-features.instance-store.md).
# Resizing tablespaces, data files, and tempfiles in RDS for Oracle
By default, Oracle tablespaces are created with auto-extend turned on and no maximum size. Because of these default settings, tablespaces can sometimes grow too large. We recommend that you specify an appropriate maximum size on permanent and temporary tablespaces, and that you carefully monitor space usage.
## Resizing permanent tablespaces
To resize a permanent tablespace in an RDS for Oracle DB instance, use any of the following Amazon RDS procedures:
+ `rdsadmin.rdsadmin_util.resize_datafile`
+ `rdsadmin.rdsadmin_util.autoextend_datafile`
The `resize_datafile` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_data_file_id` | number | — | Yes | The identifier of the data file to resize. |
| `p_size` | varchar2 | — | Yes | The size of the data file. Specify the size in bytes (the default), kilobytes (K), megabytes (M), or gigabytes (G). |
The `autoextend_datafile` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_data_file_id` | number | — | Yes | The identifier of the data file to resize. |
| `p_autoextend_state` | varchar2 | — | Yes | The state of the autoextension feature. Specify `ON` to extend the data file automatically and `OFF` to turn off autoextension. |
| `p_next` | varchar2 | — | No | The size of the next data file increment. Specify the size in bytes (the default), kilobytes (K), megabytes (M), or gigabytes (G). |
| `p_maxsize` | varchar2 | — | No | The maximum disk space allowed for automatic extension. Specify the size in bytes (the default), kilobytes (K), megabytes (M), or gigabytes (G). You can specify `UNLIMITED` to remove the file size limit. |
The following example resizes data file 4 to 500 MB.
```
EXEC rdsadmin.rdsadmin_util.resize_datafile(4,'500M');
```
The following example turns off autoextension for data file 4. It also turns on autoextension for data file 5, with an increment of 128 MB and no maximum size.
```
EXEC rdsadmin.rdsadmin_util.autoextend_datafile(4,'OFF');
EXEC rdsadmin.rdsadmin_util.autoextend_datafile(5,'ON','128M','UNLIMITED');
```
## Resizing temporary tablespaces
To resize a temporary tablespaces in an RDS for Oracle DB instance, including a read replica, use any of the following Amazon RDS procedures:
+ `rdsadmin.rdsadmin_util.resize_temp_tablespace`
+ `rdsadmin.rdsadmin_util.resize_tempfile`
+ `rdsadmin.rdsadmin_util.autoextend_tempfile`
The `resize_temp_tablespace` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_temp_tablespace_name` | varchar2 | — | Yes | The name of the temporary tablespace to resize. |
| `p_size` | varchar2 | — | Yes | The size of the tablespace. Specify the size in bytes (the default), kilobytes (K), megabytes (M), or gigabytes (G). |
The `resize_tempfile` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_temp_file_id` | number | — | Yes | The identifier of the temp file to resize. |
| `p_size` | varchar2 | — | Yes | The size of the temp file. Specify the size in bytes (the default), kilobytes (K), megabytes (M), or gigabytes (G). |
The `autoextend_tempfile` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_temp_file_id` | number | — | Yes | The identifier of the temp file to resize. |
| `p_autoextend_state` | varchar2 | — | Yes | The state of the autoextension feature. Specify `ON` to extend the temp file automatically and `OFF` to turn off autoextension. |
| `p_next` | varchar2 | — | No | The size of the next temp file increment. Specify the size in bytes (the default), kilobytes (K), megabytes (M), or gigabytes (G). |
| `p_maxsize` | varchar2 | — | No | The maximum disk space allowed for automatic extension. Specify the size in bytes (the default), kilobytes (K), megabytes (M), or gigabytes (G). You can specify `UNLIMITED` to remove the file size limit. |
The following examples resize a temporary tablespace named `TEMP` to the size of 4 GB.
```
EXEC rdsadmin.rdsadmin_util.resize_temp_tablespace('TEMP','4G');
```
```
EXEC rdsadmin.rdsadmin_util.resize_temp_tablespace('TEMP','4096000000');
```
The following example resizes a temporary tablespace based on the temp file with the file identifier `1` to the size of 2 MB.
```
EXEC rdsadmin.rdsadmin_util.resize_tempfile(1,'2M');
```
The following example turns off autoextension for temp file 1. It also sets the maximum autoextension size of temp file 2 to 10 GB, with an increment of 100 MB.
```
EXEC rdsadmin.rdsadmin_util.autoextend_tempfile(1,'OFF');
EXEC rdsadmin.rdsadmin_util.autoextend_tempfile(2,'ON','100M','10G');
```
For more information about read replicas for Oracle DB instances see [Working with read replicas for Amazon RDS for Oracle](oracle-read-replicas.md).
# Moving data between storage volumes in RDS for Oracle
You can move data files and database objects between your primary and additional storage volumes. Before you move data, consider the following points:
+ The source and target volumes must have sufficient free space.
+ Data movement operations consume I/O on both volumes.
+ Large data movements can impact database performance.
+ If you restore a snapshot, moving data between storage volumes might be slow if it is affected by EBS lazy loading.
**Topics**
+ [
## Moving data files between volumes in RDS for Oracle
](#Appendix.Oracle.CommonDBATasks.MovingDatafiles)
+ [
## Moving table data and indexes between volumes in RDS for Oracle
](#Appendix.Oracle.CommonDBATasks.MovingTableData)
+ [
## Managing LOB storage using additional volumes
](#Appendix.Oracle.CommonDBATasks.ManagingLargeLOBStorage)
## Moving data files between volumes in RDS for Oracle
To move data files between storage volumes, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.move_datafile`. Note the following requirements:
+ You must use Oracle Enterprise Edition to run the `move_datafile` procedure.
+ You can't move tablespace `SYSTEM` and `RDSADMIN`.
The `move_datafile` procedure has the following parameters.
****
| Parameter name | Data type | Required | Description |
| --- | --- | --- | --- |
| `p_data_file_id` | number | Yes | The ID of the data file to be moved. |
| `p_location` | varchar2 | Yes | The storage volume to which you want to move the data file. |
The following example moves a tablespace from the default volume `rdsdbdata` to the additional volume `rdsdbdata2`.
```
SQL> SELECT tablespace_name,file_id,file_name FROM dba_data_files
WHERE tablespace_name = 'MYNEWTABLESPACE';
TABLESPACE_NAME FILE_ID FILE_NAME
------------------------- ---------- --------------------------------------------------------------------------------
MYNEWTABLESPACE 6 /rdsdbdata/db/ORCL_A/datafile/o1_mf_mynewtab_n123abcd_.dbf
EXECUTE rdsadmin.rdsadmin_util.move_datafile( 6, 'rdsdbdata2');
PL/SQL procedure successfully completed.
SQL> SELECT tablespace_name,file_id,file_name FROM dba_data_files
WHERE tablespace_name = 'MYNEWTABLESPACE';
TABLESPACE_NAME FILE_ID FILE_NAME
------------------------- ---------- --------------------------------------------------------------------------------
MYNEWTABLESPACE 6 /rdsdbdata2/db/ORCL_A/datafile/o1_mf_mynewtab_n356efgh_.dbf
```
## Moving table data and indexes between volumes in RDS for Oracle
You can optimize database storage by creating tablespaces on additional storage volumes. Then you can move objects such as tables, indexes, and partitions to these tablespaces using standard Oracle SQL. This approach is valuable for performance tuning when your database contains data with different access patterns. For example, you could store frequently accessed operational data on high-performance storage volumes while moving rarely accessed historical data to lower-cost storage volumes.
In the following example, you create a new tablespace on high-performance volume `rdsdbdata2`. Then you move a table to your additional storage volume while the table is online. You also move the index to the same volume. Moving tables and rebuilding indexes while online requires Oracle Enterprise Edition.
```
ALTER SESSION SET db_create_file_dest = '/rdsdbdata2/db';
CREATE TABLESPACE perf_tbs DATAFILE SIZE 10G;
ALTER TABLE employees
MOVE TABLESPACE perf_tbs ONLINE;
ALTER INDEX employees_idx
REBUILD ONLINE TABLESPACE perf_tbs;
```
In the following example, you create a tablespace on a low-cost volume. Then you move a table partition to your low-cost storage volume using an online operation.
```
ALTER SESSION SET db_create_file_dest = '/rdsdbdata3/db';
CREATE TABLESPACE hist_tbs DATAFILE SIZE 10G;
ALTER TABLE orders
MOVE PARTITION orders_2022
TABLESPACE hist_tbs ONLINE;
```
In the following example, you query active sessions long operations.
```
SELECT sid,opname,sofar,totalwork,time_remaining,elapsed_seconds
FROM v$session_longops
WHERE time_remaining > 0;
```
You can check your tablespaces usage with the following query.
```
SELECT tablespace_name, used_percent
FROM dba_tablespace_usage_metrics
ORDER BY used_percent DESC;
```
## Managing LOB storage using additional volumes
Your database might contains tables with BLOB or CLOB objects that consume substantial storage but are infrequently accessed. To optimize storage, you can relocate these LOB segments to a tablespace on an additional storage volume.
In the following example, you create a tablespace for LOB data on a low-cost volume that is intended for low-access data. Then you create a table that stores data on this volume.
```
ALTER SESSION SET db_create_file_dest = '/rdsdbdata3/db';
CREATE TABLESPACE lob_data DATAFILE SIZE 5G AUTOEXTEND ON NEXT 1G;
CREATE TABLE documents (
doc_id NUMBER PRIMARY KEY,
doc_date DATE,
doc_content CLOB
) TABLESPACE user_data
LOB(doc_content) STORE AS (TABLESPACE lob_data);
```
# Working with external tables in RDS for Oracle
*Oracle external tables *are tables with data that is not in the database. Instead, the data is in external files that the database can access. By using external tables, you can access data without loading it into the database. For more information about external tables, see [Managing external tables](http://docs.oracle.com/database/121/ADMIN/tables.htm#ADMIN01507) in the Oracle documentation.
With Amazon RDS, you can store external table files in directory objects. You can create a directory object, or you can use one that is predefined in the Oracle database, such as the DATA\$1PUMP\$1DIR directory. For information about creating directory objects, see [Creating and dropping directories in the main data storage space](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.NewDirectories). You can query the ALL\$1DIRECTORIES view to list the directory objects for your Amazon RDS Oracle DB instance.
**Note**
Directory objects point to the main data storage space (Amazon EBS volume) used by your instance. The space used—along with data files, redo logs, audit, trace, and other files—counts against allocated storage.
You can move an external data file from one Oracle database to another by using the [ DBMS\$1FILE\$1TRANSFER](https://docs.oracle.com/database/121/ARPLS/d_ftran.htm#ARPLS095) package or the [UTL\$1FILE](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS069) package. The external data file is moved from a directory on the source database to the specified directory on the destination database. For information about using `DBMS_FILE_TRANSFER`, see [Importing using Oracle Data Pump](Oracle.Procedural.Importing.DataPump.md).
After you move the external data file, you can create an external table with it. The following example creates an external table that uses the `emp_xt_file1.txt` file in the USER\$1DIR1 directory.
```
CREATE TABLE emp_xt (
emp_id NUMBER,
first_name VARCHAR2(50),
last_name VARCHAR2(50),
user_name VARCHAR2(20)
)
ORGANIZATION EXTERNAL (
TYPE ORACLE_LOADER
DEFAULT DIRECTORY USER_DIR1
ACCESS PARAMETERS (
RECORDS DELIMITED BY NEWLINE
FIELDS TERMINATED BY ','
MISSING FIELD VALUES ARE NULL
(emp_id,first_name,last_name,user_name)
)
LOCATION ('emp_xt_file1.txt')
)
PARALLEL
REJECT LIMIT UNLIMITED;
```
Suppose that you want to move data that is in an Amazon RDS Oracle DB instance into an external data file. In this case, you can populate the external data file by creating an external table and selecting the data from the table in the database. For example, the following SQL statement creates the `orders_xt` external table by querying the `orders` table in the database.
```
CREATE TABLE orders_xt
ORGANIZATION EXTERNAL
(
TYPE ORACLE_DATAPUMP
DEFAULT DIRECTORY DATA_PUMP_DIR
LOCATION ('orders_xt.dmp')
)
AS SELECT * FROM orders;
```
In this example, the data is populated in the `orders_xt.dmp` file in the DATA\$1PUMP\$1DIR directory.
# Checkpointing a database
To checkpoint the database, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.checkpoint`. The `checkpoint` procedure has no parameters.
The following example checkpoints the database.
```
EXEC rdsadmin.rdsadmin_util.checkpoint;
```
# Setting distributed recovery
To set distributed recovery, use the Amazon RDS procedures `rdsadmin.rdsadmin_util.enable_distr_recovery` and `disable_distr_recovery`. The procedures have no parameters.
The following example enables distributed recovery.
```
EXEC rdsadmin.rdsadmin_util.enable_distr_recovery;
```
The following example disables distributed recovery.
```
EXEC rdsadmin.rdsadmin_util.disable_distr_recovery;
```
# Setting the database time zone
You can set the time zone of your Amazon RDS Oracle database in the following ways:
+ The `Timezone` option
The `Timezone` option changes the time zone at the host level and affects all date columns and values such as `SYSDATE`. For more information, see [Oracle time zone](Appendix.Oracle.Options.Timezone.md).
+ The Amazon RDS procedure `rdsadmin.rdsadmin_util.alter_db_time_zone`
The `alter_db_time_zone` procedure changes the time zone for only certain data types, and doesn't change `SYSDATE`. There are additional restrictions on setting the time zone listed in the [Oracle documentation](http://docs.oracle.com/cd/B19306_01/server.102/b14225/ch4datetime.htm#i1006705).
**Note**
You can also set the default time zone for Oracle Scheduler. For more information, see [Setting the time zone for Oracle Scheduler jobs](Appendix.Oracle.CommonDBATasks.Scheduler.md#Appendix.Oracle.CommonDBATasks.Scheduler.TimeZone).
The `alter_db_time_zone` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_new_tz` | varchar2 | — | Yes | The new time zone as a named region or an absolute offset from Coordinated Universal Time (UTC). Valid offsets range from -12:00 to \$114:00. |
The following example changes the time zone to UTC plus three hours.
```
EXEC rdsadmin.rdsadmin_util.alter_db_time_zone(p_new_tz => '+3:00');
```
The following example changes the time zone to the Africa/Algiers time zone.
```
EXEC rdsadmin.rdsadmin_util.alter_db_time_zone(p_new_tz => 'Africa/Algiers');
```
After you alter the time zone by using the `alter_db_time_zone` procedure, reboot your DB instance for the change to take effect. For more information, see [Rebooting a DB instance](USER_RebootInstance.md). For information about upgrading time zones, see [Time zone considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.DST).
# Generating performance reports with Automatic Workload Repository (AWR)
To gather performance data and generate reports, Oracle recommends Automatic Workload Repository (AWR). AWR requires Oracle Database Enterprise Edition and a license for the Diagnostics and Tuning packs. To enable AWR, set the `CONTROL_MANAGEMENT_PACK_ACCESS` initialization parameter to either `DIAGNOSTIC` or `DIAGNOSTIC+TUNING`.
## Working with AWR reports in RDS
To generate AWR reports, you can run scripts such as `awrrpt.sql`. These scripts are installed on the database host server. In Amazon RDS, you don't have direct access to the host. However, you can get copies of SQL scripts from another installation of Oracle Database.
You can also use AWR by running procedures in the `SYS.DBMS_WORKLOAD_REPOSITORY` PL/SQL package. You can use this package to manage baselines and snapshots, and also to display ASH and AWR reports. For example, to generate an AWR report in text format run the `DBMS_WORKLOAD_REPOSITORY.AWR_REPORT_TEXT` procedure. However, you can't reach these AWR reports from the AWS Management Console.
When working with AWR, we recommend using the `rdsadmin.rdsadmin_diagnostic_util` procedures. You can use these procedures to generate the following:
+ AWR reports
+ Active Session History (ASH) reports
+ Automatic Database Diagnostic Monitor (ADDM) reports
+ Oracle Data Pump Export dump files of AWR data
The `rdsadmin_diagnostic_util` procedures save the reports to the DB instance file system. You can access these reports from the console. You can also access reports using the `rdsadmin.rds_file_util` procedures, and you can access reports that are copied to Amazon S3 using the S3 Integration option. For more information, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles) and [Amazon S3 integration](oracle-s3-integration.md).
You can use the `rdsadmin_diagnostic_util` procedures in the following Amazon RDS for Oracle DB engine versions:
+ All Oracle Database 21c versions
+ 19.0.0.0.ru-2020-04.rur-2020-04.r1 and higher Oracle Database 19c versions
For a blog that explains how to work with diagnostic reports in a replication scenario, see [Generate AWR reports for Amazon RDS for Oracle read replicas](https://aws.amazon.com/blogs/database/generate-awr-reports-for-amazon-rds-for-oracle-read-replicas/).
## Common parameters for the diagnostic utility package
You typically use the following parameters when managing AWR and ADDM with the `rdsadmin_diagnostic_util` package.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.AWR.html)
You typically use the following parameters when managing ASH with the rdsadmin\$1diagnostic\$1util package.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.AWR.html)
## Generating an AWR report
To generate an AWR report, use the `rdsadmin.rdsadmin_diagnostic_util.awr_report` procedure.
The following example generates a AWR report for the snapshot range 101–106. The output text file is named `awrrpt_101_106.txt`. You can access this report from the AWS Management Console.
```
EXEC rdsadmin.rdsadmin_diagnostic_util.awr_report(101,106,'TEXT');
```
The following example generates an HTML report for the snapshot range 63–65. The output HTML file is named `awrrpt_63_65.html`. The procedure writes the report to the nondefault database directory named `AWR_RPT_DUMP`.
```
EXEC rdsadmin.rdsadmin_diagnostic_util.awr_report(63,65,'HTML','AWR_RPT_DUMP');
```
## Extracting AWR data into a dump file
To extract AWR data into a dump file, use the `rdsadmin.rdsadmin_diagnostic_util.awr_extract` procedure. You can use this function only at the PDB level.
The following example extracts the snapshot range 101–106. The output dump file is named `awrextract_101_106.dmp`. You can access this file through the console.
```
EXEC rdsadmin.rdsadmin_diagnostic_util.awr_extract(101,106);
```
The following example extracts the snapshot range 63–65. The output dump file is named `awrextract_63_65.dmp`. The file is stored in the nondefault database directory named `AWR_RPT_DUMP`.
```
EXEC rdsadmin.rdsadmin_diagnostic_util.awr_extract(63,65,'AWR_RPT_DUMP');
```
## Generating an ADDM report
To generate an ADDM report, use the `rdsadmin.rdsadmin_diagnostic_util.addm_report` procedure.
The following example generates an ADDM report for the snapshot range 101–106. The output text file is named `addmrpt_101_106.txt`. You can access the report through the console.
```
EXEC rdsadmin.rdsadmin_diagnostic_util.addm_report(101,106);
```
The following example generates an ADDM report for the snapshot range 63–65. The output text file is named `addmrpt_63_65.txt`. The file is stored in the nondefault database directory named `ADDM_RPT_DUMP`.
```
EXEC rdsadmin.rdsadmin_diagnostic_util.addm_report(63,65,'ADDM_RPT_DUMP');
```
## Generating an ASH report
To generate an ASH report, use the `rdsadmin.rdsadmin_diagnostic_util.ash_report` procedure.
The following example generates an ASH report that includes the data from 14 minutes ago until the current time. The name of the output file uses the format `ashrptbegin_timeend_time.txt`, where `begin_time` and `end_time` use the format `YYYYMMDDHH24MISS`. You can access the file through the console.
```
BEGIN
rdsadmin.rdsadmin_diagnostic_util.ash_report(
begin_time => SYSDATE-14/1440,
end_time => SYSDATE,
report_type => 'TEXT');
END;
/
```
The following example generates an ASH report that includes the data from November 18, 2019, at 6:07 PM through November 18, 2019, at 6:15 PM. The name of the output HTML report is `ashrpt_20190918180700_20190918181500.html`. The report is stored in the nondefault database directory named `AWR_RPT_DUMP`.
```
BEGIN
rdsadmin.rdsadmin_diagnostic_util.ash_report(
begin_time => TO_DATE('2019-09-18 18:07:00', 'YYYY-MM-DD HH24:MI:SS'),
end_time => TO_DATE('2019-09-18 18:15:00', 'YYYY-MM-DD HH24:MI:SS'),
report_type => 'html',
dump_directory => 'AWR_RPT_DUMP');
END;
/
```
## Accessing AWR reports from the console or CLI
To access AWR reports or export dump files, you can use the AWS Management Console or AWS CLI. For more information, see [Downloading a database log file](USER_LogAccess.Procedural.Downloading.md).
# Adjusting database links for use with DB instances in a VPC
To use Oracle database links with Amazon RDS DB instances inside the same virtual private cloud (VPC) or peered VPCs, the two DB instances should have a valid route between them. Verify the valid route between the DB instances by using your VPC routing tables and network access control list (ACL).
The security group of each DB instance must allow ingress to and egress from the other DB instance. The inbound and outbound rules can refer to security groups from the same VPC or a peered VPC. For more information, see [Updating your security groups to reference peered VPC security groups](https://docs.aws.amazon.com/vpc/latest/peering/working-with-vpc-peering.html#vpc-peering-security-groups).
If you have configured a custom DNS server using the DHCP Option Sets in your VPC, your custom DNS server must be able to resolve the name of the database link target. For more information, see [Setting up a custom DNS server](Appendix.Oracle.CommonDBATasks.System.md#Appendix.Oracle.CommonDBATasks.CustomDNS).
For more information about using database links with Oracle Data Pump, see [Importing using Oracle Data Pump](Oracle.Procedural.Importing.DataPump.md).
# Setting the default edition for a DB instance
You can redefine database objects in a private environment called an edition. You can use edition-based redefinition to upgrade an application's database objects with minimal downtime.
You can set the default edition of an Amazon RDS Oracle DB instance using the Amazon RDS procedure `rdsadmin.rdsadmin_util.alter_default_edition`.
The following example sets the default edition for the Amazon RDS Oracle DB instance to `RELEASE_V1`.
```
EXEC rdsadmin.rdsadmin_util.alter_default_edition('RELEASE_V1');
```
The following example sets the default edition for the Amazon RDS Oracle DB instance back to the Oracle default.
```
EXEC rdsadmin.rdsadmin_util.alter_default_edition('ORA$BASE');
```
For more information about Oracle edition-based redefinition, see [About editions and edition-based redefinition](https://docs.oracle.com/database/121/ADMIN/general.htm#ADMIN13167) in the Oracle documentation.
# Enabling auditing for the SYS.AUD\$1 table
To enable auditing on the database audit trail table `SYS.AUD$`, use the Amazon RDS procedure `rdsadmin.rdsadmin_master_util.audit_all_sys_aud_table`. The only supported audit property is `ALL`. You can't audit or not audit individual statements or operations.
Enabling auditing is supported for Oracle DB instances running the following versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
The `audit_all_sys_aud_table` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_by_access` | boolean | true | No | Set to `true` to audit `BY ACCESS`. Set to `false` to audit `BY SESSION`. |
The following query returns the current audit configuration for `SYS.AUD$` for a database.
```
SELECT * FROM DBA_OBJ_AUDIT_OPTS WHERE OWNER='SYS' AND OBJECT_NAME='AUD$';
```
The following commands enable audit of `ALL` on `SYS.AUD$` `BY ACCESS`.
```
EXEC rdsadmin.rdsadmin_master_util.audit_all_sys_aud_table;
EXEC rdsadmin.rdsadmin_master_util.audit_all_sys_aud_table(p_by_access => true);
```
The following command enables audit of `ALL` on `SYS.AUD$` `BY SESSION`.
```
EXEC rdsadmin.rdsadmin_master_util.audit_all_sys_aud_table(p_by_access => false);
```
For more information, see [AUDIT (traditional auditing)](https://docs.oracle.com/en/database/oracle/oracle-database/12.2/sqlrf/AUDIT-Traditional-Auditing.html#GUID-ADF45B07-547A-4096-8144-50241FA2D8DD) in the Oracle documentation.
# Disabling auditing for the SYS.AUD\$1 table
To disable auditing on the database audit trail table `SYS.AUD$`, use the Amazon RDS procedure `rdsadmin.rdsadmin_master_util.noaudit_all_sys_aud_table`. This procedure takes no parameters.
The following query returns the current audit configuration for `SYS.AUD$` for a database:
```
SELECT * FROM DBA_OBJ_AUDIT_OPTS WHERE OWNER='SYS' AND OBJECT_NAME='AUD$';
```
The following command disables audit of `ALL` on `SYS.AUD$`.
```
EXEC rdsadmin.rdsadmin_master_util.noaudit_all_sys_aud_table;
```
For more information, see [NOAUDIT (traditional auditing)](https://docs.oracle.com/en/database/oracle/oracle-database/12.2/sqlrf/NOAUDIT-Traditional-Auditing.html#GUID-9D8EAF18-4AB3-4C04-8BF7-37BD0E15434D) in the Oracle documentation.
# Cleaning up interrupted online index builds
To clean up failed online index builds, use the Amazon RDS procedure `rdsadmin.rdsadmin_dbms_repair.online_index_clean`.
The `online_index_clean` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `object_id` | binary\$1integer | `ALL_INDEX_ID` | No | The object ID of the index. Typically, you can use the object ID from the ORA-08104 error text. |
| `wait_for_lock` | binary\$1integer | `rdsadmin.rdsadmin_dbms_repair.lock_wait` | No | Specify `rdsadmin.rdsadmin_dbms_repair.lock_wait`, the default, to try to get a lock on the underlying object and retry until an internal limit is reached if the lock fails. Specify `rdsadmin.rdsadmin_dbms_repair.lock_nowait` to try to get a lock on the underlying object but not retry if the lock fails. |
The following example cleans up a failed online index build:
```
declare
is_clean boolean;
begin
is_clean := rdsadmin.rdsadmin_dbms_repair.online_index_clean(
object_id => 1234567890,
wait_for_lock => rdsadmin.rdsadmin_dbms_repair.lock_nowait
);
end;
/
```
For more information, see [ONLINE\$1INDEX\$1CLEAN function](https://docs.oracle.com/database/121/ARPLS/d_repair.htm#ARPLS67555) in the Oracle documentation.
# Skipping corrupt blocks
To skip corrupt blocks during index and table scans, use the `rdsadmin.rdsadmin_dbms_repair` package.
The following procedures wrap the functionality of the `sys.dbms_repair.admin_table` procedure and take no parameters:
+ `rdsadmin.rdsadmin_dbms_repair.create_repair_table`
+ `rdsadmin.rdsadmin_dbms_repair.create_orphan_keys_table`
+ `rdsadmin.rdsadmin_dbms_repair.drop_repair_table`
+ `rdsadmin.rdsadmin_dbms_repair.drop_orphan_keys_table`
+ `rdsadmin.rdsadmin_dbms_repair.purge_repair_table`
+ `rdsadmin.rdsadmin_dbms_repair.purge_orphan_keys_table`
The following procedures take the same parameters as their counterparts in the `DBMS_REPAIR` package for Oracle databases:
+ `rdsadmin.rdsadmin_dbms_repair.check_object`
+ `rdsadmin.rdsadmin_dbms_repair.dump_orphan_keys`
+ `rdsadmin.rdsadmin_dbms_repair.fix_corrupt_blocks`
+ `rdsadmin.rdsadmin_dbms_repair.rebuild_freelists`
+ `rdsadmin.rdsadmin_dbms_repair.segment_fix_status`
+ `rdsadmin.rdsadmin_dbms_repair.skip_corrupt_blocks`
For more information about handling database corruption, see [DBMS\$1REPAIR](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_REPAIR.html#GUID-B8EC4AB3-4D6A-46C9-857F-4ED53CD9C948) in the Oracle documentation.
**Example Responding to corrupt blocks**
This example shows the basic workflow for responding to corrupt blocks. Your steps will depend on the location and nature of your block corruption.
Before attempting to repair corrupt blocks, review the [DBMS\$1REPAIR](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_REPAIR.html#GUID-B8EC4AB3-4D6A-46C9-857F-4ED53CD9C948) documentation carefully.
**To skip corrupt blocks during index and table scans**
1. Run the following procedures to create repair tables if they don't already exist.
```
EXEC rdsadmin.rdsadmin_dbms_repair.create_repair_table;
EXEC rdsadmin.rdsadmin_dbms_repair.create_orphan_keys_table;
```
1. Run the following procedures to check for existing records and purge them if appropriate.
```
SELECT COUNT(*) FROM SYS.REPAIR_TABLE;
SELECT COUNT(*) FROM SYS.ORPHAN_KEY_TABLE;
SELECT COUNT(*) FROM SYS.DBA_REPAIR_TABLE;
SELECT COUNT(*) FROM SYS.DBA_ORPHAN_KEY_TABLE;
EXEC rdsadmin.rdsadmin_dbms_repair.purge_repair_table;
EXEC rdsadmin.rdsadmin_dbms_repair.purge_orphan_keys_table;
```
1. Run the following procedure to check for corrupt blocks.
```
SET SERVEROUTPUT ON
DECLARE v_num_corrupt INT;
BEGIN
v_num_corrupt := 0;
rdsadmin.rdsadmin_dbms_repair.check_object (
schema_name => '&corruptionOwner',
object_name => '&corruptionTable',
corrupt_count => v_num_corrupt
);
dbms_output.put_line('number corrupt: '||to_char(v_num_corrupt));
END;
/
COL CORRUPT_DESCRIPTION FORMAT a30
COL REPAIR_DESCRIPTION FORMAT a30
SELECT OBJECT_NAME, BLOCK_ID, CORRUPT_TYPE, MARKED_CORRUPT,
CORRUPT_DESCRIPTION, REPAIR_DESCRIPTION
FROM SYS.REPAIR_TABLE;
SELECT SKIP_CORRUPT
FROM DBA_TABLES
WHERE OWNER = '&corruptionOwner'
AND TABLE_NAME = '&corruptionTable';
```
1. Use the `skip_corrupt_blocks` procedure to enable or disable corruption skipping for affected tables. Depending on the situation, you may also need to extract data to a new table, and then drop the table containing the corrupt block.
Run the following procedure to enable corruption skipping for affected tables.
```
begin
rdsadmin.rdsadmin_dbms_repair.skip_corrupt_blocks (
schema_name => '&corruptionOwner',
object_name => '&corruptionTable',
object_type => rdsadmin.rdsadmin_dbms_repair.table_object,
flags => rdsadmin.rdsadmin_dbms_repair.skip_flag);
end;
/
select skip_corrupt from dba_tables where owner = '&corruptionOwner' and table_name = '&corruptionTable';
```
Run the following procedure to disable corruption skipping.
```
begin
rdsadmin.rdsadmin_dbms_repair.skip_corrupt_blocks (
schema_name => '&corruptionOwner',
object_name => '&corruptionTable',
object_type => rdsadmin.rdsadmin_dbms_repair.table_object,
flags => rdsadmin.rdsadmin_dbms_repair.noskip_flag);
end;
/
select skip_corrupt from dba_tables where owner = '&corruptionOwner' and table_name = '&corruptionTable';
```
1. When you have completed all repair work, run the following procedures to drop the repair tables.
```
EXEC rdsadmin.rdsadmin_dbms_repair.drop_repair_table;
EXEC rdsadmin.rdsadmin_dbms_repair.drop_orphan_keys_table;
```
## Purging the recycle bin
When you drop a table, your Oracle database doesn't immediately remove its storage space. The database renames the table and places it and any associated objects in a recycle bin. Purging the recycle bin removes these items and releases their storage space.
To purge the entire recycle bin, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.purge_dba_recyclebin`. However, this procedure can't purge the recycle bin of `SYS` and `RDSADMIN` objects. If you need to purge these objects, contact AWS Support.
The following example purges the entire recycle bin.
```
EXEC rdsadmin.rdsadmin_util.purge_dba_recyclebin;
```
# Setting the default displayed values for full redaction
To change the default displayed values for full redaction on your Amazon RDS Oracle instance, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.dbms_redact_upd_full_rdct_val`. Note that you create a redaction policy with the `DBMS_REDACT` PL/SQL package, as explained in the Oracle Database documentation. The `dbms_redact_upd_full_rdct_val` procedure specifies the characters to display for different data types affected by an existing policy.
The `dbms_redact_upd_full_rdct_val` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_number_val` | number | Null | No | Modifies the default value for columns of the `NUMBER` data type. |
| `p_binfloat_val` | binary\$1float | Null | No | Modifies the default value for columns of the `BINARY_FLOAT` data type. |
| `p_bindouble_val` | binary\$1double | Null | No | Modifies the default value for columns of the `BINARY_DOUBLE` data type. |
| `p_char_val` | char | Null | No | Modifies the default value for columns of the `CHAR` data type. |
| `p_varchar_val` | varchar2 | Null | No | Modifies the default value for columns of the `VARCHAR2` data type. |
| `p_nchar_val` | nchar | Null | No | Modifies the default value for columns of the `NCHAR` data type. |
| `p_nvarchar_val` | nvarchar2 | Null | No | Modifies the default value for columns of the `NVARCHAR2` data type. |
| `p_date_val` | date | Null | No | Modifies the default value for columns of the `DATE` data type. |
| `p_ts_val` | timestamp | Null | No | Modifies the default value for columns of the `TIMESTAMP` data type. |
| `p_tswtz_val` | timestamp with time zone | Null | No | Modifies the default value for columns of the `TIMESTAMP WITH TIME ZONE` data type. |
| `p_blob_val` | blob | Null | No | Modifies the default value for columns of the `BLOB` data type. |
| `p_clob_val` | clob | Null | No | Modifies the default value for columns of the `CLOB` data type. |
| `p_nclob_val` | nclob | Null | No | Modifies the default value for columns of the `NCLOB` data type. |
The following example changes the default redacted value to \$1 for the `CHAR` data type:
```
EXEC rdsadmin.rdsadmin_util.dbms_redact_upd_full_rdct_val(p_char_val => '*');
```
The following example changes the default redacted values for `NUMBER`, `DATE`, and `CHAR` data types:
```
BEGIN
rdsadmin.rdsadmin_util.dbms_redact_upd_full_rdct_val(
p_number_val=>1,
p_date_val=>to_date('1900-01-01','YYYY-MM-DD'),
p_varchar_val=>'X');
END;
/
```
After you alter the default values for full redaction with the `dbms_redact_upd_full_rdct_val` procedure, reboot your DB instance for the change to take effect. For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
# Performing common log-related tasks for Oracle DB instances
Following, you can find how to perform certain common DBA tasks related to logging on your Amazon RDS DB instances running Oracle. To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances, and restricts access to certain system procedures and tables that require advanced privileges.
For more information, see [Amazon RDS for Oracle database log files](USER_LogAccess.Concepts.Oracle.md).
**Topics**
+ [
## Setting force logging
](#Appendix.Oracle.CommonDBATasks.SettingForceLogging)
+ [
## Setting supplemental logging
](#Appendix.Oracle.CommonDBATasks.AddingSupplementalLogging)
+ [
## Switching online log files
](#Appendix.Oracle.CommonDBATasks.SwitchingLogfiles)
+ [
## Adding online redo logs
](#Appendix.Oracle.CommonDBATasks.RedoLogs)
+ [
## Dropping online redo logs
](#Appendix.Oracle.CommonDBATasks.DroppingRedoLogs)
+ [
# Resizing online redo logs
](Appendix.Oracle.CommonDBATasks.ResizingRedoLogs.md)
+ [
# Retaining archived redo logs
](Appendix.Oracle.CommonDBATasks.RetainRedoLogs.md)
+ [
# Accessing online and archived redo logs
](Appendix.Oracle.CommonDBATasks.Log.Download.md)
+ [
# Downloading archived redo logs from Amazon S3
](Appendix.Oracle.CommonDBATasks.download-redo-logs.md)
## Setting force logging
In force logging mode, Oracle logs all changes to the database except changes in temporary tablespaces and temporary segments (`NOLOGGING` clauses are ignored). For more information, see [Specifying FORCE LOGGING mode](https://docs.oracle.com/cd/E11882_01/server.112/e25494/create.htm#ADMIN11096) in the Oracle documentation.
To set force logging, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.force_logging`. The `force_logging` procedure has the following parameters.
****
| Parameter name | Data type | Default | Yes | Description |
| --- | --- | --- | --- | --- |
| `p_enable` | boolean | true | No | Set to `true` to put the database in force logging mode, `false` to remove the database from force logging mode. |
The following example puts the database in force logging mode.
```
EXEC rdsadmin.rdsadmin_util.force_logging(p_enable => true);
```
## Setting supplemental logging
If you enable supplemental logging, LogMiner has the necessary information to support chained rows and clustered tables. For more information, see [Supplemental logging](https://docs.oracle.com/cd/E11882_01/server.112/e22490/logminer.htm#SUTIL1582) in the Oracle documentation.
Oracle Database doesn't enable supplemental logging by default. To enable and disable supplemental logging, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.alter_supplemental_logging`. For more information about how Amazon RDS manages the retention of archived redo logs for Oracle DB instances, see [Retaining archived redo logs](Appendix.Oracle.CommonDBATasks.RetainRedoLogs.md).
The `alter_supplemental_logging` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_action` | varchar2 | — | Yes | `'ADD'` to add supplemental logging, `'DROP'` to drop supplemental logging. |
| `p_type` | varchar2 | null | No | The type of supplemental logging. Valid values are `'ALL'`, `'FOREIGN KEY'`, `'PRIMARY KEY'`, `'UNIQUE'`, or `PROCEDURAL`. |
The following example enables supplemental logging.
```
begin
rdsadmin.rdsadmin_util.alter_supplemental_logging(
p_action => 'ADD');
end;
/
```
The following example enables supplemental logging for all fixed-length maximum size columns.
```
begin
rdsadmin.rdsadmin_util.alter_supplemental_logging(
p_action => 'ADD',
p_type => 'ALL');
end;
/
```
The following example enables supplemental logging for primary key columns.
```
begin
rdsadmin.rdsadmin_util.alter_supplemental_logging(
p_action => 'ADD',
p_type => 'PRIMARY KEY');
end;
/
```
## Switching online log files
To switch log files, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.switch_logfile`. The `switch_logfile` procedure has no parameters.
The following example switches log files.
```
EXEC rdsadmin.rdsadmin_util.switch_logfile;
```
## Adding online redo logs
An Amazon RDS DB instance running Oracle starts with four online redo logs, 128 MB each. To add additional redo logs, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.add_logfile`.
The `add_logfile` procedure has the following parameters.
**Note**
The parameters are mutually exclusive.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bytes` | positive | null | No | The size of the log file in bytes. Use this parameter only if the size of the log is under 2147483648 bytes (2 GiB). Otherwise, RDS issues an error. For log sizes above this byte value, use the `p_size` parameter instead. |
| `p_size` | varchar2 | — | Yes | The size of the log file in kilobytes (K), megabytes (M), or gigabytes (G). |
The following command adds a 100 MB log file.
```
EXEC rdsadmin.rdsadmin_util.add_logfile(p_size => '100M');
```
## Dropping online redo logs
To drop redo logs, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.drop_logfile`. The `drop_logfile` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `grp` | positive | — | Yes | The group number of the log. |
The following example drops the log with group number 3.
```
EXEC rdsadmin.rdsadmin_util.drop_logfile(grp => 3);
```
You can only drop logs that have a status of unused or inactive. The following example gets the statuses of the logs.
```
SELECT GROUP#, STATUS FROM V$LOG;
GROUP# STATUS
---------- ----------------
1 CURRENT
2 INACTIVE
3 INACTIVE
4 UNUSED
```
# Resizing online redo logs
An Amazon RDS DB instance running Oracle starts with four online redo logs, 128 MB each. The following example shows how you can use Amazon RDS procedures to resize your logs from 128 MB each to 512 MB each.
```
/* Query V$LOG to see the logs. */
/* You start with 4 logs of 128 MB each. */
SELECT GROUP#, BYTES, STATUS FROM V$LOG;
GROUP# BYTES STATUS
---------- ---------- ----------------
1 134217728 INACTIVE
2 134217728 CURRENT
3 134217728 INACTIVE
4 134217728 INACTIVE
/* Add four new logs that are each 512 MB */
EXEC rdsadmin.rdsadmin_util.add_logfile(bytes => 536870912);
EXEC rdsadmin.rdsadmin_util.add_logfile(bytes => 536870912);
EXEC rdsadmin.rdsadmin_util.add_logfile(bytes => 536870912);
EXEC rdsadmin.rdsadmin_util.add_logfile(bytes => 536870912);
/* Query V$LOG to see the logs. */
/* Now there are 8 logs. */
SELECT GROUP#, BYTES, STATUS FROM V$LOG;
GROUP# BYTES STATUS
---------- ---------- ----------------
1 134217728 INACTIVE
2 134217728 CURRENT
3 134217728 INACTIVE
4 134217728 INACTIVE
5 536870912 UNUSED
6 536870912 UNUSED
7 536870912 UNUSED
8 536870912 UNUSED
/* Drop each inactive log using the group number. */
EXEC rdsadmin.rdsadmin_util.drop_logfile(grp => 1);
EXEC rdsadmin.rdsadmin_util.drop_logfile(grp => 3);
EXEC rdsadmin.rdsadmin_util.drop_logfile(grp => 4);
/* Query V$LOG to see the logs. */
/* Now there are 5 logs. */
select GROUP#, BYTES, STATUS from V$LOG;
GROUP# BYTES STATUS
---------- ---------- ----------------
2 134217728 CURRENT
5 536870912 UNUSED
6 536870912 UNUSED
7 536870912 UNUSED
8 536870912 UNUSED
/* Switch logs so that group 2 is no longer current. */
EXEC rdsadmin.rdsadmin_util.switch_logfile;
/* Query V$LOG to see the logs. */
/* Now one of the new logs is current. */
SQL>SELECT GROUP#, BYTES, STATUS FROM V$LOG;
GROUP# BYTES STATUS
---------- ---------- ----------------
2 134217728 ACTIVE
5 536870912 CURRENT
6 536870912 UNUSED
7 536870912 UNUSED
8 536870912 UNUSED
/* If the status of log 2 is still "ACTIVE", issue a checkpoint to clear it to "INACTIVE". */
EXEC rdsadmin.rdsadmin_util.checkpoint;
/* Query V$LOG to see the logs. */
/* Now the final original log is inactive. */
select GROUP#, BYTES, STATUS from V$LOG;
GROUP# BYTES STATUS
---------- ---------- ----------------
2 134217728 INACTIVE
5 536870912 CURRENT
6 536870912 UNUSED
7 536870912 UNUSED
8 536870912 UNUSED
# Drop the final inactive log.
EXEC rdsadmin.rdsadmin_util.drop_logfile(grp => 2);
/* Query V$LOG to see the logs. */
/* Now there are four 512 MB logs. */
SELECT GROUP#, BYTES, STATUS FROM V$LOG;
GROUP# BYTES STATUS
---------- ---------- ----------------
5 536870912 CURRENT
6 536870912 UNUSED
7 536870912 UNUSED
8 536870912 UNUSED
```
# Retaining archived redo logs
You can retain archived redo logs locally on your DB instance for use with products like Oracle LogMiner (`DBMS_LOGMNR`). After you have retained the redo logs, you can use LogMiner to analyze the logs. For more information, see [Using LogMiner to analyze redo log files](http://docs.oracle.com/cd/E11882_01/server.112/e22490/logminer.htm) in the Oracle documentation.
To retain archived redo logs, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.set_configuration`. If you use this procedure on a primary instance in Oracle Data Guard, RDS changes the archive log retention setting on the primary instance and open read replicas, but not on mounted replicas. RDS retains the latest archive redo logs on mounted replicas for a short period of time. RDS automatically deletes older logs downloaded to mounted replicas.
The `set_configuration` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | varchar | — | Yes | The name of the configuration to update. To change the archived redo log retention hours, set the name to `archivelog retention hours`. |
| `value` | varchar | — | Yes | The value for the configuration. Set the value the number of hours to retain the logs. |
The following example retains 24 hours of redo logs.
```
begin
rdsadmin.rdsadmin_util.set_configuration(
name => 'archivelog retention hours',
value => '24');
end;
/
commit;
```
**Note**
The commit is required for the change to take effect.
To view how long archived redo logs are kept for your DB instance, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.show_configuration`.
The following example shows the log retention time.
```
set serveroutput on
EXEC rdsadmin.rdsadmin_util.show_configuration;
```
The output shows the current setting for `archivelog retention hours`. The following output shows that archived redo logs are kept for 48 hours.
```
NAME:archivelog retention hours
VALUE:48
DESCRIPTION:ArchiveLog expiration specifies the duration in hours before archive/redo log files are automatically deleted.
```
Because the archived redo logs are retained on your DB instance, ensure that your DB instance has enough allocated storage for the retained logs. To determine how much space your DB instance has used in the last X hours, you can run the following query, replacing X with the number of hours.
```
SELECT SUM(BLOCKS * BLOCK_SIZE) bytes
FROM V$ARCHIVED_LOG
WHERE FIRST_TIME >= SYSDATE-(X/24) AND DEST_ID=1;
```
RDS for Oracle only generates archived redo logs when the backup retention period of your DB instance is greater than zero. By default the backup retention period is greater than zero.
When the archived log retention period expires, RDS for Oracle removes the archived redo logs from your DB instance. To support restoring your DB instance to a point in time, Amazon RDS retains the archived redo logs outside of your DB instance based on the backup retention period. To modify the backup retention period, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
**Note**
In some cases, you might be using JDBC on Linux to download archived redo logs and experience long latency times and connection resets. In such cases, the issues might be caused by the default random number generator setting on your Java client. We recommend setting your JDBC drivers to use a nonblocking random number generator.
# Accessing online and archived redo logs
You might want to access your online and archived redo log files for mining with external tools such as GoldenGate, Attunity, Informatica, and others. To access these files, do the following:
1. Create directory objects that provide read-only access to the physical file paths.
Use `rdsadmin.rdsadmin_master_util.create_archivelog_dir` and `rdsadmin.rdsadmin_master_util.create_onlinelog_dir`.
1. Read the files using PL/SQL.
You can read the files by using PL/SQL. For more information about reading files from directory objects, see [Listing files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ListDirectories) and [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles).
Accessing transaction logs is supported for the following releases:
+ Oracle Database 21c
+ Oracle Database 19c
The following code creates directories that provide read-only access to your online and archived redo log files:
**Important**
This code also revokes the `DROP ANY DIRECTORY` privilege.
```
EXEC rdsadmin.rdsadmin_master_util.create_archivelog_dir;
EXEC rdsadmin.rdsadmin_master_util.create_onlinelog_dir;
```
The following code drops the directories for your online and archived redo log files.
```
EXEC rdsadmin.rdsadmin_master_util.drop_archivelog_dir;
EXEC rdsadmin.rdsadmin_master_util.drop_onlinelog_dir;
```
The following code grants and revokes the `DROP ANY DIRECTORY` privilege.
```
EXEC rdsadmin.rdsadmin_master_util.revoke_drop_any_directory;
EXEC rdsadmin.rdsadmin_master_util.grant_drop_any_directory;
```
# Downloading archived redo logs from Amazon S3
You can download archived redo logs on your DB instance using the `rdsadmin.rdsadmin_archive_log_download` package. If archived redo logs are no longer on your DB instance, you might want to download them again from Amazon S3. Then you can mine the logs or use them to recover or replicate your database.
**Note**
You can't download archived redo logs on read replica instances.
## Downloading archived redo logs: basic steps
The availability of your archived redo logs depends on the following retention policies:
+ Backup retention policy – Logs inside of this policy are available in Amazon S3. Logs outside of this policy are removed.
+ Archived log retention policy – Logs inside of this policy are available on your DB instance. Logs outside of this policy are removed.
If logs aren't on your instance but are protected by your backup retention period, use `rdsadmin.rdsadmin_archive_log_download` to download them again. RDS for Oracle saves the logs to the `/rdsdbdata/log/arch` directory on your DB instance.
**To download archived redo logs from Amazon S3**
1. Configure your retention period to ensure your downloaded archived redo logs are retained for the duration you need them. Make sure to `COMMIT` your change.
RDS retains your downloaded logs according to the archived log retention policy, starting from the time the logs were downloaded. To learn how to set the retention policy, see [Retaining archived redo logs](Appendix.Oracle.CommonDBATasks.RetainRedoLogs.md).
1. Wait up to 5 minutes for the archived log retention policy change to take effect.
1. Download the archived redo logs from Amazon S3 using `rdsadmin.rdsadmin_archive_log_download`.
For more information, see [Downloading a single archived redo log](#Appendix.Oracle.CommonDBATasks.download-redo-logs.single-log) and [Downloading a series of archived redo logs](#Appendix.Oracle.CommonDBATasks.download-redo-logs.series).
**Note**
RDS automatically checks the available storage before downloading. If the requested logs consume a high percentage of space, you receive an alert.
1. Confirm that the logs were downloaded from Amazon S3 successfully.
You can view the status of your download task in a bdump file. The bdump files have the path name `/rdsdbdata/log/trace/dbtask-task-id.log`. In the preceding download step, you run a `SELECT` statement that returns the task ID in a `VARCHAR2` data type. For more information, see similar examples in [Monitoring the status of a file transfer](oracle-s3-integration.using.md#oracle-s3-integration.using.task-status).
## Downloading a single archived redo log
To download a single archived redo log to the `/rdsdbdata/log/arch` directory, use `rdsadmin.rdsadmin_archive_log_download.download_log_with_seqnum`. This procedure has the following parameter.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `seqnum` | number | — | Yes | The sequence number of the archived redo log. |
The following example downloads the log with sequence number 20.
```
SELECT rdsadmin.rdsadmin_archive_log_download.download_log_with_seqnum(seqnum => 20)
AS TASK_ID
FROM DUAL;
```
## Downloading a series of archived redo logs
To download a series of archived redo logs to the `/rdsdbdata/log/arch` directory, use `download_logs_in_seqnum_range`. Your download is limited to 300 logs per request. The `download_logs_in_seqnum_range` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `start_seq` | number | — | Yes | The starting sequence number for the series. |
| `end_seq` | number | — | Yes | The ending sequence number for the series. |
The following example downloads the logs from sequence 50 to 100.
```
SELECT rdsadmin.rdsadmin_archive_log_download.download_logs_in_seqnum_range(start_seq => 50, end_seq => 100)
AS TASK_ID
FROM DUAL;
```
# Performing common RMAN tasks for Oracle DB instances
In the following section, you can find how you can perform Oracle Recovery Manager (RMAN) DBA tasks on your Amazon RDS DB instances running Oracle. To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances. It also restricts access to certain system procedures and tables that require advanced privileges.
Use the Amazon RDS package `rdsadmin.rdsadmin_rman_util` to perform RMAN backups of your Amazon RDS for Oracle database to disk. The `rdsadmin.rdsadmin_rman_util` package supports full and incremental database file backups, tablespace backups, and archived redo log backups.
After an RMAN backup has finished, you can copy the backup files off the Amazon RDS for Oracle DB instance host. You might do this for the purpose of restoring to a non-RDS host or for long-term storage of backups. For example, you can copy the backup files to an Amazon S3 bucket. For more information, see using [Amazon S3 integration](oracle-s3-integration.md).
The backup files for RMAN backups remain on the Amazon RDS DB instance host until you remove them manually. You can use the `UTL_FILE.FREMOVE` Oracle procedure to remove files from a directory. For more information, see [FREMOVE procedure](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924) in the Oracle Database documentation.
You can't use the RMAN to restore RDS for Oracle DB instances. However, you can use RMAN to restore a backup to an on-premises or Amazon EC2 instance. For more information, see the blog article [Restore an Amazon RDS for Oracle instance to a self-managed instance](https://aws.amazon.com/blogs/database/restore-an-amazon-rds-for-oracle-instance-to-a-self-managed-instance/).
**Note**
For backing up and restoring to another Amazon RDS for Oracle DB instance, you can continue to use the Amazon RDS backup and restore features. For more information, see [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md).
**Topics**
+ [
# Prerequisites for RMAN backups
](Appendix.Oracle.CommonDBATasks.RMAN-requirements.md)
+ [
# Common parameters for RMAN procedures
](Appendix.Oracle.CommonDBATasks.CommonParameters.md)
+ [
# Validating database files in RDS for Oracle
](Appendix.Oracle.CommonDBATasks.ValidateDBFiles.md)
+ [
# Enabling and disabling block change tracking
](Appendix.Oracle.CommonDBATasks.BlockChangeTracking.md)
+ [
# Crosschecking archived redo logs
](Appendix.Oracle.CommonDBATasks.Crosscheck.md)
+ [
# Backing up archived redo log files
](Appendix.Oracle.CommonDBATasks.BackupArchivedLogs.md)
+ [
# Performing a full database backup
](Appendix.Oracle.CommonDBATasks.BackupDatabaseFull.md)
+ [
# Performing a full backup of a tenant database
](Appendix.Oracle.CommonDBATasks.BackupTenantDatabaseFull.md)
+ [
# Performing an incremental database backup
](Appendix.Oracle.CommonDBATasks.BackupDatabaseIncremental.md)
+ [
# Performing an incremental backup of a tenant database
](Appendix.Oracle.CommonDBATasks.BackupTenantDatabaseIncremental.md)
+ [
# Backing up a tablespace
](Appendix.Oracle.CommonDBATasks.BackupTablespace.md)
+ [
# Backing up a control file
](Appendix.Oracle.CommonDBATasks.backup-control-file.md)
+ [
# Performing block media recovery
](Appendix.Oracle.CommonDBATasks.block-media-recovery.md)
# Prerequisites for RMAN backups
Before backing up your database using the `rdsadmin.rdsadmin_rman_util` package, make sure that you meet the following prerequisites:
+ Make sure that your RDS for Oracle database is in `ARCHIVELOG` mode. To enable this mode, set the backup retention period to a non-zero value.
+ When backing up archived redo logs or performing a full or incremental backup that includes archived redo logs, and when backing up the database, make sure that redo log retention is set to a nonzero value. Archived redo logs are required to make database files consistent during recovery. For more information, see [Retaining archived redo logs](Appendix.Oracle.CommonDBATasks.RetainRedoLogs.md).
+ Make sure that your DB instance has sufficient free space to hold the backups. When back up your database, you specify an Oracle directory object as a parameter in the procedure call. RMAN places the files in the specified directory. You can use default directories, such as `DATA_PUMP_DIR`, or create a new directory. For more information, see [Creating and dropping directories in the main data storage space](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.NewDirectories).
You can monitor the current free space in an RDS for Oracle instance using the CloudWatch metric `FreeStorageSpace`. We recommend that your free space exceeds the current size of the database, though RMAN backs up only formatted blocks and supports compression.
# Common parameters for RMAN procedures
You can use procedures in the Amazon RDS package `rdsadmin.rdsadmin_rman_util` to perform tasks with RMAN. Several parameters are common to the procedures in the package. The package has the following common parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_directory_name` | varchar2 | A valid database directory name. | — | Yes | The name of the directory to contain the backup files. |
| `p_label` | varchar2 | `a-z`, `A-Z`, `0-9`, `'_'`, `'-'`, `'.'` | — | No | A unique string that is included in the backup file names. The limit is 30 characters. |
| `p_owner` | varchar2 | A valid owner of the directory specified in `p_directory_name`. | — | Yes | The owner of the directory to contain the backup files. |
| `p_tag` | varchar2 | `a-z`, `A-Z`, `0-9`, `'_'`, `'-'`, `'.'` | NULL | No | A string that can be used to distinguish between backups to indicate the purpose or usage of backups, such as daily, weekly, or incremental-level backups. The limit is 30 characters. The tag is not case-sensitive. Tags are always stored in uppercase, regardless of the case used when entering them. Tags don't need to be unique, so multiple backups can have the same tag. If you don't specify a tag, then RMAN assigns a default tag automatically using the format `TAGYYYYMMDDTHHMMSS`, where *YYYY* is the year, *MM* is the month, *DD* is the day, *HH* is the hour (in 24-hour format), *MM* is the minutes, and *SS* is the seconds. The date and time refer to when RMAN started the backup. For example, a backup might receive a tag `TAG20190927T214517` for a backup that started on 2019-09-27 at 21:45:17. The `p_tag` parameter is supported for the following Amazon RDS for Oracle DB engine versions: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.CommonParameters.html) |
| `p_compress` | boolean | `TRUE`, `FALSE` | `FALSE` | No | Specify `TRUE` to enable BASIC backup compression. Specify `FALSE` to disable BASIC backup compression. |
| `p_include_archive_logs` | boolean | `TRUE`, `FALSE` | `FALSE` | No | Specify `TRUE` to include archived redo logs in the backup. Specify `FALSE` to exclude archived redo logs from the backup. If you include archived redo logs in the backup, set retention to one hour or greater using the `rdsadmin.rdsadmin_util.set_configuration` procedure. Also, call the `rdsadmin.rdsadmin_rman_util.crosscheck_archivelog` procedure immediately before running the backup. Otherwise, the backup might fail due to missing archived redo log files that have been deleted by Amazon RDS management procedures. |
| `p_include_controlfile` | boolean | `TRUE`, `FALSE` | `FALSE` | No | Specify `TRUE` to include the control file in the backup. Specify `FALSE` to exclude the control file from the backup. |
| `p_optimize` | boolean | `TRUE`, `FALSE` | `TRUE` | No | Specify `TRUE` to enable backup optimization, if archived redo logs are included, to reduce backup size. Specify `FALSE` to disable backup optimization. |
| `p_parallel` | number | A valid integer between `1` and `254` for Oracle Database Enterprise Edition (EE) `1` for other Oracle Database editions | `1` | No | Number of channels. |
| `p_rman_to_dbms_output` | boolean | `TRUE`, `FALSE` | `FALSE` | No | When `TRUE`, the RMAN output is sent to the `DBMS_OUTPUT` package in addition to a file in the `BDUMP` directory. In SQL\$1Plus, use `SET SERVEROUTPUT ON` to see the output. When `FALSE`, the RMAN output is only sent to a file in the `BDUMP` directory. |
| `p_section_size_mb` | number | A valid integer | `NULL` | No | The section size in megabytes (MB). Validates in parallel by dividing each file into the specified section size. When `NULL`, the parameter is ignored. |
| `p_validation_type` | varchar2 | `'PHYSICAL'`, `'PHYSICAL+LOGICAL'` | `'PHYSICAL'` | No | The level of corruption detection. Specify `'PHYSICAL'` to check for physical corruption. An example of physical corruption is a block with a mismatch in the header and footer. Specify `'PHYSICAL+LOGICAL'` to check for logical inconsistencies in addition to physical corruption. An example of logical corruption is a corrupt block. |
# Validating database files in RDS for Oracle
You can use the Amazon RDS package `rdsadmin.rdsadmin_rman_util` to validate Amazon RDS for Oracle database files, such as data files, tablespaces, control files, and server parameter files (SPFILEs).
For more information about RMAN validation, see [ Validating database files and backups](https://docs.oracle.com/database/121/BRADV/rcmvalid.htm#BRADV90063) and [ VALIDATE](https://docs.oracle.com/database/121/RCMRF/rcmsynta2025.htm#RCMRF162) in the Oracle documentation.
**Topics**
+ [
## Validating a database
](#Appendix.Oracle.CommonDBATasks.ValidateDB)
+ [
## Validating a tenant database
](#Appendix.Oracle.CommonDBATasks.ValidateTenantDB)
+ [
## Validating a tablespace
](#Appendix.Oracle.CommonDBATasks.ValidateTablespace)
+ [
## Validating a control file
](#Appendix.Oracle.CommonDBATasks.ValidateControlFile)
+ [
## Validating an SPFILE
](#Appendix.Oracle.CommonDBATasks.ValidateSpfile)
+ [
## Validating an Oracle data file
](#Appendix.Oracle.CommonDBATasks.ValidateDataFile)
## Validating a database
To validate all of the relevant files used by an Oracle database in RDS for Oracle, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.validate_database`.
This procedure uses the following common parameters for RMAN tasks:
+ `p_validation_type`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_rman_to_dbms_output`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
The following example validates the database using the default values for the parameters.
```
EXEC rdsadmin.rdsadmin_rman_util.validate_database;
```
The following example validates the database using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.validate_database(
p_validation_type => 'PHYSICAL+LOGICAL',
p_parallel => 4,
p_section_size_mb => 10,
p_rman_to_dbms_output => FALSE);
END;
/
```
When the `p_rman_to_dbms_output` parameter is set to `FALSE`, the RMAN output is written to a file in the `BDUMP` directory.
To view the files in the `BDUMP` directory, run the following `SELECT` statement.
```
SELECT * FROM table(rdsadmin.rds_file_util.listdir('BDUMP')) order by mtime;
```
To view the contents of a file in the `BDUMP` directory, run the following `SELECT` statement.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','rds-rman-validate-nnn.txt'));
```
Replace the file name with the name of the file you want to view.
## Validating a tenant database
To validate the data files of the tenant database in a container database (CDB), use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.validate_tenant`.
This procedure applies only to the current tenant database and uses the following common parameters for RMAN tasks:
+ `p_validation_type`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_rman_to_dbms_output`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md). This procedure is supported for the following DB engine versions:
+ Oracle Database 21c (21.0.0) CDB
+ Oracle Database 19c (19.0.0) CDB
The following example validates the current tenant database using the default values for the parameters.
```
EXEC rdsadmin.rdsadmin_rman_util.validate_tenant;
```
The following example validates the current tenant database using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.validate_tenant(
p_validation_type => 'PHYSICAL+LOGICAL',
p_parallel => 4,
p_section_size_mb => 10,
p_rman_to_dbms_output => FALSE);
END;
/
```
When the `p_rman_to_dbms_output` parameter is set to `FALSE`, the RMAN output is written to a file in the `BDUMP` directory.
To view the files in the `BDUMP` directory, run the following `SELECT` statement.
```
SELECT * FROM table(rdsadmin.rds_file_util.listdir('BDUMP')) order by mtime;
```
To view the contents of a file in the `BDUMP` directory, run the following `SELECT` statement.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','rds-rman-validate-nnn.txt'));
```
Replace the file name with the name of the file you want to view.
## Validating a tablespace
To validate the files associated with a tablespace, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.validate_tablespace`.
This procedure uses the following common parameters for RMAN tasks:
+ `p_validation_type`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_rman_to_dbms_output`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure also uses the following additional parameter.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_tablespace_name` | varchar2 | A valid tablespace name | — | Yes | The name of the tablespace. |
## Validating a control file
To validate only the control file used by an Amazon RDS Oracle DB instance, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.validate_current_controlfile`.
This procedure uses the following common parameter for RMAN tasks:
+ `p_validation_type`
+ `p_rman_to_dbms_output`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
## Validating an SPFILE
To validate only the server parameter file (SPFILE) used by an Amazon RDS Oracle DB instance, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.validate_spfile`.
This procedure uses the following common parameter for RMAN tasks:
+ `p_validation_type`
+ `p_rman_to_dbms_output`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
## Validating an Oracle data file
To validate a data file, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.validate_datafile`.
This procedure uses the following common parameters for RMAN tasks:
+ `p_validation_type`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_rman_to_dbms_output`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure also uses the following additional parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_datafile` | varchar2 | A valid datafile ID number or a valid datafile name including complete path | — | Yes | The datafile ID number (from `v$datafile.file#`) or the full datafile name including the path (from `v$datafile.name`). |
| `p_from_block` | number | A valid integer | `NULL` | No | The number of the block where the validation starts within the data file. When this is `NULL`, `1` is used. |
| `p_to_block` | number | A valid integer | `NULL` | No | The number of the block where the validation ends within the data file. When this is `NULL`, the maximum block in the data file is used. |
# Enabling and disabling block change tracking
Block changing tracking records changed blocks in a tracking file. This technique can improve the performance of RMAN incremental backups. For more information, see [Using Block Change Tracking to Improve Incremental Backup Performance](https://docs.oracle.com/en/database/oracle/oracle-database/19/bradv/backing-up-database.html#GUID-4E1F605A-76A7-48D0-9D9B-7343B4327E2A) in the Oracle Database documentation.
RMAN features aren't supported in a read replica. However, as part of your high availability strategy, you might choose to enable block tracking in a read-only replica using the procedure `rdsadmin.rdsadmin_rman_util.enable_block_change_tracking`. If you promote this read-only replica to a source DB instance, block change tracking is enabled for the new source instance. Thus, your instance can benefit from fast incremental backups.
Block change tracking procedures are supported in Enterprise Edition only for the following DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
**Note**
In a single-tenant CDB, the following operations work, but no customer-visible mechanism can detect the current status of the operations. See also [Limitations of RDS for Oracle CDBs](Oracle.Concepts.CDBs.md#Oracle.Concepts.single-tenant-limitations).
To enable block change tracking for a DB instance, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.enable_block_change_tracking`. To disable block change tracking, use `disable_block_change_tracking`. These procedures take no parameters.
To determine whether block change tracking is enabled for your DB instance, run the following query.
```
SELECT STATUS, FILENAME FROM V$BLOCK_CHANGE_TRACKING;
```
The following example enables block change tracking for a DB instance.
```
EXEC rdsadmin.rdsadmin_rman_util.enable_block_change_tracking;
```
The following example disables block change tracking for a DB instance.
```
EXEC rdsadmin.rdsadmin_rman_util.disable_block_change_tracking;
```
# Crosschecking archived redo logs
You can crosscheck archived redo logs using the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.crosscheck_archivelog`.
You can use this procedure to crosscheck the archived redo logs registered in the control file and optionally delete the expired logs records. When RMAN makes a backup, it creates a record in the control file. Over time, these records increase the size of the control file. We recommend that you remove expired records periodically.
**Note**
Standard Amazon RDS backups don't use RMAN and therefore don't create records in the control file.
This procedure uses the common parameter `p_rman_to_dbms_output` for RMAN tasks.
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure also uses the following additional parameter.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_delete_expired` | boolean | `TRUE`, `FALSE` | `TRUE` | No | When `TRUE`, delete expired archived redo log records from the control file. When `FALSE`, retain the expired archived redo log records in the control file. |
This procedure is supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
The following example marks archived redo log records in the control file as expired, but does not delete the records.
```
BEGIN
rdsadmin.rdsadmin_rman_util.crosscheck_archivelog(
p_delete_expired => FALSE,
p_rman_to_dbms_output => FALSE);
END;
/
```
The following example deletes expired archived redo log records from the control file.
```
BEGIN
rdsadmin.rdsadmin_rman_util.crosscheck_archivelog(
p_delete_expired => TRUE,
p_rman_to_dbms_output => FALSE);
END;
/
```
# Backing up archived redo log files
You can use the Amazon RDS package `rdsadmin.rdsadmin_rman_util` to back up archived redo logs for an Amazon RDS Oracle DB instance.
The procedures for backing up archived redo logs are supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
**Topics**
+ [
## Backing up all archived redo logs
](#Appendix.Oracle.CommonDBATasks.BackupArchivedLogs.All)
+ [
## Backing up an archived redo log from a date range
](#Appendix.Oracle.CommonDBATasks.BackupArchivedLogs.Date)
+ [
## Backing up an archived redo log from an SCN range
](#Appendix.Oracle.CommonDBATasks.BackupArchivedLogs.SCN)
+ [
## Backing up an archived redo log from a sequence number range
](#Appendix.Oracle.CommonDBATasks.BackupArchivedLogs.Sequence)
## Backing up all archived redo logs
To back up all of the archived redo logs for an Amazon RDS Oracle DB instance, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_archivelog_all`.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
The following example backs up all archived redo logs for the DB instance.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_archivelog_all(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_parallel => 4,
p_tag => 'MY_LOG_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
## Backing up an archived redo log from a date range
To back up specific archived redo logs for an Amazon RDS Oracle DB instance by specifying a date range, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_archivelog_date`. The date range specifies which archived redo logs to back up.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure also uses the following additional parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_from_date` | date | A date that is between the `start_date` and `next_date` of an archived redo log that exists on disk. The value must be less than or equal to the value specified for `p_to_date`. | — | Yes | The starting date for the archived log backups. |
| `p_to_date` | date | A date that is between the `start_date` and `next_date` of an archived redo log that exists on disk. The value must be greater than or equal to the value specified for `p_from_date`. | — | Yes | The ending date for the archived log backups. |
The following example backs up archived redo logs in the date range for the DB instance.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_archivelog_date(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_from_date => '03/01/2019 00:00:00',
p_to_date => '03/02/2019 00:00:00',
p_parallel => 4,
p_tag => 'MY_LOG_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
## Backing up an archived redo log from an SCN range
To back up specific archived redo logs for an Amazon RDS Oracle DB instance by specifying a system change number (SCN) range, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_archivelog_scn`. The SCN range specifies which archived redo logs to back up.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure also uses the following additional parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_from_scn` | number | An SCN of an archived redo log that exists on disk. The value must be less than or equal to the value specified for `p_to_scn`. | — | Yes | The starting SCN for the archived log backups. |
| `p_to_scn` | number | An SCN of an archived redo log that exists on disk. The value must be greater than or equal to the value specified for `p_from_scn`. | — | Yes | The ending SCN for the archived log backups. |
The following example backs up archived redo logs in the SCN range for the DB instance.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_archivelog_scn(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_from_scn => 1533835,
p_to_scn => 1892447,
p_parallel => 4,
p_tag => 'MY_LOG_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
## Backing up an archived redo log from a sequence number range
To back up specific archived redo logs for an Amazon RDS Oracle DB instance by specifying a sequence number range, use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_archivelog_sequence`. The sequence number range specifies which archived redo logs to back up.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure also uses the following additional parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_from_sequence` | number | A sequence number an archived redo log that exists on disk. The value must be less than or equal to the value specified for `p_to_sequence`. | — | Yes | The starting sequence number for the archived log backups. |
| `p_to_sequence` | number | A sequence number of an archived redo log that exists on disk. The value must be greater than or equal to the value specified for `p_from_sequence`. | — | Yes | The ending sequence number for the archived log backups. |
The following example backs up archived redo logs in the sequence number range for the DB instance.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_archivelog_sequence(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_from_sequence => 11160,
p_to_sequence => 11160,
p_parallel => 4,
p_tag => 'MY_LOG_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
# Performing a full database backup
You can perform a backup of all blocks of data files included in the backup using Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_database_full`.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_include_archive_logs`
+ `p_optimize`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure is supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
The following example performs a full backup of the DB instance using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_database_full(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_parallel => 4,
p_section_size_mb => 10,
p_tag => 'FULL_DB_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
# Performing a full backup of a tenant database
You can perform a backup of all data blocks included a tenant database in a container database (CDB). Use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_tenant_full`. This procedure applies only to the current database backup and uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_include_archive_logs`
+ `p_optimize`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
The `rdsadmin_rman_util.backup_tenant_full` procedure is supported for the following RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0) CDB
+ Oracle Database 19c (19.0.0) CDB
The following example performs a full backup of the current tenant database using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_tenant_full(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_parallel => 4,
p_section_size_mb => 10,
p_tag => 'FULL_TENANT_DB_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
# Performing an incremental database backup
You can perform an incremental backup of your DB instance using the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_database_incremental`.
For more information about incremental backups, see [Incremental backups](https://docs.oracle.com/database/121/RCMRF/rcmsynta006.htm#GUID-73642FF2-43C5-48B2-9969-99001C52EB50__BGBHABHH) in the Oracle documentation.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_include_archive_logs`
+ `p_include_controlfile`
+ `p_optimize`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure is supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
This procedure also uses the following additional parameter.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_level` | number | `0`, `1` | `0` | No | Specify `0` to enable a full incremental backup. Specify `1` to enable a non-cumulative incremental backup. |
The following example performs an incremental backup of the DB instance using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_database_incremental(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_level => 1,
p_parallel => 4,
p_section_size_mb => 10,
p_tag => 'MY_INCREMENTAL_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
# Performing an incremental backup of a tenant database
You can perform an incremental backup of the current tenant database in your CDB. Use the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_tenant_incremental`.
For more information about incremental backups, see [Incremental backups](https://docs.oracle.com/database/121/RCMRF/rcmsynta006.htm#GUID-73642FF2-43C5-48B2-9969-99001C52EB50__BGBHABHH) in the Oracle Database documentation.
This procedure applies only to the current tenant database and uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_include_archive_logs`
+ `p_include_controlfile`
+ `p_optimize`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure is supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0) CDB
+ Oracle Database 19c (19.0.0) CDB
This procedure also uses the following additional parameter.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_level` | number | `0`, `1` | `0` | No | Specify `0` to enable a full incremental backup. Specify `1` to enable a non-cumulative incremental backup. |
The following example performs an incremental backup of the current tenant database using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_tenant_incremental(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_level => 1,
p_parallel => 4,
p_section_size_mb => 10,
p_tag => 'MY_INCREMENTAL_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
# Backing up a tablespace
You can back up a tablespace using the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_tablespace`.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_parallel`
+ `p_section_size_mb`
+ `p_include_archive_logs`
+ `p_include_controlfile`
+ `p_optimize`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure also uses the following additional parameter.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_tablespace_name` | varchar2 | A valid tablespace name. | — | Yes | The name of the tablespace to back up. |
This procedure is supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
The following example performs a tablespace backup using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_tablespace(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_tablespace_name => 'MYTABLESPACE',
p_parallel => 4,
p_section_size_mb => 10,
p_tag => 'MYTABLESPACE_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
# Backing up a control file
You can back up a control file using the Amazon RDS procedure `rdsadmin.rdsadmin_rman_util.backup_current_controlfile`.
This procedure uses the following common parameters for RMAN tasks:
+ `p_owner`
+ `p_directory_name`
+ `p_label`
+ `p_compress`
+ `p_rman_to_dbms_output`
+ `p_tag`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure is supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
The following example backs up a control file using the specified values for the parameters.
```
BEGIN
rdsadmin.rdsadmin_rman_util.backup_current_controlfile(
p_owner => 'SYS',
p_directory_name => 'MYDIRECTORY',
p_tag => 'CONTROL_FILE_BACKUP',
p_rman_to_dbms_output => FALSE);
END;
/
```
# Performing block media recovery
You can recovery individual data blocks, known as block media recovery, using the Amazon RDS procedures `rdsadmin.rdsadmin_rman_util.recover_datafile_block`. You can use this overloaded procedure to recover either an individual data block or a range of data blocks.
This procedure uses the following common parameter for RMAN tasks:
+ `p_rman_to_dbms_output`
For more information, see [Common parameters for RMAN procedures](Appendix.Oracle.CommonDBATasks.CommonParameters.md).
This procedure uses the following additional parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `p_datafile` | `NUMBER` | A valid data file ID number. | — | Yes | The data file containing the corrupt blocks. Specify the data file in either of the following ways: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.block-media-recovery.html) |
| `p_block` | `NUMBER` | A valid integer. | — | Yes | The number of an individual block to be recovered. The following parameters are mutually exclusive: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.block-media-recovery.html) |
| `p_from_block` | `NUMBER` | A valid integer. | — | Yes | The first block number in a range of blocks to be recovered. The following parameters are mutually exclusive: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.block-media-recovery.html) |
| `p_to_block` | `NUMBER` | A valid integer. | — | Yes | The last block number in a range of blocks to be recovered. The following parameters are mutually exclusive: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.block-media-recovery.html) |
This procedure is supported for the following Amazon RDS for Oracle DB engine versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
The following example recovers block 100 in data file 5.
```
BEGIN
rdsadmin.rdsadmin_rman_util.recover_datafile_block(
p_datafile => 5,
p_block => 100,
p_rman_to_dbms_output => TRUE);
END;
/
```
The following example recovers blocks 100 to 150 in data file 5.
```
BEGIN
rdsadmin.rdsadmin_rman_util.recover_datafile_block(
p_datafile => 5,
p_from_block => 100,
p_to_block => 150,
p_rman_to_dbms_output => TRUE);
END;
/
```
# Performing common scheduling tasks for Oracle DB instances
Some scheduler jobs owned by `SYS` can interfere with normal database operations. In such cases, Oracle Support recommends that you modify the schedule. If you need to enable or disable `SYS` jobs, test the operation on scheduled jobs in a test environment before implementing it in a production environment. To perform tasks for Oracle Scheduler jobs owned by `SYS`, use the Amazon RDS package `rdsadmin.rdsadmin_dbms_scheduler`.
The `rdsadmin.rdsadmin_dbms_scheduler` procedures are supported for the Amazon RDS for Oracle DB engine versions shown in the following table. When using this package, you can specify the `SYS` jobs listed in the table.
| Database release | Jobs enabled by default | Jobs disabled by default |
| --- | --- | --- |
| Oracle Database 19c | BSLN_MAINTAIN_STATS_JOB
CLEANUP_NON_EXIST_OBJ
CLEANUP_ONLINE_IND_BUILD
CLEANUP_ONLINE_PMO
CLEANUP_TAB_IOT_PMO
CLEANUP_TRANSIENT_PKG
CLEANUP_TRANSIENT_TYPE
DRA_REEVALUATE_OPEN_FAILURES
FILE_SIZE_UPD
ORA$AUTOTASK_CLEAN
PMO_DEFERRED_GIDX_MAINT_JOB
PURGE_LOG
RSE$CLEAN_RECOVERABLE_SCRIPT
SM$CLEAN_AUTO_SPLIT_MERGE
| FGR$AUTOPURGE_JOB
FILE_WATCHER
HM_CREATE_OFFLINE_DICTIONARY
LOAD_OPATCH_INVENTORY
ORA$PREPLUGIN_BACKUP_JOB
XMLDB_NFS_CLEANUP_JOB
|
| Oracle Database 21c | BSLN_MAINTAIN_STATS_JOB
CLEANUP_NON_EXIST_OBJ
CLEANUP_ONLINE_IND_BUILD
CLEANUP_ONLINE_PMO
CLEANUP_TAB_IOT_PMO
CLEANUP_TRANSIENT_PKG
CLEANUP_TRANSIENT_TYPE
DRA_REEVALUATE_OPEN_FAILURES
FILE_SIZE_UPD
ORA$AUTOTASK_CLEAN
PMO_DEFERRED_GIDX_MAINT_JOB
PURGE_LOG
| FGR$AUTOPURGE_JOB
FILE_WATCHER
HM_CREATE_OFFLINE_DICTIONARY
LOAD_OPATCH_INVENTORY
ORA$PREPLUGIN_BACKUP_JOB
ORA$_ATSK_AUTOSTS
XMLDB_NFS_CLEANUP_JOB
|
## Common parameters for Oracle Scheduler procedures
To perform tasks with Oracle Scheduler, use procedures in the Amazon RDS package `rdsadmin.rdsadmin_dbms_scheduler`. Several parameters are common to the procedures in the package. The package has the following common parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `name` | varchar2 | The procedures listed in the table in [Performing common scheduling tasks for Oracle DB instances](#Appendix.Oracle.CommonDBATasks.Scheduler) | — | Yes | The name of the job to modify. |
| `attribute` | varchar2 | `'REPEAT_INTERVAL'`,`'SCHEDULE_NAME'` | – | Yes | Attribute to modify. To modify the repeat interval for the job, specify `'REPEAT_INTERVAL'`. To modify the schedule name for the job, specify `'SCHEDULE_NAME'`. |
| `value` | varchar2 | A valid schedule interval or schedule name, depending on attribute used. | – | Yes | The new value of the attribute. |
## Modifying DBMS\$1SCHEDULER jobs
To modify certain components of Oracle Scheduler, use the Oracle procedure `dbms_scheduler.set_attribute`. For more information, see [DBMS\$1SCHEDULER](https://docs.oracle.com/database/121/ARPLS/d_sched.htm#ARPLS72235) and [SET\$1ATTRIBUTE procedure](https://docs.oracle.com/database/121/ARPLS/d_sched.htm#ARPLS72399) in the Oracle documentation.
When working with Amazon RDS DB instances, prepend the schema name `SYS` to the object name. The following example sets the resource plan attribute for the Monday window object.
```
BEGIN
DBMS_SCHEDULER.SET_ATTRIBUTE(
name => 'SYS.MONDAY_WINDOW',
attribute => 'RESOURCE_PLAN',
value => 'resource_plan_1');
END;
/
```
## Modifying AutoTask maintenance windows
Amazon RDS for Oracle instances are created with default settings for maintenance windows. Automated maintenance tasks such as optimizer statistics collection run during these windows. By default, the maintenance windows turn on Oracle Database Resource Manager.
To modify the window, use the `DBMS_SCHEDULER` package. You might need to modify the maintenance window settings for the following reasons:
+ You want maintenance jobs to run at a different time, with different settings, or not at all. For example, might want to modify the window duration, or change the repeat time and interval.
+ You want to avoid the performance impact of enabling Resource Manager during maintenance. For example, if the default maintenance plan is specified, and if the maintenance window opens while the database is under load, you might see wait events such as `resmgr:cpu quantum`. This wait event is related to Database Resource Manager. You have the following options:
+ Ensure that maintenance windows are active during off-peak times for your DB instance.
+ Disable the default maintenance plan by setting the `resource_plan` attribute to an empty string.
+ Set the `resource_manager_plan` parameter to `FORCE:` in your parameter group. If your instance uses Enterprise Edition, this setting prevents Database Resource Manager plans from activating.
**To modify your maintenance window settings**
1. Connect to your database using an Oracle SQL client.
1. Query the current configuration for a scheduler window.
The following example queries the configuration for `MONDAY_WINDOW`.
```
SELECT ENABLED, RESOURCE_PLAN, DURATION, REPEAT_INTERVAL
FROM DBA_SCHEDULER_WINDOWS
WHERE WINDOW_NAME='MONDAY_WINDOW';
```
The following output shows that the window is using the default values.
```
ENABLED RESOURCE_PLAN DURATION REPEAT_INTERVAL
--------------- ------------------------------ ---------------- ------------------------------
TRUE DEFAULT_MAINTENANCE_PLAN +000 04:00:00 freq=daily;byday=MON;byhour=22
;byminute=0; bysecond=0
```
1. Modify the window using the `DBMS_SCHEDULER` package.
The following example sets the resource plan to null so that the Resource Manager won't run during the maintenance window.
```
BEGIN
-- disable the window to make changes
DBMS_SCHEDULER.DISABLE(name=>'"SYS"."MONDAY_WINDOW"',force=>TRUE);
-- specify the empty string to use no plan
DBMS_SCHEDULER.SET_ATTRIBUTE(name=>'"SYS"."MONDAY_WINDOW"', attribute=>'RESOURCE_PLAN', value=>'');
-- re-enable the window
DBMS_SCHEDULER.ENABLE(name=>'"SYS"."MONDAY_WINDOW"');
END;
/
```
The following example sets the maximum duration of the window to 2 hours.
```
BEGIN
DBMS_SCHEDULER.DISABLE(name=>'"SYS"."MONDAY_WINDOW"',force=>TRUE);
DBMS_SCHEDULER.SET_ATTRIBUTE(name=>'"SYS"."MONDAY_WINDOW"', attribute=>'DURATION', value=>'0 2:00:00');
DBMS_SCHEDULER.ENABLE(name=>'"SYS"."MONDAY_WINDOW"');
END;
/
```
The following example sets the repeat interval to every Monday at 10 AM.
```
BEGIN
DBMS_SCHEDULER.DISABLE(name=>'"SYS"."MONDAY_WINDOW"',force=>TRUE);
DBMS_SCHEDULER.SET_ATTRIBUTE(name=>'"SYS"."MONDAY_WINDOW"', attribute=>'REPEAT_INTERVAL', value=>'freq=daily;byday=MON;byhour=10;byminute=0;bysecond=0');
DBMS_SCHEDULER.ENABLE(name=>'"SYS"."MONDAY_WINDOW"');
END;
/
```
## Setting the time zone for Oracle Scheduler jobs
To modify the time zone for Oracle Scheduler, you can use the Oracle procedure `dbms_scheduler.set_scheduler_attribute`. For more information about the `dbms_scheduler` package, see [DBMS\$1SCHEDULER](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_SCHEDULER.html) and [SET\$1SCHEDULER\$1ATTRIBUTE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_SCHEDULER.html#GUID-2AB97BF7-7154-4E6C-933F-B2659B18A907) in the Oracle documentation.
**To modify the current time zone setting**
1. Connect to the database using a client such as SQL Developer. For more information, see [Connecting to your DB instance using Oracle SQL developer](USER_ConnectToOracleInstance.SQLDeveloper.md).
1. Set the default time zone as following, substituting your time zone for `time_zone_name`.
```
BEGIN
DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
attribute => 'default_timezone',
value => 'time_zone_name'
);
END;
/
```
In the following example, you change the time zone to Asia/Shanghai.
Start by querying the current time zone, as shown following.
```
SELECT VALUE FROM DBA_SCHEDULER_GLOBAL_ATTRIBUTE WHERE ATTRIBUTE_NAME='DEFAULT_TIMEZONE';
```
The output shows that the current time zone is ETC/UTC.
```
VALUE
-------
Etc/UTC
```
Then you set the time zone to Asia/Shanghai.
```
BEGIN
DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
attribute => 'default_timezone',
value => 'Asia/Shanghai'
);
END;
/
```
For more information about changing the system time zone, see [Oracle time zone](Appendix.Oracle.Options.Timezone.md).
## Turning off Oracle Scheduler jobs owned by SYS
To disable an Oracle Scheduler job owned by the SYS user, use the `rdsadmin.rdsadmin_dbms_scheduler.disable` procedure.
This procedure uses the `name` common parameter for Oracle Scheduler tasks. For more information, see [Common parameters for Oracle Scheduler procedures](#Appendix.Oracle.CommonDBATasks.Scheduler.CommonParameters).
The following example disables the `SYS.CLEANUP_ONLINE_IND_BUILD` Oracle Scheduler job.
```
BEGIN
rdsadmin.rdsadmin_dbms_scheduler.disable('SYS.CLEANUP_ONLINE_IND_BUILD');
END;
/
```
## Turning on Oracle Scheduler jobs owned by SYS
To turn on an Oracle Scheduler job owned by SYS, use the `rdsadmin.rdsadmin_dbms_scheduler.enable` procedure.
This procedure uses the `name` common parameter for Oracle Scheduler tasks. For more information, see [Common parameters for Oracle Scheduler procedures](#Appendix.Oracle.CommonDBATasks.Scheduler.CommonParameters).
The following example enables the `SYS.CLEANUP_ONLINE_IND_BUILD` Oracle Scheduler job.
```
BEGIN
rdsadmin.rdsadmin_dbms_scheduler.enable('SYS.CLEANUP_ONLINE_IND_BUILD');
END;
/
```
## Modifying the Oracle Scheduler repeat interval for jobs of CALENDAR type
To modify the repeat interval to modify a SYS-owned Oracle Scheduler job of `CALENDAR` type, use the `rdsadmin.rdsadmin_dbms_scheduler.disable` procedure.
This procedure uses the following common parameters for Oracle Scheduler tasks:
+ `name`
+ `attribute`
+ `value`
For more information, see [Common parameters for Oracle Scheduler procedures](#Appendix.Oracle.CommonDBATasks.Scheduler.CommonParameters).
The following example modifies the repeat interval of the `SYS.CLEANUP_ONLINE_IND_BUILD` Oracle Scheduler job.
```
BEGIN
rdsadmin.rdsadmin_dbms_scheduler.set_attribute(
name => 'SYS.CLEANUP_ONLINE_IND_BUILD',
attribute => 'repeat_interval',
value => 'freq=daily;byday=FRI,SAT;byhour=20;byminute=0;bysecond=0');
END;
/
```
## Modifying the Oracle Scheduler repeat interval for jobs of NAMED type
Some Oracle Scheduler jobs use a schedule name instead of an interval. For this type of jobs, you must create a new named schedule in the master user schema. Use the standard Oracle `sys.dbms_scheduler.create_schedule` procedure to do this. Also, use the `rdsadmin.rdsadmin_dbms_scheduler.set_attribute procedure` to assign the new named schedule to the job.
This procedure uses the following common parameter for Oracle Scheduler tasks:
+ `name`
+ `attribute`
+ `value`
For more information, see [Common parameters for Oracle Scheduler procedures](#Appendix.Oracle.CommonDBATasks.Scheduler.CommonParameters).
The following example modifies the repeat interval of the `SYS.BSLN_MAINTAIN_STATS_JOB` Oracle Scheduler job.
```
BEGIN
DBMS_SCHEDULER.CREATE_SCHEDULE (
schedule_name => 'rds_master_user.new_schedule',
start_date => SYSTIMESTAMP,
repeat_interval => 'freq=daily;byday=MON,TUE,WED,THU,FRI;byhour=0;byminute=0;bysecond=0',
end_date => NULL,
comments => 'Repeats daily forever');
END;
/
BEGIN
rdsadmin.rdsadmin_dbms_scheduler.set_attribute (
name => 'SYS.BSLN_MAINTAIN_STATS_JOB',
attribute => 'schedule_name',
value => 'rds_master_user.new_schedule');
END;
/
```
## Turning off autocommit for Oracle Scheduler job creation
When `DBMS_SCHEDULER.CREATE_JOB` creates Oracle Scheduler jobs, it creates the jobs immediately and commits the changes. You might need to incorporate the creation of Oracle Scheduler jobs in the user transaction to do the following:
+ Roll back the Oracle Schedule job when the user transaction is rolled back.
+ Create the Oracle Scheduler job when the main user transaction is committed.
You can use the procedure `rdsadmin.rdsadmin_dbms_scheduler.set_no_commit_flag` to turn on this behavior. This procedure takes no parameters. You can use this procedure in the following RDS for Oracle releases:
+ 21.0.0.0.ru-2022-07.rur-2022-07.r1 and higher
+ 19.0.0.0.ru-2022-07.rur-2022-07.r1 and higher
The following example turns off autocommit for Oracle Scheduler, creates an Oracle Scheduler job, and then rolls back the transaction. Because autocommit is turned off, the database also rolls back the creation of the Oracle Scheduler job.
```
BEGIN
rdsadmin.rdsadmin_dbms_scheduler.set_no_commit_flag;
DBMS_SCHEDULER.CREATE_JOB(job_name => 'EMPTY_JOB',
job_type => 'PLSQL_BLOCK',
job_action => 'begin null; end;',
auto_drop => false);
ROLLBACK;
END;
/
PL/SQL procedure successfully completed.
SELECT * FROM DBA_SCHEDULER_JOBS WHERE JOB_NAME='EMPTY_JOB';
no rows selected
```
# Diagnosing problems with RDS for Oracle DB instances
Oracle Database includes a fault diagnosability infrastructure that you can use to investigate database problems. In Oracle terminology, a *problem* is a critical error such as a code bug or data corruption. An *incident* is the occurrence of a problem. If the same error occurs three times, then the infrastructure shows three incidents of this problem. For more information, see [Diagnosing and resolving problems](https://docs.oracle.com/en/database/oracle/oracle-database/19/admin/diagnosing-and-resolving-problems.html#GUID-8DEB1BE0-8FB9-4FB2-A19A-17CF6F5791C3) in the Oracle Database documentation.
The Automatic Diagnostic Repository Command Interpreter (ADRCI) utility is an Oracle command-line tool that you use to manage diagnostic data. For example, you can use this tool to investigate problems and package diagnostic data. An *incident package* includes diagnostic data for an incident or all incidents that reference a specific problem. You can upload an incident package, which is implemented as a .zip file, to Oracle Support.
To deliver a managed service experience, Amazon RDS doesn't provide shell access to ADRCI. To perform diagnostic tasks for your RDS for Oracle DB instance, use the Amazon RDS package `rdsadmin.rdsadmin_adrci_util`.
By using the functions in `rdsadmin_adrci_util`, you can list and package problems and incidents, and also show trace files. All functions return a task ID. This ID forms part of the name of log file that contains the ADRCI output, as in `dbtask-task_id.log`. The log file resides in the BDUMP directory. You can download the log file by following the procedure described in [Downloading a database log file](USER_LogAccess.Procedural.Downloading.md).
## Common parameters for diagnostic procedures
To perform diagnostic tasks, use functions in the Amazon RDS package `rdsadmin.rdsadmin_adrci_util`. The package has the following common parameters.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `incident_id` | number | A valid incident ID or null | Null | No | If the value is null, the function shows all incidents. If the value isn't null and represents a valid incident ID, the function shows the specified incident. |
| `problem_id` | number | A valid problem ID or null | Null | No | If the value is null, the function shows all problems. If the value isn't null and represents a valid problem ID, the function shows the specified problem. |
| `last` | number | A valid integer greater than 0 or null | Null | No | If the value is null, then the function displays at most 50 items. If the value isn't null, the function displays the specified number. |
## Listing incidents
To list diagnostic incidents for Oracle, use the Amazon RDS function `rdsadmin.rdsadmin_adrci_util.list_adrci_incidents`. You can list incidents in either basic or detailed mode. By default, the function lists the 50 most recent incidents.
This function uses the following common parameters:
+ `incident_id`
+ `problem_id`
+ `last`
If you specify `incident_id` and `problem_id`, then `incident_id` overrides `problem_id`. For more information, see [Common parameters for diagnostic procedures](#Appendix.Oracle.CommonDBATasks.CommonDiagParameters).
This function uses the following additional parameter.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `detail` | boolean | TRUE or FALSE | `FALSE` | No | If `TRUE`, the function lists incidents in detail mode. If `FALSE`, the function lists incidents in basic mode. |
To list all incidents, query the `rdsadmin.rdsadmin_adrci_util.list_adrci_incidents` function without any arguments. The query returns the task ID.
```
SQL> SELECT rdsadmin.rdsadmin_adrci_util.list_adrci_incidents AS task_id FROM DUAL;
TASK_ID
------------------
1590786706158-3126
```
Or call the `rdsadmin.rdsadmin_adrci_util.list_adrci_incidents` function without any arguments and store the output in a SQL client variable. You can use the variable in other statements.
```
SQL> VAR task_id VARCHAR2(80);
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.list_adrci_incidents;
PL/SQL procedure successfully completed.
```
To read the log file, call the Amazon RDS procedure `rdsadmin.rds_file_util.read_text_file`. Supply the task ID as part of the file name. The following output shows three incidents: 53523, 53522, and 53521.
```
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log'));
TEXT
-------------------------------------------------------------------------------------------------------------------------
2020-05-29 21:11:46.193 UTC [INFO ] Listing ADRCI incidents.
2020-05-29 21:11:46.256 UTC [INFO ]
ADR Home = /rdsdbdata/log/diag/rdbms/orcl_a/ORCL:
*************************************************************************
INCIDENT_ID PROBLEM_KEY CREATE_TIME
----------- ----------------------------------------------------------- ----------------------------------------
53523 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_003 2020-05-29 20:15:20.928000 +00:00
53522 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_002 2020-05-29 20:15:15.247000 +00:00
53521 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_001 2020-05-29 20:15:06.047000 +00:00
3 rows fetched
2020-05-29 21:11:46.256 UTC [INFO ] The ADRCI incidents were successfully listed.
2020-05-29 21:11:46.256 UTC [INFO ] The task finished successfully.
14 rows selected.
```
To list a particular incident, specify its ID using the `incident_id` parameter. In the following example, you query the log file for incident 53523 only.
```
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.list_adrci_incidents(incident_id=>53523);
PL/SQL procedure successfully completed.
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log'));
TEXT
------------------------------------------------------------------------------------------------------------------
2020-05-29 21:15:25.358 UTC [INFO ] Listing ADRCI incidents.
2020-05-29 21:15:25.426 UTC [INFO ]
ADR Home = /rdsdbdata/log/diag/rdbms/orcl_a/ORCL:
*************************************************************************
INCIDENT_ID PROBLEM_KEY CREATE_TIME
-------------------- ----------------------------------------------------------- ---------------------------------
53523 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_003 2020-05-29 20:15:20.928000 +00:00
1 rows fetched
2020-05-29 21:15:25.427 UTC [INFO ] The ADRCI incidents were successfully listed.
2020-05-29 21:15:25.427 UTC [INFO ] The task finished successfully.
12 rows selected.
```
## Listing problems
To list diagnostic problems for Oracle, use the Amazon RDS function `rdsadmin.rdsadmin_adrci_util.list_adrci_problems`.
By default, the function lists the 50 most recent problems.
This function uses the common parameters `problem_id` and `last`. For more information, see [Common parameters for diagnostic procedures](#Appendix.Oracle.CommonDBATasks.CommonDiagParameters).
To get the task ID for all problems, call the `rdsadmin.rdsadmin_adrci_util.list_adrci_problems` function without any arguments, and store the output in a SQL client variable.
```
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.list_adrci_problems;
PL/SQL procedure successfully completed.
```
To read the log file, call the `rdsadmin.rds_file_util.read_text_file` function, supplying the task ID as part of the file name. In the following output, the log file shows three problems: 1, 2, and 3.
```
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log'));
TEXT
----------------------------------------------------------------------------------------------------------------------
2020-05-29 21:18:50.764 UTC [INFO ] Listing ADRCI problems.
2020-05-29 21:18:50.829 UTC [INFO ]
ADR Home = /rdsdbdata/log/diag/rdbms/orcl_a/ORCL:
*************************************************************************
PROBLEM_ID PROBLEM_KEY LAST_INCIDENT LASTINC_TIME
---------- ----------------------------------------------------------- ------------- ---------------------------------
2 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_003 53523 2020-05-29 20:15:20.928000 +00:00
3 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_002 53522 2020-05-29 20:15:15.247000 +00:00
1 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_001 53521 2020-05-29 20:15:06.047000 +00:00
3 rows fetched
2020-05-29 21:18:50.829 UTC [INFO ] The ADRCI problems were successfully listed.
2020-05-29 21:18:50.829 UTC [INFO ] The task finished successfully.
14 rows selected.
```
In the following example, you list problem 3 only.
```
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.list_adrci_problems(problem_id=>3);
PL/SQL procedure successfully completed.
```
To read the log file for problem 3, call `rdsadmin.rds_file_util.read_text_file`. Supply the task ID as part of the file name.
```
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log'));
TEXT
-------------------------------------------------------------------------
2020-05-29 21:19:42.533 UTC [INFO ] Listing ADRCI problems.
2020-05-29 21:19:42.599 UTC [INFO ]
ADR Home = /rdsdbdata/log/diag/rdbms/orcl_a/ORCL:
*************************************************************************
PROBLEM_ID PROBLEM_KEY LAST_INCIDENT LASTINC_TIME
---------- ----------------------------------------------------------- ------------- ---------------------------------
3 ORA 700 [EVENT_CREATED_INCIDENT] [942] [SIMULATED_ERROR_002 53522 2020-05-29 20:15:15.247000 +00:00
1 rows fetched
2020-05-29 21:19:42.599 UTC [INFO ] The ADRCI problems were successfully listed.
2020-05-29 21:19:42.599 UTC [INFO ] The task finished successfully.
12 rows selected.
```
## Creating incident packages
You can create incident packages using the Amazon RDS function `rdsadmin.rdsadmin_adrci_util.create_adrci_package`. The output is a .zip file that you can supply to Oracle Support.
This function uses the following common parameters:
+ `problem_id`
+ `incident_id`
Make sure to specify one of the preceding parameters. If you specify both parameters, `incident_id` overrides `problem_id`. For more information, see [Common parameters for diagnostic procedures](#Appendix.Oracle.CommonDBATasks.CommonDiagParameters).
To create a package for a specific incident, call the Amazon RDS function `rdsadmin.rdsadmin_adrci_util.create_adrci_package` with the `incident_id` parameter. The following example creates a package for incident 53523.
```
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.create_adrci_package(incident_id=>53523);
PL/SQL procedure successfully completed.
```
To read the log file, call the `rdsadmin.rds_file_util.read_text_file`. You can supply the task ID as part of the file name. The output shows that you generated incident package `ORA700EVE_20200529212043_COM_1.zip`.
```
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log'));
TEXT
--------------------------------------------------------------------------------------------------------------------------------------
2020-05-29 21:20:43.031 UTC [INFO ] The ADRCI package is being created.
2020-05-29 21:20:47.641 UTC [INFO ] Generated package 1 in file /rdsdbdata/log/trace/ORA700EVE_20200529212043_COM_1.zip, mode complete
2020-05-29 21:20:47.642 UTC [INFO ] The ADRCI package was successfully created.
2020-05-29 21:20:47.642 UTC [INFO ] The task finished successfully.
```
To package diagnostic data for a particular problem, specify its ID using the `problem_id` parameter. In the following example, you package data for problem 3 only.
```
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.create_adrci_package(problem_id=>3);
PL/SQL procedure successfully completed.
```
To read the task output, call `rdsadmin.rds_file_util.read_text_file`, supplying the task ID as part of the file name. The output shows that you generated incident package `ORA700EVE_20200529212111_COM_1.zip`.
```
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log'));
TEXT
------------------------------------------------------------------------------------------------------------------------------------------------------------
2020-05-29 21:21:11.050 UTC [INFO ] The ADRCI package is being created.
2020-05-29 21:21:15.646 UTC [INFO ] Generated package 2 in file /rdsdbdata/log/trace/ORA700EVE_20200529212111_COM_1.zip, mode complete
2020-05-29 21:21:15.646 UTC [INFO ] The ADRCI package was successfully created.
2020-05-29 21:21:15.646 UTC [INFO ] The task finished successfully.
```
You can also download the log file. For more information, see [Downloading a database log file](USER_LogAccess.Procedural.Downloading.md).
## Showing trace files
You can use the Amazon RDS function `rdsadmin.rdsadmin_adrci_util.show_adrci_tracefile` to list trace files under the trace directory and all incident directories under the current ADR home. You can also show the contents of trace files and incident trace files.
This function uses the following parameter.
****
| Parameter name | Data type | Valid values | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `filename` | varchar2 | A valid trace file name | Null | No | If the value is null, the function shows all trace files. If it isn't null, the function shows the specified file. |
To show the trace file, call the Amazon RDS function `rdsadmin.rdsadmin_adrci_util.show_adrci_tracefile`.
```
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.show_adrci_tracefile;
PL/SQL procedure successfully completed.
```
To list the trace file names, call the Amazon RDS procedure `rdsadmin.rds_file_util.read_text_file`, supplying the task ID as part of the file name.
```
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log')) WHERE TEXT LIKE '%/alert_%';
TEXT
---------------------------------------------------------------
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-28
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-27
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-26
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-25
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-24
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-23
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-22
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log.2020-05-21
diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log
9 rows selected.
```
In the following example, you generate output for `alert_ORCL.log`.
```
SQL> EXEC :task_id := rdsadmin.rdsadmin_adrci_util.show_adrci_tracefile('diag/rdbms/orcl_a/ORCL/trace/alert_ORCL.log');
PL/SQL procedure successfully completed.
```
To read the log file, call `rdsadmin.rds_file_util.read_text_file`. Supply the task ID as part of the file name. The output shows the first 10 lines of alert\$1ORCL.log.
```
SQL> SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||:task_id||'.log')) WHERE ROWNUM <= 10;
TEXT
-----------------------------------------------------------------------------------------
2020-05-29 21:24:02.083 UTC [INFO ] The trace files are being displayed.
2020-05-29 21:24:02.128 UTC [INFO ] Thu May 28 23:59:10 2020
Thread 1 advanced to log sequence 2048 (LGWR switch)
Current log# 3 seq# 2048 mem# 0: /rdsdbdata/db/ORCL_A/onlinelog/o1_mf_3_hbl2p8xs_.log
Thu May 28 23:59:10 2020
Archived Log entry 2037 added for thread 1 sequence 2047 ID 0x5d62ce43 dest 1:
Fri May 29 00:04:10 2020
Thread 1 advanced to log sequence 2049 (LGWR switch)
Current log# 4 seq# 2049 mem# 0: /rdsdbdata/db/ORCL_A/onlinelog/o1_mf_4_hbl2qgmh_.log
Fri May 29 00:04:10 2020
10 rows selected.
```
You can also download the log file. For more information, see [Downloading a database log file](USER_LogAccess.Procedural.Downloading.md).
# Performing miscellaneous tasks for Oracle DB instances
Following, you can find how to perform miscellaneous DBA tasks on your Amazon RDS DB instances running Oracle. To deliver a managed service experience, Amazon RDS doesn't provide shell access to DB instances, and restricts access to certain system procedures and tables that require advanced privileges.
**Topics**
+ [
## Creating and dropping directories in the main data storage space
](#Appendix.Oracle.CommonDBATasks.NewDirectories)
+ [
## Listing files in a DB instance directory
](#Appendix.Oracle.CommonDBATasks.ListDirectories)
+ [
## Reading files in a DB instance directory
](#Appendix.Oracle.CommonDBATasks.ReadingFiles)
+ [
## Accessing Opatch files
](#Appendix.Oracle.CommonDBATasks.accessing-opatch-files)
+ [
## Managing advisor tasks
](#Appendix.Oracle.CommonDBATasks.managing-advisor-tasks)
+ [
# Transporting tablespaces
](rdsadmin_transport_util.md)
## Creating and dropping directories in the main data storage space
To create directories, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.create_directory`. You can create up to 10,000 directories, all located in your main data storage space. To drop directories, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.drop_directory`.
The `create_directory` and `drop_directory` procedures have the following required parameter.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_directory_name` | VARCHAR2 | — | Yes | The name of the directory. |
The following example creates a new directory named `PRODUCT_DESCRIPTIONS`.
```
EXEC rdsadmin.rdsadmin_util.create_directory(p_directory_name => 'product_descriptions');
```
The data dictionary stores the directory name in uppercase. You can list the directories by querying `DBA_DIRECTORIES`. The system chooses the actual host pathname automatically. The following example gets the directory path for the directory named `PRODUCT_DESCRIPTIONS`:
```
SELECT DIRECTORY_PATH
FROM DBA_DIRECTORIES
WHERE DIRECTORY_NAME='PRODUCT_DESCRIPTIONS';
DIRECTORY_PATH
----------------------------------------
/rdsdbdata/userdirs/01
```
The master user name for the DB instance has read and write privileges in the new directory, and can grant access to other users. `EXECUTE` privileges are not available for directories on a DB instance. Directories are created in your main data storage space and will consume space and I/O bandwidth.
The following example drops the directory named `PRODUCT_DESCRIPTIONS`.
```
EXEC rdsadmin.rdsadmin_util.drop_directory(p_directory_name => 'product_descriptions');
```
**Note**
You can also drop a directory by using the Oracle SQL command `DROP DIRECTORY`.
Dropping a directory doesn't remove its contents. Because the `rdsadmin.rdsadmin_util.create_directory` procedure can reuse pathnames, files in dropped directories can appear in a newly created directory. Before you drop a directory, we recommend that you use `UTL_FILE.FREMOVE` to remove files from the directory. For more information, see [FREMOVE procedure](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924) in the Oracle documentation.
## Listing files in a DB instance directory
To list the files in a directory, use the Amazon RDS procedure `rdsadmin.rds_file_util.listdir`. This procedure isn't supported on an Oracle replica. The `listdir` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_directory` | varchar2 | — | Yes | The name of the directory to list. |
The following example grants read/write privileges on the directory `PRODUCT_DESCRIPTIONS` to user `rdsadmin`, and then lists the files in this directory.
```
GRANT READ,WRITE ON DIRECTORY PRODUCT_DESCRIPTIONS TO rdsadmin;
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir(p_directory => 'PRODUCT_DESCRIPTIONS'));
```
## Reading files in a DB instance directory
To read a text file, use the Amazon RDS procedure `rdsadmin.rds_file_util.read_text_file`. The `read_text_file` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_directory` | varchar2 | — | Yes | The name of the directory that contains the file. |
| `p_filename` | varchar2 | — | Yes | The name of the file to read. |
The following example creates the file `rice.txt` in the directory `PRODUCT_DESCRIPTIONS`.
```
declare
fh sys.utl_file.file_type;
begin
fh := utl_file.fopen(location=>'PRODUCT_DESCRIPTIONS', filename=>'rice.txt', open_mode=>'w');
utl_file.put(file=>fh, buffer=>'AnyCompany brown rice, 15 lbs');
utl_file.fclose(file=>fh);
end;
/
```
The following example reads the file `rice.txt` from the directory `PRODUCT_DESCRIPTIONS`.
```
SELECT * FROM TABLE
(rdsadmin.rds_file_util.read_text_file(
p_directory => 'PRODUCT_DESCRIPTIONS',
p_filename => 'rice.txt'));
```
## Accessing Opatch files
Opatch is an Oracle utility that enables the application and rollback of patches to Oracle software. The Oracle mechanism for determining which patches have been applied to a database is the `opatch lsinventory` command. To open service requests for Bring Your Own Licence (BYOL) customers, Oracle Support requests the `lsinventory` file and sometimes the `lsinventory_detail` file generated by Opatch.
To deliver a managed service experience, Amazon RDS doesn't provide shell access to Opatch. Instead, the `lsinventory-dbv.txt` in the BDUMP directory contains the patch information related to your current engine version. When you perform a minor or major upgrade, Amazon RDS updates `lsinventory-dbv.txt` within an hour of applying the patch. To verify the applied patches, read `lsinventory-dbv.txt`. This action is similar to running the `opatch lsinventory` command.
**Note**
The examples in this section assume that the BDUMP directory is named `BDUMP`. On a read replica, the BDUMP directory name is different. To learn how to get the BDUMP name by querying `V$DATABASE.DB_UNIQUE_NAME` on a read replica, see [Listing files](USER_LogAccess.Concepts.Oracle.md#USER_LogAccess.Concepts.Oracle.WorkingWithTracefiles.ViewingBackgroundDumpDest).
The inventory files use the Amazon RDS naming convention `lsinventory-dbv.txt` and `lsinventory_detail-dbv.txt`, where *dbv* is the full name of your DB version. The `lsinventory-dbv.txt` file is available on all DB versions. The corresponding `lsinventory_detail-dbv.txt` is available on 19.0.0.0, ru-2020-01.rur-2020-01.r1 or later.
For example, if your DB version is 19.0.0.0.ru-2021-07.rur-2021-07.r1, then your inventory files have the following names.
```
lsinventory-19.0.0.0.ru-2021-07.rur-2021-07.r1.txt
lsinventory_detail-19.0.0.0.ru-2021-07.rur-2021-07.r1.txt
```
Ensure that you download the files that match the current version of your DB engine.
### Console
**To download an inventory file using the console**
1. 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**.
1. Choose the name of the DB instance that has the log file that you want to view.
1. Choose the **Logs & events** tab.
1. Scroll down to the **Logs** section.
1. In the **Logs** section, search for `lsinventory`.
1. Select the file that you want to access, and then choose **Download**.
### SQL
To read the `lsinventory-dbv.txt` in a SQL client, you can use a `SELECT` statement. For this technique, use either of the following `rdsadmin` functions: `rdsadmin.rds_file_util.read_text_file` or `rdsadmin.tracefile_listing`.
In the following sample query, replace *dbv* with your Oracle DB version. For example, your DB version might be 19.0.0.0.ru-2020-04.rur-2020-04.r1.
```
SELECT text
FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'lsinventory-dbv.txt'));
```
### PL/SQL
To read the `lsinventory-dbv.txt` in a SQL client, you can write a PL/SQL program. This program uses `utl_file` to read the file, and `dbms_output` to print it. These are Oracle-supplied packages.
In the following sample program, replace *dbv* with your Oracle DB version. For example, your DB version might be 19.0.0.0.ru-2020-04.rur-2020-04.r1.
```
SET SERVEROUTPUT ON
DECLARE
v_file SYS.UTL_FILE.FILE_TYPE;
v_line VARCHAR2(1000);
v_oracle_home_type VARCHAR2(1000);
c_directory VARCHAR2(30) := 'BDUMP';
c_output_file VARCHAR2(30) := 'lsinventory-dbv.txt';
BEGIN
v_file := SYS.UTL_FILE.FOPEN(c_directory, c_output_file, 'r');
LOOP
BEGIN
SYS.UTL_FILE.GET_LINE(v_file, v_line,1000);
DBMS_OUTPUT.PUT_LINE(v_line);
EXCEPTION
WHEN no_data_found THEN
EXIT;
END;
END LOOP;
END;
/
```
Or query `rdsadmin.tracefile_listing`, and spool the output to a file. The following example spools the output to `/tmp/tracefile.txt`.
```
SPOOL /tmp/tracefile.txt
SELECT *
FROM rdsadmin.tracefile_listing
WHERE FILENAME LIKE 'lsinventory%';
SPOOL OFF;
```
## Managing advisor tasks
Oracle Database includes a number of advisors. Each advisor supports automated and manual tasks. You can use procedures in the `rdsadmin.rdsadmin_util` package to manage some advisor tasks.
The advisor task procedures are available in the following engine versions:
+ Oracle Database 21c (21.0.0)
+ Version 19.0.0.0.ru-2021-01.rur-2021-01.r1 and higher Oracle Database 19c versions
For more information, see [Version 19.0.0.0.ru-2021-01.rur-2021-01.r1](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/oracle-version-19-0.html#oracle-version-RU-RUR.19.0.0.0.ru-2021-01.rur-2021-01.r1) in the *Amazon RDS for Oracle Release Notes*.
**Topics**
+ [
### Setting parameters for advisor tasks
](#Appendix.Oracle.CommonDBATasks.setting-task-parameters)
+ [
### Disabling AUTO\$1STATS\$1ADVISOR\$1TASK
](#Appendix.Oracle.CommonDBATasks.dropping-advisor-task)
+ [
### Re-enabling AUTO\$1STATS\$1ADVISOR\$1TASK
](#Appendix.Oracle.CommonDBATasks.recreating-advisor-task)
### Setting parameters for advisor tasks
To set parameters for some advisor tasks, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.advisor_task_set_parameter`. The `advisor_task_set_parameter` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_task_name` | varchar2 | — | Yes | The name of the advisor task whose parameters you want to change. The following values are valid: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.CommonDBATasks.Misc.html) |
| `p_parameter` | varchar2 | — | Yes | The name of the task parameter. To find valid parameters for an advisor task, run the following query. Substitute *p\$1task\$1name* with a valid value for `p_task_name`: COL PARAMETER_NAME FORMAT a30
COL PARAMETER_VALUE FORMAT a30
SELECT PARAMETER_NAME, PARAMETER_VALUE
FROM DBA_ADVISOR_PARAMETERS
WHERE TASK_NAME='p_task_name'
AND PARAMETER_VALUE != 'UNUSED'
ORDER BY PARAMETER_NAME;
|
| `p_value` | varchar2 | — | Yes | The value for a task parameter. To find valid values for task parameters, run the following query. Substitute *p\$1task\$1name* with a valid value for `p_task_name`: COL PARAMETER_NAME FORMAT a30
COL PARAMETER_VALUE FORMAT a30
SELECT PARAMETER_NAME, PARAMETER_VALUE
FROM DBA_ADVISOR_PARAMETERS
WHERE TASK_NAME='p_task_name'
AND PARAMETER_VALUE != 'UNUSED'
ORDER BY PARAMETER_NAME;
|
The following PL/SQL program sets `ACCEPT_PLANS` to `FALSE` for `SYS_AUTO_SPM_EVOLVE_TASK`. The SQL Plan Management automated task verifies the plans and generates a report of its findings, but does not evolve the plans automatically. You can use a report to identify new SQL plan baselines and accept them manually.
```
BEGIN
rdsadmin.rdsadmin_util.advisor_task_set_parameter(
p_task_name => 'SYS_AUTO_SPM_EVOLVE_TASK',
p_parameter => 'ACCEPT_PLANS',
p_value => 'FALSE');
END;
```
The following PL/SQL program sets `EXECUTION_DAYS_TO_EXPIRE` to `10` for `AUTO_STATS_ADVISOR_TASK`. The predefined task `AUTO_STATS_ADVISOR_TASK` runs automatically in the maintenance window once per day. The example sets the retention period for the task execution to 10 days.
```
BEGIN
rdsadmin.rdsadmin_util.advisor_task_set_parameter(
p_task_name => 'AUTO_STATS_ADVISOR_TASK',
p_parameter => 'EXECUTION_DAYS_TO_EXPIRE',
p_value => '10');
END;
```
### Disabling AUTO\$1STATS\$1ADVISOR\$1TASK
To disable `AUTO_STATS_ADVISOR_TASK`, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.advisor_task_drop`. The `advisor_task_drop` procedure accepts the following parameter.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_task_name` | varchar2 | — | Yes | The name of the advisor task to be disabled. The only valid value is `AUTO_STATS_ADVISOR_TASK`. |
The following command drops `AUTO_STATS_ADVISOR_TASK`.
```
EXEC rdsadmin.rdsadmin_util.advisor_task_drop('AUTO_STATS_ADVISOR_TASK')
```
You can re-enable `AUTO_STATS_ADVISOR_TASK` using `rdsadmin.rdsadmin_util.dbms_stats_init`.
### Re-enabling AUTO\$1STATS\$1ADVISOR\$1TASK
To re-enable `AUTO_STATS_ADVISOR_TASK`, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.dbms_stats_init`. The `dbms_stats_init` procedure takes no parameters.
The following command re-enables `AUTO_STATS_ADVISOR_TASK`.
```
EXEC rdsadmin.rdsadmin_util.dbms_stats_init()
```
# Transporting tablespaces
Use the Amazon RDS package `rdsadmin.rdsadmin_transport_util` to copy a set of tablespaces from an on-premises Oracle database to an RDS for Oracle DB instance. At the physical level, the transportable tablespace feature incrementally copies source data files and metadata files to your target instance. You can transfer the files using either Amazon EFS or Amazon S3. For more information, see [Migrating using Oracle transportable tablespaces](oracle-migrating-tts.md).
**Topics**
+ [
# Importing transported tablespaces to your DB instance
](rdsadmin_transport_util_import_xtts_tablespaces.md)
+ [
# Importing transportable tablespace metadata into your DB instance
](rdsadmin_transport_util_import_xtts_metadata.md)
+ [
# Listing orphaned files after a tablespace import
](rdsadmin_transport_util_list_xtts_orphan_files.md)
+ [
# Deleting orphaned data files after a tablespace import
](rdsadmin_transport_util_cleanup_incomplete_xtts_import.md)
# Importing transported tablespaces to your DB instance
Use the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces` to restore tablespaces that you have previously exported from a source DB instance. In the transport phase, you back up your read-only tablespaces, export Data Pump metadata, transfer these files to your target DB instance, and then import the tablespaces. For more information, see [Phase 4: Transport the tablespaces](oracle-migrating-tts.md#oracle-migrating-tts.final-br-phase).
## Syntax
```
FUNCTION import_xtts_tablespaces(
p_tablespace_list IN CLOB,
p_directory_name IN VARCHAR2,
p_platform_id IN NUMBER DEFAULT 13,
p_parallel IN INTEGER DEFAULT 0) RETURN VARCHAR2;
```
## Parameters
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_tablespace_list` | `CLOB` | — | Yes | The list of tablespaces to import. |
| `p_directory_name` | `VARCHAR2` | — | Yes | The directory that contains the tablespace backups. |
| `p_platform_id` | `NUMBER` | `13` | No | Provide a platform ID that matches the one specified during the backup phase. To find a list of platforms, query `V$TRANSPORTABLE_PLATFORM`. The default platform is Linux x86 64-bit, which is little endian. |
| `p_parallel` | `INTEGER` | `0` | No | The degree of parallelism. By default, parallelism is disabled. |
## Examples
The following example imports the tablespaces *TBS1*, *TBS2*, and *TBS3* from the directory *DATA\$1PUMP\$1DIR*. The source platform is AIX-Based Systems (64-bit), which has the platform ID of `6`. You can find the platform IDs by querying `V$TRANSPORTABLE_PLATFORM`.
```
VAR task_id CLOB
BEGIN
:task_id:=rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces(
'TBS1,TBS2,TBS3',
'DATA_PUMP_DIR',
p_platform_id => 6);
END;
/
PRINT task_id
```
# Importing transportable tablespace metadata into your DB instance
Use the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_metadata` to import transportable tablespace metadata into your RDS for Oracle DB instance. During the operation, the status of the metadata import is shown in the table `rdsadmin.rds_xtts_operation_info`. For more information, see [Step 5: Import tablespace metadata on your target DB instance](oracle-migrating-tts.md#oracle-migrating-tts.transport.import-dmp).
## Syntax
```
PROCEDURE import_xtts_metadata(
p_datapump_metadata_file IN SYS.DBA_DATA_FILES.FILE_NAME%TYPE,
p_directory_name IN VARCHAR2,
p_exclude_stats IN BOOLEAN DEFAULT FALSE,
p_remap_tablespace_list IN CLOB DEFAULT NULL,
p_remap_user_list IN CLOB DEFAULT NULL);
```
## Parameters
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_datapump_metadata_file` | `SYS.DBA_DATA_FILES.FILE_NAME%TYPE` | — | Yes | The name of the Oracle Data Pump file that contains the metadata for your transportable tablespaces. |
| `p_directory_name` | `VARCHAR2` | — | Yes | The directory that contains the Data Pump file. |
| `p_exclude_stats` | `BOOLEAN` | `FALSE` | No | Flag that indicates whether to exclude statistics. |
| `p_remap_tablespace_list` | `CLOB` | NULL | No | A list of tablespaces to be remapped during the metadata import. Use the format `from_tbs:to_tbs`. For example, specify `users:user_data`. |
| `p_remap_user_list` | `CLOB` | NULL | No | A list of user schemas to be remapped during the metadata import. Use the format `from_schema_name:to_schema_name`. For example, specify `hr:human_resources`. |
## Examples
The example imports the tablespace metadata from the file *xttdump.dmp*, which is located in directory *DATA\$1PUMP\$1DIR*.
```
BEGIN
rdsadmin.rdsadmin_transport_util.import_xtts_metadata('xttdump.dmp','DATA_PUMP_DIR');
END;
/
```
# Listing orphaned files after a tablespace import
Use the `rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files` procedure to list data files that were orphaned after a tablespace import. After you identify the data files, you can delete them by calling `rdsadmin.rdsadmin_transport_util.cleanup_incomplete_xtts_import`.
## Syntax
```
FUNCTION list_xtts_orphan_files RETURN xtts_orphan_files_list_t PIPELINED;
```
## Examples
The following example runs the procedure `rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files`. The output shows two data files that are orphaned.
```
SQL> SELECT * FROM TABLE(rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files);
FILENAME FILESIZE
-------------- ---------
datafile_7.dbf 104865792
datafile_8.dbf 104865792
```
# Deleting orphaned data files after a tablespace import
Use the `rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files` procedure to delete data files that were orphaned after a tablespace import. Running this command generates a log file that uses the name format `rds-xtts-delete_xtts_orphaned_files-YYYY-MM-DD.HH24-MI-SS.FF.log` in the `BDUMP` directory. Use the procedure `rdsadmin.rdsadmin_transport_util.cleanup_incomplete_xtts_import` to find the orphaned files. You can read the log file by calling the procedure `rdsadmin.rds_file_util.read_text_file`. For more information, see [Phase 6: Clean up leftover files](oracle-migrating-tts.md#oracle-migrating-tts.cleanup).
## Syntax
```
PROCEDURE cleanup_incomplete_xtts_import(
p_directory_name IN VARCHAR2);
```
## Parameters
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_directory_name` | `VARCHAR2` | — | Yes | The directory that contains the orphaned data files. |
## Examples
The following example deletes the orphaned data files in *DATA\$1PUMP\$1DIR*.
```
BEGIN
rdsadmin.rdsadmin_transport_util.cleanup_incomplete_xtts_import('DATA_PUMP_DIR');
END;
/
```
The following example reads the log file generated by the previous command.
```
SELECT *
FROM TABLE(rdsadmin.rds_file_util.read_text_file(
p_directory => 'BDUMP',
p_filename => 'rds-xtts-delete_xtts_orphaned_files-2023-06-01.09-33-11.868894000.log'));
TEXT
--------------------------------------------------------------------------------
orphan transported datafile datafile_7.dbf deleted.
orphan transported datafile datafile_8.dbf deleted.
```
# Working with storage in RDS for Oracle
Every RDS for Oracle instance has a primary storage volume. To increase storage capacity, you can attach up to three additional storage volumes to your DB instance. Depending on your workload requirements, choose between gp3 and io2 storage for each volume. For example, you might put frequently accessed data on an io2 volume and historical data on a gp3 volume.
Use additional storage volumes to enable the following benefits:
+ **Enhanced capacity** – Scale your total storage up to 256 TiB per DB instance by attaching up to three additional storage volumes.
+ **Flexible storage configuration and performance optimization** – Mix different storage types (gp3 and io2) to optimize for both cost and performance based on your data access patterns. Separate frequently accessed data on high-performance io2 storage from archival data on cost-effective gp3 storage.
+ **Expand and reduce storage capacity as needed** – Attach a volume when you need additional storage, as during data migration, and then later delete the volume. In this way, you can expand and reduce the total DB instance storage.
+ **Online data movement** – Use the built-in capabilities of Oracle database to move data between volumes without downtime.
**Note**
You can remove additional storage volumes, but you can't remove the primary volume.
**Topics**
+ [
## Considerations for using additional storage volumes with RDS for Oracle
](#User_Oracle_AdditionalStorage.considerations)
+ [
## Limitations of using additional storage volumes with RDS for Oracle
](#User_Oracle_AdditionalStorage.limitations)
+ [
## Database management operations with additional storage volumes in RDS for Oracle
](#User_Oracle_AdditionalStorage.DBManagement)
+ [
# Add, remove, or modify storage volumes with RDS for Oracle
](User_Oracle_AdditionalStorage.ModifyStorageVolumes.md)
+ [
# Backing up and restoring data with additional storage volumes in RDS for Oracle
](User_Oracle_AdditionalStorage.BackupRestore.md)
+ [
# Use cases for additional storage volumes in RDS for Oracle
](User_Oracle_AdditionalStorage.UseCases.md)
## Considerations for using additional storage volumes with RDS for Oracle
Consider the following when using additional storage volumes with RDS for Oracle:
+ You can add up to 3 additional storage volumes per instance.
+ Additional storage volumes must use the following volume names:
+ rdsdbdata2
+ rdsdbdata3
+ rdsdbdata4
+ You can only add General Purpose SSD (gp3) and Provisioned IOPS SSD (io2) storage types.
+ You can use Oracle’s online relocation capabilities to move data between volumes while your applications continue running.
+ When you create an additional storage volume by modifying the DB instance, RDS immediately creates the storage volume regardless of the schedule modifications setting. Adding a storage volume is an online operation and does not impact your database performance. See [Using the schedule modifications setting](USER_ModifyInstance.ApplyImmediately.md).
For optimal performance, check the following when you are using additional storage volumes:
+ Data movement planning
+ Schedule large movements during off-peak hours
+ Break large operations into smaller chunks
+ Monitor system resources during moves
+ Resource management
+ Keep sufficient free space on both volumes
+ Monitor I/O patterns using AWR or Statspack
+ Watch for storage-full scenarios
+ Best practices
+ Use online datafile relocation operations where possible
+ Maintain appropriate indexes
+ Regularly monitor space usage
When using additional storage volumes with replicas:
+ When you are creating an RDS for Oracle replica for a DB instance that has additional storage volumes, RDS automatically configures additional storage volumes on the replica. However, any subsequent modifications made in storage volumes of your primary DB instance are not automatically applied to the replica.
+ When managing datafile locations across volumes, we recommend using parameter group settings instead of session-level changes to ensure consistent behavior between primary and replica instances.
## Limitations of using additional storage volumes with RDS for Oracle
The following limitations apply to using additional storage volumes with RDS for Oracle:
+ You can’t add a storage volume to the instance types with less than 64GiB memory because they don’t have sufficient memory to support large storage volumes.
+ The minimum storage size is 200GiB for additional storage volumes. The primary storage volume of your DB instance should be equal to or larger than 200GiB to attach additional storage volumes. The maximum storage size for your DB instance is 256 TiB total across all volumes.
+ The following capabilities aren’t supported for DB instances with additional storage volumes:
+ Cross-region automated backups
+ Storage autoscaling (for additional storage volumes)
+ Public snapshots
+ You can't delete the primary storage volume (`rdsdbdata`), but you can delete other additional storage volumes as long as they're empty.
+ You can't store the online redo logs, archived redo logs, and control files in additional storage volumes. These files can only be stored in the primary storage volume (`rdsdbdata`).
## Database management operations with additional storage volumes in RDS for Oracle
You can perform database management operations such as creating tablespaces or moving data between storage volumes while using additional storage volumes in RDS for Oracle. For more information about database management operations with additional storage volumes, see the following sections:
+ [Specifying database file locations in RDS for Oracle](Appendix.Oracle.CommonDBATasks.TablespacesAndDatafiles.md#Appendix.Oracle.CommonDBATasks.DatabaseFileLocations)
+ [Creating and sizing tablespaces in RDS for Oracle](Appendix.Oracle.CommonDBATasks.TablespacesAndDatafiles.md#Appendix.Oracle.CommonDBATasks.CreatingTablespacesAndDatafiles)
+ [Moving data files between volumes in RDS for Oracle](Appendix.Oracle.CommonDBATasks.MovingDataBetweenVolumes.md#Appendix.Oracle.CommonDBATasks.MovingDatafiles)
# Add, remove, or modify storage volumes with RDS for Oracle
You can add, modify, and remove additional storage volumes using the AWS Management Console or AWS CLI. All operations use the `modify-db-instance` command with the `additional-storage-volumes` parameter.
**Important**
Adding or removing additional storage volumes creates a backup pending action and a blackout window. The blackout window closes when the backup workflow completes.
## Adding storage volumes
You can add up to three storage volumes beyond the primary storage volume. To add a new storage volume to your RDS for Oracle DB instance, use the `modify-db-instance` command with the `additional-storage-volumes` parameter.
The following code snippet adds a mew 5,000 GiB general purpose SSD (gp3) volume with 4000 provision IOPS name `rdsdbdata3`.
```
aws rds modify-db-instance \
--db-instance-identifier my-oracle-instance \
--region us-east-1 \
--additional-storage-volumes '[
{
"VolumeName":"rdsdbdata3",
"StorageType":"gp3",
"AllocatedStorage":5000
"IOPS":4000}
]' \
--apply-immediately
```
## Modifying storage volumes
You can modify storage type, allocated storage size, IOPS, and storage throughput settings of your additional storage volume. The following code snippet modifies the IOPS setting for the `rdsdbdata2` volume.
```
aws rds modify-db-instance \
--db-instance-identifier my-oracle-instance \
--region us-east-1 \
--additional-storage-volumes '[
{
"VolumeName":"rdsdbdata2",
"IOPS":8000}
]' \
--apply-immediately
```
**Note**
You can’t reduce the storage allocation for an additional storage volume once you’ve added it to the instance.
## Removing storage volumes
You can remove additional storage volumes from RDS for Oracle DB instances when they are no longer needed. Before removing a volume, make sure that you have moved all database files from the volume and no database objects are referencing it. Verify that the volume status is `Not-in-use`. You can remove additional storage volumes, but you can't remove the primary storage volume.
**Warning**
Before you remove an additional storage volume, make sure that no database files are stored on the volume. Removing a volume with active database files causes database corruption.
The following example removes the `rdsdbdata4` volume.
```
aws rds modify-db-instance \
--db-instance-identifier my-oracle-instance \
--region us-east-1 \
--additional-storage-volumes '[
{
"VolumeName":"rdsdbdata2",
"SetForDelete":true}
]' \
--apply-immediately
```
# Backing up and restoring data with additional storage volumes in RDS for Oracle
You can use automated backups and create a DB snapshot with your DB instance with additional storage volumes. All backup operations include both the primary volume and additional storage volumes. You can also use point-in-time recovery for your DB instance with additional storage volumes. When you restore your database, you can add storage volumes. You can also modify the storage settings of existing volumes. You cannot delete additional storage volumes when you restore your database from a snapshot.
**Topics**
+ [
## Creating manual snapshots
](#User_Oracle_AdditionalStorage.BackupRestore.ManualSnapshots)
+ [
## Restoring manual snapshots
](#User_Oracle_AdditionalStorage.BackupRestore.RestoreSnapshots)
+ [
## Point-in-time recovery
](#User_Oracle_AdditionalStorage.BackupRestore.PitR)
## Creating manual snapshots
The following example creates a manual snapshot of your database with additional storage volumes:
```
aws rds create-db-snapshot \
--db-instance-identifier my-oracle-asv-instance \
--db-snapshot-identifier my-snapshot
```
## Restoring manual snapshots
When restoring from a snapshot, you can add new additional storage volumes or modify the IOPS or throughput settings of existing volumes. The following example restores a DB instance from a snapshot and modifies the IOPS setting for the `rdsdbdata2` volume:
```
aws rds restore-db-instance-from-db-snapshot \
--db-instance-identifier my-restored-instance \
--db-snapshot-identifier my-snapshot \
--region us-east-1 \
--additional-storage-volumes '[
{
"VolumeName":"rdsdbdata2",
"IOPS":5000
}
]'
```
## Point-in-time recovery
During point-in-time recovery (PITR), you can add new additional storage volumes with custom configurations. The following example performs PITR and adds a new 5,000 GiB General Purpose SSD (gp3) with 5000 IOPS and 200 MB/s storage throughput for the `rdsdbdata2` volume:
```
aws rds restore-db-instance-to-point-in-time \
--source-db-instance-identifier my-source-instancemy-source-instance \
--target-db-instance my-pitr-instance\
--use-latest-restorable-time \
--region us-east-1 \
--additional-storage-volumes '[
{
"VolumeName":"rdsdbdata2",
"StorageType":"gp3",
"AllocatedStorage":5000,
"IOPS":5000,
"StorageThroughput":200
}
]'
```
# Use cases for additional storage volumes in RDS for Oracle
Additional storage volumes support various database management scenarios. The following sections describe common use cases and implementation approaches.
**Topics**
+ [
## Extending storage capacity beyond 64 TiB
](#User_Oracle_AdditionalStorage.UseCases.Extendingstoragecapacity)
+ [
## Storage tiering of frequently and infrequently accessed data on separate volumes
](#User_Oracle_AdditionalStorage.UseCases.Storagetiering)
+ [
## Temporary storage for data loading and unloading
](#User_Oracle_AdditionalStorage.UseCases.Temporarystorage)
+ [
## Using Oracle transportable tablespaces with an additional storage volume
](#User_Oracle_AdditionalStorage.UseCases.TransportableTablespaces)
## Extending storage capacity beyond 64 TiB
You can use additional storage volumes when your primary storage volume approaches the 64 TiB limit but need more storage space in your database. You can attach additional storage volumes to your DB instance, each up to 64TiB, using the `modify-db-instance` command. After attaching additional storage volumes, you can create tablespaces on additional storage volumes and move objects such as tables, indexes, and partitions to these tablespaces using standard Oracle SQL. For more information, see [Database management operations with additional storage volumes in RDS for Oracle](User_Oracle_AdditionalStorage.md#User_Oracle_AdditionalStorage.DBManagement).
## Storage tiering of frequently and infrequently accessed data on separate volumes
You can use additional storage volumes to optimize cost and performance by configuring different storage types between volumes. For example, you can use high-performance Provisioned IOPS SSD storage (io2) volumes for frequently accessed data while storing historical data on cost-effective General Purpose (gp3) storage volumes. You can move specific database objects (tables, indexes, and partitions) to these tablespaces using standard Oracle commands. For more information, see [Database management operations with additional storage volumes in RDS for Oracle](User_Oracle_AdditionalStorage.md#User_Oracle_AdditionalStorage.DBManagement).
## Temporary storage for data loading and unloading
You can use additional storage volumes as temporary storage for large data loads or exports with the following steps:
+ Create a directory on an additional storage volume with the following command:
```
BEGIN
rdsadmin.rdsadmin_util.create_directory(
p_directory_name => 'DATA_PUMP_DIR2',
p_database_volume_name => 'rdsdbdata2');
END;
/
```
+ After the creation of the directory, follow the steps described in [Importing using Oracle Data Pump](Oracle.Procedural.Importing.DataPump.md) to export and import your data to the new directory.
+ After the completion of the operation, remove files and optionally delete the volume to save the storage costs. You can remove the additional storage volume only when the volume is empty.
## Using Oracle transportable tablespaces with an additional storage volume
You can use additional storage volumes to move datafiles to an additional storage volume using Oracle transportable tablespaces with the following steps:
+ Set `db_create_file_dest` parameter at session level before importing transportable tablespaces into the target database with an additional storage volume.
```
ALTER SESSION SET db_create_file_dest = '/rdsdbdata2/db';
VAR x CLOB;
BEGIN
:x := rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces(
p_tablespace_list => 'TBTEST1',
p_directory_name => 'XTTS_DIR_DATA2',
p_platform_id => 13);
END;
/
PRINT :x;
```
+ Check the transportable tablespace import status:
```
ALTER SESSION SET nls_date_format = 'DD.MM.YYYY HH24:MI:SS';
COL xtts_operation_start_utc FORMAT A30
COL xtts_operation_end_utc FORMAT A30
COL xtts_operation_state FORMAT A30
COL xtts_operation_type FORMAT A30
SELECT xtts_operation_start_utc, xtts_operation_type, xtts_operation_state
FROM rdsadmin.rds_xtts_operation_info;
```
+ When transportable tablespace import completes, import transportable tablespace metadata.
```
BEGIN
rdsadmin.rdsadmin_transport_util.import_xtts_metadata(
p_datapump_metadata_file => 'xttdump.dmp',
p_directory_name => 'XTTS_DIR_DATA2');
END;
/
```
# Configuring advanced RDS for Oracle features
RDS for Oracle supports various advanced features, including HugePages, an instance store, and extended data types.
**Topics**
+ [
# Storing temporary data in an RDS for Oracle instance store
](CHAP_Oracle.advanced-features.instance-store.md)
+ [
# Turning on HugePages for an RDS for Oracle instance
](Oracle.Concepts.HugePages.md)
+ [
# Turning on extended data types in RDS for Oracle
](Oracle.Concepts.ExtendedDataTypes.md)
# Storing temporary data in an RDS for Oracle instance store
Use an instance store for the temporary tablespaces and the Database Smart Flash Cache (the flash cache) on supported RDS for Oracle DB instance classes.
**Topics**
+ [
## Overview of the RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.overview)
+ [
## Turning on an RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.Enable)
+ [
# Configuring an RDS for Oracle instance store
](CHAP_Oracle.advanced-features.instance-store.configuring.md)
+ [
# Working with an instance store on an Oracle read replica
](CHAP_Oracle.advanced-features.instance-store.replicas.md)
+ [
# Configuring a temporary tablespace group on an instance store and Amazon EBS
](CHAP_Oracle.advanced-features.instance-store.temp-ebs.md)
+ [
## Removing an RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.Disable)
## Overview of the RDS for Oracle instance store
An *instance store* provides temporary block-level storage for an RDS for Oracle DB instance. You can use an instance store for temporary storage of information that changes frequently.
An instance store is based on Non-Volatile Memory Express (NVMe) devices that are physically attached to the host computer. The storage is optimized for low latency, random I/O performance, and sequential read throughput.
The size of the instance store varies by DB instance type. For more information about the instance store, see [Amazon EC2 instance store](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html) in the *Amazon Elastic Compute Cloud User Guide for Linux Instances*.
**Topics**
+ [
### Types of data in the RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.overview.uses)
+ [
### Benefits of the RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.overview.benefits)
+ [
### Supported instance classes for the RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.overview.instance-classes)
+ [
### Supported engine versions for the RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.overview.db-versions)
+ [
### Supported AWS Regions for the RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.overview.regions)
+ [
### Cost of the RDS for Oracle instance store
](#CHAP_Oracle.advanced-features.instance-store.overview.cost)
### Types of data in the RDS for Oracle instance store
You can place the following types of RDS for Oracle temporary data in an instance store:
A temporary tablespace
Oracle Database uses temporary tablespaces to store intermediate query results that don't fit in memory. Larger queries can generate large amounts of intermediate data that needs to be cached temporarily, but doesn't need to persist. In particular, a temporary tablespace is useful for sorts, hash aggregations, and joins. If your RDS for Oracle DB instance uses the Enterprise Edition or Standard Edition 2, you can place a temporary tablespace in an instance store.
The flash cache
The flash cache improves the performance of single-block random reads in the conventional path. A best practice is to size the cache to accommodate most of your active data set. If your RDS for Oracle DB instance uses the Enterprise Edition, you can place the flash cache in an instance store.
By default, an instance store is configured for a temporary tablespace but not for the flash cache. You can't place Oracle data files and database log files in an instance store.
### Benefits of the RDS for Oracle instance store
You might consider using an instance store to store temporary files and caches that you can afford to lose. If you want to improve DB performance, or if an increasing workload is causing performance problems for your Amazon EBS storage, consider scaling to an instance class that supports an instance store.
By placing your temporary tablespace and flash cache on an instance store, you get the following benefits:
+ Lower read latencies
+ Higher throughput
+ Reduced load on your Amazon EBS volumes
+ Lower storage and snapshot costs because of reduced Amazon EBS load
+ Less need to provision high IOPS, possibly lowering your overall cost
By placing your temporary tablespace on the instance store, you deliver an immediate performance boost to queries that use temporary space. When you place the flash cache on the instance store, cached block reads typically have much lower latency than Amazon EBS reads. The flash cache needs to be "warmed up" before it delivers performance benefits. The cache warms up by itself because the database writes blocks to the flash cache as they age out of the database buffer cache.
**Note**
In some cases, the flash cache causes performance overhead because of cache management. Before you turn on the flash cache in a production environment, we recommend that you analyze your workload and test the cache in a test environment.
### Supported instance classes for the RDS for Oracle instance store
Amazon RDS supports the instance store for the following DB instance classes:
+ db.m5d
+ db.m6id
+ db.r5d
+ db.r6id
+ db.x2idn
+ db.x2iedn
RDS for Oracle supports the preceding DB instance classes for the BYOL licensing model only. For more information, see [Supported RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md#Oracle.Concepts.InstanceClasses.Supported) and [Bring Your Own License (BYOL) for EE and SE2](Oracle.Concepts.Licensing.md#Oracle.Concepts.Licensing.BYOL).
To see the total instance storage for the supported DB instance types, run the following command in the AWS CLI.
**Example**
```
aws ec2 describe-instance-types \
--filters "Name=instance-type,Values=*5d.*large*,*6id.*large*" \
--query "InstanceTypes[?contains(InstanceType,'m5d')||contains(InstanceType,'r5d')||contains(InstanceType,'m6id')||contains(InstanceType,'r6id')][InstanceType, InstanceStorageInfo.TotalSizeInGB]" \
--output table
```
The preceding command returns the raw device size for the instance store. RDS for Oracle uses a small portion of this space for configuration. The space in the instance store that is available for temporary tablespaces or the flash cache is slightly smaller.
### Supported engine versions for the RDS for Oracle instance store
The instance store is supported for the following RDS for Oracle engine versions:
+ 21.0.0.0.ru-2022-01.rur-2022-01.r1 or higher Oracle Database 21c versions
+ 19.0.0.0.ru-2021-10.rur-2021-10.r1 or higher Oracle Database 19c versions
### Supported AWS Regions for the RDS for Oracle instance store
The instance store is available in all AWS Regions where one or more of these instance types are supported. For more information on the db.m5d and db.r5d instance classes, see [DB instance classes](Concepts.DBInstanceClass.md). For more information on the instance classes supported by Amazon RDS for Oracle, see [RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md).
### Cost of the RDS for Oracle instance store
The cost of the instance store is built into the cost of the instance-store turned on instances. You don't incur additional costs by enabling an instance store on an RDS for Oracle DB instance. For more information about instance-store turned on instances, see [Supported instance classes for the RDS for Oracle instance store](#CHAP_Oracle.advanced-features.instance-store.overview.instance-classes).
## Turning on an RDS for Oracle instance store
To turn on the instance store for RDS for Oracle temporary data, do one of the following:
+ Create an RDS for Oracle DB instance using a supported instance class. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ Modify an existing RDS for Oracle DB instance to use a supported instance class. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Configuring an RDS for Oracle instance store
By default, 100% of instance store space is allocated to the temporary tablespace. To configure the instance store to allocate space to the flash cache and temporary tablespace, set the following parameters in the parameter group for your instance:
**db\$1flash\$1cache\$1size=\$1DBInstanceStore\$1\$10,2,4,6,8,10\$1/10\$1**
This parameter specifies the amount of storage space allocated for the flash cache. This parameter is valid only for Oracle Database Enterprise Edition. The default value is `{DBInstanceStore*0/10}`. If you set a nonzero value for `db_flash_cache_size`, your RDS for Oracle instance enables the flash cache after you restart the instance.
**rds.instance\$1store\$1temp\$1size=\$1DBInstanceStore\$1\$10,2,4,6,8,10\$1/10\$1**
This parameter specifies the amount of storage space allocated for the temporary tablespace. The default value is `{DBInstanceStore*10/10}`. This parameter is modifiable for Oracle Database Enterprise Edition and read-only for Standard Edition 2. If you set a nonzero value for `rds.instance_store_temp_size`, Amazon RDS allocates space in the instance store for the temporary tablespace.
You can set the `db_flash_cache_size` and `rds.instance_store_temp_size` parameters for DB instances that don't use an instance store. In this case, both settings evaluate to `0`, which turns off the feature. In this case, you can use the same parameter group for different instance sizes and for instances that don't use an instance store. If you modify these parameters, make sure to reboot the associated instances so that the changes can take effect.
If you allocate space for a temporary tablespace, Amazon RDS doesn't create the temporary tablespace automatically. To learn how to create the temporary tablespace on the instance store, see [Creating a temporary tablespace on the instance store](Appendix.Oracle.CommonDBATasks.TablespacesAndDatafiles.md#Appendix.Oracle.CommonDBATasks.creating-tts-instance-store).
The combined value of the preceding parameters must not exceed 10/10, or 100%. The following table illustrates valid and invalid parameter settings.
| db\$1flash\$1cache\$1size setting | rds.instance\$1store\$1temp\$1size setting | Explanation |
| --- | --- | --- |
| db\$1flash\$1cache\$1size=\$1DBInstanceStore\$10/10\$1 | rds.instance\$1store\$1temp\$1size=\$1DBInstanceStore\$110/10\$1 | This is a valid configuration for all editions of Oracle Database. Amazon RDS allocates 100% of instance store space to the temporary tablespace. This is the default. |
| db\$1flash\$1cache\$1size=\$1DBInstanceStore\$110/10\$1 | rds.instance\$1store\$1temp\$1size=\$1DBInstanceStore\$10/10\$1 | This is a valid configuration for Oracle Database Enterprise Edition only. Amazon RDS allocates 100% of instance store space to the flash cache. |
| db\$1flash\$1cache\$1size=\$1DBInstanceStore\$12/10\$1 | rds.instance\$1store\$1temp\$1size=\$1DBInstanceStore\$18/10\$1 | This is a valid configuration for Oracle Database Enterprise Edition only. Amazon RDS allocates 20% of instance store space to the flash cache, and 80% of instance store space to the temporary tablespace. |
| db\$1flash\$1cache\$1size=\$1DBInstanceStore\$16/10\$1 | rds.instance\$1store\$1temp\$1size=\$1DBInstanceStore\$14/10\$1 | This is a valid configuration for Oracle Database Enterprise Edition only. Amazon RDS allocates 60% of instance store space to the flash cache, and 40% of instance store space to the temporary tablespace. |
| db\$1flash\$1cache\$1size=\$1DBInstanceStore\$12/10\$1 | rds.instance\$1store\$1temp\$1size=\$1DBInstanceStore\$14/10\$1 | This is a valid configuration for Oracle Database Enterprise Edition only. Amazon RDS allocates 20% of instance store space to the flash cache, and 40% of instance store space to the temporary tablespace. |
| db\$1flash\$1cache\$1size=\$1DBInstanceStore\$18/10\$1 | rds.instance\$1store\$1temp\$1size=\$1DBInstanceStore\$18/10\$1 | This is an invalid configuration because the combined percentage of instance store space exceeds 100%. In such cases, Amazon RDS fails the attempt. |
## Considerations when changing the DB instance type
If you change your DB instance type, it can affect the configuration of the flash cache or the temporary tablespace on the instance store. Consider the following modifications and their effects:
**You scale up or scale down the DB instance that supports the instance store.**
The following values increase or decrease proportionally to the new size of the instance store:
+ The new size of the flash cache.
+ The space allocated to the temporary tablespaces that reside in the instance store.
For example, the setting `db_flash_cache_size={DBInstanceStore*6/10}` on a db.m5d.4xlarge instance provides around 340 GB of flash cache space. If you scale up the instance type to db.m5d.8xlarge, the flash cache space increases to around 680 GB.
**You modify a DB instance that doesn't use an instance store to an instance that does use an instance store.**
If `db_flash_cache_size` is set to a value larger than `0`, the flash cache is configured. If `rds.instance_store_temp_size` is set to a value larger than `0`, the instance store space is allocated for use by a temporary tablespace. RDS for Oracle doesn't move tempfiles to the instance store automatically. For information about using the allocated space, see [Creating a temporary tablespace on the instance store](Appendix.Oracle.CommonDBATasks.TablespacesAndDatafiles.md#Appendix.Oracle.CommonDBATasks.creating-tts-instance-store) or [Adding a tempfile to the instance store on a read replica](Appendix.Oracle.CommonDBATasks.using-tempfiles.md#Appendix.Oracle.CommonDBATasks.adding-tempfile-replica).
**You modify a DB instance that uses an instance store to an instance that doesn't use an instance store.**
In this case, RDS for Oracle removes the flash cache. RDS re-creates the tempfile that is currently located on the instance store on an Amazon EBS volume. The maximum size of the new tempfile is the former size of the `rds.instance_store_temp_size` parameter.
# Working with an instance store on an Oracle read replica
Read replicas support the flash cache and temporary tablespaces on an instance store. While the flash cache works the same way as on the primary DB instance, note the following differences for temporary tablespaces:
+ You can't create a temporary tablespace on a read replica. If you create a new temporary tablespace on the primary instance, RDS for Oracle replicates the tablespace information without tempfiles. To add a new tempfile, use either of the following techniques:
+ Use the Amazon RDS procedure `rdsadmin.rdsadmin_util.add_inst_store_tempfile`. RDS for Oracle creates a tempfile in the instance store on your read replica, and adds it to the specified temporary tablespace.
+ Run the `ALTER TABLESPACE … ADD TEMPFILE` command. RDS for Oracle places the tempfile on Amazon EBS storage.
**Note**
The tempfile sizes and storage types can be different on the primary DB instance and the read replica.
+ You can manage the default temporary tablespace setting only on the primary DB instance. RDS for Oracle replicates the setting to all read replicas.
+ You can configure the temporary tablespace groups only on the primary DB instance. RDS for Oracle replicates the setting to all read replicas.
# Configuring a temporary tablespace group on an instance store and Amazon EBS
You can configure a temporary tablespace group to include temporary tablespaces on both an instance store and Amazon EBS. This technique is useful when you want more temporary storage than is allowed by the maximum setting of `rds.instance_store_temp_size`.
When you configure a temporary tablespace group on both an instance store and Amazon EBS, the two tablespaces have significantly different performance characteristics. Oracle Database chooses the tablespace to serve queries based on an internal algorithm. Therefore, similar queries can vary in performance.
Typically, you create a temporary tablespace in the instance store as follows:
1. Create a temporary tablespace in the instance store.
1. Set the new tablespace as the database default temporary tablespace.
If the tablespace size in the instance store is insufficient, you can create additional temporary storage as follows:
1. Assign the temporary tablespace in the instance store to a temporary tablespace group.
1. Create a new temporary tablespace in Amazon EBS if one doesn't exist.
1. Assign the temporary tablespace in Amazon EBS to the same tablespace group that includes the instance store tablespace.
1. Set the tablespace group as the default temporary tablespace.
The following example assumes that the size of the temporary tablespace in the instance store doesn't meet your application requirements. The example creates the temporary tablespace `temp_in_inst_store` in the instance store, assigns it to tablespace group `temp_group`, adds the existing Amazon EBS tablespace named `temp_in_ebs` to this group, and sets this group as the default temporary tablespace.
```
SQL> EXEC rdsadmin.rdsadmin_util.create_inst_store_tmp_tblspace('temp_in_inst_store');
PL/SQL procedure successfully completed.
SQL> ALTER TABLESPACE temp_in_inst_store TABLESPACE GROUP temp_group;
Tablespace altered.
SQL> ALTER TABLESPACE temp_in_ebs TABLESPACE GROUP temp_group;
Tablespace altered.
SQL> EXEC rdsadmin.rdsadmin_util.alter_default_temp_tablespace('temp_group');
PL/SQL procedure successfully completed.
SQL> SELECT * FROM DBA_TABLESPACE_GROUPS;
GROUP_NAME TABLESPACE_NAME
------------------------------ ------------------------------
TEMP_GROUP TEMP_IN_EBS
TEMP_GROUP TEMP_IN_INST_STORE
SQL> SELECT PROPERTY_VALUE FROM DATABASE_PROPERTIES WHERE PROPERTY_NAME='DEFAULT_TEMP_TABLESPACE';
PROPERTY_VALUE
--------------
TEMP_GROUP
```
## Removing an RDS for Oracle instance store
To remove the instance store, modify your RDS for Oracle DB instance to use an instance type that doesn't support instance store, such as db.m5 or db.r5.
# Turning on HugePages for an RDS for Oracle instance
Amazon RDS for Oracle supports Linux kernel HugePages for increased database scalability. HugePages results in smaller page tables and less CPU time spent on memory management, increasing the performance of large database instances. For more information, see [Overview of HugePages](https://docs.oracle.com/database/121/UNXAR/appi_vlm.htm#UNXAR400) in the Oracle documentation.
You can use HugePages with all supported versions and editions of RDS for Oracle.
The `use_large_pages` parameter controls whether HugePages are turned on for a DB instance. The possible settings for this parameter are `ONLY`, `FALSE`, and `{DBInstanceClassHugePagesDefault}`. The `use_large_pages` parameter is set to `{DBInstanceClassHugePagesDefault}` in the default DB parameter group for Oracle.
To control whether HugePages are turned on for a DB instance automatically, you can use the `DBInstanceClassHugePagesDefault` formula variable in parameter groups. The value is determined as follows:
+ For the DB instance classes mentioned in the table following, `DBInstanceClassHugePagesDefault` always evaluates to `FALSE` by default, and `use_large_pages` evaluates to `FALSE`. You can turn on HugePages manually for these DB instance classes if the DB instance class has at least 14 GiB of memory.
+ For DB instance classes not mentioned in the table following, if the DB instance class has less than 14 GiB of memory, `DBInstanceClassHugePagesDefault` always evaluates to `FALSE`. Also, `use_large_pages` evaluates to `FALSE`.
+ For DB instance classes not mentioned in the table following, if the instance class has at least 14 GiB of memory and less than 100 GiB of memory, `DBInstanceClassHugePagesDefault` evaluates to `TRUE` by default. Also, `use_large_pages` evaluates to `ONLY`. You can turn off HugePages manually by setting `use_large_pages` to `FALSE`.
+ For DB instance classes not mentioned in the table following, if the instance class has at least 100 GiB of memory, `DBInstanceClassHugePagesDefault` always evaluates to `TRUE`. Also, `use_large_pages` evaluates to `ONLY` and HugePages can't be disabled.
HugePages are not turned on by default for the following DB instance classes.
****
| DB instance class family | DB instance classes with HugePages not turned on by default |
| --- | --- |
| db.m5 | db.m5.large |
| db.m4 | db.m4.large, db.m4.xlarge, db.m4.2xlarge, db.m4.4xlarge, db.m4.10xlarge |
| db.t3 | db.t3.micro, db.t3.small, db.t3.medium, db.t3.large |
For more information about DB instance classes, see [Hardware specifications for DB instance classes](Concepts.DBInstanceClass.Summary.md).
To turn on HugePages for new or existing DB instances manually, set the `use_large_pages` parameter to `ONLY`. You can't use HugePages with Oracle Automatic Memory Management (AMM). If you set the parameter `use_large_pages` to `ONLY`, then you must also set both `memory_target` and `memory_max_target` to `0`. For more information about setting DB parameters for your DB instance, see [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md).
You can also set the `sga_target`, `sga_max_size`, and `pga_aggregate_target` parameters. When you set system global area (SGA) and program global area (PGA) memory parameters, add the values together. Subtract this total from your available instance memory (`DBInstanceClassMemory`) to determine the free memory beyond the HugePages allocation. You must leave free memory of at least 2 GiB, or 10 percent of the total available instance memory, whichever is smaller.
After you configure your parameters, you must reboot your DB instance for the changes to take effect. For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
**Note**
The Oracle DB instance defers changes to SGA-related initialization parameters until you reboot the instance without failover. In the Amazon RDS console, choose **Reboot** but *do not* choose **Reboot with failover**. In the AWS CLI, call the `reboot-db-instance` command with the `--no-force-failover` parameter. The DB instance does not process the SGA-related parameters during failover or during other maintenance operations that cause the instance to restart.
The following is a sample parameter configuration for HugePages that enables HugePages manually. You should set the values to meet your needs.
```
1. memory_target = 0
2. memory_max_target = 0
3. pga_aggregate_target = {DBInstanceClassMemory*1/8}
4. sga_target = {DBInstanceClassMemory*3/4}
5. sga_max_size = {DBInstanceClassMemory*3/4}
6. use_large_pages = ONLY
```
Assume the following parameters values are set in a parameter group.
```
1. memory_target = IF({DBInstanceClassHugePagesDefault}, 0, {DBInstanceClassMemory*3/4})
2. memory_max_target = IF({DBInstanceClassHugePagesDefault}, 0, {DBInstanceClassMemory*3/4})
3. pga_aggregate_target = IF({DBInstanceClassHugePagesDefault}, {DBInstanceClassMemory*1/8}, 0)
4. sga_target = IF({DBInstanceClassHugePagesDefault}, {DBInstanceClassMemory*3/4}, 0)
5. sga_max_size = IF({DBInstanceClassHugePagesDefault}, {DBInstanceClassMemory*3/4}, 0)
6. use_large_pages = {DBInstanceClassHugePagesDefault}
```
The parameter group is used by a db.r4 DB instance class with less than 100 GiB of memory. With these parameter settings and `use_large_pages` set to `{DBInstanceClassHugePagesDefault}`, HugePages are turned on for the db.r4 instance.
Consider another example with following parameters values set in a parameter group.
```
1. memory_target = IF({DBInstanceClassHugePagesDefault}, 0, {DBInstanceClassMemory*3/4})
2. memory_max_target = IF({DBInstanceClassHugePagesDefault}, 0, {DBInstanceClassMemory*3/4})
3. pga_aggregate_target = IF({DBInstanceClassHugePagesDefault}, {DBInstanceClassMemory*1/8}, 0)
4. sga_target = IF({DBInstanceClassHugePagesDefault}, {DBInstanceClassMemory*3/4}, 0)
5. sga_max_size = IF({DBInstanceClassHugePagesDefault}, {DBInstanceClassMemory*3/4}, 0)
6. use_large_pages = FALSE
```
The parameter group is used by a db.r4 DB instance class and a db.r5 DB instance class, both with less than 100 GiB of memory. With these parameter settings, HugePages are turned off on the db.r4 and db.r5 instance.
**Note**
If this parameter group is used by a db.r4 DB instance class or db.r5 DB instance class with at least 100 GiB of memory, the `FALSE` setting for `use_large_pages` is overridden and set to `ONLY`. In this case, a customer notification regarding the override is sent.
After HugePages are active on your DB instance, you can view HugePages information by enabling enhanced monitoring. For more information, see [Monitoring OS metrics with Enhanced Monitoring](USER_Monitoring.OS.md).
# Turning on extended data types in RDS for Oracle
Amazon RDS for Oracle supports extended data types. With extended data types, the maximum size is 32,767 bytes for the `VARCHAR2`, `NVARCHAR2`, and `RAW` data types. To use extended data types, set the `MAX_STRING_SIZE` parameter to `EXTENDED`. For more information, see [Extended data types](https://docs.oracle.com/database/121/SQLRF/sql_elements001.htm#SQLRF55623) in the Oracle documentation.
If you don't want to use extended data types, keep the `MAX_STRING_SIZE` parameter set to `STANDARD` (the default). In this case, the size limits are 4,000 bytes for the `VARCHAR2` and `NVARCHAR2` data types, and 2,000 bytes for the RAW data type.
You can turn on extended data types on a new or existing DB instance. For new DB instances, DB instance creation time is typically longer when you turn on extended data types. For existing DB instances, the DB instance is unavailable during the conversion process.
## Considerations for extended data types
Consider the following when you enable extended data types for your DB instance:
+ When you turn on extended data types for a new or existing DB instance, you must reboot the instance for the change to take effect.
+ After you turn on extended data types, you can't change the DB instance back to use the standard size for data types. If you set the `MAX_STRING_SIZE` parameter back to `STANDARD` it results in the `incompatible-parameters` status.
+ When you restore a DB instance that uses extended data types, you must specify a parameter group with the `MAX_STRING_SIZE` parameter set to `EXTENDED`. During restore, if you specify the default parameter group or any other parameter group with `MAX_STRING_SIZE` set to `STANDARD` it results in the `incompatible-parameters` status.
+ When the DB instance status is `incompatible-parameters` because of the `MAX_STRING_SIZE` setting, the DB instance remains unavailable until you set the `MAX_STRING_SIZE` parameter to `EXTENDED` and reboot the DB instance.
## Turning on extended data types for a new DB instance
When you create a DB instance with `MAX_STRING_SIZE` set to `EXTENDED`, the instance shows `MAX_STRING_SIZE` set to the default `STANDARD`. Reboot the instance to enable the change.
**To turn on extended data types for a new DB instance**
1. Set the `MAX_STRING_SIZE` parameter to `EXTENDED` in a parameter group.
To set the parameter, you can either create a new parameter group or modify an existing parameter group.
For more information, see [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md).
1. Create a new RDS for Oracle DB instance.
For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
1. Associate the parameter group with `MAX_STRING_SIZE` set to `EXTENDED` with the DB instance.
For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
1. Reboot the DB instance for the parameter change to take effect.
For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
## Turning on extended data types for an existing DB instance
When you modify a DB instance to turn on extended data types, RDS converts the data in the database to use the extended sizes. The conversion and downtime occur when you next reboot the database after the parameter change. The DB instance is unavailable during the conversion.
The amount of time it takes to convert the data depends on the DB instance class, the database size, and the time of the last DB snapshot. To reduce downtime, consider taking a snapshot immediately before rebooting. This shortens the time of the backup that occurs during the conversion workflow.
**Note**
After you turn on extended data types, you can't perform a point-in-time restore to a time during the conversion. You can restore to the time immediately before the conversion or after the conversion.
**To turn on extended data types for an existing DB instance**
1. Take a snapshot of the database.
If there are invalid objects in the database, Amazon RDS tries to recompile them. The conversion to extended data types can fail if Amazon RDS can't recompile an invalid object. The snapshot enables you to restore the database if there is a problem with the conversion. Always check for invalid objects before conversion and fix or drop those invalid objects. For production databases, we recommend testing the conversion process on a copy of your DB instance first.
For more information, see [Creating a DB snapshot for a Single-AZ DB instance for Amazon RDS](USER_CreateSnapshot.md).
1. Set the `MAX_STRING_SIZE` parameter to `EXTENDED` in a parameter group.
To set the parameter, you can either create a new parameter group or modify an existing parameter group.
For more information, see [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md).
1. Modify the DB instance to associate it with the parameter group with `MAX_STRING_SIZE` set to `EXTENDED`.
For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
1. Reboot the DB instance for the parameter change to take effect.
For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
# Importing data into Oracle on Amazon RDS
How you import data into an Amazon RDS for Oracle DB instance depends on the following:
+ The amount of data you have
+ The number of database objects in your database
+ The variety of database objects in your database
For example, you can use the following tools, depending on your requirements:
+ Oracle SQL Developer – Import a simple, 20 MB database.
+ Oracle Data Pump – Import complex databases, or databases that are several hundred megabytes or several terabytes in size. For example, you can transport tablespaces from an on-premises database to your RDS for Oracle DB instance. You can use Amazon S3 or Amazon EFS to transfer the data files and metadata. For more information, see [Migrating using Oracle transportable tablespaces](oracle-migrating-tts.md), [Amazon EFS integration](oracle-efs-integration.md), and [Amazon S3 integration](oracle-s3-integration.md).
+ AWS Database Migration Service (AWS DMS) – Migrate databases without downtime. For more information about AWS DMS, see [ What is AWS Database Migration Service](https://docs.aws.amazon.com/dms/latest/userguide/Welcome.html) and the blog post [Migrating Oracle databases with near-zero downtime using AWS DMS](https://aws.amazon.com/blogs/database/migrating-oracle-databases-with-near-zero-downtime-using-aws-dms/).
**Important**
Before you use the preceding migration techniques, we recommend that you back up your database. After you import the data, you can back up your RDS for Oracle DB instances by creating snapshots. Later, you can restore the snapshots. For more information, see [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md).
For many database engines, ongoing replication can continue until you are ready to switch over to the target database. You can use AWS DMS to migrate to RDS for Oracle from either the same database engine or a different engine. If you migrate from a different database engine, you can use the AWS Schema Conversion Tool to migrate schema objects that AWS DMS doesn't migrate.
**Topics**
+ [
# Importing using Oracle SQL Developer
](Oracle.Procedural.Importing.SQLDeveloper.md)
+ [
# Migrating using Oracle transportable tablespaces
](oracle-migrating-tts.md)
+ [
# Importing using Oracle Data Pump
](Oracle.Procedural.Importing.DataPump.md)
+ [
# Importing using Oracle Export/Import
](Oracle.Procedural.Importing.ExportImport.md)
+ [
# Importing using Oracle SQL\$1Loader
](Oracle.Procedural.Importing.SQLLoader.md)
+ [
# Migrating with Oracle materialized views
](Oracle.Procedural.Importing.Materialized.md)
# Importing using Oracle SQL Developer
Oracle SQL Developer is a graphical Java tool distributed without cost by Oracle. SQL Developer provides options for migrating data between two Oracle databases, or for migrating data from other databases, such as MySQL, to an Oracle database. This tool is best for migrating small databases.
You can install this tool on your desktop computer (Windows, Linux, or Mac) or on one of your servers. After you install SQL Developer, you can use it to connect to your source and target databases. Use the **Database Copy** command on the Tools menu to copy your data to your RDS for Oracle DB instance.
To download SQL Developer, go to [http://www.oracle.com/technetwork/developer-tools/sql-developer](http://www.oracle.com/technetwork/developer-tools/sql-developer).
We recommend that you read the Oracle SQL Developer product documentation before you begin migrating your data. Oracle also has documentation on how to migrate from other databases, including MySQL and SQL Server. For more information, see [http://www.oracle.com/technetwork/database/migration](http://www.oracle.com/technetwork/database/migration) in the Oracle documentation.
# Migrating using Oracle transportable tablespaces
You can use the Oracle transportable tablespaces feature to copy a set of tablespaces from an on-premises Oracle database to an RDS for Oracle DB instance. At the physical level, you transfer source data files and metadata files to your target DB instance using either Amazon EFS or Amazon S3. The transportable tablespaces feature uses the `rdsadmin.rdsadmin_transport_util` package. For syntax and semantics of this package, see [Transporting tablespaces](rdsadmin_transport_util.md).
For blog posts that explain how to transport tablespaces, see [Migrate Oracle Databases to AWS using transportable tablespace](https://aws.amazon.com/blogs/database/migrate-oracle-databases-to-aws-using-transportable-tablespace/) and [Amazon RDS for Oracle Transportable Tablespaces using RMAN](https://aws.amazon.com/blogs/database/amazon-rds-for-oracle-transportable-tablespaces-using-rman/).
**Topics**
+ [
## Overview of Oracle transportable tablespaces
](#oracle-migrating-tts.overview)
+ [
## Phase 1: Set up your source host
](#oracle-migrating-tts.setup-phase)
+ [
## Phase 2: Prepare the full tablespace backup
](#oracle-migrating-tts.initial-br-phase)
+ [
## Phase 3: Make and transfer incremental backups
](#oracle-migrating-tts.roll-forward-phase)
+ [
## Phase 4: Transport the tablespaces
](#oracle-migrating-tts.final-br-phase)
+ [
## Phase 5: Validate the transported tablespaces
](#oracle-migrating-tts.validate)
+ [
## Phase 6: Clean up leftover files
](#oracle-migrating-tts.cleanup)
## Overview of Oracle transportable tablespaces
A transportable tablespace set consists of data files for the set of tablespaces being transported and an export dump file containing tablespace metadata. In a physical migration solution such as transportable tablespaces, you transfer physical files: data files, configuration files, and Data Pump dump files.
**Topics**
+ [
### Advantages and disadvantages of transportable tablespaces
](#oracle-migrating-tts.overview.benefits)
+ [
### Limitations for transportable tablespaces
](#oracle-migrating-tts.limitations)
+ [
### Prerequisites for transportable tablespaces
](#oracle-migrating-tts.requirements)
### Advantages and disadvantages of transportable tablespaces
We recommend that you use transportable tablespaces when you need to migrate one or more large tablespaces to RDS with minimum downtime. Transportable tablespaces offer the following advantages over logical migration:
+ Downtime is lower than most other Oracle migration solutions.
+ Because the transportable tablespace feature copies only physical files, it avoids the data integrity errors and logical corruption that can occur in logical migration.
+ No additional license is required.
+ You can migrate a set of tablespaces across different platforms and endianness types, for example, from an Oracle Solaris platform to Linux. However, transporting tablespaces to and from Windows servers isn't supported.
**Note**
Linux is fully tested and supported. Not all UNIX variations have been tested.
If you use transportable tablespaces, you can transport data using either Amazon S3 or Amazon EFS:
+ When you use EFS, your backups remain in the EFS file system for the duration of the import. You can remove the files afterward. In this technique, you don't need to provision EBS storage for your DB instance. For this reason, we recommend using Amazon EFS instead of S3. For more information, see [Amazon EFS integration](oracle-efs-integration.md).
+ When you use S3, you download RMAN backups to EBS storage attached to your DB instance. The files remain in your EBS storage during the import. After the import, you can free up this space, which remains allocated to your DB instance.
The primary disadvantage of transportable tablespaces is that you need relatively advanced knowledge of Oracle Database. For more information, see [Transporting Tablespaces Between Databases](https://docs.oracle.com/en/database/oracle/oracle-database/19/admin/transporting-data.html#GUID-F7B2B591-AA88-4D16-8DCF-712763923FFB) in the *Oracle Database Administrator’s Guide*.
### Limitations for transportable tablespaces
Oracle Database limitations for transportable tablespaces apply when you use this feature in RDS for Oracle. For more information, see [Limitations on Transportable Tablespaces]( https://docs.oracle.com/en/database/oracle/oracle-database/19/admin/transporting-data.html#GUID-DAB51E42-9BBC-4001-B5CB-0ECDBE128787) and [General Limitations on Transporting Data](https://docs.oracle.com/en/database/oracle/oracle-database/19/admin/transporting-data.html#GUID-28800719-6CB9-4A71-95DD-4B61AA603173) in the *Oracle Database Administrator’s Guide*. Note the following additional limitations for transportable tablespaces in RDS for Oracle:
+ Neither the source or target database can use Standard Edition 2 (SE2). Only Enterprise Edition is supported.
+ You can't use an Oracle Database 11g database as a source. The RMAN cross-platform transportable tablespaces feature relies on the RMAN transport mechanism, which Oracle Database 11g doesn't support.
+ You can't migrate data from an RDS for Oracle DB instance using transportable tablespaces. You can only use transportable tablespaces to migrate data to an RDS for Oracle DB instance.
+ The Windows operating system isn't supported.
+ You can't transport tablespaces into a database at a lower release level. The target database must be at the same or later release level as the source database. For example, you can’t transport tablespaces from Oracle Database 21c into Oracle Database 19c.
+ You can't transport administrative tablespaces such as `SYSTEM` and `SYSAUX`.
+ You can't transport non-data objects such as PL/SQL packages, Java classes, views, triggers, sequences, users, roles, and temporary tables. To transport non-data objects, create them manually or use Data Pump metadata export and import. For more information, see [My Oracle Support Note 1454872.1](https://support.oracle.com/knowledge/Oracle%20Cloud/1454872_1.html).
+ You can't transport tablespaces that are encrypted or use encrypted columns.
+ If you transfer files using Amazon S3, the maximum supported file size is 5 TiB.
+ If the source database uses Oracle options such as Spatial, you can't transport tablespaces unless the same options are configured on the target database.
+ You can't transport tablespaces into an RDS for Oracle DB instance in an Oracle replica configuration. As a workaround, you can delete all replicas, transport the tablespaces, and then recreate the replicas.
### Prerequisites for transportable tablespaces
Before you begin, complete the following tasks:
+ Review the requirements for transportable tablespaces described in the following documents in My Oracle Support:
+ [Reduce Transportable Tablespace Downtime using Cross Platform Incremental Backup (Doc ID 2471245.1)](https://support.oracle.com/epmos/faces/DocumentDisplay?id=2471245.1)
+ [Transportable Tablespace (TTS) Restrictions and Limitations: Details, Reference, and Version Where Applicable (Doc ID 1454872.1)](https://support.oracle.com/epmos/faces/DocumentDisplay?id=1454872.1)
+ [Primary Note for Transportable Tablespaces (TTS) -- Common Questions and Issues (Doc ID 1166564.1)](https://support.oracle.com/epmos/faces/DocumentDisplay?id=1166564.1)
+ Plan for endianness conversion. If you specify the source platform ID, RDS for Oracle converts the endianness automatically. To learn how to find platform IDs, see [Data Guard Support for Heterogeneous Primary and Physical Standbys in Same Data Guard Configuration (Doc ID 413484.1)](https://support.oracle.com/epmos/faces/DocumentDisplay?id=413484.1).
+ Make sure that the transportable tablespace feature is enabled on your target DB instance. The feature is enabled only if you don't get an `ORA-20304` error when you run the following query:
```
SELECT * FROM TABLE(rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files);
```
If the transportable tablespace feature isn't enabled, reboot your DB instance. For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
+ Make sure that the time zone file is the same in the source and target databases.
+ Make sure that the database character sets on the source and target databases meet either of the following requirements:
+ The character sets are the same.
+ The character sets are compatible. For a list of compatibility requirements, see [General Limitations on Transporting Data](https://docs.oracle.com/en/database/oracle/oracle-database/19/spmdu/general-limitations-on-transporting-data.html#GUID-28800719-6CB9-4A71-95DD-4B61AA603173) in the Oracle Database documentation.
+ If you plan to transfer files using Amazon S3, do the following:
+ Make sure that an Amazon S3 bucket is available for file transfers, and that the Amazon S3 bucket is in the same AWS Region as your DB instance. For instructions, see [Create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html) in the *Amazon Simple Storage Service Getting Started Guide*.
+ Prepare the Amazon S3 bucket for Amazon RDS integration by following the instructions in [Configuring IAM permissions for RDS for Oracle integration with Amazon S3](oracle-s3-integration.preparing.md).
+ If you plan to transfer files using Amazon EFS, make sure that you have configured EFS according to the instructions in [Amazon EFS integration](oracle-efs-integration.md).
+ We strongly recommend that you turn on automatic backups in your target DB instance. Because the [ metadata import step](#oracle-migrating-tts.transport.import-dmp) can potentially fail, it's important to be able to restore your DB instance to its state before the import, thereby avoiding the necessity to back up, transfer, and import your tablespaces again.
## Phase 1: Set up your source host
In this step, you copy the transport tablespaces scripts provided by My Oracle Support and set up necessary configuration files. In the following steps, the *source host* is running the database that contains the tablespaces to be transported to your *target instance*.
**To set up your source host**
1. Log in to your source host as the owner of your Oracle home.
1. Make sure that your `ORACLE_HOME` and `ORACLE_SID` environment variables point to your source database.
1. Log in to your database as an administrator, and verify that the time zone version, DB character set, and national character set are the same as in your target database.
```
SELECT * FROM V$TIMEZONE_FILE;
SELECT * FROM NLS_DATABASE_PARAMETERS
WHERE PARAMETER IN ('NLS_CHARACTERSET','NLS_NCHAR_CHARACTERSET');
```
1. Set up the transportable tablespace utility as described in [Oracle Support note 2471245.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=2471245.1).
The setup includes editing the `xtt.properties` file on your source host. The following sample `xtt.properties` file specifies backups of three tablespaces in the `/dsk1/backups` directory. These are the tablespaces that you intend to transport to your target DB instance. It also specifies the source platform ID to convert the endianness automatically.
**Note**
For valid platform IDs, see [Data Guard Support for Heterogeneous Primary and Physical Standbys in Same Data Guard Configuration (Doc ID 413484.1)](https://support.oracle.com/epmos/faces/DocumentDisplay?id=413484.1).
```
#linux system
platformid=13
#list of tablespaces to transport
tablespaces=TBS1,TBS2,TBS3
#location where backup will be generated
src_scratch_location=/dsk1/backups
#RMAN command for performing backup
usermantransport=1
```
## Phase 2: Prepare the full tablespace backup
In this phase, you back up your tablespaces for the first time, transfer the backups to your target host, and then restore them using the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces`. When this phase is complete, the initial tablespace backups reside on your target DB instance and can be updated with incremental backups.
**Topics**
+ [
### Step 1: Back up the tablespaces on your source host
](#oracle-migrating-tts.backup-full)
+ [
### Step 2: Transfer the backup files to your target DB instance
](#oracle-migrating-tts.transfer-full)
+ [
### Step 3: Import the tablespaces on your target DB instance
](#oracle-migrating-tts.initial-tts-import)
### Step 1: Back up the tablespaces on your source host
In this step, you use the `xttdriver.pl` script to make a full backup of your tablespaces. The output of `xttdriver.pl` is stored in the `TMPDIR` environment variable.
**To back up your tablespaces**
1. If your tablespaces are in read-only mode, log in to your source database as a user with the `ALTER TABLESPACE` privilege, and place your tablespaces in read/write mode. Otherwise, skip to the next step.
The following example places `tbs1`, `tbs2`, and `tbs3` in read/write mode.
```
ALTER TABLESPACE tbs1 READ WRITE;
ALTER TABLESPACE tbs2 READ WRITE;
ALTER TABLESPACE tbs3 READ WRITE;
```
1. Back up your tablespaces using the `xttdriver.pl` script. Optionally, you can specify `--debug` to run the script in debug mode.
```
export TMPDIR=location_of_log_files
cd location_of_xttdriver.pl
$ORACLE_HOME/perl/bin/perl xttdriver.pl --backup
```
### Step 2: Transfer the backup files to your target DB instance
In this step, copy the backup and configuration files from your scratch location to your target DB instance. Choose one of the following options:
+ If the source and target hosts share an Amazon EFS file system, use an operating system utility such as `cp` to copy your backup files and the `res.txt` file from your scratch location to a shared directory. Then skip to [Step 3: Import the tablespaces on your target DB instance](#oracle-migrating-tts.initial-tts-import).
+ If you need to stage your backups to an Amazon S3 bucket, complete the following steps.
![\[Transfer files using either Amazon S3 or Amazon EFS.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-tts.png)
#### Step 2.2: Upload the backups to your Amazon S3 bucket
Upload your backups and the `res.txt` file from your scratch directory to your Amazon S3 bucket. For more information, see [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) in the *Amazon Simple Storage Service User Guide*.
#### Step 2.3: Download the backups from your Amazon S3 bucket to your target DB instance
In this step, you use the procedure `rdsadmin.rdsadmin_s3_tasks.download_from_s3` to download your backups to your RDS for Oracle DB instance.
**To download your backups from your Amazon S3 bucket**
1. Start SQL\$1Plus or Oracle SQL Developer and log in to your RDS for Oracle DB instance.
1. Download the backups from the Amazon S3 bucket to your target DB instance by using the Amazon RDS procedure `rdsadmin.rdsadmin_s3_tasks.download_from_s3` to d. The following example downloads all of the files from an Amazon S3 bucket named `amzn-s3-demo-bucket` to the `DATA_PUMP_DIR` directory.
```
EXEC UTL_FILE.FREMOVE ('DATA_PUMP_DIR', 'res.txt');
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
The `SELECT` statement returns the ID of the task in a `VARCHAR2` data type. For more information, see [Downloading files from an Amazon S3 bucket to an Oracle DB instance](oracle-s3-integration.using.md#oracle-s3-integration.using.download).
### Step 3: Import the tablespaces on your target DB instance
To restore your tablespaces to your target DB instance, use the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces`. This procedure automatically converts the data files to the correct endian format.
If you import from a platform other than Linux, specify the source platform using the parameter `p_platform_id` when you call `import_xtts_tablespaces`. Make sure that the platform ID that you specify matches the one specified in the `xtt.properties` file in [Step 2: Export tablespace metadata on your source host](#oracle-migrating-tts.transport.export).
**Import the tablespaces on your target DB instance**
1. Start an Oracle SQL client and log in to your target RDS for Oracle DB instance as the master user.
1. Run the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces`, specifying the tablespaces to import and the directory containing the backups.
The following example imports the tablespaces *TBS1*, *TBS2*, and *TBS3* from the directory *DATA\$1PUMP\$1DIR*. The source platform is AIX-Based Systems (64-bit), which has the platform ID of `6`. You can find the platform IDs by querying `V$TRANSPORTABLE_PLATFORM`.
```
VAR task_id CLOB
BEGIN
:task_id:=rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces(
'TBS1,TBS2,TBS3',
'DATA_PUMP_DIR',
p_platform_id => 6);
END;
/
PRINT task_id
```
1. (Optional) Monitor progress by querying the table `rdsadmin.rds_xtts_operation_info`. The `xtts_operation_state` column shows the value `EXECUTING`, `COMPLETED`, or `FAILED`.
```
SELECT * FROM rdsadmin.rds_xtts_operation_info;
```
**Note**
For long-running operations, you can also query `V$SESSION_LONGOPS`, `V$RMAN_STATUS`, and `V$RMAN_OUTPUT`.
1. View the log of the completed import by using the task ID from the previous step.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||'&task_id'||'.log'));
```
Make sure that the import succeeded before continuing to the next step.
## Phase 3: Make and transfer incremental backups
In this phase, you make and transfer incremental backups periodically while the source database is active. This technique reduces the size of your final tablespace backup. If you take multiple incremental backups, you must copy the `res.txt` file after the last incremental backup before you can apply it on the target instance.
The steps are the same as in [Phase 2: Prepare the full tablespace backup](#oracle-migrating-tts.initial-br-phase), except that the import step is optional.
## Phase 4: Transport the tablespaces
In this phase, you back up your read-only tablespaces and export Data Pump metadata, transfer these files to your target host, and import both the tablespaces and the metadata.
**Topics**
+ [
### Step 1: Back up your read-only tablespaces
](#oracle-migrating-tts.final-backup)
+ [
### Step 2: Export tablespace metadata on your source host
](#oracle-migrating-tts.transport.export)
+ [
### Step 3: (Amazon S3 only) Transfer the backup and export files to your target DB instance
](#oracle-migrating-tts.transport)
+ [
### Step 4: Import the tablespaces on your target DB instance
](#oracle-migrating-tts.restore-full)
+ [
### Step 5: Import tablespace metadata on your target DB instance
](#oracle-migrating-tts.transport.import-dmp)
### Step 1: Back up your read-only tablespaces
This step is identical to [Step 1: Back up the tablespaces on your source host](#oracle-migrating-tts.backup-full), with one key difference: you place your tablespaces in read-only mode before backing up your tablespaces for the last time.
The following example places `tbs1`, `tbs2`, and `tbs3` in read-only mode.
```
ALTER TABLESPACE tbs1 READ ONLY;
ALTER TABLESPACE tbs2 READ ONLY;
ALTER TABLESPACE tbs3 READ ONLY;
```
### Step 2: Export tablespace metadata on your source host
Export your tablespace metadata by running the `expdb` utility on your source host. The following example exports tablespaces *TBS1*, *TBS2*, and *TBS3* to dump file *xttdump.dmp* in directory *DATA\$1PUMP\$1DIR*.
```
expdp username/pwd \
dumpfile=xttdump.dmp \
directory=DATA_PUMP_DIR \
statistics=NONE \
transport_tablespaces=TBS1,TBS2,TBS3 \
transport_full_check=y \
logfile=tts_export.log
```
If *DATA\$1PUMP\$1DIR* is a shared directory in Amazon EFS, skip to [Step 4: Import the tablespaces on your target DB instance](#oracle-migrating-tts.restore-full).
### Step 3: (Amazon S3 only) Transfer the backup and export files to your target DB instance
If you are using Amazon S3 to stage your tablespace backups and Data Pump export file, complete the following steps.
#### Step 3.1: Upload the backups and dump file from your source host to your Amazon S3 bucket
Upload your backup and dump files from your source host to your Amazon S3 bucket. For more information, see [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) in the *Amazon Simple Storage Service User Guide*.
#### Step 3.2: Download the backups and dump file from your Amazon S3 bucket to your target DB instance
In this step, you use the procedure `rdsadmin.rdsadmin_s3_tasks.download_from_s3` to download your backups and dump file to your RDS for Oracle DB instance. Follow the steps in [Step 2.3: Download the backups from your Amazon S3 bucket to your target DB instance](#oracle-migrating-tts.download-full).
### Step 4: Import the tablespaces on your target DB instance
Use the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces` to restore the tablespaces. For syntax and semantics of this procedure, see [Importing transported tablespaces to your DB instance](rdsadmin_transport_util_import_xtts_tablespaces.md)
**Important**
After you complete your final tablespace import, the next step is [importing the Oracle Data Pump metadata](#oracle-migrating-tts.transport.export). If the import fails, it's important to return your DB instance to its state before the failure. Thus, we recommend that you create a DB snapshot of your DB instance by following the instructions in [Creating a DB snapshot for a Single-AZ DB instance for Amazon RDS](USER_CreateSnapshot.md). The snapshot will contain all imported tablespaces, so if the import fails, you don’t need to repeat the backup and import process.
If your target DB instance has automatic backups turned on, and Amazon RDS doesn't detect that a valid snapshot was initiated before you import the metadata, RDS attempts to create a snapshot. Depending on your instance activity, this snapshot might or might not succeed. If a valid snapshot isn't detected or a snapshot can't be initiated, the metadata import exits with errors.
**Import the tablespaces on your target DB instance**
1. Start an Oracle SQL client and log in to your target RDS for Oracle DB instance as the master user.
1. Run the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces`, specifying the tablespaces to import and the directory containing the backups.
The following example imports the tablespaces *TBS1*, *TBS2*, and *TBS3* from the directory *DATA\$1PUMP\$1DIR*.
```
BEGIN
:task_id:=rdsadmin.rdsadmin_transport_util.import_xtts_tablespaces('TBS1,TBS2,TBS3','DATA_PUMP_DIR');
END;
/
PRINT task_id
```
1. (Optional) Monitor progress by querying the table `rdsadmin.rds_xtts_operation_info`. The `xtts_operation_state` column shows the value `EXECUTING`, `COMPLETED`, or `FAILED`.
```
SELECT * FROM rdsadmin.rds_xtts_operation_info;
```
**Note**
For long-running operations, you can also query `V$SESSION_LONGOPS`, `V$RMAN_STATUS`, and `V$RMAN_OUTPUT`.
1. View the log of the completed import by using the task ID from the previous step.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file('BDUMP', 'dbtask-'||'&task_id'||'.log'));
```
Make sure that the import succeeded before continuing to the next step.
1. Take a manual DB snapshot by following the instructions in [Creating a DB snapshot for a Single-AZ DB instance for Amazon RDS](USER_CreateSnapshot.md).
### Step 5: Import tablespace metadata on your target DB instance
In this step, you import the transportable tablespace metadata into your RDS for Oracle DB instance using the procedure `rdsadmin.rdsadmin_transport_util.import_xtts_metadata`. For syntax and semantics of this procedure, see [Importing transportable tablespace metadata into your DB instance](rdsadmin_transport_util_import_xtts_metadata.md). During the operation, the status of the import is shown in the table `rdsadmin.rds_xtts_operation_info`.
**Important**
Before you import metadata, we strongly recommend that you confirm that a DB snapshot was successfully created after you imported your tablespaces. If the import step fails, restore your DB instance, address the import errors, and then attempt the import again.
**Import the Data Pump metadata into your RDS for Oracle DB instance**
1. Start your Oracle SQL client and log in to your target DB instance as the master user.
1. Create the users that own schemas in your transported tablespaces, if these users don't already exist.
```
CREATE USER tbs_owner IDENTIFIED BY password;
```
1. Import the metadata, specifying the name of the dump file and its directory location.
```
BEGIN
rdsadmin.rdsadmin_transport_util.import_xtts_metadata('xttdump.dmp','DATA_PUMP_DIR');
END;
/
```
1. (Optional) Query the transportable tablespace history table to see the status of the metadata import.
```
SELECT * FROM rdsadmin.rds_xtts_operation_info;
```
When the operation completes, your tablespaces are in read-only mode.
1. (Optional) View the log file.
The following example lists the contents of the BDUMP directory and then queries the import log.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir(p_directory => 'BDUMP'));
SELECT * FROM TABLE(rdsadmin.rds_file_util.read_text_file(
p_directory => 'BDUMP',
p_filename => 'rds-xtts-import_xtts_metadata-2023-05-22.01-52-35.560858000.log'));
```
## Phase 5: Validate the transported tablespaces
In this optional step, you validate your transported tablespaces using the procedure `rdsadmin.rdsadmin_rman_util.validate_tablespace`, and then place your tablespaces in read/write mode.
**To validate the transported data**
1. Start SQL\$1Plus or SQL Developer and log in to your target DB instance as the master user.
1. Validate the tablespaces using the procedure `rdsadmin.rdsadmin_rman_util.validate_tablespace`.
```
SET SERVEROUTPUT ON
BEGIN
rdsadmin.rdsadmin_rman_util.validate_tablespace(
p_tablespace_name => 'TBS1',
p_validation_type => 'PHYSICAL+LOGICAL',
p_rman_to_dbms_output => TRUE);
rdsadmin.rdsadmin_rman_util.validate_tablespace(
p_tablespace_name => 'TBS2',
p_validation_type => 'PHYSICAL+LOGICAL',
p_rman_to_dbms_output => TRUE);
rdsadmin.rdsadmin_rman_util.validate_tablespace(
p_tablespace_name => 'TBS3',
p_validation_type => 'PHYSICAL+LOGICAL',
p_rman_to_dbms_output => TRUE);
END;
/
```
1. Place your tablespaces in read/write mode.
```
ALTER TABLESPACE TBS1 READ WRITE;
ALTER TABLESPACE TBS2 READ WRITE;
ALTER TABLESPACE TBS3 READ WRITE;
```
## Phase 6: Clean up leftover files
In this optional step, you remove any unneeded files. Use the `rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files` procedure to list data files that were orphaned after a tablespace import, and then use `rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files` procedure to delete them. For syntax and semantics of these procedures, see [Listing orphaned files after a tablespace import](rdsadmin_transport_util_list_xtts_orphan_files.md) and [Deleting orphaned data files after a tablespace import](rdsadmin_transport_util_cleanup_incomplete_xtts_import.md).
**To clean up leftover files**
1. Remove old backups in *DATA\$1PUMP\$1DIR* as follows:
1. List the backup files by running `rdsadmin.rdsadmin_file_util.listdir`.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir(p_directory => 'DATA_PUMP_DIR'));
```
1. Remove the backups one by one by calling `UTL_FILE.FREMOVE`.
```
EXEC UTL_FILE.FREMOVE ('DATA_PUMP_DIR', 'backup_filename');
```
1. If you imported tablespaces but didn't import metadata for these tablespaces, you can delete the orphaned data files as follows:
1. List the orphaned data files that you need to delete. The following example runs the procedure `rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files`.
```
SQL> SELECT * FROM TABLE(rdsadmin.rdsadmin_transport_util.list_xtts_orphan_files);
FILENAME FILESIZE
-------------- ---------
datafile_7.dbf 104865792
datafile_8.dbf 104865792
```
1. Delete the orphaned files by running the procedure `rdsadmin.rdsadmin_transport_util.cleanup_incomplete_xtts_import`.
```
BEGIN
rdsadmin.rdsadmin_transport_util.cleanup_incomplete_xtts_import('DATA_PUMP_DIR');
END;
/
```
The cleanup operation generates a log file that uses the name format `rds-xtts-delete_xtts_orphaned_files-YYYY-MM-DD.HH24-MI-SS.FF.log` in the `BDUMP` directory.
1. Read the log file generated in the previous step. The following example reads log `rds-xtts-delete_xtts_orphaned_files-2023-06-01.09-33-11.868894000.log`.
```
SELECT *
FROM TABLE(rdsadmin.rds_file_util.read_text_file(
p_directory => 'BDUMP',
p_filename => 'rds-xtts-delete_xtts_orphaned_files-2023-06-01.09-33-11.868894000.log'));
TEXT
--------------------------------------------------------------------------------
orphan transported datafile datafile_7.dbf deleted.
orphan transported datafile datafile_8.dbf deleted.
```
1. If you imported tablespaces and imported metadata for these tablespaces, but you encountered compatibility errors or other Oracle Data Pump issues, clean up the partially transported data files as follows:
1. List the tablespaces that contain partially transported data files by querying `DBA_TABLESPACES`.
```
SQL> SELECT TABLESPACE_NAME FROM DBA_TABLESPACES WHERE PLUGGED_IN='YES';
TABLESPACE_NAME
--------------------------------------------------------------------------------
TBS_3
```
1. Drop the tablespaces and the partially transported data files.
```
DROP TABLESPACE TBS_3 INCLUDING CONTENTS AND DATAFILES;
```
# Importing using Oracle Data Pump
Oracle Data Pump is a utility that allows you to export Oracle data to a dump file and import it into another Oracle database. It is a long-term replacement for the Oracle Export/Import utilities. Oracle Data Pump is the recommended way to move large amounts of data from an Oracle database to an Amazon RDS DB instance.
The examples in this section show one way to import data into an Oracle database, but Oracle Data Pump supports other techniques. For more information, see the [Oracle Database documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-data-pump.html#GUID-501A9908-BCC5-434C-8853-9A6096766B5A).
The examples in this section use the `DBMS_DATAPUMP` package. You can accomplish the same tasks using the Oracle Data Pump command line utilities `impdp` and `expdp`. You can install these utilities on a remote host as part of an Oracle Client installation, including Oracle Instant Client. For more information, see [How do I use Oracle Instant Client to run Data Pump Import or Export for my Amazon RDS for Oracle DB instance?](https://aws.amazon.com/premiumsupport/knowledge-center/rds-oracle-instant-client-datapump/)
**Topics**
+ [
## Overview of Oracle Data Pump
](#Oracle.Procedural.Importing.DataPump.Overview)
+ [
## Importing data with Oracle Data Pump and an Amazon S3 bucket
](#Oracle.Procedural.Importing.DataPump.S3)
+ [
## Importing data with Oracle Data Pump and a database link
](#Oracle.Procedural.Importing.DataPump.DBLink)
## Overview of Oracle Data Pump
Oracle Data Pump is made up of the following components:
+ Command-line clients `expdp` and `impdp`
+ The `DBMS_DATAPUMP` PL/SQL package
+ The `DBMS_METADATA` PL/SQL package
You can use Oracle Data Pump for the following scenarios:
+ Import data from an Oracle database, either on-premises or on an Amazon EC2 instance, to an RDS for Oracle DB instance.
+ Import data from an RDS for Oracle DB instance to an Oracle database, either on-premises or on an Amazon EC2 instance.
+ Import data between RDS for Oracle DB instances, for example, to migrate data from EC2-Classic to VPC.
To download Oracle Data Pump utilities, see [Oracle database software downloads](http://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.html) on the Oracle Technology Network website. For compatibility considerations when migrating between versions of Oracle Database, see the [ Oracle Database documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-data-pump-overview.html#GUID-BAA3B679-A758-4D55-9820-432D9EB83C68).
### Oracle Data Pump workflow
Typically, you use Oracle Data Pump in the following stages:
1. Export your data into a dump file on the source database.
1. Upload your dump file to your destination RDS for Oracle DB instance. You can transfer using an Amazon S3 bucket or by using a database link between the two databases.
1. Import the data from your dump file into your RDS for Oracle DB instance.
### Oracle Data Pump best practices
When you use Oracle Data Pump to import data into an RDS for Oracle instance, we recommend the following best practices:
+ Perform imports in `schema` or `table` mode to import specific schemas and objects.
+ Limit the schemas you import to those required by your application.
+ Don't import in `full` mode or import schemas for system-maintained components.
Because RDS for Oracle doesn't allow access to `SYS` or `SYSDBA` administrative users, these actions might damage the Oracle data dictionary and affect the stability of your database.
+ When loading large amounts of data, do the following:
1. Transfer the dump file to the target RDS for Oracle DB instance.
1. Take a DB snapshot of your instance.
1. Test the import to verify that it succeeds.
If database components are invalidated, you can delete the DB instance and re-create it from the DB snapshot. The restored DB instance includes any dump files staged on the DB instance when you took the DB snapshot.
+ Don't import dump files that were created using the Oracle Data Pump export parameters `TRANSPORT_TABLESPACES`, `TRANSPORTABLE`, or `TRANSPORT_FULL_CHECK`. RDS for Oracle DB instances don't support importing these dump files.
+ Don't import dump files that contain Oracle Scheduler objects in `SYS`, `SYSTEM`, `RDSADMIN`, `RDSSEC`, and `RDS_DATAGUARD`, and belong to the following categories:
+ Jobs
+ Programs
+ Schedules
+ Chains
+ Rules
+ Evaluation contexts
+ Rule sets
RDS for Oracle DB instances don't support importing these dump files.
+ To exclude unsupported Oracle Scheduler objects, use additional directives during the Data Pump export. If you use `DBMS_DATAPUMP`, you can add an additional `METADATA_FILTER` before the `DBMS_METADATA.START_JOB`:
```
DBMS_DATAPUMP.METADATA_FILTER(
v_hdnl,
'EXCLUDE_NAME_EXPR',
q'[IN (SELECT NAME FROM SYS.OBJ$
WHERE TYPE# IN (66,67,74,79,59,62,46)
AND OWNER# IN
(SELECT USER# FROM SYS.USER$
WHERE NAME IN ('RDSADMIN','SYS','SYSTEM','RDS_DATAGUARD','RDSSEC')
)
)
]',
'PROCOBJ'
);
```
If you use `expdp`, create a parameter file that contains the `exclude` directive shown in the following example. Then use `PARFILE=parameter_file` with your `expdp` command.
```
exclude=procobj:"IN
(SELECT NAME FROM sys.OBJ$
WHERE TYPE# IN (66,67,74,79,59,62,46)
AND OWNER# IN
(SELECT USER# FROM SYS.USER$
WHERE NAME IN ('RDSADMIN','SYS','SYSTEM','RDS_DATAGUARD','RDSSEC')
)
)"
```
## Importing data with Oracle Data Pump and an Amazon S3 bucket
The following import process uses Oracle Data Pump and an Amazon S3 bucket. The steps are as follows:
1. Export data on the source database using the Oracle [DBMS\$1DATAPUMP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_DATAPUMP.html) package.
1. Place the dump file in an Amazon S3 bucket.
1. Download the dump file from the Amazon S3 bucket to the `DATA_PUMP_DIR` directory on the target RDS for Oracle DB instance.
1. Import the data from the copied dump file into the RDS for Oracle DB instance using the package `DBMS_DATAPUMP`.
**Topics**
+ [
### Requirements for Importing data with Oracle Data Pump and an Amazon S3 bucket
](#Oracle.Procedural.Importing.DataPumpS3.requirements)
+ [
### Step 1: Grant privileges to the database user on the RDS for Oracle target DB instance
](#Oracle.Procedural.Importing.DataPumpS3.Step1)
+ [
### Step 2: Export data into a dump file using DBMS\$1DATAPUMP
](#Oracle.Procedural.Importing.DataPumpS3.Step2)
+ [
### Step 3: Upload the dump file to your Amazon S3 bucket
](#Oracle.Procedural.Importing.DataPumpS3.Step3)
+ [
### Step 4: Download the dump file from your Amazon S3 bucket to your target DB instance
](#Oracle.Procedural.Importing.DataPumpS3.Step4)
+ [
### Step 5: Import your dump file into your target DB instance using DBMS\$1DATAPUMP
](#Oracle.Procedural.Importing.DataPumpS3.Step5)
+ [
### Step 6: Clean up
](#Oracle.Procedural.Importing.DataPumpS3.Step6)
### Requirements for Importing data with Oracle Data Pump and an Amazon S3 bucket
The process has the following requirements:
+ Make sure that an Amazon S3 bucket is available for file transfers, and that the Amazon S3 bucket is in the same AWS Region as the DB instance. For instructions, see [Create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html) in the *Amazon Simple Storage Service Getting Started Guide*.
+ The object that you upload into the Amazon S3 bucket must be 5 TB or less. For more information about working with objects in Amazon S3, see [Amazon Simple Storage Service User Guide](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html).
**Note**
If you dump file exceeds 5 TB, you can run the Oracle Data Pump export with the parallel option. This operation spreads the data into multiple dump files so that you do not exceed the 5 TB limit for individual files.
+ You must prepare the Amazon S3 bucket for Amazon RDS integration by following the instructions in [Configuring IAM permissions for RDS for Oracle integration with Amazon S3](oracle-s3-integration.preparing.md).
+ You must ensure that you have enough storage space to store the dump file on the source instance and the target DB instance.
**Note**
This process imports a dump file into the `DATA_PUMP_DIR` directory, a preconfigured directory on all Oracle DB instances. This directory is located on the same storage volume as your data files. When you import the dump file, the existing Oracle data files use more space. Thus, you should make sure that your DB instance can accommodate that additional use of space. The imported dump file is not automatically deleted or purged from the `DATA_PUMP_DIR` directory. To remove the imported dump file, use [UTL\$1FILE.FREMOVE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html#GUID-09B09C2A-2C21-4F70-BF04-D0EEA7B59CAF), found on the Oracle website.
### Step 1: Grant privileges to the database user on the RDS for Oracle target DB instance
In this step, you create the schemas into which you plan to import data and grant the users necessary privileges.
**To create users and grant necessary privileges on the RDS for Oracle target instance**
1. Use SQL\$1Plus or Oracle SQL Developer to log in as the master user to the RDS for Oracle DB instance into which the data will be imported. For information about connecting to a DB instance, see [Connecting to your Oracle DB instance](USER_ConnectToOracleInstance.md).
1. Create the required tablespaces before you import the data. For more information, see [Creating and sizing tablespaces in RDS for Oracle](Appendix.Oracle.CommonDBATasks.TablespacesAndDatafiles.md#Appendix.Oracle.CommonDBATasks.CreatingTablespacesAndDatafiles).
1. Create the user account and grant the necessary permissions and roles if the user account into which the data is imported doesn't exist. If you plan to import data into multiple user schemas, create each user account and grant the necessary privileges and roles to it.
For example, the following SQL statements create a new user and grant the necessary permissions and roles to import the data into the schema owned by this user. Replace `schema_1` with the name of your schema in this step and in the following steps.
```
CREATE USER schema_1 IDENTIFIED BY my_password;
GRANT CREATE SESSION, RESOURCE TO schema_1;
ALTER USER schema_1 QUOTA 100M ON users;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
The preceding statements grant the new user the `CREATE SESSION` privilege and the `RESOURCE` role. You might need additional privileges and roles depending on the database objects that you import.
### Step 2: Export data into a dump file using DBMS\$1DATAPUMP
To create a dump file, use the `DBMS_DATAPUMP` package.
**To export Oracle data into a dump file**
1. Use SQL Plus or Oracle SQL Developer to connect to the source RDS for Oracle DB instance with an administrative user. If the source database is an RDS for Oracle DB instance, connect with the Amazon RDS master user.
1. Export the data by calling `DBMS_DATAPUMP` procedures.
The following script exports the `SCHEMA_1` schema into a dump file named `sample.dmp` in the `DATA_PUMP_DIR` directory. Replace `SCHEMA_1` with the name of the schema that you want to export.
```
DECLARE
v_hdnl NUMBER;
BEGIN
v_hdnl := DBMS_DATAPUMP.OPEN(
operation => 'EXPORT',
job_mode => 'SCHEMA',
job_name => null
);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl ,
filename => 'sample.dmp' ,
directory => 'DATA_PUMP_DIR',
filetype => dbms_datapump.ku$_file_type_dump_file
);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'sample_exp.log',
directory => 'DATA_PUMP_DIR' ,
filetype => dbms_datapump.ku$_file_type_log_file
);
DBMS_DATAPUMP.METADATA_FILTER(v_hdnl,'SCHEMA_EXPR','IN (''SCHEMA_1'')');
DBMS_DATAPUMP.METADATA_FILTER(
v_hdnl,
'EXCLUDE_NAME_EXPR',
q'[IN (SELECT NAME FROM SYS.OBJ$
WHERE TYPE# IN (66,67,74,79,59,62,46)
AND OWNER# IN
(SELECT USER# FROM SYS.USER$
WHERE NAME IN ('RDSADMIN','SYS','SYSTEM','RDS_DATAGUARD','RDSSEC')
)
)
]',
'PROCOBJ'
);
DBMS_DATAPUMP.START_JOB(v_hdnl);
END;
/
```
**Note**
Data Pump starts jobs asynchronously. For information about monitoring a Data Pump job, see [ Monitoring job status](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-data-pump-overview.html#GUID-E365D74E-12CD-495C-BA23-5A55F679C7E7) in the Oracle documentation.
1. (Optional) View the contents of the export log by calling the `rdsadmin.rds_file_util.read_text_file` procedure. For more information, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles).
### Step 3: Upload the dump file to your Amazon S3 bucket
Use the Amazon RDS procedure `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` to copy the dump file to the Amazon S3 bucket. The following example uploads all of the files from the `DATA_PUMP_DIR` directory to an Amazon S3 bucket named `amzn-s3-demo-bucket`.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
The `SELECT` statement returns the ID of the task in a `VARCHAR2` data type. For more information, see [Uploading files from your RDS for Oracle DB instance to an Amazon S3 bucket](oracle-s3-integration.using.md#oracle-s3-integration.using.upload).
### Step 4: Download the dump file from your Amazon S3 bucket to your target DB instance
Perform this step using the Amazon RDS procedure `rdsadmin.rdsadmin_s3_tasks.download_from_s3`. When you download a file to a directory, the procedure `download_from_s3` skips the download if an identically named file already exists in the directory. To remove a file from the download directory, use [UTL\$1FILE.FREMOVE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html#GUID-09B09C2A-2C21-4F70-BF04-D0EEA7B59CAF), found on the Oracle website.
**To download your dump file**
1. Start SQL\$1Plus or Oracle SQL Developer and log in as the master on your Amazon RDS target Oracle DB instance
1. Download the dump file using the Amazon RDS procedure `rdsadmin.rdsadmin_s3_tasks.download_from_s3`.
The following example downloads all files from an Amazon S3 bucket named `amzn-s3-demo-bucket` to the directory `DATA_PUMP_DIR`.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
The `SELECT` statement returns the ID of the task in a `VARCHAR2` data type. For more information, see [Downloading files from an Amazon S3 bucket to an Oracle DB instance](oracle-s3-integration.using.md#oracle-s3-integration.using.download).
### Step 5: Import your dump file into your target DB instance using DBMS\$1DATAPUMP
Use `DBMS_DATAPUMP` to import the schema into your RDS for Oracle DB instance. Additional options such as `METADATA_REMAP` might be required.
**To import data into your target DB instance**
1. Start SQL\$1Plus or SQL Developer and log in as the master user to your RDS for Oracle DB instance.
1. Import the data by calling `DBMS_DATAPUMP` procedures.
The following example imports the *SCHEMA\$11* data from `sample_copied.dmp` into your target DB instance.
```
DECLARE
v_hdnl NUMBER;
BEGIN
v_hdnl := DBMS_DATAPUMP.OPEN(
operation => 'IMPORT',
job_mode => 'SCHEMA',
job_name => null);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'sample_copied.dmp',
directory => 'DATA_PUMP_DIR',
filetype => dbms_datapump.ku$_file_type_dump_file);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'sample_imp.log',
directory => 'DATA_PUMP_DIR',
filetype => dbms_datapump.ku$_file_type_log_file);
DBMS_DATAPUMP.METADATA_FILTER(v_hdnl,'SCHEMA_EXPR','IN (''SCHEMA_1'')');
DBMS_DATAPUMP.START_JOB(v_hdnl);
END;
/
```
**Note**
Data Pump jobs are started asynchronously. For information about monitoring a Data Pump job, see [ Monitoring job status](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-data-pump-overview.html#GUID-E365D74E-12CD-495C-BA23-5A55F679C7E7) in the Oracle documentation. You can view the contents of the import log by using the `rdsadmin.rds_file_util.read_text_file` procedure. For more information, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles).
1. Verify the data import by listing the schema tables on your target DB instance.
For example, the following query returns the number of tables for `SCHEMA_1`.
```
SELECT COUNT(*) FROM DBA_TABLES WHERE OWNER='SCHEMA_1';
```
### Step 6: Clean up
After the data has been imported, you can delete the files that you don't want to keep.
**To remove unneeded files**
1. Start SQL\$1Plus or SQL Developer and log in as the master user to your RDS for Oracle DB instance.
1. List the files in `DATA_PUMP_DIR` using the following command.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir('DATA_PUMP_DIR')) ORDER BY MTIME;
```
1. Delete files in `DATA_PUMP_DIR` that you no longer require, use the following command.
```
EXEC UTL_FILE.FREMOVE('DATA_PUMP_DIR','filename');
```
For example, the following command deletes the file named `sample_copied.dmp`.
```
EXEC UTL_FILE.FREMOVE('DATA_PUMP_DIR','sample_copied.dmp');
```
## Importing data with Oracle Data Pump and a database link
The following import process uses Oracle Data Pump and the Oracle [DBMS\$1FILE\$1TRANSFER](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_FILE_TRANSFER.html) package. The steps are as follows:
1. Connect to a source Oracle database, which can be an on-premises database, Amazon EC2 instance, or an RDS for Oracle DB instance.
1. Export data using the [DBMS\$1DATAPUMP](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_DATAPUMP.html) package.
1. Use `DBMS_FILE_TRANSFER.PUT_FILE` to copy the dump file from the Oracle database to the `DATA_PUMP_DIR` directory on the target RDS for Oracle DB instance that is connected using a database link.
1. Import the data from the copied dump file into the RDS for Oracle DB instance using the ` DBMS_DATAPUMP` package.
The import process using Oracle Data Pump and the `DBMS_FILE_TRANSFER` package has the following steps.
**Topics**
+ [
### Requirements for importing data with Oracle Data Pump and a database link
](#Oracle.Procedural.Importing.DataPumpDBLink.requirements)
+ [
### Step 1: Grant privileges to the user on the RDS for Oracle target DB instance
](#Oracle.Procedural.Importing.DataPumpDBLink.Step1)
+ [
### Step 2: Grant privileges to the user on the source database
](#Oracle.Procedural.Importing.DataPumpDBLink.Step2)
+ [
### Step 3: Create a dump file using DBMS\$1DATAPUMP
](#Oracle.Procedural.Importing.DataPumpDBLink.Step3)
+ [
### Step 4: Create a database link to the target DB instance
](#Oracle.Procedural.Importing.DataPumpDBLink.Step4)
+ [
### Step 5: Copy the exported dump file to the target DB instance using DBMS\$1FILE\$1TRANSFER
](#Oracle.Procedural.Importing.DataPumpDBLink.Step5)
+ [
### Step 6: Import the data file to the target DB instance using DBMS\$1DATAPUMP
](#Oracle.Procedural.Importing.DataPumpDBLink.Step6)
+ [
### Step 7: Clean up
](#Oracle.Procedural.Importing.DataPumpDBLink.Step7)
### Requirements for importing data with Oracle Data Pump and a database link
The process has the following requirements:
+ You must have execute privileges on the `DBMS_FILE_TRANSFER` and `DBMS_DATAPUMP` packages.
+ You must have write privileges to the `DATA_PUMP_DIR` directory on the source DB instance.
+ You must ensure that you have enough storage space to store the dump file on the source instance and the target DB instance.
**Note**
This process imports a dump file into the `DATA_PUMP_DIR` directory, a preconfigured directory on all Oracle DB instances. This directory is located on the same storage volume as your data files. When you import the dump file, the existing Oracle data files use more space. Thus, you should make sure that your DB instance can accommodate that additional use of space. The imported dump file is not automatically deleted or purged from the `DATA_PUMP_DIR` directory. To remove the imported dump file, use [UTL\$1FILE.FREMOVE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html#GUID-09B09C2A-2C21-4F70-BF04-D0EEA7B59CAF), found on the Oracle website.
### Step 1: Grant privileges to the user on the RDS for Oracle target DB instance
To grant privileges to the user on the RDS for Oracle target DB instance, take the following steps:
1. Use SQL Plus or Oracle SQL Developer to connect to the RDS for Oracle DB instance into which you intend to import the data. Connect as the Amazon RDS master user. For information about connecting to the DB instance, see [Connecting to your Oracle DB instance](USER_ConnectToOracleInstance.md).
1. Create the required tablespaces before you import the data. For more information, see [Creating and sizing tablespaces in RDS for Oracle](Appendix.Oracle.CommonDBATasks.TablespacesAndDatafiles.md#Appendix.Oracle.CommonDBATasks.CreatingTablespacesAndDatafiles).
1. If the user account into which the data is imported doesn't exist, create the user account and grant the necessary permissions and roles. If you plan to import data into multiple user schemas, create each user account and grant the necessary privileges and roles to it.
For example, the following commands create a new user named *schema\$11* and grant the necessary permissions and roles to import the data into the schema for this user.
```
CREATE USER schema_1 IDENTIFIED BY my-password;
GRANT CREATE SESSION, RESOURCE TO schema_1;
ALTER USER schema_1 QUOTA 100M ON users;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
The preceding example grants the new user the `CREATE SESSION` privilege and the `RESOURCE` role. Additional privileges and roles might be required depending on the database objects that you import.
**Note**
Replace `schema_1` with the name of your schema in this step and in the following steps.
### Step 2: Grant privileges to the user on the source database
Use SQL\$1Plus or Oracle SQL Developer to connect to the RDS for Oracle DB instance that contains the data to be imported. If necessary, create a user account and grant the necessary permissions.
**Note**
If the source database is an Amazon RDS instance, you can skip this step. You use your Amazon RDS master user account to perform the export.
The following commands create a new user and grant the necessary permissions.
```
CREATE USER export_user IDENTIFIED BY my-password;
GRANT CREATE SESSION, CREATE TABLE, CREATE DATABASE LINK TO export_user;
ALTER USER export_user QUOTA 100M ON users;
GRANT READ, WRITE ON DIRECTORY data_pump_dir TO export_user;
GRANT SELECT_CATALOG_ROLE TO export_user;
GRANT EXECUTE ON DBMS_DATAPUMP TO export_user;
GRANT EXECUTE ON DBMS_FILE_TRANSFER TO export_user;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
### Step 3: Create a dump file using DBMS\$1DATAPUMP
To create a dump file, do the following:
1. Use SQL\$1Plus or Oracle SQL Developer to connect to the source Oracle instance with an administrative user or with the user you created in step 2. If the source database is an Amazon RDS for Oracle DB instance, connect with the Amazon RDS master user.
1. Create a dump file using the Oracle Data Pump utility.
The following script creates a dump file named *sample.dmp* in the `DATA_PUMP_DIR` directory.
```
DECLARE
v_hdnl NUMBER;
BEGIN
v_hdnl := DBMS_DATAPUMP.OPEN(
operation => 'EXPORT' ,
job_mode => 'SCHEMA' ,
job_name => null
);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'sample.dmp' ,
directory => 'DATA_PUMP_DIR' ,
filetype => dbms_datapump.ku$_file_type_dump_file
);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl ,
filename => 'sample_exp.log' ,
directory => 'DATA_PUMP_DIR' ,
filetype => dbms_datapump.ku$_file_type_log_file
);
DBMS_DATAPUMP.METADATA_FILTER(
v_hdnl ,
'SCHEMA_EXPR' ,
'IN (''SCHEMA_1'')'
);
DBMS_DATAPUMP.METADATA_FILTER(
v_hdnl,
'EXCLUDE_NAME_EXPR',
q'[IN (SELECT NAME FROM sys.OBJ$
WHERE TYPE# IN (66,67,74,79,59,62,46)
AND OWNER# IN
(SELECT USER# FROM SYS.USER$
WHERE NAME IN ('RDSADMIN','SYS','SYSTEM','RDS_DATAGUARD','RDSSEC')
)
)
]',
'PROCOBJ'
);
DBMS_DATAPUMP.START_JOB(v_hdnl);
END;
/
```
**Note**
Data Pump jobs are started asynchronously. For information about monitoring a Data Pump job, see [ Monitoring job status](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-data-pump-overview.html#GUID-E365D74E-12CD-495C-BA23-5A55F679C7E7) in the Oracle documentation. You can view the contents of the export log by using the `rdsadmin.rds_file_util.read_text_file` procedure. For more information, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles).
### Step 4: Create a database link to the target DB instance
Create a database link between your source DB instance and your target DB instance. Your local Oracle instance must have network connectivity to the DB instance in order to create a database link and to transfer your export dump file.
Perform this step connected with the same user account as the previous step.
If you are creating a database link between two DB instances inside the same VPC or peered VPCs, the two DB instances should have a valid route between them. The security group of each DB instance must allow ingress to and egress from the other DB instance. The security group inbound and outbound rules can refer to security groups from the same VPC or a peered VPC. For more information, see [Adjusting database links for use with DB instances in a VPC](Appendix.Oracle.CommonDBATasks.DBLinks.md).
The following command creates a database link named `to_rds` that connects to the Amazon RDS master user at the target DB instance.
```
CREATE DATABASE LINK to_rds
CONNECT TO IDENTIFIED BY
USING '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=)
(PORT=))(CONNECT_DATA=(SID=)))';
```
### Step 5: Copy the exported dump file to the target DB instance using DBMS\$1FILE\$1TRANSFER
Use `DBMS_FILE_TRANSFER` to copy the dump file from the source database instance to the target DB instance. The following script copies a dump file named sample.dmp from the source instance to a target database link named *to\$1rds* (created in the previous step).
```
BEGIN
DBMS_FILE_TRANSFER.PUT_FILE(
source_directory_object => 'DATA_PUMP_DIR',
source_file_name => 'sample.dmp',
destination_directory_object => 'DATA_PUMP_DIR',
destination_file_name => 'sample_copied.dmp',
destination_database => 'to_rds' );
END;
/
```
### Step 6: Import the data file to the target DB instance using DBMS\$1DATAPUMP
Use Oracle Data Pump to import the schema in the DB instance. Additional options such as METADATA\$1REMAP might be required.
Connect to the DB instance with the Amazon RDS master user account to perform the import.
```
DECLARE
v_hdnl NUMBER;
BEGIN
v_hdnl := DBMS_DATAPUMP.OPEN(
operation => 'IMPORT',
job_mode => 'SCHEMA',
job_name => null);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'sample_copied.dmp',
directory => 'DATA_PUMP_DIR',
filetype => dbms_datapump.ku$_file_type_dump_file );
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'sample_imp.log',
directory => 'DATA_PUMP_DIR',
filetype => dbms_datapump.ku$_file_type_log_file);
DBMS_DATAPUMP.METADATA_FILTER(v_hdnl,'SCHEMA_EXPR','IN (''SCHEMA_1'')');
DBMS_DATAPUMP.START_JOB(v_hdnl);
END;
/
```
**Note**
Data Pump jobs are started asynchronously. For information about monitoring a Data Pump job, see [ Monitoring job status](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-data-pump-overview.html#GUID-E365D74E-12CD-495C-BA23-5A55F679C7E7) in the Oracle documentation. You can view the contents of the import log by using the `rdsadmin.rds_file_util.read_text_file` procedure. For more information, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles).
You can verify the data import by viewing the user's tables on the DB instance. For example, the following query returns the number of tables for `schema_1`.
```
SELECT COUNT(*) FROM DBA_TABLES WHERE OWNER='SCHEMA_1';
```
### Step 7: Clean up
After the data has been imported, you can delete the files that you don't want to keep. You can list the files in `DATA_PUMP_DIR` using the following command.
```
SELECT * FROM TABLE(rdsadmin.rds_file_util.listdir('DATA_PUMP_DIR')) ORDER BY MTIME;
```
To delete files in `DATA_PUMP_DIR` that you no longer require, use the following command.
```
EXEC UTL_FILE.FREMOVE('DATA_PUMP_DIR','');
```
For example, the following command deletes the file named `"sample_copied.dmp"`.
```
EXEC UTL_FILE.FREMOVE('DATA_PUMP_DIR','sample_copied.dmp');
```
# Importing using Oracle Export/Import
You might consider Oracle Export/Import utilities for migrations in the following conditions:
+ Your data size is small.
+ Data types such as binary float and double aren't required.
The import process creates the necessary schema objects. Thus, you don't need to run a script to create the objects beforehand.
The easiest way to install the Oracle the export and import utilities is to install the Oracle Instant Client. To download the software, go to [https://www.oracle.com/database/technologies/instant-client.html](https://www.oracle.com/database/technologies/instant-client.html). For documentation, see [Instant Client for SQL\$1Loader, Export, and Import](https://docs.oracle.com/en/database/oracle/oracle-database/21/sutil/instant-client-sql-loader-export-import.html#GUID-FF1B6F75-09F5-4911-9317-9776FAD15965) in the *Oracle Database Utilities* manual.
**To export tables and then import them**
1. Export the tables from the source database using the `exp` command.
The following command exports the tables named `tab1`, `tab2`, and `tab3`. The dump file is `exp_file.dmp`.
```
exp cust_dba@ORCL FILE=exp_file.dmp TABLES=(tab1,tab2,tab3) LOG=exp_file.log
```
The export creates a binary dump file that contains both the schema and data for the specified tables.
1. Import the schema and data into a target database using the `imp` command.
The following command imports the tables `tab1`, `tab2`, and `tab3` from dump file `exp_file.dmp`.
```
imp cust_dba@targetdb FROMUSER=cust_schema TOUSER=cust_schema \
TABLES=(tab1,tab2,tab3) FILE=exp_file.dmp LOG=imp_file.log
```
Export and Import have other variations that might be better suited to your requirements. See the Oracle Database documentation for full details.
# Importing using Oracle SQL\$1Loader
You might consider Oracle SQL\$1Loader for large databases that contain a limited number of objects. Because the process of exporting from a source database and loading to a target database is specific to the schema, the following example creates the sample schema objects, exports from a source, and then loads the data into a target database.
The easiest way to install Oracle SQL\$1Loader is to install the Oracle Instant Client. To download the software, go to [https://www.oracle.com/database/technologies/instant-client.html](https://www.oracle.com/database/technologies/instant-client.html). For documentation, see [Instant Client for SQL\$1Loader, Export, and Import](https://docs.oracle.com/en/database/oracle/oracle-database/21/sutil/instant-client-sql-loader-export-import.html#GUID-FF1B6F75-09F5-4911-9317-9776FAD15965) in the *Oracle Database Utilities* manual.
**To import data using Oracle SQL\$1Loader**
1. Create a sample source table using the following SQL statement.
```
CREATE TABLE customer_0 TABLESPACE users
AS (SELECT ROWNUM id, o.*
FROM ALL_OBJECTS o, ALL_OBJECTS x
WHERE ROWNUM <= 1000000);
```
1. On the target RDS for Oracle DB instance, create a destination table for loading the data. The clause `WHERE 1=2` ensures that you copy the structure of `ALL_OBJECTS`, but don't copy any rows.
```
CREATE TABLE customer_1 TABLESPACE users
AS (SELECT 0 AS ID, OWNER, OBJECT_NAME, CREATED
FROM ALL_OBJECTS
WHERE 1=2);
```
1. Export the data from the source database to a text file. The following example uses SQL\$1Plus. For your data, you will likely need to generate a script that does the export for all the objects in the database.
```
ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY/MM/DD HH24:MI:SS'
SET LINESIZE 800 HEADING OFF FEEDBACK OFF ARRAY 5000 PAGESIZE 0
SPOOL customer_0.out
SET MARKUP HTML PREFORMAT ON
SET COLSEP ','
SELECT id, owner, object_name, created
FROM customer_0;
SPOOL OFF
```
1. Create a control file to describe the data. You might need to write a script to perform this step.
```
cat << EOF > sqlldr_1.ctl
load data
infile customer_0.out
into table customer_1
APPEND
fields terminated by "," optionally enclosed by '"'
(
id POSITION(01:10) INTEGER EXTERNAL,
owner POSITION(12:41) CHAR,
object_name POSITION(43:72) CHAR,
created POSITION(74:92) date "YYYY/MM/DD HH24:MI:SS"
)
```
If needed, copy the files generated by the preceding code to a staging area, such as an Amazon EC2 instance.
1. Import the data using SQL\$1Loader with the appropriate user name and password for the target database.
```
sqlldr cust_dba@targetdb CONTROL=sqlldr_1.ctl BINDSIZE=10485760 READSIZE=10485760 ROWS=1000
```
# Migrating with Oracle materialized views
To migrate large datasets efficiently, you can use Oracle materialized view replication. With replication, you can keep the target tables synchronized with the source tables. Thus, you can switch over to Amazon RDS later, if needed.
Before you can migrate using materialized views, make sure that you meet the following requirements:
+ Configure access from the target database to the source database. In the following example, access rules were enabled on the source database to allow the RDS for Oracle target database to connect to the source over SQL\$1Net.
+ Create a database link from the RDS for Oracle DB instance to the source database.
**To migrate data using materialized views**
1. Create a user account on both source and RDS for Oracle target instances that can authenticate with the same password. The following example creates a user named `dblink_user`.
```
CREATE USER dblink_user IDENTIFIED BY my-password
DEFAULT TABLESPACE users
TEMPORARY TABLESPACE temp;
GRANT CREATE SESSION TO dblink_user;
GRANT SELECT ANY TABLE TO dblink_user;
GRANT SELECT ANY DICTIONARY TO dblink_user;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
1. Create a database link from the RDS for Oracle target instance to the source instance using your newly created user.
```
CREATE DATABASE LINK remote_site
CONNECT TO dblink_user IDENTIFIED BY my-password
USING '(description=(address=(protocol=tcp) (host=my-host)
(port=my-listener-port)) (connect_data=(sid=my-source-db-sid)))';
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
1. Test the link:
```
SELECT * FROM V$INSTANCE@remote_site;
```
1. Create a sample table with primary key and materialized view log on the source instance.
```
CREATE TABLE customer_0 TABLESPACE users
AS (SELECT ROWNUM id, o.*
FROM ALL_OBJECTS o, ALL_OBJECTS x
WHERE ROWNUM <= 1000000);
ALTER TABLE customer_0 ADD CONSTRAINT pk_customer_0 PRIMARY KEY (id) USING INDEX;
CREATE MATERIALIZED VIEW LOG ON customer_0;
```
1. On the target RDS for Oracle DB instance, create a materialized view.
```
CREATE MATERIALIZED VIEW customer_0
BUILD IMMEDIATE REFRESH FAST
AS (SELECT *
FROM cust_dba.customer_0@remote_site);
```
1. On the target RDS for Oracle DB instance, refresh the materialized view.
```
EXEC DBMS_MVIEW.REFRESH('CUSTOMER_0', 'f');
```
1. Drop the materialized view and include the `PRESERVE TABLE` clause to retain the materialized view container table and its contents.
```
DROP MATERIALIZED VIEW customer_0 PRESERVE TABLE;
```
The retained table has the same name as the dropped materialized view.
# Working with read replicas for Amazon RDS for Oracle
To configure replication between Oracle DB instances, you can create replica databases. For an overview of Amazon RDS read replicas, see [Overview of Amazon RDS read replicasOverview](USER_ReadRepl.md#USER_ReadRepl.Overview). For a summary of the differences between Oracle replicas and other DB engines, see [Differences between read replicas for DB engines](USER_ReadRepl.Overview.Differences.md).
**Topics**
+ [
# Overview of RDS for Oracle replicas
](oracle-read-replicas.overview.md)
+ [
# Requirements and considerations for RDS for Oracle replicas
](oracle-read-replicas.limitations.md)
+ [
# Preparing to create an Oracle replica
](oracle-read-replicas.Configuration.md)
+ [
# Creating an RDS for Oracle replica in mounted mode
](oracle-read-replicas.creating-in-mounted-mode.md)
+ [
# Modifying the RDS for Oracle replica mode
](oracle-read-replicas.changing-replica-mode.md)
+ [
# Working with RDS for Oracle replica backups
](oracle-read-replicas.backups.md)
+ [
# Performing an Oracle Data Guard switchover
](oracle-replication-switchover.md)
+ [
# Troubleshooting RDS for Oracle replicas
](oracle-read-replicas.troubleshooting.md)
+ [
# Redo transport compression with RDS for Oracle
](oracle-read-replicas.redo-transport-compression.md)
# Overview of RDS for Oracle replicas
An *Oracle replica* database is a physical copy of your primary database. An Oracle replica in read-only mode is called a *read replica*. An Oracle replica in mounted mode is called a *mounted replica*. Oracle Database doesn't permit writes in a replica, but you can promote a replica to make it writable. The promoted read replica has the replicated data to the point when the request was made to promote it.
The following video provides a helpful overview of RDS for Oracle disaster recovery.
[](http://www.youtube.com/watch?v=-XpzhIevwVg)
For more information, see the blog post [Managed disaster recovery with Amazon RDS for Oracle cross-Region automated backups - Part 1](https://aws.amazon.com/blogs/database/managed-disaster-recovery-with-amazon-rds-for-oracle-cross-region-automated-backups-part-1/) and [Managed disaster recovery with Amazon RDS for Oracle cross-Region automated backups - Part 2](https://aws.amazon.com/blogs/database/part-2-managed-disaster-recovery-with-amazon-rds-for-oracle-xrab/).
**Topics**
+ [
## Read-only and mounted replicas
](#oracle-read-replicas.overview.modes)
+ [
## Read replicas of CDBs
](#oracle-read-replicas.overview.data-guard)
+ [
## Archived redo log retention
](#oracle-read-replicas.overview.log-retention)
+ [
## Outages during Oracle replication
](#oracle-read-replicas.overview.outages)
## Read-only and mounted replicas
When creating or modifying an Oracle replica, you can place it in either of the following modes:
Read-only
This is the default. Active Data Guard transmits and applies changes from the source database to all read replica databases.
You can create up to five read replicas from one source DB instance. For general information about read replicas that applies to all DB engines, see [Working with DB instance read replicas](USER_ReadRepl.md). For information about Oracle Data Guard, see [Oracle Data Guard concepts and administration](https://docs.oracle.com/en/database/oracle/oracle-database/19/sbydb/oracle-data-guard-concepts.html#GUID-F78703FB-BD74-4F20-9971-8B37ACC40A65) in the Oracle documentation.
Mounted
In this case, replication uses Oracle Data Guard, but the replica database doesn't accept user connections. The primary use for mounted replicas is cross-Region disaster recovery.
A mounted replica can't serve a read-only workload. The mounted replica deletes archived redo log files after it applies them, regardless of the archived log retention policy.
You can create a combination of mounted and read-only DB replicas for the same source DB instance. You can change a read-only replica to mounted mode, or change a mounted replica to read-only mode. In either case, the Oracle database preserves the archived log retention setting.
## Read replicas of CDBs
RDS for Oracle supports Data Guard read replicas for Oracle Database 19c and 21c CDBs in both single-tenant and multi-tenant configurations. You can create, manage, and promote read replicas in a CDB just as you can in a non-CDB. Mounted replicas are also supported. You get the following benefits:
+ Managed disaster recovery, high availability, and read-only access to your replicas
+ The ability to create read replicas in a different AWS Region.
+ Integration with the existing RDS read replica APIs: [CreateDBInstanceReadReplica](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstanceReadReplica.html), [PromoteReadReplica](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_PromoteReadReplica.html), and [SwitchoverReadReplica](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_SwitchoverReadReplica.html)
To use this feature, you need an Active Data Guard license and an Oracle Database Enterprise Edition license for both the replica and primary DB instances. There are no additional costs related to using CDB architecture. You pay only for your DB instances.
For more information about the single-tenant and multi-tenant configurations of the CDB architecture, see [Overview of RDS for Oracle CDBs](Oracle.Concepts.CDBs.md).
## Archived redo log retention
If a primary DB instance has no cross-Region read replicas, Amazon RDS for Oracle keeps a minimum of two hours of archived redo logs on the source DB instance. This is true regardless of the setting for `archivelog retention hours` in `rdsadmin.rdsadmin_util.set_configuration`.
RDS purges logs from the source DB instance after two hours or after the archive log retention hours setting has passed, whichever is longer. RDS purges logs from the read replica after the archive log retention hours setting has passed only if they have been successfully applied to the database.
In some cases, a primary DB instance might have one or more cross-Region read replicas. If so, Amazon RDS for Oracle keeps the transaction logs on the source DB instance until they have been transmitted and applied to all cross-Region read replicas. For information about `rdsadmin.rdsadmin_util.set_configuration`, see [Retaining archived redo logs](Appendix.Oracle.CommonDBATasks.RetainRedoLogs.md).
## Outages during Oracle replication
When you create a read replica, Amazon RDS takes a DB snapshot of your source DB instance and begins replication. The source DB instance experiences a very brief I/O suspension when the DB snapshot operation begins. The I/O suspension typically lasts about one second. You can avoid the I/O suspension if the source DB instance is a Multi-AZ deployment, because in that case the snapshot is taken from the secondary DB instance.
The DB snapshot becomes the Oracle replica. Amazon RDS sets the necessary parameters and permissions for the source database and replica without service interruption. Similarly, if you delete a replica, no outage occurs.
# Requirements and considerations for RDS for Oracle replicas
Before creating an Oracle replica, familiarize yourself with the following requirements and considerations.
**Topics**
+ [
## Version and licensing requirements for RDS for Oracle replicas
](#oracle-read-replicas.limitations.versions-and-licenses)
+ [
## Option group limitations for RDS for Oracle replicas
](#oracle-read-replicas.limitations.options)
+ [
## Backup and restore considerations for RDS for Oracle replicas
](#oracle-read-replicas.limitations.backups)
+ [
## Oracle Data Guard requirements and limitations for RDS for Oracle replicas
](#oracle-read-replicas.data-guard.requirements)
+ [
## Multi-tenant configuration limitations for RDS for Oracle replicas
](#oracle-read-replicas.limitations.multitenant)
+ [
## Miscellaneous considerations for RDS for Oracle replicas
](#oracle-read-replicas.limitations.miscellaneous)
## Version and licensing requirements for RDS for Oracle replicas
Before you create an RDS for Oracle replica, consider the following:
+ If the replica is in read-only mode, make sure that you have an Active Data Guard license. If you place the replica in mounted mode, you don't need an Active Data Guard license. Only the Oracle DB engine supports mounted replicas.
+ Oracle replicas are supported only for Oracle Enterprise Edition (EE).
+ Oracle replicas of non-CDBs are supported only for DB instances created using non-CDB instances running Oracle Database 19c.
+ Oracle replicas are available for DB instances running only on DB instance classes with two or more vCPUs. A source DB instance can't use the db.t3.small instance class.
+ The Oracle DB engine version of the source DB instance and all its replicas must be the same. Amazon RDS upgrades the replicas immediately after upgrading the source DB instance, regardless of a replica's maintenance window. For major version upgrades of cross-Region replicas, Amazon RDS automatically does the following:
+ Generates an option group for the target version.
+ Copies all options and option settings from the original option group to the new option group.
+ Associates the upgraded cross-Region replica with the new option group.
For more information about upgrading the DB engine version, see [Upgrading the RDS for Oracle DB engine](USER_UpgradeDBInstance.Oracle.md).
## Option group limitations for RDS for Oracle replicas
When working with option groups for your RDS for Oracle replica, consider the following:
+ You can't use a replica option group different from the source DB instance option group when the source and replica are in the same AWS Region.
Modifications to the source option group or source option group membership propagate to Oracle replicas. These changes are applied to the replicas immediately after they are applied to the source DB instance, regardless of the replica's maintenance window. For more information about option groups, see [Working with option groups](USER_WorkingWithOptionGroups.md).
+ You can't remove an RDS for Oracle cross-Region replica from its dedicated option group, which is automatically created for the replica.
+ You can't add the dedicated option group for an RDS for Oracle cross-Region replica to a different DB instance.
+ You can't add or remove nonreplicated options from a dedicated option group for an RDS for Oracle cross-Region replica, with the exception of the following options:
+ `NATIVE_NETWORK_ENCRYPTION`
+ `OEM`
+ `OEM_AGENT`
+ `SSL`
To add other options to an RDS for Oracle cross-Region replica, add them to the source DB instance's option group. The option is also installed on all of the source DB instance's replicas. For licensed options, make sure that there are sufficient licenses for the replicas.
When you promote an RDS for Oracle cross-Region replica, the promoted replica behaves the same as other Oracle DB instances, including the management of its options. You can promote a replica explicitly or implicitly by deleting its source DB instance.
For more information about option groups, see [Working with option groups](USER_WorkingWithOptionGroups.md).
+ You can't add the `EFS_INTEGRATION` option to RDS for Oracle cross-Region replicas.
## Backup and restore considerations for RDS for Oracle replicas
Before you create an RDS for Oracle replica, consider the following:
+ To create snapshots of RDS for Oracle replicas or turn on automatic backups, make sure to set the backup retention period manually. Automatic backups aren't turned on by default.
+ When you restore a replica backup, you restore to the database time, not the time that the backup was taken. The database time refers to the latest applied transaction time of the data in the backup. The difference is significant because a replica can lag behind the primary for minutes or hours.
To find the difference, use the `describe-db-snapshots` command. Compare the `snapshotDatabaseTime`, which is the database time of the replica backup, and the `OriginalSnapshotCreateTime` field, which is the latest applied transaction on the primary database.
## Oracle Data Guard requirements and limitations for RDS for Oracle replicas
Before you create an RDS for Oracle replica, note the following requirements and limitations:
+ If your primary DB instance uses the single-tenant or multi-tenant configuration of the multitenant architecture, consider the following:
+ You must use Oracle Database 19c or higher with the Enterprise Edition.
+ Your primary CDB instance must be in an `ACTIVE` lifecycle.
+ You can't convert a non-CDB primary instance to a CDB instance and convert its replicas in the same operation. Instead, delete the non-CDB replicas, convert the primary DB instance to a CDB, and then create new replicas
+ Make sure that a logon trigger on a primary DB instance permits access to the `RDS_DATAGUARD` user and to any user whose `AUTHENTICATED_IDENTITY` value is `RDS_DATAGUARD` or `rdsdb`. Also, the trigger must not set the current schema for the `RDS_DATAGUARD` user.
+ To avoid blocking connections from the Data Guard broker process, don't enable restricted sessions. For more information about restricted sessions, see [Enabling and disabling restricted sessions](Appendix.Oracle.CommonDBATasks.RestrictedSession.md).
## Multi-tenant configuration limitations for RDS for Oracle replicas
When using the multi-tenant configuration on an RDS for Oracle replica, note the following limitations:
+ You can only create, delete, or modify tenant databases on the primary DB instance. These changes automatically propagate to the replicas.
+ Tenant databases on an RDS for Oracle primary, source, or replica cannot be created with a custom character set. If you require a custom character set, create the tenant databases before creating read replicas for the DB instance.
## Miscellaneous considerations for RDS for Oracle replicas
Before you create an RDS for Oracle replica, consider the following:
+ When you are creating an RDS for Oracle replica for a DB instance that has additional storage volumes, RDS automatically configure additional storage volumes on the replica. However, any subsequent modifications made in storage volumes of your primary DB instance are not automatically applied to the replica.
+ If you add additional storage volumes in your primary DB instance, RDS does not automatically add additional storage volumes to the replica. You need to modify your replica to add additional storage volumes.
+ If you modify storage volumes configuration such as storage size and IOPS in your primary DB instance, RDS does not automatically modify storage volumes in the replica. You need to modify your replica to update storage volume configurations.
+ When managing datafile locations across volumes, note that changes made on your primary instance don't automatically sync to replicas.
+ For read-only replicas: You can either use parameter group settings to control default file locations, or manually move files after they're created.
+ For mounted replicas: Manual changes to datafile locations in the primary database require recreating the mounted replica to reflect those changes. To avoid this, we recommend using parameter group settings to manage default file locations.
+ If your DB instance is a source for one or more cross-Region replicas, the source DB retains its archived redo log files until they are applied on all cross-Region replicas. The archived redo logs might result in increased storage consumption.
+ To avoid disrupting RDS automation, system triggers must permit specific users to log on to the primary and replica database. [System triggers](https://docs.oracle.com/en/database/oracle/oracle-database/19/lnpls/plsql-triggers.html#GUID-FE23FCE8-DE36-41EF-80A9-6B4B49E80E5B) include DDL, logon, and database role triggers. We recommend that you add code to your triggers to exclude the users listed in the following sample code:
```
-- Determine who the user is
SELECT SYS_CONTEXT('USERENV','AUTHENTICATED_IDENTITY') INTO CURRENT_USER FROM DUAL;
-- The following users should always be able to login to either the Primary or Replica
IF CURRENT_USER IN ('master_user', 'SYS', 'SYSTEM', 'RDS_DATAGUARD', 'rdsdb') THEN
RETURN;
END IF;
```
+ Block change tracking is supported for read-only replicas, but not for mounted replicas. You can change a mounted replica to a read-only replica, and then enable block change tracking. For more information, see [Enabling and disabling block change tracking](Appendix.Oracle.CommonDBATasks.BlockChangeTracking.md).
+ You can't create an Oracle read replica when the source database manages master user credentials with Secrets Manager.
# Preparing to create an Oracle replica
Before you can begin using your replica, perform the following tasks.
**Topics**
+ [
## Enabling automatic backups
](#oracle-read-replicas.configuration.autobackups)
+ [
## Enabling force logging mode
](#oracle-read-replicas.configuration.force-logging)
+ [
## Changing your logging configuration
](#oracle-read-replicas.configuration.logging-config)
+ [
## Setting the MAX\$1STRING\$1SIZE parameter
](#oracle-read-replicas.configuration.string-size)
+ [
## Planning compute and storage resources
](#oracle-read-replicas.configuration.planning-resources)
## Enabling automatic backups
Before a DB instance can serve as a source DB instance, make sure to enable automatic backups on the source DB instance. To learn how to perform this procedure, see [Enabling automated backups](USER_WorkingWithAutomatedBackups.Enabling.md).
## Enabling force logging mode
We recommend that you enable force logging mode. In force logging mode, the Oracle database writes redo records even when `NOLOGGING` is used with data definition language (DDL) statements.
**To enable force logging mode**
1. Log in to your Oracle database using a client tool such as SQL Developer.
1. Enable force logging mode by running the following procedure.
```
exec rdsadmin.rdsadmin_util.force_logging(p_enable => true);
```
For more information about this procedure, see [Setting force logging](Appendix.Oracle.CommonDBATasks.Log.md#Appendix.Oracle.CommonDBATasks.SettingForceLogging).
## Changing your logging configuration
For *n* online redo logs of size *m*, RDS automatically creates *n*\$11 standby logs of size *m* on the primary DB instance and all replicas. Whenever you change the logging configuration on the primary, the changes propagate automatically to the replicas.
If you change your logging configuration, consider the following guidelines:
+ We recommend that you complete the changes before making a DB instance the source for replicas. RDS for Oracle also supports updating the instance after it becomes a source.
+ Before you change the logging configuration on the primary DB instance, check that each replica has enough storage to accommodate the new configuration.
You can modify the logging configuration for a DB instance by using the Amazon RDS procedures `rdsadmin.rdsadmin_util.add_logfile` and `rdsadmin.rdsadmin_util.drop_logfile`. For more information, see [Adding online redo logs](Appendix.Oracle.CommonDBATasks.Log.md#Appendix.Oracle.CommonDBATasks.RedoLogs) and [Dropping online redo logs](Appendix.Oracle.CommonDBATasks.Log.md#Appendix.Oracle.CommonDBATasks.DroppingRedoLogs).
## Setting the MAX\$1STRING\$1SIZE parameter
Before you create an Oracle replica, ensure that the setting of the `MAX_STRING_SIZE` parameter is the same on the source DB instance and the replica. You can do this by associating them with the same parameter group. If you have different parameter groups for the source and the replica, you can set `MAX_STRING_SIZE` to the same value. For more information about setting this parameter, see [Turning on extended data types for a new DB instance](Oracle.Concepts.ExtendedDataTypes.md#Oracle.Concepts.ExtendedDataTypes.CreateDBInstance).
## Planning compute and storage resources
Ensure that the source DB instance and its replicas are sized properly, in terms of compute and storage, to suit their operational load. If a replica reaches compute, network, or storage resource capacity, the replica stops receiving or applying changes from its source. Amazon RDS for Oracle doesn't intervene to mitigate high replica lag between a source DB instance and its replicas. You can modify the storage and CPU resources of a replica independently from its source and other replicas.
# Creating an RDS for Oracle replica in mounted mode
By default, Oracle replicas are read-only. To create a replica in mounted mode, use the console, the AWS CLI, or the RDS API.
## Console
**To create a mounted replica from a source 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**.
1. Choose the Oracle DB instance that you want to use as the source for a mounted replica.
1. For **Actions**, choose **Create replica**.
1. For **Replica mode**, choose **Mounted**.
1. Choose the settings that you want to use. For **DB instance identifier**, enter a name for the read replica. Adjust other settings as needed.
1. For **Regions**, choose the Region where the mounted replica will be launched.
1. Choose your instance size and storage type. We recommend that you use the same DB instance class and storage type as the source DB instance for the read replica.
1. For **Multi-AZ deployment**, choose **Create a standby instance** to create a standby of your replica in another Availability Zone for failover support for the mounted replica. Creating your mounted replica as a Multi-AZ DB instance is independent of whether the source database is a Multi-AZ DB instance.
1. Choose the other settings that you want to use.
1. Choose **Create replica**.
In the **Databases** page, the mounted replica has the role Replica.
## AWS CLI
To create an Oracle replica in mounted mode, set `--replica-mode` to `mounted` in the AWS CLI command [create-db-instance-read-replica](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-instance-read-replica.html).
**Example**
For Linux, macOS, or Unix:
```
aws rds create-db-instance-read-replica \
--db-instance-identifier myreadreplica \
--source-db-instance-identifier mydbinstance \
--replica-mode mounted
```
For Windows:
```
aws rds create-db-instance-read-replica ^
--db-instance-identifier myreadreplica ^
--source-db-instance-identifier mydbinstance ^
--replica-mode mounted
```
To change a read-only replica to a mounted state, set `--replica-mode` to `mounted` in the AWS CLI command [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html). To place a mounted replica in read-only mode, set `--replica-mode` to `open-read-only`.
## RDS API
To create an Oracle replica in mounted mode, specify `ReplicaMode=mounted` in the RDS API operation [CreateDBInstanceReadReplica](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstanceReadReplica.html).
# Modifying the RDS for Oracle replica mode
To change the replica mode of an existing replica, use the console, AWS CLI, or RDS API. When you change to mounted mode, the replica disconnects all active connections. When you change to read-only mode, Amazon RDS initializes Active Data Guard.
The change operation can take a few minutes. During the operation, the DB instance status changes to **modifying**. For more information about status changes, see [Viewing Amazon RDSDB instance status](accessing-monitoring.md#Overview.DBInstance.Status).
## Console
**To change the replica mode of an Oracle replica from mounted to read-only**
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**.
1. Choose the mounted replica database.
1. Choose **Modify**.
1. For **Replica mode**, choose **Read-only**.
1. Choose the other settings that you want to change.
1. Choose **Continue**.
1. For **Scheduling of modifications**, choose **Apply immediately**.
1. Choose **Modify DB instance**.
## AWS CLI
To change a read replica to mounted mode, set `--replica-mode` to `mounted` in the AWS CLI command [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html). To change a mounted replica to read-only mode, set `--replica-mode` to `open-read-only`.
**Example**
For Linux, macOS, or Unix:
```
aws rds modify-db-instance \
--db-instance-identifier myreadreplica \
--replica-mode mode
```
For Windows:
```
aws rds modify-db-instance ^
--db-instance-identifier myreadreplica ^
--replica-mode mode
```
## RDS API
To change a read-only replica to mounted mode, set `ReplicaMode=mounted` in [ModifyDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstanceReadReplica.html). To change a mounted replica to read-only mode, set `ReplicaMode=read-only`.
# Working with RDS for Oracle replica backups
You can create and restore backups of an RDS for Oracle replica. Both automatic backups and manual snapshots are supported. For more information, see [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md). The following sections describe the key differences between managing backups of a primary and an RDS for Oracle replica.
## Turning on RDS for Oracle replica backups
An Oracle replica doesn't have automated backups turned on by default. You turn on automated backups by setting the backup retention period to a positive nonzero value.
### Console
**To enable automated backups immediately**
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 DB instance or Multi-AZ DB cluster that you want to modify.
1. Choose **Modify**.
1. For **Backup retention period**, choose a positive nonzero value, for example three days.
1. Choose **Continue**.
1. Choose **Apply immediately**.
1. Choose **Modify DB instance** or **Modify cluster** to save your changes and enable automated backups.
### AWS CLI
To enable automated backups, use the AWS CLI [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) or [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) command.
Include the following parameters:
+ `--db-instance-identifier` (or `--db-cluster-identifier` for a Multi-AZ DB cluster)
+ `--backup-retention-period`
+ `--apply-immediately` or `--no-apply-immediately`
In the following example, we enable automated backups by setting the backup retention period to three days. The changes are applied immediately.
**Example**
For Linux, macOS, or Unix:
```
aws rds modify-db-instance \
--db-instance-identifier my_db_instance \
--backup-retention-period 3 \
--apply-immediately
```
For Windows:
```
aws rds modify-db-instance ^
--db-instance-identifier my_db_instance ^
--backup-retention-period 3 ^
--apply-immediately
```
### RDS API
To enable automated backups, use the RDS API [ModifyDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html) or [ModifyDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) operation with the following required parameters:
+ `DBInstanceIdentifier` or `DBClusterIdentifier`
+ `BackupRetentionPeriod`
## Restoring an RDS for Oracle replica backup
You can restore an Oracle replica backup just as you can restore a backup of the primary instance. For more information, see the following:
+ [Restoring to a DB instance](USER_RestoreFromSnapshot.md)
+ [Restoring a DB instance to a specified time for Amazon RDS](USER_PIT.md)
The main consideration when you restore a replica backup is determining the point in time to which you are restoring. The database time refers to the latest applied transaction time of the data in the backup. When you restore a replica backup, you restore to the database time, not the time when the backup completed. The difference is significant because an RDS for Oracle replica can lag behind the primary by minutes or hours. Thus, the database time of a replica backup, and thus the point in time to which you restore it, might be much earlier than the backup creation time.
To find the difference between database time and creation time, use the `describe-db-snapshots` command. Compare the `SnapshotDatabaseTime`, which is the database time of the replica backup, and the `OriginalSnapshotCreateTime` field, which is the latest applied transaction on the primary database. The following example shows the difference between the two times:
```
aws rds describe-db-snapshots \
--db-instance-identifier my-oracle-replica
--db-snapshot-identifier my-replica-snapshot
{
"DBSnapshots": [
{
"DBSnapshotIdentifier": "my-replica-snapshot",
"DBInstanceIdentifier": "my-oracle-replica",
"SnapshotDatabaseTime": "2022-07-26T17:49:44Z",
...
"OriginalSnapshotCreateTime": "2021-07-26T19:49:44Z"
}
]
}
```
# Performing an Oracle Data Guard switchover
A *switchover* is a role reversal between a primary database and a standby database. During a switchover, the original primary database transitions to a standby role, while the original standby database transitions to the primary role.
In an Oracle Data Guard environment, a primary database supports one or more standby databases. You can perform a managed, switchover-based role transition from a primary database to a standby database. A *switchover* is a role reversal between a primary database and a standby database. During a switchover, the original primary database transitions to a standby role, while the original standby database transitions to the primary role.
**Topics**
+ [
## Overview of Oracle Data Guard switchover
](#oracle-replication-switchover.overview)
+ [
# Requirements for the Oracle Data Guard switchover
](oracle-switchover.preparing.md)
+ [
# Initiating the Oracle Data Guard switchover
](oracle-switchover.initiating.md)
+ [
# Monitoring the Oracle Data Guard switchover
](oracle-switchover.monitoring.md)
## Overview of Oracle Data Guard switchover
Amazon RDS supports a fully managed, switchover-based role transition for Oracle Database replicas. You can only initiate a switchover to a standby database that is mounted or open read-only.
The replicas can reside in separate AWS Regions or in different Availability Zones (AZs) of a single Region. All AWS Regions are supported.
![\[Switch over a standby instance to make it the primary DB instance\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/read-replica-switchover.png)
A switchover differs from a read replica promotion. In a switchover, the source and replica DB instances change roles. In a promotion, a read replica becomes a source DB instance, but the source DB instance doesn't become a replica. For more information, see [Promoting a read replica to be a standalone DB instance](USER_ReadRepl.Promote.md).
**Topics**
+ [
### Benefits of Oracle Data Guard switchover
](#oracle-replication-switchover.overview.benefits)
+ [
### Supported Oracle Database versions
](#oracle-replication-switchover.overview.engine-support)
+ [
### Cost of Oracle Data Guard switchover
](#oracle-replication-switchover.overview.cost)
+ [
### How Oracle Data Guard switchover works
](#oracle-replication-switchover.overview.how-it-works)
### Benefits of Oracle Data Guard switchover
Just as for RDS for Oracle read replicas, a managed switchover relies on Oracle Data Guard. The operation is designed to have zero data loss. Amazon RDS automates the following aspects of the switchover:
+ Reverses the roles of your primary database and specified standby database, putting the new standby database in the same state (mounted or read-only) as the original standby
+ Ensures data consistency
+ Maintains your replication configuration after the transition
+ Supports repeated reversals, allowing your new standby database to return to its original primary role
### Supported Oracle Database versions
Oracle Data Guard switchover is supported for Oracle Database 19c and higher releases.
### Cost of Oracle Data Guard switchover
The Oracle Data Guard switchover feature doesn't incur additional costs. Oracle Database Enterprise Edition includes support for standby databases in mounted mode. To open standby databases in read-only mode, you need the Oracle Active Data Guard option.
### How Oracle Data Guard switchover works
Oracle Data Guard switchover is a fully managed operation. You initiate the switchover for a standby database by issuing the CLI command `switchover-read-replica`. Then Amazon RDS modifies the primary and standby roles in your replication configuration.
The *original standby* and *original primary* are the roles that exist before the switchover. The *new standby* and *new primary* are the roles that exist after the switchover. A *bystander replica* is a replica database that serves as a standby database in the Oracle Data Guard environment but is not switching roles.
**Topics**
+ [
#### Stages of the Oracle Data Guard switchover
](#oracle-replication-switchover.overview.how-it-works.during-switchover)
+ [
#### After the Oracle Data Guard switchover
](#oracle-replication-switchover.overview.how-it-works.after-switchover)
#### Stages of the Oracle Data Guard switchover
To perform the switchover, Amazon RDS must take the following steps:
1. Block new transactions on the original primary database. During the switchover, Amazon RDS interrupts replication for all databases in your Oracle Data Guard configuration. During the switchover, the original primary database can't process write requests.
1. Ship unapplied transactions to the original standby database, and apply them.
1. Restart the new standby database in read-only or mounted mode. The mode depends on the open state of the original standby database before the switchover.
1. Open the new primary database in read/write mode.
#### After the Oracle Data Guard switchover
Amazon RDS switches the roles of the primary and standby database. You are responsible for reconnecting your application and performing any other desired configuration.
**Topics**
+ [
##### Success criteria
](#oracle-replication-switchover.overview.how-it-works.after-switchover.success)
+ [
##### Connection to the new primary database
](#oracle-replication-switchover.overview.how-it-works.after-switchover.connection)
+ [
##### Configuration of the new primary database
](#oracle-replication-switchover.overview.how-it-works.after-switchover.success.configuration)
##### Success criteria
The Oracle Data Guard switchover is successful when the original standby database does the following:
+ Transitions to its role as new primary database
+ Completes its reconfiguration
To limit downtime, your new primary database becomes active as soon as possible. Because Amazon RDS configures bystander replicas asynchronously, these replicas might become active after the original primary database.
##### Connection to the new primary database
Amazon RDS won't propagate your current database connections to the new primary database after the switchover. After the Oracle Data Guard switchover completes, reconnect your application to the new primary database.
##### Configuration of the new primary database
To perform a switchover to the new primary database, Amazon RDS changes the mode of the original standby database to open. The change in role is the only change to the database. Amazon RDS doesn't set up features such as Multi-AZ replication.
If you perform a switchover to a cross-Region replica with different options, the new primary database keeps its own options. Amazon RDS won't migrate the options on the original primary database. If the original primary database had options such as SSL, NNE, OEM, and OEM\$1AGENT, Amazon RDS doesn't propagate them to the new primary database.
# Requirements for the Oracle Data Guard switchover
Before initiating the Oracle Data Guard switchover, make sure that your replication environment meets the following requirements:
+ The original standby database is mounted or open read-only.
+ Automatic backups are enabled on the original standby database.
+ The original primary database and the original standby database are in the `available` state.
+ The original primary database and the original standby database don't have pending maintenance actions in any of the following states: `required`, `next window`, or `in progress`. Actions in these states block switchover. To learn how to check the status of pending maintenance updates, see [Viewing pending maintenance updates](USER_UpgradeDBInstance.Maintenance.md#USER_UpgradeDBInstance.Maintenance.Viewing).
Pending maintenance actions in the `available` state don't block switchover. RDS for Oracle frequently releases operating system (OS) updates in the `available` state. These pending OS updates won't block a switchover unless you schedule them for the next maintenance window, which puts them in the `next window` state.
**Note**
If you want to defer a scheduled maintenance action so that you can execute a switchover, choose **Actions** and then **Defer upgrade** in the RDS console. You can also prevent a switchover from being blocked by applying a pending maintenance action or moving the maintenance window to an interval before your switchover. For more information, see the re:Post article [How to remove RDS pending maintenance items](https://repost.aws/questions/QUV3dBjmVVRnmVV1pAlzjx1w/how-to-remove-rds-pending-maintenance-item).
+ The original standby database is in the replicating state.
+ You aren't attempting to initiate a switchover when either the primary database or standby database is currently in a switchover lifecycle. If a replica database is reconfiguring after a switchover, Amazon RDS prevents you from initiating another switchover.
**Note**
A *bystander replica* is a replica in the Oracle Data Guard configuration that isn't the target of the switchover. Bystander replicas can be in any state during the switchover.
+ The original standby database has a configuration that is as close as desired to the original primary database. Assume a scenario where the original primary and original standby databases have different options. After the switchover completes, Amazon RDS doesn't automatically reconfigure the new primary database to have the same options as the original primary database.
+ You configure your desired Multi-AZ deployment before initiating a switchover. Amazon RDS doesn't manage Multi-AZ as part of the switchover. The Multi-AZ deployment remains as it is.
Assume that db\$1maz is the primary database in a Multi-AZ deployment, and db\$1saz is a Single-AZ replica. You initiate a switchover from db\$1maz to db\$1saz. Afterward, db\$1maz is a Multi-AZ replica database, and db\$1saz is a Single-AZ primary database. The new primary database is now unprotected by a Multi-AZ deployment.
+ In preparation for a cross-Region switchover, the primary database doesn't use the same option group as a DB instance outside of the replication configuration. For a cross-Region switchover to succeed, the current primary database and its read replicas must be the only DB instances to use the option group of the current primary database. Otherwise, Amazon RDS prevents the switchover.
# Initiating the Oracle Data Guard switchover
You can switch over an RDS for Oracle read replica to the primary role, and the former primary DB instance to a replica role.
## Console
**To switch over an Oracle read replica to the primary DB role**
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 Amazon RDS console, choose **Databases**.
The **Databases** pane appears. Each read replica shows **Replica** in the **Role** column.
1. Choose the read replica that you want to switch over to the primary role.
1. For **Actions**, choose **Switch over replica**.
1. Choose **I acknowledge**. Then choose **Switch over replica**.
1. On the **Databases** page, monitor the progress of the switchover.
![\[Monitor the progress of the Oracle Data Guard switchover.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-switchover-progress.png)
When the switchover completes, the role of the switchover target changes from **Replica** to **Source**.
![\[The source and replica databases change roles.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-switchover-complete.png)
## AWS CLI
To switch over an Oracle replica to the primary DB role, use the AWS CLI [https://docs.aws.amazon.com/cli/latest/reference/rds/switchover-read-replica.html](https://docs.aws.amazon.com/cli/latest/reference/rds/switchover-read-replica.html) command. The following examples make the Oracle replica named *replica-to-be-made-primary* into the new primary database.
**Example**
For Linux, macOS, or Unix:
```
aws rds switchover-read-replica \
--db-instance-identifier replica-to-be-made-primary
```
For Windows:
```
aws rds switchover-read-replica ^
--db-instance-identifier replica-to-be-made-primary
```
## RDS API
To switch over an Oracle replica to the primary DB role, call the Amazon RDS API [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_SwitchoverReadReplica.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_SwitchoverReadReplica.html) operation with the required parameter `DBInstanceIdentifier`. This parameter specifies the name of the Oracle replica that you want to assume the primary DB role.
# Monitoring the Oracle Data Guard switchover
To check the status of your instances, use the AWS CLI command `describe-db-instances`. The following command checks the status of the DB instance *orcl2*. This database was a standby database before the switchover, but is the new primary database after the switchover.
```
aws rds describe-db-instances \
--db-instance-identifier orcl2
```
To confirm that the switchover completed successfully, query `V$DATABASE.OPEN_MODE`. Check that the value for the new primary database is `READ WRITE`.
```
SELECT OPEN_MODE FROM V$DATABASE;
```
To look for switchover-related events, use the AWS CLI command `describe-events`. The following example looks for events on the *orcl2* instance.
```
aws rds describe-events \
--source-identifier orcl2 \
--source-type db-instance
```
# Troubleshooting RDS for Oracle replicas
This section describes possible replication problems and solutions.
**Topics**
+ [
## Monitoring Oracle replication lag
](#oracle-read-replicas.troubleshooting.lag)
+ [
## Troubleshooting Oracle replication failure after adding or modifying triggers
](#oracle-read-replicas.troubleshooting.triggers)
## Monitoring Oracle replication lag
To monitor replication lag in Amazon CloudWatch, view the Amazon RDS `ReplicaLag` metric. For more information about replication lag time, see [Monitoring read replication](USER_ReadRepl.Monitoring.md) and [Amazon CloudWatch metrics for Amazon RDS](rds-metrics.md).
For a read replica, if the lag time is too long, query the following views:
+ `V$ARCHIVED_LOG` – Shows which commits have been applied to the read replica.
+ `V$DATAGUARD_STATS` – Shows a detailed breakdown of the components that make up the `ReplicaLag` metric.
+ `V$DATAGUARD_STATUS` – Shows the log output from Oracle's internal replication processes.
For a mounted replica, if the lag time is too long, you can't query the `V$` views. Instead, do the following:
+ Check the `ReplicaLag` metric in CloudWatch.
+ Check the alert log file for the replica in the console. Look for errors in the recovery messages. The messages include the log sequence number, which you can compare to the primary sequence number. For more information, see [Amazon RDS for Oracle database log files](USER_LogAccess.Concepts.Oracle.md).
## Troubleshooting Oracle replication failure after adding or modifying triggers
If you add or modify any triggers, and if replication fails afterward, the problem may be the triggers. Ensure that the trigger excludes the following user accounts, which are required by RDS for replication:
+ User accounts with administrator privileges
+ `SYS`
+ `SYSTEM`
+ `RDS_DATAGUARD`
+ `rdsdb`
For more information, see [Miscellaneous considerations for RDS for Oracle replicas](oracle-read-replicas.limitations.md#oracle-read-replicas.limitations.miscellaneous).
# Redo transport compression with RDS for Oracle
Use RDS for Oracle redo transport compression to improve the replication performance between your primary DB instance and standby replicas. This is particularly useful in environments that have limited network bandwidth or high-latency connections.
## Obtaining a license for redo transport compression
Redo transport compression is part of the [Oracle Advanced Compression](//www.oracle.com/database/advanced-compression/) option. To use redo transport compression, you need a valid license for the Oracle Advanced Compression option. For licensing information, contact your Oracle representative.
## Configuring redo transport compression
To configure redo transport compression, you can use the `rds.replica.redo_compression` parameter. This parameter is available for Oracle versions 19c and 21c.
The `rds.replica.redo_compression` parameter accepts the following values:
+ `DISABLE` – Default value that disables redo transport compression.
+ `ENABLE` – Value that enables redo transport compression through the default algorithm [ZLIB](https://zlib.net/).
+ `ZLIB` – Value that explicitly enables redo transport compression using the ZLIB algorithm, which provides good compression ratios.
+ `LZO` – Value that explicitly enables redo transport compression using the [LZO](https://www.oberhumer.com/opensource/lzo/) algorithm, which optimizes compression speed, particularly during decompression.
## Performance considerations for redo transport compression
Compression and decompression operations consume CPU resources on both the primary and standby instances. If you use redo transport compression, consider instance resource usage and network conditions.
## Related topics for redo transport compression
For more information on configuring redo transport compression, see the following resources:
+ [DB parameter groups for Amazon RDS DB instances](USER_WorkingWithDBInstanceParamGroups.md)
+ [RedoCompression](https://docs.oracle.com/en/database/oracle/oracle-database/19/dgbkr/oracle-data-guard-broker-properties.html#GUID-5E6DDFD0-6196-48EB-94AF-21A1AFBB7DE1) in the Oracle Database 19c release notes
# Adding options to Oracle DB instances
In Amazon RDS, an option is an additional feature. Following, you can find a description of options that you can add to Amazon RDS instances running the Oracle DB engine.
**Topics**
+ [
# Overview of Oracle DB options
](Appendix.Oracle.Options.overview.md)
+ [
# Amazon S3 integration
](oracle-s3-integration.md)
+ [
# Oracle Application Express (APEX)
](Appendix.Oracle.Options.APEX.md)
+ [
# Amazon EFS integration
](oracle-efs-integration.md)
+ [
# Oracle Java virtual machine
](oracle-options-java.md)
+ [
# Oracle Enterprise Manager
](Oracle.Options.OEM.md)
+ [
# Oracle Label Security
](Oracle.Options.OLS.md)
+ [
# Oracle Locator
](Oracle.Options.Locator.md)
+ [
# Oracle native network encryption
](Appendix.Oracle.Options.NetworkEncryption.md)
+ [
# Oracle OLAP
](Oracle.Options.OLAP.md)
+ [
# Oracle Secure Sockets Layer
](Appendix.Oracle.Options.SSL.md)
+ [
# Oracle Spatial
](Oracle.Options.Spatial.md)
+ [
# Oracle SQLT
](Oracle.Options.SQLT.md)
+ [
# Oracle Statspack
](Appendix.Oracle.Options.Statspack.md)
+ [
# Oracle time zone
](Appendix.Oracle.Options.Timezone.md)
+ [
# Oracle time zone file autoupgrade
](Appendix.Oracle.Options.Timezone-file-autoupgrade.md)
+ [
# Oracle Transparent Data Encryption
](Appendix.Oracle.Options.AdvSecurity.md)
+ [
# Oracle UTL\$1MAIL
](Oracle.Options.UTLMAIL.md)
+ [
# Oracle XML DB
](Appendix.Oracle.Options.XMLDB.md)
# Overview of Oracle DB options
To enable options for your Oracle database, add them to an option group, and then associate the option group with your DB instance. For more information, see [Working with option groups](USER_WorkingWithOptionGroups.md).
**Topics**
+ [
## Summary of Oracle Database options
](#Appendix.Oracle.Options.summary)
+ [
## Options supported for different editions
](#Appendix.Oracle.Options.editions)
+ [
## Memory requirements for specific options
](#Appendix.Oracle.Options.memory)
## Summary of Oracle Database options
You can add the following options for Oracle DB instances.
****
| Option | Option ID |
| --- | --- |
| [Amazon S3 integration](oracle-s3-integration.md) | `S3_INTEGRATION` |
| [Oracle Application Express (APEX)](Appendix.Oracle.Options.APEX.md) | `APEX` `APEX-DEV` |
| [Oracle Enterprise Manager](Oracle.Options.OEM.md) | `OEM` `OEM_AGENT` |
| [Oracle Java virtual machine](oracle-options-java.md) | `JVM` |
| [Oracle Label Security](Oracle.Options.OLS.md) | `OLS` |
| [Oracle Locator](Oracle.Options.Locator.md) | `LOCATOR` |
| [Oracle native network encryption](Appendix.Oracle.Options.NetworkEncryption.md) | `NATIVE_NETWORK_ENCRYPTION` |
| [Oracle OLAP](Oracle.Options.OLAP.md) | `OLAP` |
| [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md) | `SSL` |
| [Oracle Spatial](Oracle.Options.Spatial.md) | `SPATIAL` |
| [Oracle SQLT](Oracle.Options.SQLT.md) | `SQLT` |
| [Oracle Statspack](Appendix.Oracle.Options.Statspack.md) | `STATSPACK` |
| [Oracle time zone](Appendix.Oracle.Options.Timezone.md) | `Timezone` |
| [Oracle time zone file autoupgrade](Appendix.Oracle.Options.Timezone-file-autoupgrade.md) | `TIMEZONE_FILE_AUTOUPGRADE` |
| [Oracle Transparent Data Encryption](Appendix.Oracle.Options.AdvSecurity.md) | `TDE` |
| [Oracle UTL\$1MAIL](Oracle.Options.UTLMAIL.md) | `UTL_MAIL` |
| [Oracle XML DB](Appendix.Oracle.Options.XMLDB.md) | `XMLDB` |
## Options supported for different editions
RDS for Oracle prevents you from adding options to an edition if they aren't supported. To find out which RDS options are supported in different Oracle Database editions, use the command `aws rds describe-option-group-options`. The following example lists supported options for Oracle Database 19c Enterprise Edition.
```
aws rds describe-option-group-options \
--engine-name oracle-ee \
--major-engine-version 19
```
For more information, see [describe-option-group-options](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-option-group-options.html) in the *AWS CLI Command Reference*.
## Memory requirements for specific options
Some options require additional memory to run on your DB instance. For example, Oracle Enterprise Manager Database Control uses about 300 MB of RAM. If you enable this option for a small DB instance, you might encounter performance problems due to memory constraints. You can adjust the Oracle parameters so that the database requires less RAM. Alternatively, you can scale up to a larger DB instance.
# Amazon S3 integration
You can transfer files between your RDS for Oracle DB instance and an Amazon S3 bucket. You can use Amazon S3 integration with Oracle Database features such as Oracle Data Pump. For example, you can download Data Pump files from Amazon S3 to your RDS for Oracle DB instance. For more information, see [Importing data into Oracle on Amazon RDS](Oracle.Procedural.Importing.md).
**Note**
Your DB instance and your Amazon S3 bucket must be in the same AWS Region.
**Topics**
+ [
# Configuring IAM permissions for RDS for Oracle integration with Amazon S3
](oracle-s3-integration.preparing.md)
+ [
# Adding the Amazon S3 integration option
](oracle-s3-integration.preparing.option-group.md)
+ [
# Transferring files between Amazon RDS for Oracle and an Amazon S3 bucket
](oracle-s3-integration.using.md)
+ [
## Troubleshooting Amazon S3 integration
](#oracle-s3-integration.troubleshooting)
+ [
# Removing the Amazon S3 integration option
](oracle-s3-integration.removing.md)
# Configuring IAM permissions for RDS for Oracle integration with Amazon S3
For RDS for Oracle to integrate with Amazon S3, your DB instance must have access to an Amazon S3 bucket. The Amazon VPC used by your DB instance doesn't need to provide access to the Amazon S3 endpoints.
RDS for Oracle supports transferring files between a DB instance in one account and an Amazon S3 bucket in a different account. Where additional steps are required, they are noted in the following sections.
**Topics**
+ [
## Step 1: Create an IAM policy for your Amazon RDS role
](#oracle-s3-integration.preparing.policy)
+ [
## Step 2: (Optional) Create an IAM policy for your Amazon S3 bucket
](#oracle-s3-integration.preparing.policy-bucket)
+ [
## Step 3: Create an IAM role for your DB instance and attach your policy
](#oracle-s3-integration.preparing.role)
+ [
## Step 4: Associate your IAM role with your RDS for Oracle DB instance
](#oracle-s3-integration.preparing.instance)
## Step 1: Create an IAM policy for your Amazon RDS role
In this step, you create an AWS Identity and Access Management (IAM) policy with the permissions required to transfer files between your Amazon S3 bucket and your RDS DB instance. This step assumes that you have already created an S3 bucket.
Before you create the policy, note the following pieces of information:
+ The Amazon Resource Name (ARN) for your bucket
+ The ARN for your AWS KMS key, if your bucket uses SSE-KMS or SSE-S3 encryption
**Note**
An RDS for Oracle DB instance can't access Amazon S3 buckets encrypted with SSE-C.
For more information, see [Protecting data using server-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html) in the *Amazon Simple Storage Service User Guide*.
### Console
**To create an IAM policy to allow Amazon RDS to access your Amazon S3 bucket**
1. Open the [IAM Management Console](https://console.aws.amazon.com/iam/home?#home).
1. Under **Access management**, choose **Policies**.
1. Choose **Create Policy**.
1. On the **Visual editor** tab, choose **Choose a service**, and then choose **S3**.
1. For **Actions**, choose **Expand all**, and then choose the bucket permissions and object permissions required to transfer files from an Amazon S3 bucket to Amazon RDS. For example, do the following:
+ Expand **List**, and then select **ListBucket**.
+ Expand **Read**, and then select **GetObject**.
+ Expand **Write**, and then select **PutObject**, **DeleteObject**, **AbortMultipartUpload**, and **ListMultipartUploadParts**. The multipart upload permissions are required when uploading large files (100 MB or larger) to Amazon S3.
+ Expand **Permissions management**, and then select **PutObjectAcl**. This permission is necessary if you plan to upload files to a bucket owned by a different account, and this account needs full control of the bucket contents.
*Object permissions* are permissions for object operations in Amazon S3. You must grant them for objects in a bucket, not the bucket itself. For more information, see [Permissions for object operations](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-actions.html#using-with-s3-actions-related-to-objects).
1. Choose **Resources**, and then do the following:
1. Choose **Specific**.
1. For **bucket**, choose **Add ARN**. Enter your bucket ARN. The bucket name is filled in automatically. Then choose **Add**.
1. If the **object** resource is shown, either choose **Add ARN** to add resources manually or choose **Any**.
**Note**
You can set **Amazon Resource Name (ARN)** to a more specific ARN value to allow Amazon RDS to access only specific files or folders in an Amazon S3 bucket. For more information about how to define an access policy for Amazon S3, see [Managing access permissions to your Amazon S3 resources](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html).
1. (Optional) Choose **Add additional permissions** to add resources to the policy. For example, do the following:
1. If your bucket is encrypted with a custom KMS key, select **KMS** for the service.
1. For **Manual actions**, select the following:
+ **Encrypt**
+ **ReEncrypt from** and **ReEncrypt to**
+ **Decrypt**
+ **DescribeKey**
+ **GenerateDataKey**
1. For **Resources**, choose **Specific**.
1. For **key**, choose **Add ARN**. Enter the ARN of your custom key as the resource, and then choose **Add**.
For more information, see [Protecting Data Using Server-Side Encryption with KMS keys Stored in AWS Key Management Service (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html) in the *Amazon Simple Storage Service User Guide*.
1. If you want Amazon RDS to access to access other buckets, add the ARNs for these buckets. Optionally, you can also grant access to all buckets and objects in Amazon S3.
1. Choose **Next: Tags** and then **Next: Review**.
1. For **Name**, enter a name for your IAM policy, for example `rds-s3-integration-policy`. You use this name when you create an IAM role to associate with your DB instance. You can also add an optional **Description** value.
1. Choose **Create policy**.
### AWS CLI
Create an AWS Identity and Access Management (IAM) policy that grants Amazon RDS access to an Amazon S3 bucket. After you create the policy, note the ARN of the policy. You need the ARN for a subsequent step.
Include the appropriate actions in the policy based on the type of access required:
+ `GetObject` – Required to transfer files from an Amazon S3 bucket to Amazon RDS.
+ `ListBucket` – Required to transfer files from an Amazon S3 bucket to Amazon RDS.
+ `PutObject` – Required to transfer files from Amazon RDS to an Amazon S3 bucket.
+ `AbortMultipartUpload` – Required for multipart uploads when transferring large files (100 MB or larger) from Amazon RDS to an Amazon S3 bucket.
+ `ListMultipartUploadParts` – Required for multipart uploads when transferring large files (100 MB or larger) from Amazon RDS to an Amazon S3 bucket.
The following AWS CLI command creates an IAM policy named `rds-s3-integration-policy` with these options. It grants access to a bucket named `amzn-s3-demo-bucket`.
**Example**
For Linux, macOS, or Unix:
```
aws iam create-policy \
--policy-name rds-s3-integration-policy \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "s3integration",
"Action": [
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}'
```
The following example includes permissions for custom KMS keys.
```
aws iam create-policy \
--policy-name rds-s3-integration-policy \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "s3integration",
"Action": [
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject",
"kms:Decrypt",
"kms:Encrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey",
"kms:DescribeKey",
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:kms:::your-kms-arn"
]
}
]
}'
```
For Windows:
```
aws iam create-policy ^
--policy-name rds-s3-integration-policy ^
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "s3integration",
"Action": [
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}'
```
The following example includes permissions for custom KMS keys.
```
aws iam create-policy ^
--policy-name rds-s3-integration-policy ^
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "s3integration",
"Action": [
"s3:GetObject",
"s3:ListBucket",
"s3:PutObject",
"kms:Decrypt",
"kms:Encrypt",
"kms:ReEncrypt",
"kms:GenerateDataKey",
"kms:DescribeKey",
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:kms:::your-kms-arn"
]
}
]
}'
```
## Step 2: (Optional) Create an IAM policy for your Amazon S3 bucket
This step is necessary only in the following conditions:
+ You plan to upload files to an Amazon S3 bucket from one account (account A) and access them from a different account (account B).
+ Account B owns the bucket.
+ Account B needs full control of objects loaded into the bucket.
If the preceding conditions don't apply to you, skip to [Step 3: Create an IAM role for your DB instance and attach your policy](#oracle-s3-integration.preparing.role).
To create your bucket policy, make sure you have the following:
+ The account ID for account A
+ The user name for account A
+ The ARN value for the Amazon S3 bucket in account B
### Console
**To create or edit a bucket policy**
1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/).
1. In the **Buckets** list, choose the name of the bucket that you want to create a bucket policy for or whose bucket policy you want to edit.
1. Choose **Permissions**.
1. Under **Bucket policy**, choose **Edit**. This opens the Edit bucket policy page.
1. On the **Edit bucket policy **page, explore **Policy examples** in the *Amazon S3 User Guide*, choose **Policy generator** to generate a policy automatically, or edit the JSON in the **Policy** section.
If you choose **Policy generator**, the AWS Policy Generator opens in a new window:
1. On the **AWS Policy Generator** page, in **Select Type of Policy**, choose **S3 Bucket Policy**.
1. Add a statement by entering the information in the provided fields, and then choose **Add Statement**. Repeat for as many statements as you would like to add. For more information about these fields, see the [IAM JSON policy elements reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide*.
**Note**
For convenience, the **Edit bucket policy** page displays the **Bucket ARN **(Amazon Resource Name) of the current bucket above the **Policy** text field. You can copy this ARN for use in the statements on the **AWS Policy Generator** page.
1. After you finish adding statements, choose **Generate Policy**.
1. Copy the generated policy text, choose **Close**, and return to the **Edit bucket policy** page in the Amazon S3 console.
1. In the **Policy** box, edit the existing policy or paste the bucket policy from the Policy generator. Make sure to resolve security warnings, errors, general warnings, and suggestions before you save your policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ExamplePermissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:user/account-A-user"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-destination-bucket",
"arn:aws:s3:::amzn-s3-demo-destination-bucket/*"
]
}
]
}
```
------
1. Choose **Save changes**, which returns you to the Bucket Permissions page.
## Step 3: Create an IAM role for your DB instance and attach your policy
This step assumes that you have created the IAM policy in [Step 1: Create an IAM policy for your Amazon RDS role](#oracle-s3-integration.preparing.policy). In this step, you create a role for your RDS for Oracle DB instance and then attach your policy to the role.
### Console
**To create an IAM role to allow Amazon RDS to access an Amazon S3 bucket**
1. Open the [IAM Management Console](https://console.aws.amazon.com/iam/home?#home).
1. In the navigation pane, choose **Roles**.
1. Choose **Create role**.
1. Choose **AWS service**.
1. For **Use cases for other AWS services:**, choose **RDS** and then **RDS – Add Role to Database**. Then choose **Next**.
1. For **Search** under **Permissions policies**, enter the name of the IAM policy you created in [Step 1: Create an IAM policy for your Amazon RDS role](#oracle-s3-integration.preparing.policy), and select the policy when it appears in the list. Then choose **Next**.
1. For **Role name**, enter a name for your IAM role, for example, `rds-s3-integration-role`. You can also add an optional **Description** value.
1. Choose **Create role**.
### AWS CLI
**To create a role and attach your policy to it**
1. Create an IAM role that Amazon RDS can assume on your behalf to access your Amazon S3 buckets.
We recommend using the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context keys in resource-based trust relationships to limit the service's permissions to a specific resource. This is the most effective way to protect against the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).
You might use both global condition context keys and have the `aws:SourceArn` value contain the account ID. In this case, the `aws:SourceAccount` value and the account in the `aws:SourceArn` value must use the same account ID when used in the same statement.
+ Use `aws:SourceArn` if you want cross-service access for a single resource.
+ Use `aws:SourceAccount` if you want to allow any resource in that account to be associated with the cross-service use.
In the trust relationship, make sure to use the `aws:SourceArn` global condition context key with the full Amazon Resource Name (ARN) of the resources accessing the role.
The following AWS CLI command creates the role named `rds-s3-integration-role` for this purpose.
**Example**
For Linux, macOS, or Unix:
```
aws iam create-role \
--role-name rds-s3-integration-role \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "my_account_ID",
"aws:SourceArn": "arn:aws:rds:Region:my_account_ID:db:dbname"
}
}
}
]
}'
```
For Windows:
```
aws iam create-role ^
--role-name rds-s3-integration-role ^
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "my_account_ID",
"aws:SourceArn": "arn:aws:rds:Region:my_account_ID:db:dbname"
}
}
}
]
}'
```
For more information, see [Creating a role to delegate permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
1. After the role is created, note the ARN of the role. You need the ARN for a subsequent step.
1. Attach the policy you created to the role you created.
The following AWS CLI command attaches the policy to the role named `rds-s3-integration-role`.
**Example**
For Linux, macOS, or Unix:
```
aws iam attach-role-policy \
--policy-arn your-policy-arn \
--role-name rds-s3-integration-role
```
For Windows:
```
aws iam attach-role-policy ^
--policy-arn your-policy-arn ^
--role-name rds-s3-integration-role
```
Replace `your-policy-arn` with the policy ARN that you noted in a previous step.
## Step 4: Associate your IAM role with your RDS for Oracle DB instance
The last step in configuring permissions for Amazon S3 integration is associating your IAM role with your DB instance. Note the following requirements:
+ You must have access to an IAM role with the required Amazon S3 permissions policy attached to it.
+ You can only associate one IAM role with your RDS for Oracle DB instance at a time.
+ Your DB instance must be in the **Available** state.
### Console
**To associate your IAM role with your RDS 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. Choose **Databases** from the navigation pane.
1. Choose the RDS for Oracle DB instance name to display its details.
1. On the **Connectivity & security** tab, scroll down to the **Manage IAM roles** section at the bottom of the page.
1. For **Add IAM roles to this instance**, choose the role that you created in [Step 3: Create an IAM role for your DB instance and attach your policy](#oracle-s3-integration.preparing.role).
1. For **Feature**, choose **S3\$1INTEGRATION**.
![\[Add S3_INTEGRATION role\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/ora-s3-integration-role.png)
1. Choose **Add role**.
### AWS CLI
The following AWS CLI command adds the role to an Oracle DB instance named `mydbinstance`.
**Example**
For Linux, macOS, or Unix:
```
aws rds add-role-to-db-instance \
--db-instance-identifier mydbinstance \
--feature-name S3_INTEGRATION \
--role-arn your-role-arn
```
For Windows:
```
aws rds add-role-to-db-instance ^
--db-instance-identifier mydbinstance ^
--feature-name S3_INTEGRATION ^
--role-arn your-role-arn
```
Replace `your-role-arn` with the role ARN that you noted in a previous step. `S3_INTEGRATION` must be specified for the `--feature-name` option.
# Adding the Amazon S3 integration option
To integrate Amazon RDS for Oracle with Amazon S3, your DB instance must be associated with an option group that includes the `S3_INTEGRATION` option.
## Console
**To configure an option group for Amazon S3 integration**
1. Create a new option group or identify an existing option group to which you can add the `S3_INTEGRATION` option.
For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the `S3_INTEGRATION` option to the option group.
For information about adding an option to an option group, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Create a new RDS for Oracle DB instance and associate the option group with it, or modify an RDS for Oracle DB instance to associate the option group with it.
For information about creating a DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
For information about modifying a DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## AWS CLI
**To configure an option group for Amazon S3 integration**
1. Create a new option group or identify an existing option group to which you can add the `S3_INTEGRATION` option.
For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the `S3_INTEGRATION` option to the option group.
For example, the following AWS CLI command adds the `S3_INTEGRATION` option to an option group named **myoptiongroup**.
**Example**
For Linux, macOS, or Unix:
```
aws rds add-option-to-option-group \
--option-group-name myoptiongroup \
--options OptionName=S3_INTEGRATION,OptionVersion=1.0
```
For Windows:
```
aws rds add-option-to-option-group ^
--option-group-name myoptiongroup ^
--options OptionName=S3_INTEGRATION,OptionVersion=1.0
```
1. Create a new RDS for Oracle DB instance and associate the option group with it, or modify an RDS for Oracle DB instance to associate the option group with it.
For information about creating a DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
For information about modifying an RDS for Oracle DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Transferring files between Amazon RDS for Oracle and an Amazon S3 bucket
To transfer files between an RDS for Oracle DB instance and an Amazon S3 bucket, you can use the Amazon RDS package `rdsadmin_s3_tasks`. You can compress files with GZIP when uploading them, and decompress them when downloading.
**Topics**
+ [
## Requirements and limitations for file transfers
](#oracle-s3-integration.using.reqs)
+ [
## Uploading files from your RDS for Oracle DB instance to an Amazon S3 bucket
](#oracle-s3-integration.using.upload)
+ [
## Downloading files from an Amazon S3 bucket to an Oracle DB instance
](#oracle-s3-integration.using.download)
+ [
## Monitoring the status of a file transfer
](#oracle-s3-integration.using.task-status)
## Requirements and limitations for file transfers
Before transferring files between your DB instance and an Amazon S3 bucket, note the following:
+ The `rdsadmin_s3_tasks` package transfers files located in a single directory. You can't include subdirectories in a transfer.
+ The maximum object size in an Amazon S3 bucket is 5 TB.
+ Tasks created by `rdsadmin_s3_tasks` run asynchronously.
+ You can upload files from the Data Pump directory, such as `DATA_PUMP_DIR`, or any user-created directory. You can't upload files from a directory used by Oracle background processes, such as the `adump`, `bdump`, or `trace` directories.
+ The download limit is 2000 files per procedure call for `download_from_s3`. If you need to download more than 2000 files from Amazon S3, split your download into separate actions, with no more than 2000 files per procedure call.
+ If a file exists in your download folder, and you attempt to download a file with the same name, `download_from_s3` skips the download. To remove a file from the download directory, use the PL/SQL procedure [UTL\$1FILE.FREMOVE](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/UTL_FILE.html#GUID-09B09C2A-2C21-4F70-BF04-D0EEA7B59CAF).
## Uploading files from your RDS for Oracle DB instance to an Amazon S3 bucket
To upload files from your DB instance to an Amazon S3 bucket, use the procedure `rdsadmin.rdsadmin_s3_tasks.upload_to_s3`. For example, you can upload Oracle Recovery Manager (RMAN) backup files or Oracle Data Pump files. For more information about working with objects, see [Amazon Simple Storage Service User Guide](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingObjects.html). For more information about performing RMAN backups, see [Performing common RMAN tasks for Oracle DB instances](Appendix.Oracle.CommonDBATasks.RMAN.md).
The `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | required | The name of the Amazon S3 bucket to upload files to. |
| `p_directory_name` | VARCHAR2 | – | required | The name of the Oracle directory object to upload files from. The directory can be any user-created directory object or the Data Pump directory, such as `DATA_PUMP_DIR`. You can't upload files from a directory used by background processes, such as `adump`, `bdump`, and `trace`. You can only upload files from the specified directory. You can't upload files in subdirectories in the specified directory. |
| `p_s3_prefix` | VARCHAR2 | – | required | An Amazon S3 file name prefix that files are uploaded to. An empty prefix uploads all files to the top level in the specified Amazon S3 bucket and doesn't add a prefix to the file names. For example, if the prefix is `folder_1/oradb`, files are uploaded to `folder_1`. In this case, the `oradb` prefix is added to each file. |
| `p_prefix` | VARCHAR2 | – | required | A file name prefix that file names must match to be uploaded. An empty prefix uploads all files in the specified directory. |
| `p_compression_level` | NUMBER | `0` | optional | The level of GZIP compression. Valid values range from `0` to `9`: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-s3-integration.using.html) |
| `p_bucket_owner_full_control` | VARCHAR2 | – | optional | The access control setting for the bucket. The only valid values are null or `FULL_CONTROL`. This setting is required only if you upload files from one account (account A) into a bucket owned by a different account (account B), and account B needs full control of the files. |
The return value for the `rdsadmin.rdsadmin_s3_tasks.upload_to_s3` procedure is a task ID.
The following example uploads all of the files in the `DATA_PUMP_DIR` directory to the Amazon S3 bucket named *amzn-s3-demo-bucket*. The files aren't compressed.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => '',
p_s3_prefix => '',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
The following example uploads all of the files with the prefix `db` in the `DATA_PUMP_DIR` directory to the Amazon S3 bucket named `amzn-s3-demo-bucket`. Amazon RDS applies the highest level of GZIP compression to the files.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => 'db',
p_s3_prefix => '',
p_directory_name => 'DATA_PUMP_DIR',
p_compression_level => 9)
AS TASK_ID FROM DUAL;
```
The following example uploads all of the files in the `DATA_PUMP_DIR` directory to the Amazon S3 bucket named `amzn-s3-demo-bucket`. The files are uploaded to a `dbfiles` folder. In this example, the GZIP compression level is *1*, which is the fastest level of compression.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => '',
p_s3_prefix => 'dbfiles/',
p_directory_name => 'DATA_PUMP_DIR',
p_compression_level => 1)
AS TASK_ID FROM DUAL;
```
The following example uploads all of the files in the `DATA_PUMP_DIR` directory to the Amazon S3 bucket named `amzn-s3-demo-bucket`. The files are uploaded to a `dbfiles` folder and `ora` is added to the beginning of each file name. No compression is applied.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_prefix => '',
p_s3_prefix => 'dbfiles/ora',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
The following example assumes that the command is run in account A, but account B requires full control of the bucket contents. The command `rdsadmin_s3_tasks.upload_to_s3` transfers all files in the `DATA_PUMP_DIR` directory to the bucket named `s3bucketOwnedByAccountB`. Access control is set to `FULL_CONTROL` so that account B can access the files in the bucket. The GZIP compression level is *6*, which balances speed and file size.
```
SELECT rdsadmin.rdsadmin_s3_tasks.upload_to_s3(
p_bucket_name => 's3bucketOwnedByAccountB',
p_prefix => '',
p_s3_prefix => '',
p_directory_name => 'DATA_PUMP_DIR',
p_bucket_owner_full_control => 'FULL_CONTROL',
p_compression_level => 6)
AS TASK_ID FROM DUAL;
```
In each example, the `SELECT` statement returns the ID of the task in a `VARCHAR2` data type.
You can view the result by displaying the task's output file.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Replace *`task-id`* with the task ID returned by the procedure.
**Note**
Tasks are executed asynchronously.
## Downloading files from an Amazon S3 bucket to an Oracle DB instance
To download files from an Amazon S3 bucket to an RDS for Oracle instance, use the Amazon RDS procedure `rdsadmin.rdsadmin_s3_tasks.download_from_s3`.
The `download_from_s3` procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_bucket_name` | VARCHAR2 | – | Required | The name of the Amazon S3 bucket to download files from. |
| `p_directory_name` | VARCHAR2 | – | Required | The name of the Oracle directory object to download files to. The directory can be any user-created directory object or the Data Pump directory, such as `DATA_PUMP_DIR`. |
| `p_error_on_zero_downloads` | VARCHAR2 | FALSE | Optional | A flag that determines whether the task raises an error when no objects in the Amazon S3 bucket match the prefix. If this parameter is not set or set to FALSE (default), the task prints a message that no objects were found, but doesn't raise an exception or fail. If this parameter is TRUE, the task raises an exception and fails. Examples of prefix specifications that can fail match tests are spaces in prefixes, as in `' import/test9.log'`, and case mismatches, as in `test9.log` and `test9.LOG`. |
| `p_s3_prefix` | VARCHAR2 | – | Required | A file name prefix that file names must match to be downloaded. An empty prefix downloads all of the top level files in the specified Amazon S3 bucket, but not the files in folders in the bucket. The procedure downloads Amazon S3 objects only from the first level folder that matches the prefix. Nested directory structures matching the specified prefix are not downloaded. For example, suppose that an Amazon S3 bucket has the folder structure `folder_1/folder_2/folder_3`. You specify the `'folder_1/folder_2/'` prefix. In this case, only the files in `folder_2` are downloaded, not the files in `folder_1` or `folder_3`. If, instead, you specify the `'folder_1/folder_2'` prefix, all files in `folder_1` that match the `'folder_2'` prefix are downloaded, and no files in `folder_2` are downloaded. |
| `p_decompression_format` | VARCHAR2 | – | Optional | The decompression format. Valid values are `NONE` for no decompression and `GZIP` for decompression. |
The return value for the `rdsadmin.rdsadmin_s3_tasks.download_from_s3` procedure is a task ID.
The following example downloads all files in the Amazon S3 bucket named `amzn-s3-demo-bucket` to the `DATA_PUMP_DIR` directory. The files aren't compressed, so no decompression is applied.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
The following example downloads all of the files with the prefix `db` in the Amazon S3 bucket named `amzn-s3-demo-bucket` to the `DATA_PUMP_DIR` directory. The files are compressed with GZIP, so decompression is applied. The parameter `p_error_on_zero_downloads` turns on prefix error checking, so if the prefix doesn't match any files in the bucket, the task raises and exception and fails.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_s3_prefix => 'db',
p_directory_name => 'DATA_PUMP_DIR',
p_decompression_format => 'GZIP',
p_error_on_zero_downloads => 'TRUE')
AS TASK_ID FROM DUAL;
```
The following example downloads all of the files in the folder `myfolder/` in the Amazon S3 bucket named `amzn-s3-demo-bucket` to the `DATA_PUMP_DIR` directory. Use the `p_s3_prefix` parameter to specify the Amazon S3 folder. The uploaded files are compressed with GZIP, but aren't decompressed during the download.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_s3_prefix => 'myfolder/',
p_directory_name => 'DATA_PUMP_DIR',
p_decompression_format => 'NONE')
AS TASK_ID FROM DUAL;
```
The following example downloads the file `mydumpfile.dmp` in the Amazon S3 bucket named `amzn-s3-demo-bucket` to the `DATA_PUMP_DIR` directory. No decompression is applied.
```
SELECT rdsadmin.rdsadmin_s3_tasks.download_from_s3(
p_bucket_name => 'amzn-s3-demo-bucket',
p_s3_prefix => 'mydumpfile.dmp',
p_directory_name => 'DATA_PUMP_DIR')
AS TASK_ID FROM DUAL;
```
In each example, the `SELECT` statement returns the ID of the task in a `VARCHAR2` data type.
You can view the result by displaying the task's output file.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Replace *`task-id`* with the task ID returned by the procedure.
**Note**
Tasks are executed asynchronously.
You can use the `UTL_FILE.FREMOVE` Oracle procedure to remove files from a directory. For more information, see [FREMOVE procedure](https://docs.oracle.com/database/121/ARPLS/u_file.htm#ARPLS70924) in the Oracle documentation.
## Monitoring the status of a file transfer
File transfer tasks publish Amazon RDS events when they start and when they complete. The event message contains the task ID for the file transfer. For information about viewing events, see [Viewing Amazon RDS events](USER_ListEvents.md).
You can view the status of an ongoing task in a bdump file. The bdump files are located in the `/rdsdbdata/log/trace` directory. Each bdump file name is in the following format.
```
dbtask-task-id.log
```
Replace `task-id` with the ID of the task that you want to monitor.
**Note**
Tasks are executed asynchronously.
You can use the `rdsadmin.rds_file_util.read_text_file` stored procedure to view the contents of bdump files. For example, the following query returns the contents of the `dbtask-1234567890123-1234.log` bdump file.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1234567890123-1234.log'));
```
The following sample shows the log file for a failed transfer.
```
TASK_ID
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1234567890123-1234
TEXT
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2023-04-17 18:21:33.993 UTC [INFO ] File #1: Uploading the file /rdsdbdata/datapump/A123B4CDEF567890G1234567890H1234/sample.dmp to Amazon S3 with bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.188 UTC [ERROR] RDS doesn't have permission to write to Amazon S3 bucket name amzn-s3-demo-bucket and key sample.dmp.
2023-04-17 18:21:34.189 UTC [INFO ] The task failed.
```
## Troubleshooting Amazon S3 integration
For troubleshooting tips, see the AWS re:Post article [How do troubleshoot issues when I integrate Amazon RDS for Oracle with Amazon S3?](https://repost.aws/en/knowledge-center/rds-oracle-s3-integration).
# Removing the Amazon S3 integration option
You can remove Amazon S3 integration option from a DB instance.
To remove the Amazon S3 integration option from a DB instance, do one of the following:
+ To remove the Amazon S3 integration option from multiple DB instances, remove the `S3_INTEGRATION` option from the option group to which the DB instances belong. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ To remove the Amazon S3 integration option from a single DB instance, modify the instance and specify a different option group that doesn't include the `S3_INTEGRATION` option. You can specify the default (empty) option group or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle Application Express (APEX)
Amazon RDS supports Oracle Application Express (APEX) through the use of the `APEX` and `APEX-DEV` options. You can deploy Oracle APEX as a runtime environment or as a full development environment for web-based applications. Using Oracle APEX, you can build applications entirely within the web browser. For more information, see [Oracle application Express](https://apex.oracle.com/) in the Oracle documentation.
**Topics**
+ [
## Oracle APEX components
](#Appendix.Oracle.Options.APEX.components)
+ [
# Requirements and limitations
](Appendix.Oracle.Options.APEX.Requirements.md)
+ [
# Setting up Oracle APEX and Oracle Rest Data Services (ORDS)
](Appendix.Oracle.Options.APEX.settingUp.md)
+ [
# Configuring Oracle Rest Data Services (ORDS)
](Appendix.Oracle.Options.APEX.ORDSConf.md)
+ [
# Upgrading and removing Oracle APEX
](Appendix.Oracle.Options.APEX.UpgradeandRemove.md)
## Oracle APEX components
Oracle APEX consists of the following main components:
+ A *repository* that stores the metadata for Oracle APEX applications and components. The repository consists of tables, indexes, and other objects that are installed in your Amazon RDS DB instance.
+ A *listener* that manages HTTP communications with Oracle APEX clients. The listener resides on a separate host such as an Amazon EC2 instance, an on-premises server at your company, or your desktop computer. The listener accepts incoming connections from web browsers, forwards them to the Amazon RDS DB instance for processing, and then sends results from the repository back to the browsers.
RDS for Oracle supports the following types of listeners:
+ For Oracle APEX version 5.0 and later, use Oracle REST Data Services (ORDS) version 19.1 and higher. We recommend that you use the latest supported version of Oracle APEX and ORDS. This documentation describes older versions for backwards compatibility only.
+ For Oracle APEX version 4.1.1, you can use Oracle APEX Listener version 1.1.4.
+ You can use Oracle HTTP Server and `mod_plsql` listeners.
**Note**
Amazon RDS doesn't support the Oracle XML DB HTTP server with the embedded PL/SQL gateway as a listener for Oracle APEX. In general, Oracle recommends against using the embedded PL/SQL gateway for applications that run on the internet.
For more information about these listener types, see [About choosing a web listener](https://docs.oracle.com/database/apex-5.1/HTMIG/choosing-web-listener.htm#HTMIG29321) in the Oracle documentation.
When you add the `APEX` and `APEX-DEV` options to your RDS for Oracle DB instance, Amazon RDS installs the Oracle APEX repository only. Install your listener on a separate host.
# Requirements and limitations
The following topic lists the requirements and limitations for Oracle APEX and ORDS.
## Oracle APEX version requirements
The `APEX` option uses storage on the DB instance class for your DB instance. Following are the supported versions and approximate storage requirements for Oracle APEX.
****
| Oracle APEX version | Storage requirements | Supported Oracle Database versions | Notes |
| --- | --- | --- | --- |
| Oracle APEX version 24.2.v1 | 114 MiB | All | This version includes patch 37885097: PSE BUNDLE FOR APEX 24.2 (PSES ON TOP OF 24.2.0), PATCH\$1VERSION 4. |
| Oracle APEX version 24.1.v1 | 112 MiB | All | This version includes patch 36695709: PSE BUNDLE FOR APEX 24.1 (PSES ON TOP OF 24.1.0), PATCH\$1VERSION 3. If you need exactly the same APEX images version to install on your EC2 instance, download patch 37544819: 24.1.3 PSE BUNDLE FOR APEX 24.1 (PSES ON TOP OF 24.1.0). |
| Oracle APEX version 23.2.v1 | 110 MiB | All | This version includes patch 35895964: PSE BUNDLE FOR APEX 23.2 (PSES ON TOP OF 23.2.0), PATCH\$1VERSION 6. If you need exactly the same APEX images version to install on your EC2 instance, download patch 37593125: 23.2.6 PSE BUNDLE FOR APEX 23.2 (PSES ON TOP OF 23.2.0). |
| Oracle APEX version 23.1.v1 | 106 MiB | All | This version includes patch 35283657: PSE BUNDLE FOR APEX 23.1 (PSES ON TOP OF 23.1.0), PATCH\$1VERSION 2. |
| Oracle APEX version 22.2.v1 | 106 MiB | All | This version includes patch 34628174: PSE BUNDLE FOR APEX 22.2 (PSES ON TOP OF 22.2.0), PATCH\$1VERSION 4. |
| Oracle APEX version 22.1.v1 | 124 MiB | All | This version includes patch 34020981: PSE BUNDLE FOR APEX 22.1 (PSES ON TOP OF 22.1.0), PATCH\$1VERSION 6. |
| Oracle APEX version 21.2.v1 | 125 MiB | All | This version includes patch 33420059: PSE BUNDLE FOR APEX 21.2 (PSES ON TOP OF 21.2.0), PATCH\$1VERSION 8. |
| Oracle APEX version 21.1.v1 | 125 MiB | All | This version includes patch 32598392: PSE BUNDLE FOR APEX 21.1, PATCH\$1VERSION 3. |
| Oracle APEX version 20.2.v1 | 148 MiB | All except Oracle Database 21c | This version includes patch 32006852: PSE BUNDLE FOR APEX 20.2, PATCH\$1VERSION 2020.11.12. You can see the patch number and date by running the following query: SELECT PATCH_VERSION, PATCH_NUMBER
FROM APEX_PATCHES;
|
| Oracle APEX version 20.1.v1 | 173 MiB | All except Oracle Database 21c | This version includes patch 30990551: PSE BUNDLE FOR APEX 20.1, PATCH\$1VERSION 2020.07.15. |
| Oracle APEX version 19.2.v1 | 149 MiB | All except Oracle Database 21c | |
| Oracle APEX version 19.1.v1 | 148 MiB | All except Oracle Database 21c | |
For downloadable Oracle APEX .zip files, see [ Oracle APEX Prior Release Archives ](https://www.oracle.com/tools/downloads/apex-all-archives-downloads.html) on the Oracle website.
## Oracle APEX and ORDS prerequisites
Note the following prerequisites for using Oracle APEX and ORDS:
+ Your system must use the Java Runtime Environment (JRE).
+ Your Oracle client installation must include the following:
+ SQL\$1Plus or SQL Developer for administration tasks
+ Oracle Net Services for configuring connections to your RDS for Oracle DB instance
## Oracle APEX limitations
You can't modify the `APEX_version` user account, which is managed by Amazon RDS. Thus, you can't apply database profiles or enforce password rules on this user. The profiles and password settings for `APEX_version` are predefined by Oracle and AWS and are designed to meet the security requirements for Amazon RDS.
# Setting up Oracle APEX and Oracle Rest Data Services (ORDS)
The following topic lists the steps required to set up Oracle APEX and ORDS
**Topics**
+ [
## Adding the APEX and APEX-DEV options to your DB instance
](#Appendix.Oracle.Options.APEX.Add)
+ [
## Unlocking the public user account on your DB instance
](#Appendix.Oracle.Options.APEX.PublicUser)
+ [
## Configuring RESTful services for Oracle APEX
](#Appendix.Oracle.Options.APEX.ConfigureRESTful)
+ [
## Preparing to install ORDS on a separate host
](#Appendix.Oracle.Options.APEX.ORDS.ords-setup)
+ [
## Setting up Oracle APEX listener
](#Appendix.Oracle.Options.APEX.Listener)
## Adding the APEX and APEX-DEV options to your DB instance
To add the `APEX` and `APEX-DEV` options to your RDS for Oracle DB instance, do the following:
1. Create a new option group, or copy or modify an existing option group.
1. Add the `APEX` and `APEX-DEV` options to the option group.
1. Associate the option group with your DB instance.
When you add the `APEX` and `APEX-DEV` options, a brief outage occurs while your DB instance is automatically restarted.
**Note**
`APEX_MAIL` is available when the `APEX` option is installed. The execute privilege for the `APEX_MAIL` package is granted to `PUBLIC` so you don't need the APEX administrative account to use it.
**To add the APEX and APEX-DEV options to a DB instance**
1. Determine the option group that you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine**, choose the Oracle edition that you want to use. The `APEX` and `APEX-DEV` options are supported on all editions.
1. For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the options to the option group. If you want to deploy only the Oracle APEX runtime environment, add only the `APEX` option. To deploy the full development environment, add both the `APEX` and `APEX-DEV` options.
For **Version**, choose the version of Oracle APEX that you want to use.
**Important**
If you add the `APEX` or `APEX-DEV` options to an existing option group that is already attached to one or more DB instances, a brief outage occurs. During this outage, all the DB instances are automatically restarted.
For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. When you add the `APEX` or `APEX-DEV` options to an existing DB instance, a brief outage occurs while your DB instance is automatically restarted. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Unlocking the public user account on your DB instance
After you have installed the `APEX` or `APEX-DEV` options your DB instance, make sure to do the following:
1. Change the password for the `APEX_PUBLIC_USER` account.
1. Unlock the account.
You can do this by using the Oracle SQL\$1Plus command line utility. Connect to your DB instance as the master user, and issue the following commands. Replace `new_password` with a password of your choice.
```
1. ALTER USER APEX_PUBLIC_USER IDENTIFIED BY new_password;
2. ALTER USER APEX_PUBLIC_USER ACCOUNT UNLOCK;
```
## Configuring RESTful services for Oracle APEX
To configure RESTful services in Oracle APEX (not needed for Oracle APEX 4.1.1.V1), use SQL\$1Plus to connect to your DB instance as the master user. After you do this, run the `rdsadmin.rdsadmin_run_apex_rest_config` stored procedure. When you run the stored procedure, you provide passwords for the following users:
+ `APEX_LISTENER`
+ `APEX_REST_PUBLIC_USER`
The stored procedure runs the `apex_rest_config.sql` script, which creates new database accounts for these users.
**Note**
Configuration isn't required for Oracle APEX version 4.1.1.v1. For this Oracle APEX version only, you don't need to run the stored procedure.
The following command runs the stored procedure.
```
1. EXEC rdsadmin.rdsadmin_run_apex_rest_config('apex_listener_password', 'apex_rest_public_user_password');
```
## Preparing to install ORDS on a separate host
Install ORDS on a separate host such as an Amazon EC2 instance, an on-premises server at your company, or your desktop computer. The examples in this section,assume that your host runs Linux and is named `myapexhost.example.com`.
Before you can install ORDS, you need to create a nonprivileged OS user, and then download and unzip the Oracle APEX installation file.
**To prepare for ORDS installation**
1. Log in to `myapexhost.example.com` as `root`.
1. Create a nonprivileged OS user to own the listener installation. The following command creates a new user named *apexuser*.
```
useradd -d /home/apexuser apexuser
```
The following command assigns a password to the new user.
```
passwd apexuser;
```
1. Log in to `myapexhost.example.com` as `apexuser`, and download the Oracle APEX installation file from Oracle to your `/home/apexuser` directory:
+ [http://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html](http://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html)
+ [Oracle application Express prior release archives](http://www.oracle.com/technetwork/developer-tools/apex/downloads/all-archives-099381.html)
1. Unzip the file in the `/home/apexuser` directory.
```
unzip apex_version.zip
```
After you unzip the file, there is an `apex` directory in the `/home/apexuser` directory.
1. While you are still logged into `myapexhost.example.com` as `apexuser`, download the Oracle REST Data Services file from Oracle to your `/home/apexuser` directory: [http://www.oracle.com/technetwork/developer-tools/apex-listener/downloads/index.html](http://www.oracle.com/technetwork/developer-tools/apex-listener/downloads/index.html).
## Setting up Oracle APEX listener
**Note**
Oracle APEX Listener is deprecated.
Amazon RDS for Oracle continues to support Oracle APEX version 4.1.1 and Oracle APEX Listener version 1.1.4. We recommend that you use the latest supported versions of Oracle APEX and ORDS.
Install Oracle APEX Listener on a separate host such as an Amazon EC2 instance, an on-premises server at your company, or your desktop computer. We assume that the name of your host is `myapexhost.example.com`, and that your host is running Linux.
### Preparing to install Oracle APEX listener
Before you can install Oracle APEX Listener, you need to create a nonprivileged OS user, and then download and unzip the Oracle APEX installation file.
**To prepare for Oracle APEX listener installation**
1. Log in to `myapexhost.example.com` as `root`.
1. Create a nonprivileged OS user to own the listener installation. The following command creates a new user named *apexuser*.
```
useradd -d /home/apexuser apexuser
```
The following command assigns a password to the new user.
```
passwd apexuser;
```
1. Log in to `myapexhost.example.com` as `apexuser`, and download the Oracle APEX installation file from Oracle to your `/home/apexuser` directory:
+ [http://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html](http://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html)
+ [Oracle application Express prior release archives](http://www.oracle.com/technetwork/developer-tools/apex/downloads/all-archives-099381.html)
1. Unzip the file in the `/home/apexuser` directory.
```
unzip apex_.zip
```
After you unzip the file, there is an `apex` directory in the `/home/apexuser` directory.
1. While you are still logged into `myapexhost.example.com` as `apexuser`, download the Oracle APEX Listener file from Oracle to your `/home/apexuser` directory.
#### Installing and configuring Oracle APEX listener
Before you can use Oracle APEX, you need to download the `apex.war` file, use Java to install Oracle APEX Listener, and then start the listener.
**To install and configure Oracle APEX listener**
1. Create a new directory based on Oracle APEX Listener and open the listener file.
Run the following code:
```
mkdir /home/apexuser/apexlistener
cd /home/apexuser/apexlistener
unzip ../apex_listener.version.zip
```
1. Run the following code.
```
java -Dapex.home=./apex -Dapex.images=/home/apexuser/apex/images -Dapex.erase -jar ./apex.war
```
1. Enter information for the program prompts following:
+ The APEX Listener Administrator user name. The default is *adminlistener*.
+ A password for the APEX Listener Administrator.
+ The APEX Listener Manager user name. The default is *managerlistener*.
+ A password for the APEX Listener Administrator.
The program prints a URL that you need to complete the configuration, as follows.
```
INFO: Please complete configuration at: http://localhost:8080/apex/listenerConfigure
Database is not yet configured
```
1. Leave Oracle APEX Listener running so that you can use Oracle Application Express. When you have finished this configuration procedure, you can run the listener in the background.
1. From your web browser, go to the URL provided by the Oracle APEX Listener program. The Oracle Application Express Listener administration window appears. Enter the following information:
+ **Username** – `APEX_PUBLIC_USER`
+ **Password** – the password for *APEX\$1PUBLIC\$1USER*. This password is the one that you specified earlier when you configured the Oracle APEX repository. For more information, see [Unlocking the public user account on your DB instance](#Appendix.Oracle.Options.APEX.PublicUser).
+ **Connection type** – Basic
+ **Hostname** – the endpoint of your Amazon RDS DB instance, such as `mydb.f9rbfa893tft.us-east-1.rds.amazonaws.com`.
+ **Port** – 1521
+ **SID** – the name of the database on your Amazon RDS DB instance, such as `mydb`.
1. Choose **Apply**. The Oracle APEX administration window appears.
1. Set a password for the Oracle APEX `admin` user. To do this, use SQL\$1Plus to connect to your DB instance as the master user, and then run the following commands.
```
1. EXEC rdsadmin.rdsadmin_util.grant_apex_admin_role;
2. grant APEX_ADMINISTRATOR_ROLE to master;
3. @/home/apexuser/apex/apxchpwd.sql
```
Replace `master` with your master user name. When the `apxchpwd.sql` script prompts you, enter a new `admin` password.
1. Return to the Oracle APEX administration window in your browser and choose **Administration**. Next, choose **Application Express Internal Administration**. When you are prompted for credentials, enter the following information:
+ **User name** – `admin`
+ **Password** – the password you set using the `apxchpwd.sql` script
Choose **Login**, and then set a new password for the `admin` user.
Your listener is now ready for use.
# Configuring Oracle Rest Data Services (ORDS)
The following topic lists the configuration options for ORDS 21 and 22:
**Topics**
+ [
## Installing and configuring ORDS 21 and lower
](#Appendix.Oracle.Options.APEX.ORDS)
+ [
## Installing and configuring ORDS 22 and higher
](#Appendix.Oracle.Options.APEX.ORDS22)
## Installing and configuring ORDS 21 and lower
You are now ready to install and configure Oracle Rest Data Services (ORDS) for use with Oracle APEX. For Oracle APEX version 5.0 and later, use ORDS versions 19.1 to 21. To learn how to install ORDS 22 and higher, see [Installing and configuring ORDS 22 and higher](#Appendix.Oracle.Options.APEX.ORDS22).
Install the listener on a separate host such as an Amazon EC2 instance, an on-premises server at your company, or your desktop computer. For the examples in this section, we assume that the name of your host is `myapexhost.example.com`, and that your host is running Linux.
**To install and configure ORDS 21 and lower for use with Oracle APEX**
1. Go to [Oracle REST data services](https://www.oracle.com/database/technologies/appdev/rest-data-services-downloads-212.html), and examine the Readme. Make sure that you have the required version of Java installed.
1. Create a new directory for your ORDS installation.
```
mkdir /home/apexuser/ORDS
cd /home/apexuser/ORDS
```
1. Download the file `ords.version.number.zip` from [Oracle REST data services](https://www.oracle.com/database/technologies/appdev/rest-data-services-downloads-212.html).
1. Unzip the file into the `/home/apexuser/ORDS` directory.
1. If you're installing ORDS in a multitenant database, add the following line to the file `/home/apexuser/ORDS/params/ords_params.properties`:
```
pdb.disable.lockdown=false
```
1. Grant the master user the required privileges to install ORDS.
After the options for Oracle APEX are installed, give the master user the required privileges to install the ORDS schema. You can do this by connecting to the database and running the following commands. Replace `MASTER_USER` with the uppercase name of your master user.
**Important**
When you enter the user name, use uppercase unless you created the user with a case-sensitive identifier. For example, if you run `CREATE USER myuser` or `CREATE USER MYUSER`, the data dictionary stores `MYUSER`. However, if you use double quotes in `CREATE USER "MyUser"`, the data dictionary stores `MyUser`. For more information, see [Granting SELECT or EXECUTE privileges to SYS objects](Appendix.Oracle.CommonDBATasks.TransferPrivileges.md).
```
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_OBJECTS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_ROLE_PRIVS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONS_COLUMNS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONSTRAINTS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_OBJECTS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_PROCEDURES', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TABLES', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_VIEWS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('WPIUTL', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SESSION', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_UTILITY', 'MASTER_USER', 'EXECUTE', true);
```
**Note**
These commands apply to ORDS version 19.1 and later.
1. Install the ORDS schema using the downloaded ords.war file.
```
java -jar ords.war install advanced
```
The program prompts you for the following information. The default values are in brackets. For more information, see [Introduction to Oracle REST data services](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/20.2/aelig/installing-REST-data-services.html#GUID-6F7B4E61-B730-4E73-80B8-F53299123730) in the Oracle documentation.
+ Enter the location to store configuration data:
Enter */home/apexuser/ORDS*. This is the location of the ORDS configuration files.
+ Specify the database connection type to use. Enter number for [1] Basic [2] TNS [3] Custom URL [1]:
Choose the desired connection type.
+ Enter the name of the database server [localhost]: *DB\$1instance\$1endpoint*
Choose the default or enter the correct value.
+ Enter the database listener port [1521]: *DB\$1instance\$1port*
Choose the default or enter the correct value.
+ Enter 1 to specify the database service name, or 2 to specify the database SID [1]:
Choose `2` to specify the database SID.
+ Database SID [xe]
Choose the default or enter the correct value.
+ Enter 1 if you want to verify/install Oracle REST Data Services schema or 2 to skip this step [1]:
Choose `1`. This step creates the Oracle REST Data Services proxy user named ORDS\$1PUBLIC\$1USER.
+ Enter the database password for ORDS\$1PUBLIC\$1USER:
Enter the password, and then confirm it.
+ Requires to login with administrator privileges to verify Oracle REST Data Services schema.
Enter the administrator user name: *master\$1user*
Enter the database password for *master\$1user*: *master\$1user\$1password*
Confirm the password: *master\$1user\$1password*
**Note**
Specify a password other than the prompt shown here as a security best practice.
+ Enter the default tablespace for ORDS\$1METADATA [SYSAUX].
Enter the temporary tablespace for ORDS\$1METADATA [TEMP].
Enter the default tablespace for ORDS\$1PUBLIC\$1USER [USERS].
Enter the temporary tablespace for ORDS\$1PUBLIC\$1USER [TEMP].
+ Enter 1 if you want to use PL/SQL Gateway or 2 to skip this step. If you're using Oracle Application Express or migrating from mod\$1plsql, you must enter 1 [1].
Choose the default.
+ Enter the PL/SQL Gateway database user name [APEX\$1PUBLIC\$1USER]
Choose the default.
+ Enter the database password for APEX\$1PUBLIC\$1USER:
Enter the password, and then confirm it.
+ Enter 1 to specify passwords for Application Express RESTful Services database users (APEX\$1LISTENER, APEX\$1REST\$1PUBLIC\$1USER) or 2 to skip this step [1]:
Choose `2` for APEX 4.1.1.V1; choose `1` for all other APEX versions.
+ [Not needed for APEX 4.1.1.v1] Database password for APEX\$1LISTENER
Enter the password (if required), and then confirm it.
+ [Not needed for APEX 4.1.1.v1] Database password for APEX\$1REST\$1PUBLIC\$1USER
Enter the password (if required), and then confirm it.
+ Enter a number to select a feature to enable:
Enter `1` to enable all features: SQL Developer Web, REST Enabled SQL, and Database API.
+ Enter 1 if you wish to start in standalone mode or 2 to exit [1]:
Enter `1`.
+ Enter the APEX static resources location:
If you unzipped APEX installation files into `/home/apexuser`, enter `/home/apexuser/apex/images`. Otherwise, enter `unzip_path/apex/images`, where *unzip\$1path* is the directory where you unzipped the file.
+ Enter 1 if using HTTP or 2 if using HTTPS [1]:
If you enter `1`, specify the HTTP port. If you enter `2`, specify the HTTPS port and the SSL host name. The HTTPS option prompts you to specify how you will provide the certificate:
+ Enter `1` to use the self-signed certificate.
+ Enter `2` to provide your own certificate. If you enter `2`, specify the path for the SSL certificate and the path for the SSL certificate private key.
1. Set a password for the APEX `admin` user. To do this, use SQL\$1Plus to connect to your DB instance as the master user, and then run the following commands.
```
1. EXEC rdsadmin.rdsadmin_util.grant_apex_admin_role;
2. grant APEX_ADMINISTRATOR_ROLE to master;
3. @/home/apexuser/apex/apxchpwd.sql
```
Replace `master` with your master user name. When the `apxchpwd.sql` script prompts you, enter a new `admin` password.
1. Start the ORDS listener. Run the following code.
```
java -jar ords.war
```
The first time you start ORDS, you are prompted to provide the location of the APEX Static resources. This images folder is located in the `/apex/images` directory in the installation directory for APEX.
1. Return to the Oracle APEX administration window in your browser and choose **Administration**. Next, choose **Application Express Internal Administration**. When you are prompted for credentials, enter the following information:
+ **User name** – `admin`
+ **Password** – the password you set using the `apxchpwd.sql` script
Choose **Login**, and then set a new password for the `admin` user.
Your listener is now ready for use.
## Installing and configuring ORDS 22 and higher
You are now ready to install and configure Oracle Rest Data Services (ORDS) for use with Oracle APEX. For the examples in this section, we assume that the name of your separate host is `myapexhost.example.com`, and that your host is running Linux. The instructions for ORDS 22 differ from the instructions for previous releases.
**To install and configure ORDS 22 and higher for use with Oracle APEX**
1. Go to [Oracle REST data services](http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html), and examine the Readme for the ORDS version that you plan to download. Make sure that you have the required version of Java installed.
1. Create a new directory for your ORDS installation.
```
mkdir /home/apexuser/ORDS
cd /home/apexuser/ORDS
```
1. Download the file `ords.version.number.zip` or `ords-latest.zip` from [Oracle REST data services](http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html).
1. Unzip the file into the `/home/apexuser/ORDS` directory.
1. Grant the master user the required privileges to install ORDS.
After the `APEX` option is installed, give the master user the required privileges to install the ORDS schema. You can do this by logging in to the database and running the following commands. Replace `MASTER_USER` with the uppercase name of your master user.
**Important**
When you enter the user name, use uppercase unless you created the user with a case-sensitive identifier. For example, if you run `CREATE USER myuser` or `CREATE USER MYUSER`, the data dictionary stores `MYUSER`. However, if you use double quotes in `CREATE USER "MyUser"`, the data dictionary stores `MyUser`. For more information, see [Granting SELECT or EXECUTE privileges to SYS objects](Appendix.Oracle.CommonDBATasks.TransferPrivileges.md).
```
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_OBJECTS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_ROLE_PRIVS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONS_COLUMNS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_CONSTRAINTS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_OBJECTS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_PROCEDURES', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TAB_COLUMNS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_TABLES', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('USER_VIEWS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('WPIUTL', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SESSION', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_UTILITY', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_LOB', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_ASSERT', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_OUTPUT', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SCHEDULER', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('HTP', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('OWA', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('WPG_DOCLOAD', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_CRYPTO', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_METADATA', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_SQL', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('UTL_SMTP', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBMS_NETWORK_ACL_ADMIN', 'MASTER_USER', 'EXECUTE', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('SESSION_PRIVS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_USERS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_NETWORK_ACL_PRIVILEGES', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_NETWORK_ACLS', 'MASTER_USER', 'SELECT', true);
exec rdsadmin.rdsadmin_util.grant_sys_object('DBA_REGISTRY', 'MASTER_USER', 'SELECT', true);
```
**Note**
The preceding commands apply to ORDS 22 and later.
1. Install the ORDS schema using the downloaded `ords` script. Specify directories to contain configuration files and log files. Oracle Corporation recommends not placing these directories inside the directory that contains the ORDS product software.
```
mkdir -p /home/apexuser/ords_config /home/apexuser/ords_logs
/home/apexuser/ORDS/bin/ords \
--config /home/apexuser/ords_config \
install --interactive --log-folder /home/apexuser/ords_logs
```
For DB instances running the container database (CDB) architecture, use ORDS 23.3 or higher and pass the `--pdb-skip-disable-lockdown` argument when installing ORDS.
```
/home/apexuser/ORDS/bin/ords \
--config /home/apexuser/ords_config \
install --interactive --log-folder /home/apexuser/ords_logs --pdb-skip-disable-lockdown
```
The program prompts you for the following information. The default values are in brackets. For more information, see [Introduction to Oracle REST data services](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/20.2/aelig/installing-REST-data-services.html#GUID-6F7B4E61-B730-4E73-80B8-F53299123730) in the Oracle documentation.
+ `Choose the type of installation:`
Choose **2** to install ORDS schemas in the database and create a database connection pool in the local ORDS configuration files.
+ `Specify the database connection type to use. Enter number for [1] Basic [2] TNS [3] Custom URL:`
Choose the desired connection type. This example assumes that you choose **1**.
+ `Enter the name of the database server [localhost]:` ***DB\$1instance\$1endpoint***
Choose the default or enter the correct value.
+ `Enter the database listener port [1521]:` ***DB\$1instance\$1port***
Choose the default **1521** or enter the correct value.
+ `Enter the database service name [orcl]:`
Enter the database name used by your RDS for Oracle DB instance.
+ `Provide database user name with administrator privileges`
Enter the master user name for your RDS for Oracle DB instance.
+ `Enter the database password for [username]:`
Enter the master user password for your RDS for Oracle DB instance.
+ `Enter the default tablespace for ORDS_METADATA and ORDS_PUBLIC_USER [SYSAUX]:`
+ `Enter the temporary tablespace for ORDS_METADATA [TEMP]. Enter the default tablespace for ORDS_PUBLIC_USER [USERS]. Enter the temporary tablespace for ORDS_PUBLIC_USER [TEMP].`
+ `Enter a number to select additional feature(s) to enable [1]:`
+ `Enter a number to configure and start ORDS in standalone mode [1]: `
Choose **2** to skip starting ORDS immediately in standalone mode.
+ `Enter a number to select the protocol [1] HTTP`
+ `Enter the HTTP port [8080]:`
+ `Enter the APEX static resources location:`
Enter the path to the Oracle APEX installation files (`/home/apexuser/apex/images`).
1. Set a password for the Oracle APEX `admin` user. To do this, use SQL\$1Plus to connect to your DB instance as the master user, and then run the following commands.
```
1. EXEC rdsadmin.rdsadmin_util.grant_apex_admin_role;
2. grant APEX_ADMINISTRATOR_ROLE to master;
3. @/home/apexuser/apex/apxchpwd.sql
```
Replace `master` with your master user name. When the `apxchpwd.sql` script prompts you, enter a new `admin` password.
1. Run ORDS in standalone mode using the `ords` script with the `serve` command. For production deployments, consider using supported Java EE application servers such as Apache Tomcat or Oracle WebLogic Server. For more information, see [Deploying and Monitoring Oracle REST Data Services](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/23.1/ordig/deploying-and-monitoring-oracle-rest-data-services.html#GUID-6791F5DF-AC67-4885-BFFA-B80964C17EC9) in the Oracle Database documentation.
```
/home/apexuser/ORDS/bin/ords \
--config /home/apexuser/ords_config serve \
--port 8193 \
--apex-images /home/apexuser/apex/images
```
If ORDS is running but unable to access the Oracle APEX installation, you might see the following error, particularly on non-CDB instances.
```
The procedure named apex_admin could not be accessed, it may not be declared, or the user executing this request may not have been granted execute privilege on the procedure, or a function specified by security.requestValidationFunction configuration property has prevented access.
```
To fix this error, change the request validation function used by ORDS by running the `ords` script with the `config` command. By default, ORDS uses the `ords_util.authorize_plsql_gateway` procedure, which is only supported on CDB instances. For non-CDB instances, you can change this procedure to the `wwv_flow_epg_include_modules.authorize` package. See the Oracle Database documentation and Oracle Support for best practices on configuring the proper request validation function for your use case.
1. Return to the Oracle APEX administration window in your browser and choose **Administration**. Next, choose **Application Express Internal Administration**. When you are prompted for credentials, enter the following information:
+ **User name** – `admin`
+ **Password** – the password you set using the `apxchpwd.sql` script
Choose **Login**, and then set a new password for the `admin` user.
Your listener is now ready for use.
# Upgrading and removing Oracle APEX
To upgrade or remove Oracle APEX, follow the instructions in this topic:
**Topics**
+ [
## Upgrading the Oracle APEX version
](#Appendix.Oracle.Options.APEX.Upgrade)
+ [
## Removing the APEX and APEX-DEV options
](#Appendix.Oracle.Options.APEX.Remove)
## Upgrading the Oracle APEX version
**Important**
Back up your DB instance before you upgrade Oracle APEX. For more information, see [Creating a DB snapshot for a Single-AZ DB instance for Amazon RDS](USER_CreateSnapshot.md) and [Testing an Oracle DB upgrade](USER_UpgradeDBInstance.Oracle.UpgradeTesting.md).
To upgrade Oracle APEX with your DB instance, do the following:
+ Create a new option group for the upgraded version of your DB instance.
+ Add the upgraded versions of the `APEX` and `APEX-DEV` options to the new option group. Be sure to include any other options that your DB instance uses. For more information, see [Option group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.OG).
+ When you upgrade your DB instance, specify the new option group for your upgraded DB instance.
After you upgrade your version of Oracle APEX, the Oracle APEX schema for the previous version might still exist in your database. If you don't need it anymore, you can drop the old Oracle APEX schema from your database after you upgrade.
If you upgrade the Oracle APEX version and RESTful services were not configured in the previous Oracle APEX version, we recommend that you configure RESTful services. For more information, see [Configuring RESTful services for Oracle APEX](Appendix.Oracle.Options.APEX.settingUp.md#Appendix.Oracle.Options.APEX.ConfigureRESTful).
In some cases when you plan to do a major version upgrade of your DB instance, you might find that you're using an Oracle APEX version that isn't compatible with your target database version. In these cases, you can upgrade your version of Oracle APEX before you upgrade your DB instance. Upgrading Oracle APEX first can reduce the amount of time that it takes to upgrade your DB instance.
**Note**
After upgrading Oracle APEX, install and configure a listener for use with the upgraded version. For instructions, see [Setting up Oracle APEX listener](Appendix.Oracle.Options.APEX.settingUp.md#Appendix.Oracle.Options.APEX.Listener).
## Removing the APEX and APEX-DEV options
You can remove the `APEX` and `APEX-DEV` options from a DB instance. To remove these options from your DB instance, do one of the following:
+ To remove the `APEX` and `APEX-DEV` options from multiple DB instances, remove the options from the option group they belong to. This change affects all DB instances that use the option group. When you remove the options from an option group that is attached to multiple DB instances, a brief outage occurs while the DB instances are restarted.
For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ To remove the `APEX` and `APEX-DEV` options from a single DB instance, modify the DB instance and specify a different option group that doesn't include these options. You can specify the default (empty) option group, or a different custom option group. When you remove the options, a brief outage occurs while your DB instance is automatically restarted.
For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
When you remove the `APEX` and `APEX-DEV` options from a DB instance, the APEX schema is removed from your database.
# Amazon EFS integration
Amazon Elastic File System (Amazon EFS) provides serverless, fully elastic file storage so that you can share file data without provisioning or managing storage capacity and performance. With Amazon EFS, you can create a file system and then mount it in your VPC through the NFS versions 4.0 and 4.1 (NFSv4) protocol. Then you can use the EFS file system like any other POSIX-compliant file system. For general information, see [What is Amazon Elastic File System?](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) and the AWS blog [Integrate Amazon RDS for Oracle with Amazon EFS](https://aws.amazon.com//blogs/database/integrate-amazon-rds-for-oracle-with-amazon-efs/).
**Topics**
+ [
## Overview of Amazon EFS integration
](#oracle-efs-integration.overview)
+ [
# Configuring network permissions for RDS for Oracle integration with Amazon EFS
](oracle-efs-integration.network.md)
+ [
# Configuring IAM permissions for RDS for Oracle integration with Amazon EFS
](oracle-efs-integration.iam.md)
+ [
# Adding the EFS\$1INTEGRATION option
](oracle-efs-integration.adding.md)
+ [
# Configuring Amazon EFS file system permissions
](oracle-efs-integration.file-system.md)
+ [
# Transferring files between RDS for Oracle and an Amazon EFS file system
](oracle-efs-integration.transferring.md)
+ [
# Removing the EFS\$1INTEGRATION option
](oracle-efs-integration.removing.md)
+ [
# Troubleshooting Amazon EFS integration
](oracle-efs-integration.troubleshooting.md)
## Overview of Amazon EFS integration
With Amazon EFS, you can transfer files between your RDS for Oracle DB instance and an EFS file system. For example, you can use EFS to support the following use cases:
+ Share a file system between applications and multiple database servers.
+ Create a shared directory for migration-related files, including transportable tablespace data files. For more information, see [Migrating using Oracle transportable tablespaces](oracle-migrating-tts.md).
+ Store and share archived redo log files without allocating additional storage space on the server.
+ Use Oracle Database utilities such as `UTL_FILE` to read and write files.
### Advantages to Amazon EFS integration
When you choose an EFS file system over alternative data transfer solutions, you get the following benefits:
+ You can transfer Oracle Data Pump files between Amazon EFS and your RDS for Oracle DB instance. You don’t need to copy these files locally because Data Pump imports directly from the EFS file system. For more information, see [Importing data into Oracle on Amazon RDS](Oracle.Procedural.Importing.md).
+ Data migration is faster than using a database link.
+ You avoid allocating storage space on your RDS for Oracle DB instance to hold the files.
+ An EFS file systems can automatically scale storage without requiring you to provision it.
+ Amazon EFS integration has no minimum fees or setup costs. You pay only for what you use.
+ Amazon EFS integration supports two forms of encryption: encryption of data in transit and encryption at rest. Encryption of data in transit is enabled by default using TLS version 1.2. You can enable encryption of data at rest when creating an Amazon EFS file system. For more information, see [Encrypting data at rest](https://docs.aws.amazon.com/efs/latest/ug/encryption-at-rest.html) in the *Amazon Elastic File System User Guide*.
### Requirements for Amazon EFS integration
Make sure that you meet the following requirements:
+ Your database must run database version 19.0.0.0.ru-2022-07.rur-2022-07.r1 or higher.
+ Your DB instance and your EFS file system must be in the same AWS Region, VPC, and AWS account. RDS for Oracle doesn't support cross-account and cross-Region access for EFS.
+ Your VPC must have both **DNS Resolution** and **DNS Hostnames** enabled. For more information, see [DNS attributes in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support) in the *Amazon Virtual Private Cloud User Guide*.
+ If you use a DNS name in the `mount` command, make sure your VPC configured to use the DNS server provided by Amazon. Custom DNS servers aren't supported.
+ You must use non-RDS solutions to back up your EFS file system. RDS for Oracle doesn't support automated backups or manual DB snapshots of an EFS file system. For more information, see [Backing up your Amazon EFS file systems](https://docs.aws.amazon.com/efs/latest/ug/efs-backup-solutions.html).
# Configuring network permissions for RDS for Oracle integration with Amazon EFS
For RDS for Oracle to integrate with Amazon EFS, make sure that your DB instance has network access to an EFS file system. For more information, see [Controlling network access to Amazon EFS file systems for NFS clients](https://docs.aws.amazon.com/efs/latest/ug/NFS-access-control-efs.html) in the *Amazon Elastic File System User Guide*.
**Topics**
+ [
## Controlling network access with security groups
](#oracle-efs-integration.network.inst-access)
+ [
## Controlling network access with file system policies
](#oracle-efs-integration.network.file-system-policy)
## Controlling network access with security groups
You can control your DB instance access to EFS file systems using network layer security mechanisms such as VPC security groups. To allow access to an EFS file system for your DB instance, make sure that your EFS file system meets the following requirements:
+ An EFS mount target exists in every Availability Zone used by an RDS for Oracle DB instance.
An *EFS mount target* provides an IP address for an NFSv4 endpoint at which you can mount an EFS file system. You mount your file system using its DNS name, which resolves to the IP address of the EFS mount target in the used by the Availability Zone of your DB instance.
You can configure DB instances in different AZs to use the same EFS file system. For Multi-AZ, you need a mount point for each AZ in your deployment. You might need to move a DB instance to a different AZ. For these reasons, we recommend that you create an EFS mount point in each AZ in your VPC. By default, when you create a new EFS file system using the console, RDS creates mount targets for all AZs.
+ A security group is attached to the mount target.
+ The security group has an inbound rule to allow the network subnet or security group of the RDS for Oracle DB instance on TCP/2049 (Type NFS).
For more information, see [Creating Amazon EFS file systems](https://docs.aws.amazon.com/efs/latest/ug/creating-using-create-fs.html#configure-efs-network-access) and [Creating and managing EFS mount targets and security groups](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs.html) in the *Amazon Elastic File System User Guide*.
## Controlling network access with file system policies
Amazon EFS integration with RDS for Oracle works with the default (empty) EFS file system policy. The default policy doesn't use IAM to authenticate. Instead, it grants full access to any anonymous client that can connect to the file system using a mount target. The default policy is in effect whenever a user-configured file system policy isn't in effect, including at file system creation. For more information, see [Default EFS file system policy](https://docs.aws.amazon.com/efs/latest/ug/iam-access-control-nfs-efs.html#default-filesystempolicy) in the *Amazon Elastic File System User Guide*.
To strengthen access to your EFS file system for all clients, including RDS for Oracle, you can configure IAM permissions. In this approach, you create a file system policy. For more information, see [Creating file system policies](https://docs.aws.amazon.com/efs/latest/ug/create-file-system-policy.html) in the *Amazon Elastic File System User Guide*.
# Configuring IAM permissions for RDS for Oracle integration with Amazon EFS
By default, Amazon EFS integration feature doesn't use an IAM role: the `USE_IAM_ROLE` option setting is `FALSE`. To integrate RDS for Oracle with Amazon EFS and an IAM role, your DB instance must have IAM permissions to access an Amazon EFS file system.
**Topics**
+ [
## Step 1: Create an IAM role for your DB instance and attach your policy
](#oracle-efs-integration.iam.role)
+ [
## Step 2: Create a file system policy for your Amazon EFS file system
](#oracle-efs-integration.iam.policy)
+ [
## Step 3: Associate your IAM role with your RDS for Oracle DB instance
](#oracle-efs-integration.iam.instance)
## Step 1: Create an IAM role for your DB instance and attach your policy
In this step, you create a role for your RDS for Oracle DB instance to allow Amazon RDS to access your EFS file system.
### Console
**To create an IAM role to allow Amazon RDS access to an EFS file system**
1. Open the [IAM Management Console](https://console.aws.amazon.com/iam/home?#home).
1. In the navigation pane, choose **Roles**.
1. Choose **Create role**.
1. For **AWS service**, choose **RDS**.
1. For **Select your use case**, choose **RDS – Add Role to Database**.
1. Choose **Next**.
1. Don't add any permissions policies. Choose **Next**.
1. Set **Role name** to a name for your IAM role, for example `rds-efs-integration-role`. You can also add an optional **Description** value.
1. Choose **Create role**.
### AWS CLI
To limit the service's permissions to a specific resource, we recommend using the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context keys in resource-based trust relationships. This is the most effective way to protect against the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).
You might use both global condition context keys and have the `aws:SourceArn` value contain the account ID. In this case, the `aws:SourceAccount` value and the account in the `aws:SourceArn` value must use the same account ID when used in the same statement.
+ Use `aws:SourceArn` if you want cross-service access for a single resource.
+ Use `aws:SourceAccount` if you want to allow any resource in that account to be associated with the cross-service use.
In the trust relationship, make sure to use the `aws:SourceArn` global condition context key with the full Amazon Resource Name (ARN) of the resources accessing the role.
The following AWS CLI command creates the role named `rds-efs-integration-role` for this purpose.
**Example**
For Linux, macOS, or Unix:
```
aws iam create-role \
--role-name rds-efs-integration-role \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": my_account_ID,
"aws:SourceArn": "arn:aws:rds:Region:my_account_ID:db:dbname"
}
}
}
]
}'
```
For Windows:
```
aws iam create-role ^
--role-name rds-efs-integration-role ^
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": my_account_ID,
"aws:SourceArn": "arn:aws:rds:Region:my_account_ID:db:dbname"
}
}
}
]
}'
```
For more information, see [Creating a role to delegate permissions to an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
## Step 2: Create a file system policy for your Amazon EFS file system
In this step, you create a file system policy for your EFS file system.
**To create or edit an EFS file system policy**
1. Open the [EFS Management Console](https://console.aws.amazon.com/efs/home?#home).
1. Choose **File Systems**.
1. On the **File systems** page, choose the file system that you want to edit or create a file system policy for. The details page for that file system is displayed.
1. Choose the **File system policy** tab.
If the policy is empty, then the default EFS file system policy is in use. For more information, see [Default EFS file system policy](https://docs.aws.amazon.com/efs/latest/ug/iam-access-control-nfs-efs.html#default-filesystempolicy ) in the *Amazon Elastic File System User Guide*.
1. Choose **Edit**. The **File system policy** page appears.
1. In **Policy editor**, enter a policy such as the following, and then choose **Save**.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "ExamplePolicy01",
"Statement": [
{
"Sid": "ExampleStatement01",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/rds-efs-integration-role"
},
"Action": [
"elasticfilesystem:ClientMount",
"elasticfilesystem:ClientWrite",
"elasticfilesystem:ClientRootAccess"
],
"Resource": "arn:aws:elasticfilesystem:us-east-1:123456789012:file-system/fs-1234567890abcdef0"
}
]
}
```
------
## Step 3: Associate your IAM role with your RDS for Oracle DB instance
In this step, you associate your IAM role with your DB instance. Be aware of the following requirements:
+ You must have access to an IAM role with the required Amazon EFS permissions policy attached to it.
+ You can associate only one IAM role with your RDS for Oracle DB instance at a time.
+ The status of your instance must be **Available**.
For more information, see [Identity and access management for Amazon EFS](https://docs.aws.amazon.com/efs/latest/ug/auth-and-access-control.html) in the *Amazon Elastic File System User Guide*.
### Console
**To associate your IAM role with your RDS 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. Choose **Databases**.
1. If your database instance is unavailable, choose **Actions** and then **Start**. When the instance status shows **Started**, go to the next step.
1. Choose the Oracle DB instance name to display its details.
1. On the **Connectivity & security** tab, scroll down to the **Manage IAM roles** section at the bottom of the page.
1. Choose the role to add in the **Add IAM roles to this instance** section.
1. For **Feature**, choose **EFS\$1INTEGRATION**.
1. Choose **Add role**.
### AWS CLI
The following AWS CLI command adds the role to an Oracle DB instance named `mydbinstance`.
**Example**
For Linux, macOS, or Unix:
```
aws rds add-role-to-db-instance \
--db-instance-identifier mydbinstance \
--feature-name EFS_INTEGRATION \
--role-arn your-role-arn
```
For Windows:
```
aws rds add-role-to-db-instance ^
--db-instance-identifier mydbinstance ^
--feature-name EFS_INTEGRATION ^
--role-arn your-role-arn
```
Replace `your-role-arn` with the role ARN that you noted in a previous step. `EFS_INTEGRATION` must be specified for the `--feature-name` option.
# Adding the EFS\$1INTEGRATION option
To integrate Amazon RDS for Oracle with Amazon EFS, your DB instance must be associated with an option group that includes the `EFS_INTEGRATION` option.
Multiple Oracle DB instances that belong to the same option group share the same EFS file system. Different DB instances can access the same data, but access can be divided by using different Oracle directories. For more information see [Transferring files between RDS for Oracle and an Amazon EFS file system](oracle-efs-integration.transferring.md).
## Console
**To configure an option group for Amazon EFS integration**
1. Create a new option group or identify an existing option group to which you can add the `EFS_INTEGRATION` option.
For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the `EFS_INTEGRATION` option to the option group. You need to specify the `EFS_ID` file system ID and set the `USE_IAM_ROLE` flag.
For more information, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Associate the option group with your DB instance in either of the following ways:
+ Create a new Oracle DB instance and associate the option group with it. For information about creating a DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ Modify an Oracle DB instance to associate the option group with it. For information about modifying an Oracle DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## AWS CLI
**To configure an option group for EFS integration**
1. Create a new option group or identify an existing option group to which you can add the `EFS_INTEGRATION` option.
For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the `EFS_INTEGRATION` option to the option group.
For example, the following AWS CLI command adds the `EFS_INTEGRATION` option to an option group named **myoptiongroup**.
**Example**
For Linux, macOS, or Unix:
```
aws rds add-option-to-option-group \
--option-group-name myoptiongroup \
--options "OptionName=EFS_INTEGRATION,OptionSettings=\
[{Name=EFS_ID,Value=fs-1234567890abcdef0},{Name=USE_IAM_ROLE,Value=TRUE}]"
```
For Windows:
```
aws rds add-option-to-option-group ^
--option-group-name myoptiongroup ^
--options "OptionName=EFS_INTEGRATION,OptionSettings=^
[{Name=EFS_ID,Value=fs-1234567890abcdef0},{Name=USE_IAM_ROLE,Value=TRUE}]"
```
1. Associate the option group with your DB instance in either of the following ways:
+ Create a new Oracle DB instance and associate the option group with it. For information about creating a DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ Modify an Oracle DB instance to associate the option group with it. For information about modifying an Oracle DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Configuring Amazon EFS file system permissions
By default, only the root user (UID `0`) has read, write, and execute permissions for a newly created EFS file system. For other users to modify the file system, the root user must explicitly grant them access. The user for the RDS for Oracle DB instance is in the `others` category. For more information, see [Working with users, groups, and permissions at the Network File System (NFS) Level](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs-nfs-permissions.html) in the *Amazon Elastic File System User Guide*.
To allow your RDS for Oracle DB instance to read and write files on an EFS file system, do the following:
+ Mount an EFS file system locally on your Amazon EC2 or on-premises instance.
+ Configure fine grain permissions.
For example, to grant `other` users permissions to write to the EFS file system root, run `chmod 777` on this directory. For more information, see [Example Amazon EFS file system use cases and permissions](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs-nfs-permissions.html#accessing-fs-nfs-permissions-ex-scenarios) in the *Amazon Elastic File System User Guide*.
# Transferring files between RDS for Oracle and an Amazon EFS file system
To transfer files between an RDS for Oracle instance and an Amazon EFS file system, create at least one Oracle directory and configure EFS file system permissions to control DB instance access.
**Topics**
+ [
## Creating an Oracle directory
](#oracle-efs-integration.transferring.od)
+ [
## Transferring data to and from an EFS file system: examples
](#oracle-efs-integration.transferring.upload)
## Creating an Oracle directory
To create an Oracle directory, use the procedure `rdsadmin.rdsadmin_util.create_directory_efs`. The procedure has the following parameters.
****
| Parameter name | Data type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `p_directory_name` | VARCHAR2 | – | Yes | The name of the Oracle directory. |
| `p_path_on_efs` | VARCHAR2 | – | Yes | The path on the EFS file system. The prefix of the path name uses the pattern `/rdsefs-fsid/`, where *fsid* is a placeholder for your EFS file system ID. For example, if your EFS file system is named `fs-1234567890abcdef0`, and you create a subdirectory on this file system named `mydir`, you could specify the following value: /rdsefs-fs-1234567890abcdef0/mydir
|
Assume that you create a subdirectory named `/datapump1` on the EFS file system `fs-1234567890abcdef0`. The following example creates an Oracle directory `DATA_PUMP_DIR_EFS` that points to the `/datapump1` directory on the EFS file system. The file system path value for the `p_path_on_efs` parameter is prefixed with the string `/rdsefs-`.
```
BEGIN
rdsadmin.rdsadmin_util.create_directory_efs(
p_directory_name => 'DATA_PUMP_DIR_EFS',
p_path_on_efs => '/rdsefs-fs-1234567890abcdef0/datapump1');
END;
/
```
## Transferring data to and from an EFS file system: examples
The following example uses Oracle Data Pump to export the table named `MY_TABLE` to file `datapump.dmp`. This file resides on an EFS file system.
```
DECLARE
v_hdnl NUMBER;
BEGIN
v_hdnl := DBMS_DATAPUMP.OPEN(operation => 'EXPORT', job_mode => 'TABLE', job_name=>null);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'datapump.dmp',
directory => 'DATA_PUMP_DIR_EFS',
filetype => dbms_datapump.ku$_file_type_dump_file);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'datapump-exp.log',
directory => 'DATA_PUMP_DIR_EFS',
filetype => dbms_datapump.ku$_file_type_log_file);
DBMS_DATAPUMP.METADATA_FILTER(v_hdnl,'NAME_EXPR','IN (''MY_TABLE'')');
DBMS_DATAPUMP.START_JOB(v_hdnl);
END;
/
```
The following example uses Oracle Data Pump to import the table named `MY_TABLE` from file `datapump.dmp`. This file resides on an EFS file system.
```
DECLARE
v_hdnl NUMBER;
BEGIN
v_hdnl := DBMS_DATAPUMP.OPEN(
operation => 'IMPORT',
job_mode => 'TABLE',
job_name => null);
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'datapump.dmp',
directory => 'DATA_PUMP_DIR_EFS',
filetype => dbms_datapump.ku$_file_type_dump_file );
DBMS_DATAPUMP.ADD_FILE(
handle => v_hdnl,
filename => 'datapump-imp.log',
directory => 'DATA_PUMP_DIR_EFS',
filetype => dbms_datapump.ku$_file_type_log_file);
DBMS_DATAPUMP.METADATA_FILTER(v_hdnl,'NAME_EXPR','IN (''MY_TABLE'')');
DBMS_DATAPUMP.START_JOB(v_hdnl);
END;
/
```
For more information, see [Importing data into Oracle on Amazon RDS](Oracle.Procedural.Importing.md).
# Removing the EFS\$1INTEGRATION option
The steps for removing the `EFS_INTEGRATION` option depend on whether you're removing the option from multiple DB instances or a single instance.
| Number of DB instances | Action | Related information |
| --- | --- | --- |
| Multiple | Remove the EFS\$1INTEGRATION option from the option group to which the DB instances belong. This change affects all instances that use the option group. | [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption) |
| Single | Modify the DB instance and specify a different option group that doesn't include the EFS\$1INTEGRATION option. You can specify the default (empty) option group or a different custom option group. | [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md) |
After you remove the `EFS_INTEGRATION` option, you can optionally delete the EFS file system that was connected to your DB instances.
# Troubleshooting Amazon EFS integration
Your RDS for Oracle DB instance monitors the connectivity to an Amazon EFS file system. When monitoring detects an issue, it might try to correct the issue and publish an event in the RDS console. For more information, see [Viewing Amazon RDS events](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ListEvents.html).
Use the information in this section to help you diagnose and fix common issues when you work with Amazon EFS integration.
| Notification | Description | Action |
| --- | --- | --- |
| `The EFS for RDS Oracle instance instance_name isn't available on the primary host. NFS port 2049 of your EFS isn't reachable.` | The DB instance can't communicate with the EFS file system. | Make sure of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-efs-integration.troubleshooting.html) |
| `The EFS isn't reachable.` | An error occurred during the installation of the `EFS_INTEGRATION` option. | Make sure of the following: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-efs-integration.troubleshooting.html) |
| `The associated role with your DB instance wasn't found.` | An error occurred during the installation of the `EFS_INTEGRATION` option. | Make sure that you associated an IAM role with your RDS for Oracle DB instance. |
| `The associated role with your DB instance wasn't found.` | An error occurred during the installation of the `EFS_INTEGRATION` option. RDS for Oracle was restored from a DB snapshot with the `USE_IAM_ROLE` option setting of `TRUE`. | Make sure that you associated an IAM role with your RDS for Oracle DB instance. |
| `The associated role with your DB instance wasn't found.` | An error occurred during the installation of the `EFS_INTEGRATION` option. RDS for Oracle was created from an all-in-one CloudFormation template with the `USE_IAM_ROLE` option setting of `TRUE`. | As a workaround, complete the following steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-efs-integration.troubleshooting.html) |
| `PLS-00302: component 'CREATE_DIRECTORY_EFS' must be declared` | This error can occur when you're using a version of RDS for Oracle that doesn't support Amazon EFS. | Make sure that you are using RDS for Oracle DB instance version 19.0.0.0.ru-2022-07.rur-2022-07.r1 or higher. |
| `Read access of your EFS is denied. Check your file system policy.` | Your DB instance can't read the EFS file system. | Make sure that your EFS file system allows read access through the IAM role or on the EFS file system level. |
| N/A | Your DB instance can't write to the EFS file system. | Take the following steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-efs-integration.troubleshooting.html) |
# Oracle Java virtual machine
Amazon RDS supports Oracle Java Virtual Machine (JVM) through the use of the `JVM` option. Oracle Java provides a SQL schema and functions that facilitate Oracle Java features in an Oracle database. For more information, see [ Introduction to Java in Oracle database](https://docs.oracle.com/database/121/JJDEV/chone.htm) in the Oracle documentation. You can use Oracle JVM with all versions of Oracle Database 21c (21.0.0) and Oracle Database 19c (19.0.0).
## Considerations for Oracle JVM
Java implementation in Amazon RDS has a limited set of permissions. The master user is granted the `RDS_JAVA_ADMIN` role, which grants a subset of the privileges granted by the `JAVA_ADMIN` role. To list the privileges granted to the `RDS_JAVA_ADMIN` role, run the following query on your DB instance:
```
SELECT * FROM dba_java_policy
WHERE grantee IN ('RDS_JAVA_ADMIN', 'PUBLIC')
AND enabled = 'ENABLED'
ORDER BY type_name, name, grantee;
```
## Prerequisites for Oracle JVM
The following are prerequisites for using Oracle Java:
+ Your DB instance must be of a large enough class. Oracle Java isn't supported for the db.t3.small DB instance classes. For more information, see [DB instance classes](Concepts.DBInstanceClass.md).
+ Your DB instance must have **Auto Minor Version Upgrade** enabled. This option enables your DB instance to receive minor DB engine version upgrades automatically when they become available. Amazon RDS uses this option to update your DB instance to the latest Oracle Patch Set Update (PSU) or Release Update (RU). For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Best practices for Oracle JVM
The following are best practices for using Oracle Java:
+ For maximum security, use the `JVM` option with Secure Sockets Layer (SSL). For more information, see [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md).
+ Configure your DB instance to restrict network access. For more information, see [Scenarios for accessing a DB instance in a VPC](USER_VPC.Scenarios.md) and [Working with a DB instance in a VPC](USER_VPC.WorkingWithRDSInstanceinaVPC.md).
+ Update the configuration of your HTTPS endpoints to support TLSv1.2 if you meet the following conditions:
+ You use Oracle Java Virtual Machine (JVM) to connect an HTTPS endpoint over TLSv1 or TLSv1.1 protocols.
+ Your endpoint doesn't support the TLSv1.2 protocol.
+ You haven't applied the April 2021 release update to your Oracle DB.
By updating your endpoint configuration, you ensure that the connectivity of the JVM to the HTTPS endpoint will continue to work. For more information about TLS changes in the Oracle JRE and JDK, see [Oracle JRE and JDK Cryptographic Roadmap](https://java.com/en/jre-jdk-cryptoroadmap.html).
## Adding the Oracle JVM option
The following is the general process for adding the `JVM` option to a DB instance:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with the DB instance.
There is a brief outage while the `JVM` option is added. After you add the option, you don't need to restart your DB instance. As soon as the option group is active, Oracle Java is available.
**Note**
During this outage, password verification functions are disabled briefly. You can also expect to see events related to password verification functions during the outage. Password verification functions are enabled again before the Oracle DB instance is available.
**To add the JVM option to a DB instance**
1. Determine the option group that you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
+ For **Engine**, choose the DB engine used by the DB instance (**oracle-ee**, **oracle-se**, **oracle-se1**, or **oracle-se2**).
+ For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **JVM** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, apply the option group by modifying the instance and attaching the new option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
1. Grant the required permissions to users.
The Amazon RDS master user has the permissions to use the `JVM` option by default. If other users require these permissions, connect to the DB instance as the master user in a SQL client and grant the permissions to the users.
The following example grants the permissions to use the `JVM` option to the `test_proc` user.
```
create user test_proc identified by password;
CALL dbms_java.grant_permission('TEST_PROC', 'oracle.aurora.security.JServerPermission', 'LoadClassInPackage.*', '');
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
After the user is granted the permissions, the following query should return output.
```
select * from dba_java_policy where grantee='TEST_PROC';
```
**Note**
The Oracle user name is case-sensitive, and it usually has all uppercase characters.
## Removing the Oracle JVM option
You can remove the `JVM` option from a DB instance. There is a brief outage while the option is removed. After you remove the `JVM` option, you don't need to restart your DB instance.
**Warning**
Removing the `JVM` option can result in data loss if the DB instance is using data types that were enabled as part of the option. Back up your data before proceeding. For more information, see [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md).
To remove the `JVM` option from a DB instance, do one of the following:
+ Remove the `JVM` option from the option group it belongs to. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ Modify the DB instance and specify a different option group that doesn't include the `JVM` option. This change affects a single DB instance. You can specify the default (empty) option group, or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle Enterprise Manager
Amazon RDS supports Oracle Enterprise Manager (OEM). OEM is the Oracle product line for integrated management of enterprise information technology.
Amazon RDS supports OEM on Oracle Database 19c non-CDBs or CDBs. The following table describes the supported OEM options.
****
| Option | Option ID | Supported OEM releases |
| --- | --- | --- |
| [OEM Database Express](Appendix.Oracle.Options.OEM_DBControl.md) | `OEM` | OEM Database Express 19c |
| [OEM Management Agent](Oracle.Options.OEMAgent.md) | `OEM_AGENT` | OEM Cloud Control for 13c |
**Note**
You can use OEM Database or OEM Management Agent, but not both.
# Oracle Enterprise Manager Database Express
Amazon RDS supports Oracle Enterprise Manager Database Express (EM Express) through the use of the OEM option. Amazon RDS supports EM Express for Oracle Database 19c using the CDB or non-CDB architecture.
EM Express is a web-based database management tool included in your database and is only available when it is open. It supports key performance management and basic database administration functions. For more information, see [Introduction to Oracle Enterprise Manager Database Express](https://docs.oracle.com/en/database/oracle/oracle-database/19/admqs/getting-started-with-database-administration.html#GUID-BA75AD46-D22E-4914-A31E-C395CD6A2BBA) in the Oracle Database documentation.
**Note**
EM Express isn't supported on the db.t3.small DB instance class. For more information about DB instance classes, see [RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md).
## OEM option settings
Amazon RDS supports the following settings for the OEM option.
****
| Option setting | Valid values | Description |
| --- | --- | --- |
| **Port** | An integer value | The port on the RDS for Oracle DB instance that listens for EM Express. The default is 5500. |
| **Security Groups** | — | A security group that has access to **Port**. |
## Step 1: Adding the OEM option
The general process for adding the OEM option to a DB instance is the following:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with your DB instance.
When you add the OEM option, a brief outage occurs while your DB instance is automatically restarted.
**To add the OEM option to a DB instance**
1. Determine the option group you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine** choose the oracle edition for your DB instance.
1. For **Major engine version** choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the OEM option to the option group, and configure the option settings. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption). For more information about each setting, see [OEM option settings](#Appendix.Oracle.Options.OEM_DBControl.Options).
**Note**
If you add the OEM option to an existing option group that is already attached to one or more DB instances, a brief outage occurs while all the DB instances are automatically restarted.
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, apply the option group by modifying the instance and attaching the new option group. When you add the OEM option, a brief outage occurs while your DB instance is automatically restarted. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
**Note**
You can also use the AWS CLI to add the OEM option. For examples, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
## Step 2: (CDB only) Unlocking the DBSNMP user account
If your DB instance uses the CDB architecture, you must log in to EM Express as `DBSNMP`. in a CDB, `DBSNMP` is a common user. By default, this account is locked. If your DB instance doesn't use the CDB architecture, skip this step.
**To unlock the DBSNMP user account in a CDB instance**
1. In SQL\$1Plus or another Oracle SQL application, log in to your DB instance as your master user.
1. Run the following stored procedure to unlock the `DBSNMP` account:
```
1. EXEC rdsadmin.rdsadmin_util.reset_oem_agent_password('new_password');
```
If you receive an error stating that the procedure doesn't exist, reboot your CDB instance to install it automatically. For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
## Step 3: Accessing EM Express through your browser
When you access EM Express from your web browser, a login window appears that prompts you for a user name and password.
**To access EM Express through your browser**
1. Identify the endpoint and EM Express port for your Amazon RDS DB instance. For information about finding the endpoint for your Amazon RDS DB instance, see [Finding the endpoint of your RDS for Oracle DB instance](USER_Endpoint.md).
1. Enter a URL in your browser locator bar using the following format.
```
https://endpoint.rds.amazonaws.com:port/em
```
For example, if the endpoint for your Amazon RDS DB instance is `mydb.a1bcde234fgh.us-east-1.rds.amazonaws.com`, and your EM Express port is `1158`, then use the following URL to access EM Express.
```
1. https://mydb.f9rbfa893tft.us-east-1.rds.amazonaws.com:1158/em
```
1. When prompted for your login details, do one of the following actions, depending on your database architecture:
**Your database is a non-CDB.**
Type the master user name and master password for your DB instance.
**Your database is a CDB.**
Enter `DBSNMP` for the user and the `DBSNMP` password. Leave the `Container` field empty.
## Modifying OEM Database settings
After you enable OEM Database, you can modify the Security Groups setting for the option.
You can't modify the OEM port number after you have associated the option group with a DB instance. To change the OEM port number for a DB instance, do the following:
1. Create a new option group.
1. Add the OEM option with the new port number to the new option group.
1. Remove the existing option group from the DB instance.
1. Add the new option group to the DB instance.
For more information about how to modify option settings, see [Modifying an option setting](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.ModifyOption). For more information about each setting, see [OEM option settings](#Appendix.Oracle.Options.OEM_DBControl.Options).
## Running OEM Database Express tasks
You can use Amazon RDS procedures to run certain OEM Database Express tasks. By running these procedures, you can do the tasks listed following.
**Note**
OEM Database Express tasks run asynchronously.
**Topics**
+ [
### Switching the website front end for OEM Database Express to Adobe Flash
](#Appendix.Oracle.Options.OEM_DBControl.DBTasks.FrontEndToFlash)
+ [
### Switching the website front end for OEM Database Express to Oracle JET
](#Appendix.Oracle.Options.OEM_DBControl.DBTasks.FrontEndToOracleJET)
### Switching the website front end for OEM Database Express to Adobe Flash
**Note**
This task is available only for Oracle Database 19c non-CDBs.
Starting with Oracle Database 19c, Oracle has deprecated the former OEM Database Express user interface, which was based on Adobe Flash. Instead, OEM Database Express now uses an interface built with Oracle JET. If you experience difficulties with the new interface, you can switch back to the deprecated Flash-based interface. Difficulties you might experience with the new interface include being stuck on a `Loading` screen after logging in to OEM Database Express. You might also miss certain features that were present in the Flash-based version of OEM Database Express.
To switch the OEM Database Express website front end to Adobe Flash, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_tasks.em_express_frontend_to_flash`. This procedure is equivalent to the `execemx emx` SQL command.
Security best practices discourage the use of Adobe Flash. Although you can revert to the Flash-based OEM Database Express, we recommend the use of the JET-based OEM Database Express websites if possible. If you revert to using Adobe Flash and want to switch back to using Oracle JET, use the `rdsadmin.rdsadmin_oem_tasks.em_express_frontend_to_jet` procedure. After an Oracle database upgrade, a newer version of Oracle JET might resolve JET-related issues in OEM Database Express. For more information about switching to Oracle JET, see [Switching the website front end for OEM Database Express to Oracle JET](#Appendix.Oracle.Options.OEM_DBControl.DBTasks.FrontEndToOracleJET).
**Note**
Running this task from the source DB instance for a read replica also causes the read replica to switch its OEM Database Express website front ends to Adobe Flash.
The following procedure invocation creates a task to switch the OEM Database Express website to Adobe Flash and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_tasks.em_express_frontend_to_flash() as TASK_ID from DUAL;
```
You can view the result by displaying the task's output file.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Replace *`task-id`* with the task ID returned by the procedure. For more information about the Amazon RDS procedure `rdsadmin.rds_file_util.read_text_file`, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles)
You can also view the contents of the task's output file in the AWS Management Console by searching the log entries in the **Logs & events** section for the `task-id`.
### Switching the website front end for OEM Database Express to Oracle JET
**Note**
This task is available only for Oracle Database 19c non-CDBs.
To switch the OEM Database Express website front end to Oracle JET, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_tasks.em_express_frontend_to_jet`. This procedure is equivalent to the `execemx omx` SQL command.
By default, the OEM Database Express websites for Oracle DB instances running 19c or later use Oracle JET. If you used the `rdsadmin.rdsadmin_oem_tasks.em_express_frontend_to_flash` procedure to switch the OEM Database Express website front end to Adobe Flash, you can switch back to Oracle JET. To do this, use the `rdsadmin.rdsadmin_oem_tasks.em_express_frontend_to_jet` procedure. For more information about switching to Adobe Flash, see [Switching the website front end for OEM Database Express to Adobe Flash](#Appendix.Oracle.Options.OEM_DBControl.DBTasks.FrontEndToFlash).
**Note**
Running this task from the source DB instance for a read replica also causes the read replica to switch its OEM Database Express website front ends to Oracle JET.
The following procedure invocation creates a task to switch the OEM Database Express website to Oracle JET and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_tasks.em_express_frontend_to_jet() as TASK_ID from DUAL;
```
You can view the result by displaying the task's output file.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-task-id.log'));
```
Replace *`task-id`* with the task ID returned by the procedure. For more information about the Amazon RDS procedure `rdsadmin.rds_file_util.read_text_file`, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles)
You can also view the contents of the task's output file in the AWS Management Console by searching the log entries in the **Logs & events** section for the `task-id`.
## Removing the OEM Database option
You can remove the OEM option from a DB instance. When you remove the OEM option, a brief outage occurs while your instance is automatically restarted. Therefore, after you remove the OEM option, you don't need to restart your DB instance.
To remove the OEM option from a DB instance, do one of the following:
+ Remove the OEM option from the option group it belongs to. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ Modify the DB instance and specify a different option group that doesn't include the OEM option. This change affects a single DB instance. You can specify the default (empty) option group, or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle Management Agent for Enterprise Manager Cloud Control
Oracle Enterprise Manager (OEM) Management Agent is a software component that monitors targets running on hosts and communicates that information to the middle-tier Oracle Management Service (OMS). Amazon RDS supports Management Agent through the use of the `OEM_AGENT` option.
For more information, see [Overview of Oracle Enterprise Manager cloud control 12c](http://docs.oracle.com/cd/E24628_01/doc.121/e25353/overview.htm) and [Overview of Oracle Enterprise Manager cloud control 13c](http://docs.oracle.com/cd/E63000_01/EMCON/overview.htm#EMCON109) in the Oracle documentation.
**Topics**
+ [
## Requirements for Management Agent
](#Oracle.Options.OEMAgent.PreReqs)
+ [
## OMS host communication prerequisites
](#Oracle.Options.OEMAgent.PreReqs.host)
+ [
## Limitations for Management Agent
](#Oracle.Options.OEMAgent.limitations)
+ [
## Option settings for Management Agent
](#Oracle.Options.OEMAgent.Options)
+ [
## Enabling the Management Agent option for your DB instance
](#Oracle.Options.OEMAgent.Enable)
+ [
## Removing the Management Agent option
](#Oracle.Options.OEMAgent.Remove)
+ [
## Performing database tasks with the Management Agent
](#Oracle.Options.OEMAgent.DBTasks)
## Requirements for Management Agent
Following are general requirements for using Management Agent:
+ You can use either the CDB or non-CDB architecture.
+ You must use an Oracle Management Service (OMS) that is configured to connect to your DB instance. Note the following OMS requirements:
+ Management Agent version 24.1.0.0.v1 requires OMS version 24.1.
+ Management Agent versions 13.5.0.0.v2 and 13.5.0.0.v3 require OMS version 13.5.0.23 or 24.1.
+ Management Agent version 13.5.0.0.v1 requires OMS version 13.5.0.0 or 24.1.
+ Management Agent versions 13.4.0.9.v1 and 13.4.0.9.v2 require OMS version 13.4.0.9 or later and patch 32198287.
+ In most cases, you must configure your VPC to allow connections from OMS to your DB instance. If you aren't familiar with Amazon Virtual Private Cloud (Amazon VPC), we recommend that you complete the steps in [Tutorial: Create a VPC for use with a DB instance (IPv4 only)](CHAP_Tutorials.WebServerDB.CreateVPC.md) before continuing.
+ You can use Management Agent with Oracle Enterprise Manager Cloud Control for 12c and 13c. Ensure that you have sufficient storage space for your OEM release:
+ At least 8.5 GiB for OEM 24ai Release 1
+ At least 8.5 GiB for OEM 13c Release 5
+ At least 8.5 GiB for OEM 13c Release 4
+ At least 8.5 GiB for OEM 13c Release 3
+ At least 5.5 GiB for OEM 13c Release 2
+ At least 4.5 GiB for OEM 13c Release 1
+ At least 2.5 GiB for OEM 12c
+ If you're using Management Agent versions `OEM_AGENT 13.2.0.0.v3` and `13.3.0.0.v2`, and if you want to use TCPS connectivity, follow the instructions in [Configuring third party CA certificates for communication with target databases](https://docs.oracle.com/cd/E73210_01/EMSEC/GUID-8337AD48-1A32-4CD5-84F3-256FAE93D043.htm#EMSEC15996) in the Oracle documentation. Also, update the JDK on your OMS by following the instructions in the Oracle document with the Oracle Doc ID 2241358.1. This step ensures that OMS supports all the cipher suites that the database supports.
**Note**
TCPS connectivity between the Management Agent and the DB instance is supported for Management Agent `OEM_AGENT 13.2.0.0.v3`, `13.3.0.0.v2`, `13.4.0.9.v1`, and higher versions.
## OMS host communication prerequisites
Make sure that your OMS host and your Amazon RDS DB instance can communicate. Do the following:
+ To connect from the Management Agent to your OMS host when your OMS host is behind a firewall, add the IP addresses of your DB instances to the firewall. Make sure the firewall for the OMS allows the following network traffic:
From the OMS host to your DB instance
Configure a one-way firewall rule that allows traffic from the OMS host to the database listener port (default 1521) and the OEM Agent port (default 3872).
From your DB instance to the OMS host
Configure a one-way firewall rule that allows traffic from the DB instance to the OMS HTTP port (default 4903).
+ To connect from your OMS to the Management Agent, if your OMS has a publicly resolvable host name, add the OMS address to a security group. Your security group must have inbound rules that allow access to the DB listener port and the Management Agent port. For an example of creating a security and adding inbound rules, see [Tutorial: Create a VPC for use with a DB instance (IPv4 only)](CHAP_Tutorials.WebServerDB.CreateVPC.md).
+ To connect from your OMS to the Management Agent, if your OMS doesn't have a publicly resolvable host name, use one of the following:
+ If your OMS is hosted on an Amazon Elastic Compute Cloud (Amazon EC2) instance in a private VPC, you can set up VPC peering to connect from OMS to Management Agent. For more information, see [A DB instance in a VPC accessed by an EC2 instance in a different VPC](USER_VPC.Scenarios.md#USER_VPC.Scenario3).
+ If your OMS is hosted on-premises, you can set up a VPN connection to allow access from OMS to Management Agent. For more information, see [A DB instance in a VPC accessed by a client application through the internet](USER_VPC.Scenarios.md#USER_VPC.Scenario4) or [VPN connections](https://docs.aws.amazon.com/vpc/latest/userguide/vpn-connections.html).
+ To connect OEM Management Agent version 13.5.0.0 (v1-v3) or 24.1.0.0.v1 to a 24.1 OMS host, set `MINIMUM_TLS_VERSION` to use the TLS 1.2 protocol `TLSv1.2` in your configuration options.
## Limitations for Management Agent
Following are some limitations to using Management Agent:
+ You can't provide custom Oracle Management Agent images.
+ Administrative tasks such as job execution and database patching, that require host credentials, aren't supported.
+ Host metrics and the process list aren't guaranteed to reflect the actual system state. Thus, you shouldn't use OEM to monitor the root file system or mount point file system. For more information about monitoring the operating system, see [Monitoring OS metrics with Enhanced Monitoring](USER_Monitoring.OS.md).
+ Autodiscovery isn't supported. You must manually add database targets.
+ OMS module availability depends on your database edition. For example, the database performance diagnosis and tuning module is only available for Oracle Database Enterprise Edition.
+ Management Agent consumes additional memory and computing resources. If you experience performance problems after enabling the `OEM_AGENT` option, we recommend that you scale up to a larger DB instance class. For more information, see [DB instance classes](Concepts.DBInstanceClass.md) and [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
+ The user running the `OEM_AGENT` on the Amazon RDS host doesn't have operating system access to the alert log. Thus, you can't collect metrics for `DB Alert Log` and `DB Alert Log Error Status` in OEM.
## Option settings for Management Agent
Amazon RDS supports the following settings for the Management Agent option.
| Option setting | Required | Valid values | Description |
| --- | --- | --- | --- |
| **Version** (`AGENT_VERSION`) | Yes | `24.1.0.0.v1` `13.5.0.0.v3` `13.5.0.0.v2` `13.5.0.0.v1` `13.4.0.9.v2` `13.4.0.9.v1` `13.3.0.0.v2` `13.3.0.0.v1` `13.2.0.0.v3` `13.2.0.0.v2` `13.2.0.0.v1` `13.1.0.0.v1` | The version of the Management Agent software. The minimum supported version is `13.1.0.0.v1`. The AWS CLI option name is `OptionVersion`. In the AWS GovCloud (US) Regions, 13.1 versions aren't available. |
| **Port** (`AGENT_PORT`) | Yes | An integer value | The port on the DB instance that listens for the OMS host. The default is 3872. Your OMS host must belong to a security group that has access to this port. The AWS CLI option name is `Port`. |
| **Security Groups** | Yes | Existing security groups | A security group that has access to **Port**. Your OMS host must belong to this security group. The AWS CLI option name is `VpcSecurityGroupMemberships` or `DBSecurityGroupMemberships`. |
| **OMS\$1HOST** | Yes | A string value, for example *my.example.oms* | The publicly accessible host name or IP address of the OMS. The AWS CLI option name is `OMS_HOST`. |
| **OMS\$1PORT** | Yes | An integer value | The HTTPS upload port on the OMS Host that listens for the Management Agent. To determine the HTTPS upload port, connect to the OMS host, and run the following command (which requires the `SYSMAN` password): emctl status oms -details The AWS CLI option name is `OMS_PORT`. |
| **AGENT\$1REGISTRATION\$1PASSWORD** | Yes | A string value | The password that the Management Agent uses to authenticate itself with the OMS. We recommend that you create a persistent password in your OMS before enabling the `OEM_AGENT` option. With a persistent password you can share a single Management Agent option group among multiple Amazon RDS databases. The AWS CLI option name is `AGENT_REGISTRATION_PASSWORD`. |
| **ALLOW\$1TLS\$1ONLY** | No | `true`, `false` (default) | A value that configures the OEM Agent to support only the `TLSv1` protocol while the agent listens as a server. This setting is no longer supported. Management Agent versions 13.1.0.0.v1 and higher support Transport Layer Security (TLS) by default. |
| **MINIMUM\$1TLS\$1VERSION** | No | `TLSv1` (default), `TLSv1.2` | A value that specifies the minimum TLS version supported by the OEM Agent while the agent listens as a server. Desupported agent versions only support the `TLSv1` setting. To connect 13.5.0.0 (v1-v3) or 24.1.0.0.v1 to a 24.1 OMS host, set this to `TLSv1.2`. |
| **TLS\$1CIPHER\$1SUITE** | No | See [Option settings for Management Agent](#Oracle.Options.OEMAgent.Options). | A value that specifies the TLS cipher suite used by the OEM Agent while the agent listens as a server. |
The following table lists the TLS cipher suites that the Management Agent option supports.
| Cipher suite | Agent version supported | FedRAMP compliant |
| --- | --- | --- |
| TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | All | No |
| TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | 13.1.0.0.v1 and higher | No |
| TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | 13.2.0.0.v3 and higher | No |
| TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 | 13.2.0.0.v3 and higher | No |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | 13.2.0.0.v3 and higher | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | 13.2.0.0.v3 and higher | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | 13.2.0.0.v3 and higher | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | 13.2.0.0.v3 and higher | Yes |
| TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | 13.4.0.9.v1 and higher | Yes |
| TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | 13.4.0.9.v1 and higher | Yes |
### Certificate compatibility with cipher suites
RDS for Oracle supports both RSA and Elliptic Curve Digital Signature Algorithm (ECDSA) certificates. When you configure the OEM Agent option for your DB instance, you must ensure that the cipher suites you specify in the `TLS_CIPHER_SUITE` option setting are compatible with the certificate type used by your DB instance.
The following table shows the compatibility between certificate types and cipher suites:
| Certificate type | Compatible cipher suites | Incompatible cipher suites |
| --- | --- | --- |
| RSA certificates (rds-ca-2019, rds-ca-rsa2048-g1, rds-ca-rsa4096-g1) | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 |
| ECDSA certificates (rds-ca-ecc384-g1) | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 |
When you specify a cipher suite in the `TLS_CIPHER_SUITE` option setting, make sure it is compatible with the certificate type used by your DB instance. If you attempt to associate an option group with an OEM Agent option that contains a cipher suite incompatible with the certificate type of a DB instance, the operation will fail with an error message indicating the incompatibility.
## Enabling the Management Agent option for your DB instance
To enable the Management Agent option, use the following steps:
**Topics**
+ [
### Step 1: Adding the Management Agent option to your DB instance
](#Oracle.Options.OEMAgent.Add)
+ [
### Step 2: Unlocking the DBSNMP user account
](#Oracle.Options.OEMAgent.DBSNMP)
+ [
### Step 3: Adding your targets to the Management Agent console
](#Oracle.Options.OEMAgent.Using)
### Step 1: Adding the Management Agent option to your DB instance
To add the Management Agent option to your DB instance, do the following:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with the DB instance.
If you encounter errors, check [My Oracle Support](https://support.oracle.com/) documents for information about resolving specific problems.
After you add the Management Agent option, you don't need to restart your DB instance. As soon as the option group is active, the OEM Agent is active.
If your OMS host is using an untrusted third-party certificate, Amazon RDS returns the following error.
```
You successfully installed the OEM_AGENT option. Your OMS host is using an untrusted third party certificate.
Configure your OMS host with the trusted certificates from your third party.
```
If this error is returned, the Management Agent option isn't enabled until the problem is corrected. For information about correcting the problem, see the My Oracle Support document [2202569.1](https://support.oracle.com/epmos/faces/DocContentDisplay?id=2202569.1).
#### Console
**To add the Management Agent option to your DB instance**
1. Determine the option group you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine** choose the oracle edition for your DB instance.
1. For **Major engine version** choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **OEM\$1AGENT** option to the option group, and configure the option settings. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption). For more information about each setting, see [Option settings for Management Agent](#Oracle.Options.OEMAgent.Options).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
#### AWS CLI
The following example uses the AWS CLI [add-option-to-option-group](https://docs.aws.amazon.com/cli/latest/reference/rds/add-option-to-option-group.html) command to add the `OEM_AGENT` option to an option group called `myoptiongroup`.
For Linux, macOS, or Unix:
```
aws rds add-option-to-option-group \
--option-group-name "myoptiongroup" \
--options OptionName=OEM_AGENT,OptionVersion=13.1.0.0.v1,Port=3872,VpcSecurityGroupMemberships=sg-1234567890,OptionSettings=[{Name=OMS_HOST,Value=my.example.oms},{Name=OMS_PORT,Value=4903},{Name=AGENT_REGISTRATION_PASSWORD,Value=password}] \
--apply-immediately
```
For Windows:
```
aws rds add-option-to-option-group ^
--option-group-name "myoptiongroup" ^
--options OptionName=OEM_AGENT,OptionVersion=13.1.0.0.v1,Port=3872,VpcSecurityGroupMemberships=sg-1234567890,OptionSettings=[{Name=OMS_HOST,Value=my.example.oms},{Name=OMS_PORT,Value=4903},{Name=AGENT_REGISTRATION_PASSWORD,Value=password}] ^
--apply-immediately
```
### Step 2: Unlocking the DBSNMP user account
The Management Agent uses the `DBSNMP` user account to connect to the database and report issues to Oracle Enterprise Manager. In a CDB, `DBSNMP` is a common user. This user account is necessary for both the Management Agent and OEM Database Express. By default, this account is locked. The procedure for unlocking this account differs depending on whether your database uses the non-CDB or CDB architecture.
**To unlock the DBSNMP user account**
1. In SQL\$1Plus or another Oracle SQL application, log in to your DB instance as your master user.
1. Do either of the following actions, depending on the database architecture:
**Your database is a non-CDB.**
Run the following SQL statement:
```
1. ALTER USER dbsnmp IDENTIFIED BY new_password ACCOUNT UNLOCK;
```
**Your database is a CDB.**
Run the following stored procedure to unlock the `DBSNMP` account:
```
1. EXEC rdsadmin.rdsadmin_util.reset_oem_agent_password('new_password');
```
If you receive an error stating that the procedure doesn't exist, reboot your CDB instance to install it automatically. For more information, see [Rebooting a DB instance](USER_RebootInstance.md).
### Step 3: Adding your targets to the Management Agent console
To add a DB instance as a target, make sure you know the endpoint and port. For information about finding the endpoint for your Amazon RDS DB instance, see [Finding the endpoint of your RDS for Oracle DB instance](USER_Endpoint.md). If your database uses the CDB architecture, then add the `CDB$ROOT` container separately as a target.
**To add targets to the Management Agent console**
1. In your OMS console, choose **Setup**, **Add Target**, **Add Targets Manually**.
1. Choose **Add Targets Declaratively by Specifying Target Monitoring Properties**.
1. For **Target Type**, choose **Database Instance**.
1. For **Monitoring Agent**, choose the agent with the identifier that is the same as your RDS DB instance identifier.
1. Choose **Add Manually**.
1. Enter the endpoint for your Amazon RDS DB instance, or choose it from the host name list. Make sure that the specified host name matches the endpoint of the Amazon RDS DB instance.
1. Specify the following database properties:
+ For **Target name**, enter a name.
+ For **Database system name**, enter a name.
+ For **Monitor username**, enter **dbsnmp**.
+ For **Monitor password**, enter the password from [Step 2: Unlocking the DBSNMP user account](#Oracle.Options.OEMAgent.DBSNMP).
+ For **Role**, enter **normal**.
+ For **Oracle home path**, enter **/oracle**.
+ For **Listener Machine name**, the agent identifier already appears.
+ For **Port**, enter the database port. The RDS default port is 1521.
+ For **Database name**, enter the name of your database. If your database is a CDB, this name is `RDSCDB`.
1. Choose **Test Connection**.
1. Choose **Next**. The target database appears in your list of monitored resources.
## Removing the Management Agent option
You can remove the OEM Agent from a DB instance. After you remove the OEM Agent, you don't need to restart your DB instance.
To remove the OEM Agent from a DB instance, do one of the following:
+ Remove the OEM Agent option from the option group it belongs to. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ Modify the DB instance and specify a different option group that doesn't include the OEM Agent option. This change affects a single DB instance. You can specify the default (empty) option group, or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Performing database tasks with the Management Agent
You can use Amazon RDS procedures to run certain EMCTL commands on the Management Agent. By running these procedures, you can do the tasks listed following.
**Note**
Tasks are executed asynchronously.
**Topics**
+ [
### Securing the Management Agent
](#Oracle.Options.OEMAgent.DBTasks.SecureAgent)
+ [
### Getting the status of the Management Agent
](#Oracle.Options.OEMAgent.DBTasks.GetAgentStatus)
+ [
### Restarting the Management Agent
](#Oracle.Options.OEMAgent.DBTasks.RestartAgent)
+ [
### Listing the targets monitored by the Management Agent
](#Oracle.Options.OEMAgent.DBTasks.ListTargets)
+ [
### Listing the collection threads monitored by the Management Agent
](#Oracle.Options.OEMAgent.DBTasks.ListCollectionThreads)
+ [
### Clearing the Management Agent state
](#Oracle.Options.OEMAgent.DBTasks.ClearState)
+ [
### Making the Management Agent upload its OMS
](#Oracle.Options.OEMAgent.DBTasks.ForceUploadOMS)
+ [
### Pinging the OMS
](#Oracle.Options.OEMAgent.DBTasks.PingOMS)
+ [
### Viewing the status of an ongoing task
](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus)
### Securing the Management Agent
To secure the Management Agent, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.secure_oem_agent`. This procedure is equivalent to running the `emctl secure agent` command.
The following procedure creates a task to secure the Management Agent and returns the ID of the task:
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.secure_oem_agent as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Getting the status of the Management Agent
To get the status of the Management Agent, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.get_status_oem_agent`. This procedure is equivalent to the `emctl status agent` command.
The following procedure creates a task to get the Management Agent's status and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.get_status_oem_agent() as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Restarting the Management Agent
To restart the Management Agent, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.restart_oem_agent`. This procedure is equivalent to running the `emctl stop agent` and `emctl start agent` commands.
The following procedure creates a task to restart the Management Agent and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.restart_oem_agent as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Listing the targets monitored by the Management Agent
To list the targets monitored by the Management Agent, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.list_targets_oem_agent`. This procedure is equivalent to running the `emctl config agent listtargets` command.
The following procedure creates a task to list the targets monitored by the Management Agent and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.list_targets_oem_agent as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Listing the collection threads monitored by the Management Agent
To list of all the running, ready, and scheduled collection threads monitored by the Management Agent, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.list_clxn_threads_oem_agent`. This procedure is equivalent to the `emctl status agent scheduler` command.
The following procedure creates a task to list the collection threads and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.list_clxn_threads_oem_agent() as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Clearing the Management Agent state
To clear the Management Agent's state, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.clearstate_oem_agent`. This procedure is equivalent to running the `emctl clearstate agent` command.
The following procedure creates a task that clears the Management Agent's state and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.clearstate_oem_agent() as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Making the Management Agent upload its OMS
To make the Management Agent upload the Oracle Management Server (OMS) associated with it, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.upload_oem_agent`. This procedure is equivalent to running the `emclt upload agent` command.
The following procedure creates a task that makes the Management Agent upload its associated OMS and return the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.upload_oem_agent() as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Pinging the OMS
To ping the Management Agent's OMS, run the Amazon RDS procedure `rdsadmin.rdsadmin_oem_agent_tasks.ping_oms_oem_agent`. This procedure is equivalent to running the `emctl pingOMS` command.
The following procedure creates a task that pings the Management Agent's OMS and returns the ID of the task.
```
SELECT rdsadmin.rdsadmin_oem_agent_tasks.ping_oms_oem_agent() as TASK_ID from DUAL;
```
To display the output file for the task and view the result, see [Viewing the status of an ongoing task](#Oracle.Options.OEMAgent.DBTasks.ViewTaskStatus).
### Viewing the status of an ongoing task
You can view the status of an ongoing task in a bdump file. The bdump files are located in the `/rdsdbdata/log/trace` directory. Each bdump file name is in the following format.
```
dbtask-task-id.log
```
When you want to monitor a task, replace `task-id` with the ID of the task that you want to monitor.
To view the contents of bdump files, run the Amazon RDS procedure `rdsadmin.rds_file_util.read_text_file`. The following query returns the contents of the `dbtask-1546988886389-2444.log` bdump file.
```
SELECT text FROM table(rdsadmin.rds_file_util.read_text_file('BDUMP','dbtask-1546988886389-2444.log'));
```
For more information about the Amazon RDS procedure `rdsadmin.rds_file_util.read_text_file`, see [Reading files in a DB instance directory](Appendix.Oracle.CommonDBATasks.Misc.md#Appendix.Oracle.CommonDBATasks.ReadingFiles).
# Oracle Label Security
Amazon RDS supports Oracle Label Security for the Enterprise Edition of Oracle Database through the use of the OLS option.
Most database security controls access at the object level. Oracle Label Security provides fine-grained control of access to individual table rows. For example, you can use Label Security to enforce regulatory compliance with a policy-based administration model. You can use Label Security policies to control access to sensitive data, and restrict access to only users with the appropriate clearance level. For more information, see [Introduction to Oracle Label Security](https://docs.oracle.com/database/121/OLSAG/intro.htm#OLSAG001) in the Oracle documentation.
**Topics**
+ [
## Requirements for Oracle Label Security
](#Oracle.Options.OLS.PreReqs)
+ [
## Considerations when using Oracle Label Security
](#Oracle.Options.OLS.Using)
+ [
## Adding the Oracle Label Security option
](#Oracle.Options.OLS.Add)
+ [
## Troubleshooting
](#Oracle.Options.OLS.Troubleshooting)
## Requirements for Oracle Label Security
Familiarize yourself with the following requirements for Oracle Label Security:
+ Your DB instance must use the Bring Your Own License model. For more information, see [RDS for Oracle licensing options](Oracle.Concepts.Licensing.md).
+ You must have a valid license for Oracle Enterprise Edition with Software Update License and Support.
+ Your Oracle license must include the Label Security option.
## Considerations when using Oracle Label Security
To use Oracle Label Security, you create policies that control access to specific rows in your tables. For more information, see [Creating an Oracle Label Security policy](https://docs.oracle.com/database/121/OLSAG/getstrtd.htm#OLSAG3096) in the Oracle documentation.
Consider the following:
+ Oracle Label Security is a permanent and persistent option. Because the option is permanent, you can't remove it from an option group. If you add Oracle Label Security to an option group and associate it with your DB instance, you can later associate a different option group with your DB instance, but this group must also contain the Oracle Label Security option.
+ When you work with Label Security, you perform all actions as the `LBAC_DBA` role. The master user for your DB instance is granted the `LBAC_DBA` role. You can grant the `LBAC_DBA` role to other users so that they can administer Label Security policies.
+ Make sure to grant access to the `OLS_ENFORCEMENT` package to any new users who require access to Oracle Label Security. To grant access to the `OLS_ENFORCEMENT` package, connect to the DB instance as the master user and run the following SQL statement:
```
GRANT ALL ON LBACSYS.OLS_ENFORCEMENT TO username;
```
+ You can configure Label Security through Oracle Enterprise Manager (OEM) Cloud Control. Amazon RDS supports OEM Cloud Control through the Management Agent option. For more information, see [Oracle Management Agent for Enterprise Manager Cloud Control](Oracle.Options.OEMAgent.md).
## Adding the Oracle Label Security option
The general process for adding the Oracle Label Security option to a DB instance is the following:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
**Important**
Oracle Label Security is a permanent and persistent option.
1. Associate the option group with the DB instance.
After you add the Label Security option, as soon as the option group is active, Label Security is active.
**To add the label security option to a DB instance**
1. Determine the option group you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine**, choose **oracle-ee**.
1. For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **OLS** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
**Important**
If you add Label Security to an existing option group that is already attached to one or more DB instances, all the DB instances are restarted.
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. When you add the Label Security option to an existing DB instance, a brief outage occurs while your DB instance is automatically restarted. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Troubleshooting
The following are issues you might encounter when you use Oracle Label Security.
****
| Issue | Troubleshooting suggestions |
| --- | --- |
| When you try to create a policy, you see an error message similar to the following: `insufficient authorization for the SYSDBA package`. | A known issue with Oracle's Label Security feature prevents users with usernames of 16 or 24 characters from running Label Security commands. You can create a new user with a different number of characters, grant LBAC\$1DBA to the new user, log in as the new user, and run the OLS commands as the new user. For additional information, contact Oracle Support. |
# Oracle Locator
Amazon RDS supports Oracle Locator through the use of the `LOCATOR` option. Oracle Locator provides capabilities that are typically required to support internet and wireless service-based applications and partner-based GIS solutions. Oracle Locator is a limited subset of Oracle Spatial. For more information, see [Oracle Locator](https://docs.oracle.com/database/121/SPATL/sdo_locator.htm#SPATL340) in the Oracle documentation.
**Important**
If you use Oracle Locator, Amazon RDS automatically updates your DB instance to the latest Oracle PSU if there are security vulnerabilities with a Common Vulnerability Scoring System (CVSS) score of 9\$1 or other announced security vulnerabilities.
## Supported database releases for Oracle Locator
RDS for Oracle supports Oracle Locator for Oracle Database 19c. Oracle Locator isn't supported for Oracle Database 21c, but its functionality is available in the Oracle Spatial option. Formerly, the Spatial option required additional licenses. Oracle Locator represented a subset of Oracle Spatial features and didn't require additional licenses. In 2019, Oracle announced that all Oracle Spatial features were included in the Enterprise Edition and Standard Edition 2 licenses without additional cost. Consequently, the Oracle Spatial option no longer required additional licensing. For more information, see [Machine Learning, Spatial and Graph - No License Required\$1](https://blogs.oracle.com/database/post/machine-learning-spatial-and-graph-no-license-required) in the Oracle Database Insider blog.
## Prerequisites for Oracle Locator
The following are prerequisites for using Oracle Locator:
+ Your DB instance must be of sufficient class. Oracle Locator is not supported for the db.t3.small DB instance classes. For more information, see [RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md).
+ Your DB instance must have **Auto Minor Version Upgrade** enabled. This option enables your DB instance to receive minor DB engine version upgrades automatically when they become available and is required for any options that install the Oracle Java Virtual Machine (JVM). Amazon RDS uses this option to update your DB instance to the latest Oracle Patch Set Update (PSU) or Release Update (RU). For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Best practices for Oracle Locator
The following are best practices for using Oracle Locator:
+ For maximum security, use the `LOCATOR` option with Secure Sockets Layer (SSL). For more information, see [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md).
+ Configure your DB instance to restrict access to your DB instance. For more information, see [Scenarios for accessing a DB instance in a VPC](USER_VPC.Scenarios.md) and [Working with a DB instance in a VPC](USER_VPC.WorkingWithRDSInstanceinaVPC.md).
## Adding the Oracle Locator option
The following is the general process for adding the `LOCATOR` option to a DB instance:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with the DB instance.
If Oracle Java Virtual Machine (JVM) is *not* installed on the DB instance, there is a brief outage while the `LOCATOR` option is added. There is no outage if Oracle Java Virtual Machine (JVM) is already installed on the DB instance. After you add the option, you don't need to restart your DB instance. As soon as the option group is active, Oracle Locator is available.
**Note**
During this outage, password verification functions are disabled briefly. You can also expect to see events related to password verification functions during the outage. Password verification functions are enabled again before the Oracle DB instance is available.
**To add the `LOCATOR` option to a DB instance**
1. Determine the option group that you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine**, choose the oracle edition for your DB instance.
1. For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **LOCATOR** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Using Oracle Locator
After you enable the Oracle Locator option, you can begin using it. You should only use Oracle Locator features. Don't use any Oracle Spatial features unless you have a license for Oracle Spatial.
For a list of features that are supported for Oracle Locator, see [Features Included with Locator](https://docs.oracle.com/database/121/SPATL/sdo_locator.htm#GUID-EC6DEA23-8FD7-4109-A0C1-93C0CE3D6FF2__CFACCEEG) in the Oracle documentation.
For a list of features that are not supported for Oracle Locator, see [Features Not Included with Locator](https://docs.oracle.com/database/121/SPATL/sdo_locator.htm#GUID-EC6DEA23-8FD7-4109-A0C1-93C0CE3D6FF2__CFABACEA) in the Oracle documentation.
## Removing the Oracle Locator option
After you drop all objects that use data types provided by the `LOCATOR` option, you can remove the option from a DB instance. If Oracle Java Virtual Machine (JVM) is *not* installed on the DB instance, there is a brief outage while the `LOCATOR` option is removed. There is no outage if Oracle Java Virtual Machine (JVM) is already installed on the DB instance. After you remove the `LOCATOR` option, you don't need to restart your DB instance.
**To drop the `LOCATOR` option**
1. Back up your data.
**Warning**
If the instance uses data types that were enabled as part of the option, and if you remove the `LOCATOR` option, you can lose data. For more information, see [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md).
1. Check whether any existing objects reference data types or features of the `LOCATOR` option.
If `LOCATOR` options exist, the instance can get stuck when applying the new option group that doesn't have the `LOCATOR` option. You can identify the objects by using the following queries:
```
SELECT OWNER, SEGMENT_NAME, TABLESPACE_NAME, BYTES/1024/1024 mbytes
FROM DBA_SEGMENTS
WHERE SEGMENT_TYPE LIKE '%TABLE%'
AND (OWNER, SEGMENT_NAME) IN
(SELECT DISTINCT OWNER, TABLE_NAME
FROM DBA_TAB_COLUMNS
WHERE DATA_TYPE='SDO_GEOMETRY'
AND OWNER <> 'MDSYS')
ORDER BY 1,2,3,4;
SELECT OWNER, TABLE_NAME, COLUMN_NAME
FROM DBA_TAB_COLUMNS
WHERE DATA_TYPE = 'SDO_GEOMETRY'
AND OWNER <> 'MDSYS'
ORDER BY 1,2,3;
```
1. Drop any objects that reference data types or features of the `LOCATOR` option.
1. Do one of the following:
+ Remove the `LOCATOR` option from the option group it belongs to. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ Modify the DB instance and specify a different option group that doesn't include the `LOCATOR` option. This change affects a single DB instance. You can specify the default (empty) option group, or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle native network encryption
Amazon RDS supports Oracle native network encryption (NNE). With the `NATIVE_NETWORK_ENCRYPTION` option, you can encrypt data as it moves to and from a DB instance. Amazon RDS supports NNE for all editions of Oracle Database.
A detailed discussion of Oracle native network encryption is beyond the scope of this guide, but you should understand the strengths and weaknesses of each algorithm and key before you decide on a solution for your deployment. For information about the algorithms and keys that are available through Oracle native network encryption, see [Configuring network data encryption](http://www.oracle.com/webfolder/technetwork/tutorials/obe/db/11g/r2/prod/security/network_encrypt/ntwrkencrypt.htm) in the Oracle documentation. For more information about AWS security, see the [AWS security center](http://aws.amazon.com/security).
**Note**
You can use Native Network Encryption or Secure Sockets Layer, but not both. For more information, see [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md).
**Topics**
+ [
# NATIVE\$1NETWORK\$1ENCRYPTION option settings
](Oracle.Options.NNE.Options.md)
+ [
# Adding the NATIVE\$1NETWORK\$1ENCRYPTION option
](Oracle.Options.NNE.Add.md)
+ [
# Setting NNE values in the sqlnet.ora
](Oracle.Options.NNE.Using.md)
+ [
# Modifying NATIVE\$1NETWORK\$1ENCRYPTION option settings
](Oracle.Options.NNE.ModifySettings.md)
+ [
# Removing the NATIVE\$1NETWORK\$1ENCRYPTION option
](Oracle.Options.NNE.Remove.md)
# NATIVE\$1NETWORK\$1ENCRYPTION option settings
You can specify encryption requirements on both the server and the client. The DB instance can act as a client when, for example, it uses a database link to connect to another database. You might want to avoid forcing encryption on the server side. For example, you might not want to force all client communications to use encryption because the server requires it. In this case, you can force encryption on the client side using the `SQLNET.*CLIENT` options.
Amazon RDS supports the following settings for the `NATIVE_NETWORK_ENCRYPTION` option.
**Note**
When you use commas to separate values for an option setting, don't put a space after the comma.
****
| Option setting | Valid values | Default values | Description |
| --- | --- | --- | --- |
| `SQLNET.ALLOW_WEAK_CRYPTO_CLIENTS` | `TRUE`, `FALSE` | `TRUE` | The behavior of the server when a client using a non-secure cipher attempts to connect to the database. If `TRUE`, clients can connect even if they aren't patched with the July 2021 PSU. If the setting is `FALSE`, clients can connect to the database only when they are patched with the July 2021 PSU. Before you set `SQLNET.ALLOW_WEAK_CRYPTO_CLIENTS` to `FALSE`, make sure that the following conditions are met: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Oracle.Options.NNE.Options.html) |
| `SQLNET.ALLOW_WEAK_CRYPTO` | `TRUE`, `FALSE` | `TRUE` | The behavior of the server when a client using a non-secure cipher attempts to connect to the database. The following ciphers are considered not secure: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Oracle.Options.NNE.Options.html) If the setting is `TRUE`, clients can connect when they use the preceding non-secure ciphers. If the setting is `FALSE`, the database prevents clients from connecting when they use the preceding non-secure ciphers. Before you set `SQLNET.ALLOW_WEAK_CRYPTO` to `FALSE`, make sure that the following conditions are met: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Oracle.Options.NNE.Options.html) |
| `SQLNET.CRYPTO_CHECKSUM_CLIENT` | `Accepted`, `Rejected`, `Requested`, `Required` | `Requested` | The data integrity behavior when a DB instance connects to the client, or a server acting as a client. When a DB instance uses a database link, it acts as a client. `Requested` indicates that the client doesn't require the DB instance to perform a checksum. |
| `SQLNET.CRYPTO_CHECKSUM_SERVER` | `Accepted`, `Rejected`, `Requested`, `Required` | `Requested` | The data integrity behavior when a client, or a server acting as a client, connects to the DB instance. When a DB instance uses a database link, it acts as a client. `Requested` indicates that the DB instance doesn't require the client to perform a checksum. |
| `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT` | `SHA256`, `SHA384`, `SHA512`, `SHA1`, `MD5` | `SHA256`, `SHA384`, `SHA512` | A list of checksum algorithms. You can specify either one value or a comma-separated list of values. If you use a comma, don't insert a space after the comma; otherwise, you receive an `InvalidParameterValue` error. This parameter and `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER `must have a common cipher. |
| `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER` | `SHA256`, `SHA384`, `SHA512`, `SHA1`, `MD5` | `SHA256`, `SHA384`, `SHA512`, `SHA1`, `MD5` | A list of checksum algorithms. You can specify either one value or a comma-separated list of values. If you use a comma, don't insert a space after the comma; otherwise, you receive an `InvalidParameterValue` error. This parameter and `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT` must have a common cipher. |
| `SQLNET.ENCRYPTION_CLIENT` | `Accepted`, `Rejected`, `Requested`, `Required` | `Requested` | The encryption behavior of the client when a client, or a server acting as a client, connects to the DB instance. When a DB instance uses a database link, it acts as a client. `Requested` indicates that the client does not require traffic from the server to be encrypted. |
| `SQLNET.ENCRYPTION_SERVER` | `Accepted`, `Rejected`, `Requested`, `Required` | `Requested` | The encryption behavior of the server when a client, or a server acting as a client, connects to the DB instance. When a DB instance uses a database link, it acts as a client. `Requested` indicates that the DB instance does not require traffic from the client to be encrypted. |
| `SQLNET.ENCRYPTION_TYPES_CLIENT` | `RC4_256`, `AES256`, `AES192`, `3DES168`, `RC4_128`, `AES128`, `3DES112`, `RC4_56`, `DES`, `RC4_40`, `DES40` | `RC4_256`, `AES256`, `AES192`, `3DES168`, `RC4_128`, `AES128`, `3DES112`, `RC4_56`, `DES`, `RC4_40`, `DES40` | A list of encryption algorithms used by the client. The client attempts to decrypt the server input by trying each algorithm in order, proceeding until an algorithm succeeds or the end of the list is reached. Amazon RDS uses the following default list from Oracle. RDS starts with `RC4_256` and proceeds down the list in order. You can change the order or limit the algorithms that the DB instance will accept. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Oracle.Options.NNE.Options.html) You can specify either one value or a comma-separated list of values. If you a comma, don't insert a space after the comma; otherwise, you receive an `InvalidParameterValue` error. This parameter and `SQLNET.SQLNET.ENCRYPTION_TYPES_SERVER` must have a common cipher. |
| `SQLNET.ENCRYPTION_TYPES_SERVER` | `RC4_256`, `AES256`, `AES192`, `3DES168`, `RC4_128`, `AES128`, `3DES112`, `RC4_56`, `DES`, `RC4_40`, `DES40` | `RC4_256`, `AES256`, `AES192`, `3DES168`, `RC4_128`, `AES128`, `3DES112`, `RC4_56`, `DES`, `RC4_40`, `DES40` | A list of encryption algorithms used by the DB instance. The DB instance uses each algorithm, in order, to attempt to decrypt the client input until an algorithm succeeds or until the end of the list is reached. Amazon RDS uses the following default list from Oracle. You can change the order or limit the algorithms that the client will accept. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Oracle.Options.NNE.Options.html) You can specify either one value or a comma-separated list of values. If you a comma, don't insert a space after the comma; otherwise, you receive an `InvalidParameterValue` error. This parameter and `SQLNET.SQLNET.ENCRYPTION_TYPES_SERVER` must have a common cipher. |
# Adding the NATIVE\$1NETWORK\$1ENCRYPTION option
The general process for adding the `NATIVE_NETWORK_ENCRYPTION` option to a DB instance is the following:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with the DB instance.
When the option group is active, NNE is active.
**To add the NATIVE\$1NETWORK\$1ENCRYPTION option to a DB instance using the AWS Management Console**
1. For **Engine**, choose the Oracle edition that you want to use. NNE is supported on all editions.
1. For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **NATIVE\$1NETWORK\$1ENCRYPTION** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
**Note**
After you add the **NATIVE\$1NETWORK\$1ENCRYPTION** option, you don't need to restart your DB instances. As soon as the option group is active, NNE is active.
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. After you add the **NATIVE\$1NETWORK\$1ENCRYPTION** option, you don't need to restart your DB instance. As soon as the option group is active, NNE is active. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Setting NNE values in the sqlnet.ora
With Oracle native network encryption, you can set network encryption on the server side and client side. The client is the computer used to connect to the DB instance. You can specify the following client settings in the sqlnet.ora:
+ `SQLNET.ALLOW_WEAK_CRYPTO`
+ `SQLNET.ALLOW_WEAK_CRYPTO_CLIENTS`
+ `SQLNET.CRYPTO_CHECKSUM_CLIENT`
+ `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT`
+ `SQLNET.ENCRYPTION_CLIENT`
+ `SQLNET.ENCRYPTION_TYPES_CLIENT`
For information, see [Configuring network data encryption and integrity for Oracle servers and clients](http://docs.oracle.com/cd/E11882_01/network.112/e40393/asoconfg.htm) in the Oracle documentation.
Sometimes, the DB instance rejects a connection request from an application. For example, a rejection can occur when the encryption algorithms on the client and on the server don't match. To test Oracle native network encryption, add the following lines to the sqlnet.ora file on the client:
```
DIAG_ADR_ENABLED=off
TRACE_DIRECTORY_CLIENT=/tmp
TRACE_FILE_CLIENT=nettrace
TRACE_LEVEL_CLIENT=16
```
When a connection is attempted, the preceding lines generate a trace file on the client called `/tmp/nettrace*`. The trace file contains information about the connection. For more information about connection-related issues when you are using Oracle Native Network Encryption, see [About negotiating encryption and integrity](http://docs.oracle.com/cd/E11882_01/network.112/e40393/asoconfg.htm#autoId12) in the Oracle Database documentation.
# Modifying NATIVE\$1NETWORK\$1ENCRYPTION option settings
After you enable the `NATIVE_NETWORK_ENCRYPTION` option, you can modify its settings. Currently, you can modify `NATIVE_NETWORK_ENCRYPTION` option settings only with the AWS CLI or RDS API. You can't use the console. The following example modifies two settings in the option.
```
aws rds add-option-to-option-group \
--option-group-name my-option-group \
--options "OptionName=NATIVE_NETWORK_ENCRYPTION,OptionSettings=[{Name=SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER,Value=SHA256},{Name=SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER,Value=SHA256}]" \
--apply-immediately
```
To learn how to modify option settings using the CLI, see [AWS CLI](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.ModifyOption.CLI). For more information about each setting, see [NATIVE\$1NETWORK\$1ENCRYPTION option settings](Oracle.Options.NNE.Options.md).
**Topics**
+ [
## Modifying CRYPTO\$1CHECKSUM\$1\$1 values
](#Oracle.Options.NNE.ModifySettings.checksum)
+ [
## Modifying ALLOW\$1WEAK\$1CRYPTO\$1 settings
](#Oracle.Options.NNE.ModifySettings.encryption)
## Modifying CRYPTO\$1CHECKSUM\$1\$1 values
If you modify **NATIVE\$1NETWORK\$1ENCRYPTION** option settings, make sure that the following option settings have at least one common cipher:
+ `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER`
+ `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT`
The following example shows a scenario in which you modify `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER`. The configuration is valid because the `CRYPTO_CHECKSUM_TYPES_CLIENT` and `CRYPTO_CHECKSUM_TYPES_SERVER` both use `SHA256`.
| Option setting | Values before modification | Values after modification |
| --- | --- | --- |
| `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT` | `SHA256`, `SHA384`, `SHA512` | No change |
| `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER` | `SHA256`, `SHA384`, `SHA512`, `SHA1`, `MD5` | SHA1,MD5,SHA256 |
For another example, assume that you want to modify `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER` from its default setting to `SHA1,MD5`. In this case, make sure you set `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT` to `SHA1` or `MD5`. These algorithms aren't included in the default values for `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT`.
## Modifying ALLOW\$1WEAK\$1CRYPTO\$1 settings
To set the `SQLNET.ALLOW_WEAK_CRYPTO*` options from the default value to `FALSE`, make sure that the following conditions are met:
+ `SQLNET.ENCRYPTION_TYPES_SERVER` and `SQLNET.ENCRYPTION_TYPES_CLIENT` have one matching secure encryption method. A method is considered secure if it's not `DES`, `3DES`, or `RC4` (all key lengths).
+ `SQLNET.CHECKSUM_TYPES_SERVER` and `SQLNET.CHECKSUM_TYPES_CLIENT` have one matching secure checksumming method. A method is considered secure if it's not `MD5`.
+ The client is patched with the July 2021 PSU. If the client isn't patched, the client loses the connection and receives the `ORA-12269` error.
The following example shows sample NNE settings. Assume that you want to set `SQLNET.ENCRYPTION_TYPES_SERVER` and `SQLNET.ENCRYPTION_TYPES_CLIENT` to FALSE, thereby blocking non-secure connections. The checksum option settings meet the prerequisites because they both have `SHA256`. However, `SQLNET.ENCRYPTION_TYPES_CLIENT` and `SQLNET.ENCRYPTION_TYPES_SERVER` use the `DES`, `3DES`, and `RC4` encryption methods, which are non-secure. Therefore, to set the `SQLNET.ALLOW_WEAK_CRYPTO*` options to `FALSE`, first set `SQLNET.ENCRYPTION_TYPES_SERVER` and `SQLNET.ENCRYPTION_TYPES_CLIENT` to a secure encryption method such as `AES256`.
| Option setting | Values |
| --- | --- |
| `SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT` | `SHA256`, `SHA384`, `SHA512` |
| `SQLNET.CRYPTO_CHECKSUM_TYPES_SERVER` | SHA1,MD5,SHA256 |
| `SQLNET.ENCRYPTION_TYPES_CLIENT` | `RC4_256`, `3DES168`, `DES40` |
| `SQLNET.ENCRYPTION_TYPES_SERVER` | `RC4_256`, `3DES168`, `DES40` |
# Removing the NATIVE\$1NETWORK\$1ENCRYPTION option
You can remove NNE from a DB instance.
To remove the `NATIVE_NETWORK_ENCRYPTION` option from a DB instance, do one of the following:
+ To remove the option from multiple DB instances, remove the `NATIVE_NETWORK_ENCRYPTION` option from the option group they belong to. This change affects all DB instances that use the option group. After you remove the `NATIVE_NETWORK_ENCRYPTION` option, you don't need to restart your DB instances. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ To remove the option from a single DB instance, modify the DB instance and specify a different option group that doesn't include the `NATIVE_NETWORK_ENCRYPTION` option. You can specify the default (empty) option group, or a different custom option group. After you remove the `NATIVE_NETWORK_ENCRYPTION` option, you don't need to restart your DB instance. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle OLAP
Amazon RDS supports Oracle OLAP through the use of the `OLAP` option. This option provides On-line Analytical Processing (OLAP) for Oracle DB instances. You can use Oracle OLAP to analyze large amounts of data by creating dimensional objects and cubes in accordance with the OLAP standard. For more information, see [the Oracle documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/olaug/index.html).
**Important**
If you use Oracle OLAP, Amazon RDS automatically updates your DB instance to the latest Oracle PSU if there are security vulnerabilities with a Common Vulnerability Scoring System (CVSS) score of 9\$1 or other announced security vulnerabilities.
Amazon RDS supports Oracle OLAP for the Enterprise Edition of Oracle Database 19c and higher.
## Prerequisites for Oracle OLAP
The following are prerequisites for using Oracle OLAP:
+ You must have an Oracle OLAP license from Oracle. For more information, see [Licensing Information](https://docs.oracle.com/en/database/oracle/oracle-database/19/dblic/Licensing-Information.html#GUID-B6113390-9586-46D7-9008-DCC9EDA45AB4) in the Oracle documentation.
+ Your DB instance must be of a sufficient instance class. Oracle OLAP isn't supported for the db.t3.small DB instance classes. For more information, see [RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md).
+ Your DB instance must have **Auto Minor Version Upgrade** enabled. This option enables your DB instance to receive minor DB engine version upgrades automatically when they become available and is required for any options that install the Oracle Java Virtual Machine (JVM). Amazon RDS uses this option to update your DB instance to the latest Oracle Patch Set Update (PSU) or Release Update (RU). For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
+ Your DB instance must not have a user named `OLAPSYS`. If it does, the OLAP option installation fails.
## Best practices for Oracle OLAP
The following are best practices for using Oracle OLAP:
+ For maximum security, use the `OLAP` option with Secure Sockets Layer (SSL). For more information, see [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md).
+ Configure your DB instance to restrict access to your DB instance. For more information, see [Scenarios for accessing a DB instance in a VPC](USER_VPC.Scenarios.md) and [Working with a DB instance in a VPC](USER_VPC.WorkingWithRDSInstanceinaVPC.md).
## Adding the Oracle OLAP option
The following is the general process for adding the `OLAP` option to a DB instance:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with the DB instance.
If Oracle Java Virtual Machine (JVM) is *not* installed on the DB instance, there is a brief outage while the `OLAP` option is added. There is no outage if Oracle Java Virtual Machine (JVM) is already installed on the DB instance. After you add the option, you don't need to restart your DB instance. As soon as the option group is active, Oracle OLAP is available.
**To add the OLAP option to a DB instance**
1. Determine the option group that you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
+ For **Engine**, choose the Oracle edition for your DB instance.
+ For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **OLAP** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, apply the option group by modifying the instance and attaching the new option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Using Oracle OLAP
After you enable the Oracle OLAP option, you can begin using it. For a list of features that are supported for Oracle OLAP, see [the Oracle documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/olaug/overview.html#GUID-E2056FE4-C623-4D29-B7D8-C4762F941966).
## Removing the Oracle OLAP option
After you drop all objects that use data types provided by the `OLAP` option, you can remove the option from a DB instance. If Oracle Java Virtual Machine (JVM) is *not* installed on the DB instance, there is a brief outage while the `OLAP` option is removed. There is no outage if Oracle Java Virtual Machine (JVM) is already installed on the DB instance. After you remove the `OLAP` option, you don't need to restart your DB instance.
**To drop the `OLAP` option**
1. Back up your data.
**Warning**
If the instance uses data types that were enabled as part of the option, and if you remove the `OLAP` option, you can lose data. For more information, see [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md).
1. Check whether any existing objects reference data types or features of the `OLAP` option.
1. Drop any objects that reference data types or features of the `OLAP` option.
1. Do one of the following:
+ Remove the `OLAP` option from the option group it belongs to. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ Modify the DB instance and specify a different option group that doesn't include the `OLAP` option. This change affects a single DB instance. You can specify the default (empty) option group, or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle Secure Sockets Layer
To enable SSL encryption for an RDS for Oracle DB instance, add the Oracle SSL option to the option group associated with the DB instance. Amazon RDS uses a second port, as required by Oracle, for SSL connections. This approach allows both clear text and SSL-encrypted communication to occur at the same time between a DB instance and SQL\$1Plus. For example, you can use the port with clear text communication to communicate with other resources inside a VPC while using the port with SSL-encrypted communication to communicate with resources outside the VPC.
**Note**
You can use either SSL or Native Network Encryption (NNE) on the same RDS for Oracle DB instance, but not both. If you use SSL encryption, make sure to turn off any other connection encryption. For more information, see [Oracle native network encryption](Appendix.Oracle.Options.NetworkEncryption.md).
SSL/TLS and NNE are no longer part of Oracle Advanced Security. In RDS for Oracle, you can use SSL encryption with all licensed editions of the following database versions:
+ Oracle Database 21c (21.0.0)
+ Oracle Database 19c (19.0.0)
**Topics**
+ [
## TLS versions for the Oracle SSL option
](#Appendix.Oracle.Options.SSL.TLS)
+ [
## Cipher suites for the Oracle SSL option
](#Appendix.Oracle.Options.SSL.CipherSuites)
+ [
## FIPS support
](#Appendix.Oracle.Options.SSL.FIPS)
+ [
## Certificate compatibility with cipher suites
](#Appendix.Oracle.Options.SSL.CertificateCompatibility)
+ [
# Adding the SSL option
](Appendix.Oracle.Options.SSL.OptionGroup.md)
+ [
# Configuring SQL\$1Plus to use SSL with an RDS for Oracle DB instance
](Appendix.Oracle.Options.SSL.ClientConfiguration.md)
+ [
# Connecting to an RDS for Oracle DB instance using SSL
](Appendix.Oracle.Options.SSL.Connecting.md)
+ [
# Setting up an SSL connection over JDBC
](Appendix.Oracle.Options.SSL.JDBC.md)
+ [
# Enforcing a DN match with an SSL connection
](Appendix.Oracle.Options.SSL.DNMatch.md)
+ [
# Troubleshooting SSL connections
](Appendix.Oracle.Options.SSL.troubleshooting.md)
## TLS versions for the Oracle SSL option
Amazon RDS for Oracle supports Transport Layer Security (TLS) versions 1.0 and 1.2. When you add a new Oracle SSL option, set `SQLNET.SSL_VERSION` explicitly to a valid value. The following values are allowed for this option setting:
+ `"1.0"` – Clients can connect to the DB instance using TLS version 1.0 only. For existing Oracle SSL options, `SQLNET.SSL_VERSION` is set to `"1.0"` automatically. You can change the setting if necessary.
+ `"1.2"` – Clients can connect to the DB instance using TLS 1.2 only.
+ `"1.2 or 1.0"` – Clients can connect to the DB instance using either TLS 1.2 or 1.0.
## Cipher suites for the Oracle SSL option
Amazon RDS for Oracle supports multiple SSL cipher suites. By default, the Oracle SSL option is configured to use the `SSL_RSA_WITH_AES_256_CBC_SHA` cipher suite. To specify a different cipher suite to use over SSL connections, use the `SQLNET.CIPHER_SUITE` option setting.
You can specify multiple values for `SQLNET.CIPHER_SUITE`. This technique is useful if you have database links between your DB instances and decide to update your cipher suites.
The following table summarizes SSL support for RDS for Oracle in all editions of Oracle Database 19c and 21c.
| Cipher suite (SQLNET.CIPHER\$1SUITE) | TLS version support (SQLNET.SSL\$1VERSION) | FIPS support | FedRAMP compliant |
| --- | --- | --- | --- |
| SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA (default) | 1.0 and 1.2 | Yes | No |
| SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 | 1.2 | Yes | No |
| SSL\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | 1.2 | Yes | No |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | 1.2 | Yes | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 | 1.2 | Yes | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | 1.2 | Yes | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | 1.2 | Yes | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | 1.2 | Yes | Yes |
| TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | 1.2 | Yes | Yes |
| TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | 1.2 | Yes | Yes |
| TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | 1.2 | Yes | Yes |
## FIPS support
RDS for Oracle allows you to use the Federal Information Processing Standard (FIPS) standard for 140-2. FIPS 140-2 is a United States government standard that defines cryptographic module security requirements. You turn on the FIPS standard by setting `FIPS.SSLFIPS_140` to `TRUE` for the Oracle SSL option. When FIPS 140-2 is configured for SSL, the cryptographic libraries encrypt data between the client and the RDS for Oracle DB instance.
Clients must use the cipher suite that is FIPS-compliant. When establishing a connection, the client and RDS for Oracle DB instance negotiate which cipher suite to use when transmitting messages back and forth. The table in [Cipher suites for the Oracle SSL option](#Appendix.Oracle.Options.SSL.CipherSuites) shows the FIPS-compliant SSL cipher suites for each TLS version. For more information, see [Oracle database FIPS 140-2 settings](https://docs.oracle.com/en/database/oracle/oracle-database/12.2/dbseg/oracle-database-fips-140-settings.html#GUID-DDBEB3F9-B216-44BB-8C18-43B5E468CBBB) in the Oracle Database documentation.
## Certificate compatibility with cipher suites
RDS for Oracle supports both RSA and Elliptic Curve Digital Signature Algorithm (ECDSA) certificates. When you configure SSL for your DB instance, you must ensure that the cipher suites you specify in the `SQLNET.CIPHER_SUITE` option setting are compatible with the certificate type used by your DB instance.
The following table shows the compatibility between certificate types and cipher suites:
| Certificate type | Compatible cipher suites | Incompatible cipher suites |
| --- | --- | --- |
| RSA certificates (rds-ca-2019, rds-ca-rsa2048-g1, rds-ca-rsa4096-g1) | SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 SSL\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 |
| ECDSA certificates (rds-ca-ecc384-g1) | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA SSL\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA256 SSL\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
When you specify multiple cipher suites in the `SQLNET.CIPHER_SUITE` option setting, make sure to include at least one cipher suite that is compatible with the certificate type used by your DB instance. If you're using an option group with multiple DB instances that have different certificate types, include at least one cipher suite for each certificate type.
If you attempt to associate an option group with an SSL option that contains only cipher suites incompatible with the certificate type of a DB instance, the operation will fail with an error message indicating the incompatibility.
# Adding the SSL option
To use SSL, your RDS for Oracle DB instance must be associated with an option group that includes the `SSL` option.
## Console
**To add the SSL option to an option group**
1. Create a new option group or identify an existing option group to which you can add the `SSL` option.
For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the `SSL` option to the option group.
If you want to use only FIPS-verified cipher suites for SSL connections, set the option `FIPS.SSLFIPS_140` to `TRUE`. For information about the FIPS standard, see [FIPS support](Appendix.Oracle.Options.SSL.md#Appendix.Oracle.Options.SSL.FIPS).
For information about adding an option to an option group, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Create a new RDS for Oracle DB instance and associate the option group with it, or modify an RDS for Oracle DB instance to associate the option group with it.
For information about creating an DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
For information about modifying an DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## AWS CLI
**To add the SSL option to an option group**
1. Create a new option group or identify an existing option group to which you can add the `SSL` option.
For information about creating an option group, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the `SSL` option to the option group.
Specify the following option settings:
+ `Port` – The SSL port number
+ `VpcSecurityGroupMemberships` – The VPC security group for which the option is enabled
+ `SQLNET.SSL_VERSION` – The TLS version that client can use to connect to the DB instance
For example, the following AWS CLI command adds the `SSL` option to an option group named `ora-option-group`.
**Example**
For Linux, macOS, or Unix:
```
aws rds add-option-to-option-group --option-group-name ora-option-group \
--options 'OptionName=SSL,Port=2484,VpcSecurityGroupMemberships="sg-68184619",OptionSettings=[{Name=SQLNET.SSL_VERSION,Value=1.0}]'
```
For Windows:
```
aws rds add-option-to-option-group --option-group-name ora-option-group ^
--options 'OptionName=SSL,Port=2484,VpcSecurityGroupMemberships="sg-68184619",OptionSettings=[{Name=SQLNET.SSL_VERSION,Value=1.0}]'
```
1. Create a new RDS for Oracle DB instance and associate the option group with it, or modify an RDS for Oracle DB instance to associate the option group with it.
For information about creating an DB instance, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
For information about modifying an DB instance, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Configuring SQL\$1Plus to use SSL with an RDS for Oracle DB instance
Before you can connect to an RDS for Oracle DB instance that uses the Oracle SSL option, you must configure SQL\$1Plus before connecting.
**Note**
To allow access to the DB instance from the appropriate clients, ensure that your security groups are configured correctly. For more information, see [Controlling access with security groups](Overview.RDSSecurityGroups.md). Also, these instructions are for SQL\$1Plus and other clients that directly use an Oracle home. For JDBC connections, see [Setting up an SSL connection over JDBC](Appendix.Oracle.Options.SSL.JDBC.md).
**To configure SQL\$1Plus to use SSL to connect to an RDS for Oracle DB instance**
1. Set the `ORACLE_HOME` environment variable to the location of your Oracle home directory.
The path to your Oracle home directory depends on your installation. The following example sets the `ORACLE_HOME` environment variable.
```
prompt>export ORACLE_HOME=/home/user/app/user/product/19.0.0/dbhome_1
```
For information about setting Oracle environment variables, see [SQL\$1Plus environment variables](http://docs.oracle.com/database/121/SQPUG/ch_two.htm#SQPUG331) in the Oracle documentation, and also see the Oracle installation guide for your operating system.
1. Append `$ORACLE_HOME/lib` to the `LD_LIBRARY_PATH` environment variable.
The following is an example that sets the LD\$1LIBRARY\$1PATH environment variable.
```
prompt>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib
```
1. Create a directory for the Oracle wallet at `$ORACLE_HOME/ssl_wallet`.
The following is an example that creates the Oracle wallet directory.
```
prompt>mkdir $ORACLE_HOME/ssl_wallet
```
1. Download the certificate bundle .pem file that works for all AWS Regions and put the file in the ssl\$1wallet directory. For information, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
1. In the `$ORACLE_HOME/network/admin` directory, modify or create the `tnsnames.ora` file and include the following entry.
```
net_service_name =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS =
(PROTOCOL = TCPS)
(HOST = endpoint)
(PORT = ssl_port_number)
)
)
(CONNECT_DATA =
(SID = database_name)
)
(SECURITY =
(SSL_SERVER_CERT_DN = "C=US,ST=Washington,L=Seattle,O=Amazon.com,OU=RDS,CN=endpoint")
)
)
```
1. In the same directory, modify or create the sqlnet.ora file and include the following parameters.
**Note**
To communicate with entities over a TLS secured connection, Oracle requires a wallet with the necessary certificates for authentication. You can use Oracle's ORAPKI utility to create and maintain Oracle wallets, as shown in step 7. For more information, see [Setting up Oracle wallet using ORAPKI](https://docs.oracle.com/cd/E92519_02/pt856pbr3/eng/pt/tsvt/task_SettingUpOracleWalletUsingORAPKI.html) in the Oracle documentation.
```
WALLET_LOCATION = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = $ORACLE_HOME/ssl_wallet)))
SSL_CLIENT_AUTHENTICATION = FALSE
SSL_VERSION = 1.0
SSL_CIPHER_SUITES = (SSL_RSA_WITH_AES_256_CBC_SHA)
SSL_SERVER_DN_MATCH = ON
```
**Note**
You can set `SSL_VERSION` to a higher value if your DB instance supports it.
1. Run the following command to create the Oracle wallet.
```
prompt>orapki wallet create -wallet $ORACLE_HOME/ssl_wallet -auto_login_only
```
1. Extract each certificate in the .pem bundle file into a separate .pem file using an OS utility.
1. Add each certificate to your wallet using separate `orapki` commands, replacing `certificate-pem-file` with the absolute file name of the .pem file.
```
prompt>orapki wallet add -wallet $ORACLE_HOME/ssl_wallet -trusted_cert -cert
certificate-pem-file -auto_login_only
```
For more information, see [Rotating your SSL/TLS certificate](UsingWithRDS.SSL-certificate-rotation.md).
# Connecting to an RDS for Oracle DB instance using SSL
After you configure SQL\$1Plus to use SSL as described previously, you can connect to the RDS for Oracle DB instance with the SSL option. Optionally, you can first export the `TNS_ADMIN` value that points to the directory that contains the tnsnames.ora and sqlnet.ora files. Doing so ensures that SQL\$1Plus can find these files consistently. The following example exports the `TNS_ADMIN` value.
```
export TNS_ADMIN=${ORACLE_HOME}/network/admin
```
Connect to the DB instance. For example, you can connect using SQL\$1Plus and a ** in a tnsnames.ora file.
```
sqlplus mydbuser@net_service_name
```
You can also connect to the DB instance using SQL\$1Plus without using a tnsnames.ora file by using the following command.
```
sqlplus 'mydbuser@(DESCRIPTION = (ADDRESS = (PROTOCOL = TCPS)(HOST = endpoint) (PORT = ssl_port_number))(CONNECT_DATA = (SID = database_name)))'
```
You can also connect to the RDS for Oracle DB instance without using SSL. For example, the following command connects to the DB instance through the clear text port without SSL encryption.
```
sqlplus 'mydbuser@(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = endpoint) (PORT = port_number))(CONNECT_DATA = (SID = database_name)))'
```
If you want to close Transmission Control Protocol (TCP) port access, create a security group with no IP address ingresses and add it to the instance. This addition closes connections over the TCP port, while still allowing connections over the SSL port that are specified from IP addresses within the range permitted by the SSL option security group.
# Setting up an SSL connection over JDBC
To use an SSL connection over JDBC, you must create a keystore, trust the Amazon RDS root CA certificate, and use the code snippet specified following.
To create the keystore in JKS format, you can use the following command. For more information about creating the keystore, see the [Creating a keystore](https://docs.oracle.com/cd/E35822_01/server.740/es_admin/src/tadm_ssl_jetty_keystore.html) in the Oracle documentation. For reference information, see [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html) in the *Java Platform, Standard Edition Tools Reference*.
```
keytool -genkey -alias client -validity 365 -keyalg RSA -keystore clientkeystore
```
Take the following steps to trust the Amazon RDS root CA certificate.
**To trust the Amazon RDS root CA certificate**
1. Download the certificate bundle .pem file that works for all AWS Regions and put the file in the ssl\$1wallet directory.
For information about downloading certificates, see [Using SSL/TLS to encrypt a connection to a DB instance or cluster ](UsingWithRDS.SSL.md).
1. Extract each certificate in the .pem file into a separate file using an OS utility.
1. Convert each certificate to .der format using a separate `openssl` command, replacing *certificate-pem-file* with the name of the certificate .pem file (without the .pem extension).
```
openssl x509 -outform der -in certificate-pem-file.pem -out certificate-pem-file.der
```
1. Import each certificate into the keystore using the following command.
```
keytool -import -alias rds-root -keystore clientkeystore.jks -file certificate-pem-file.der
```
For more information, see [Rotating your SSL/TLS certificate](UsingWithRDS.SSL-certificate-rotation.md).
1. Confirm that the key store was created successfully.
```
keytool -list -v -keystore clientkeystore.jks
```
Enter the keystore password when you are prompted for it.
The following code example shows how to set up the SSL connection using JDBC.
```
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;
public class OracleSslConnectionTest {
private static final String DB_SERVER_NAME = "dns-name-provided-by-amazon-rds";
private static final Integer SSL_PORT = "ssl-option-port-configured-in-option-group";
private static final String DB_SID = "oracle-sid";
private static final String DB_USER = "user-name";
private static final String DB_PASSWORD = "password";
// This key store has only the prod root ca.
private static final String KEY_STORE_FILE_PATH = "file-path-to-keystore";
private static final String KEY_STORE_PASS = "keystore-password";
public static void main(String[] args) throws SQLException {
final Properties properties = new Properties();
final String connectionString = String.format(
"jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=%s)(PORT=%d))(CONNECT_DATA=(SID=%s)))",
DB_SERVER_NAME, SSL_PORT, DB_SID);
properties.put("user", DB_USER);
properties.put("password", DB_PASSWORD);
properties.put("oracle.jdbc.J2EE13Compliant", "true");
properties.put("javax.net.ssl.trustStore", KEY_STORE_FILE_PATH);
properties.put("javax.net.ssl.trustStoreType", "JKS");
properties.put("javax.net.ssl.trustStorePassword", KEY_STORE_PASS);
final Connection connection = DriverManager.getConnection(connectionString, properties);
// If no exception, that means handshake has passed, and an SSL connection can be opened
}
}
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
# Enforcing a DN match with an SSL connection
You can use the Oracle parameter `SSL_SERVER_DN_MATCH` to enforce that the distinguished name (DN) for the database server matches its service name. If you enforce the match verifications, then SSL ensures that the certificate is from the server. If you don't enforce the match verification, then SSL performs the check but allows the connection, regardless if there is a match. If you do not enforce the match, you allow the server to potentially fake its identity.
To enforce DN matching, add the DN match property and use the connection string specified below.
Add the property to the client connection to enforce DN matching.
```
properties.put("oracle.net.ssl_server_dn_match", "TRUE");
```
Use the following connection string to enforce DN matching when using SSL.
```
final String connectionString = String.format(
"jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=%s)(PORT=%d))" +
"(CONNECT_DATA=(SID=%s))" +
"(SECURITY = (SSL_SERVER_CERT_DN =
\"C=US,ST=Washington,L=Seattle,O=Amazon.com,OU=RDS,CN=%s\")))",
DB_SERVER_NAME, SSL_PORT, DB_SID, DB_SERVER_NAME);
```
# Troubleshooting SSL connections
You might query your database and receive the `ORA-28860` error.
```
ORA-28860: Fatal SSL error
28860. 00000 - "Fatal SSL error"
*Cause: An error occurred during the SSL connection to the peer. It is likely that this side sent data which the peer rejected.
*Action: Enable tracing to determine the exact cause of this error.
```
This error occurs when the client attempts to connect using a version of TLS that the server doesn't support. To avoid this error, edit the sqlnet.ora and set `SSL_VERSION` to the correct TLS version. For more information, see [Oracle Support Document 2748438.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=2748438.1) in My Oracle Support.
# Oracle Spatial
Amazon RDS supports Oracle Spatial through the use of the `SPATIAL` option. Oracle Spatial provides a SQL schema and functions that facilitate the storage, retrieval, update, and query of collections of spatial data in an Oracle database. For more information, see [Spatial Concepts](http://docs.oracle.com/database/121/SPATL/spatial-concepts.htm#SPATL010) in the Oracle documentation. Amazon RDS supports Oracle Spatial in all editions of all supported releases.
## How Spatial Patch Bundles (SPBs) work
Every quarter, RDS for Oracle releases new minor engine versions for every supported major engine. A Release Update (RU) engine version incorporates bug fixes from Oracle by including the RU patches for the specified quarter. A Spatial Patch Bundle (SPB) engine version contains RU patches plus patches specific to Oracle Spatial. For example, 19.0.0.0.ru-2025-01.spb-1.r1 is a minor engine version that contains the RU patches in engine version 19.0.0.0.ru-2025-01.rur-2025-01.r1 plus Spatial patches. SPBs are supported only for Oracle Database 19c.
SPBs function in the same way as RUs, although they are named differently. An RU uses the naming format 19.0.0.0.ru-2025-01.rur-2025-01.r1. An SPB name includes the text "spb," as in 19.0.0.0.ru-2025-01.spb-1.r1. Typically, an SPB is released 2–3 weeks after its corresponding quarterly RU. For example, 19.0.0.0.ru-2025-01.spb-1.r1 is released after 19.0.0.0.ru-2025-01.rur-2025-01.r1.
RDS for Oracle has separate paths for automatic minor version upgrades of RUs and SPBs. If your DB instance uses an RU, then RDS automatically upgrades your instance to an RU. If your DB instance uses an SPB, then RDS upgrades your instance to an SPB.
For more information about RUs and SPBs, see [Oracle minor version upgrades](USER_UpgradeDBInstance.Oracle.Minor.md). For a list of supported RUs and SPBs for Oracle Database 19c, see [Amazon RDS for Oracle Database 19c (19.0.0.0)](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/oracle-version-19-0.html) in *Amazon RDS for Oracle Release Notes*.
## Prerequisites for Oracle Spatial
The following are prerequisites for using Oracle Spatial:
+ Make sure that your DB instance is of a sufficient instance class. Oracle Spatial isn't supported for the db.t3.small DB instance classes. For more information, see [RDS for Oracle DB instance classes](Oracle.Concepts.InstanceClasses.md).
+ Make sure that your DB instance has **Auto Minor Version Upgrade** enabled. This option enables your DB instance to receive minor DB engine version upgrades automatically when they become available and is required for any options that install the Oracle Java Virtual Machine (JVM). Amazon RDS uses this option to update your DB instance to the latest Oracle Patch Set Update (PSU) or Release Update (RU). For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Best practices for Oracle Spatial
The following are best practices for using Oracle Spatial:
+ For maximum security, use the `SPATIAL` option with Secure Sockets Layer (SSL). For more information, see [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md).
+ Configure your DB instance to restrict access to your DB instance. For more information, see [Scenarios for accessing a DB instance in a VPC](USER_VPC.Scenarios.md) and [Working with a DB instance in a VPC](USER_VPC.WorkingWithRDSInstanceinaVPC.md).
## Adding the Oracle Spatial option
The following is the general process for adding the `SPATIAL` option to a DB instance:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with the DB instance.
If Oracle Java Virtual Machine (JVM) is *not* installed on the DB instance, there is a brief outage while the `SPATIAL` option is added. There is no outage if Oracle Java Virtual Machine (JVM) is already installed on the DB instance. After you add the option, you don't need to restart your DB instance. As soon as the option group is active, Oracle Spatial is available.
**Note**
During this outage, password verification functions are disabled briefly. You can also expect to see events related to password verification functions during the outage. Password verification functions are enabled again before the Oracle DB instance is available.
**To add the `SPATIAL` option to a DB instance**
1. Determine the option group that you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine**, choose the Oracle edition for your DB instance.
1. For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **SPATIAL** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Removing the Oracle Spatial option
After you drop all objects that use data types provided by the `SPATIAL` option, you can drop the option from a DB instance. If Oracle Java Virtual Machine (JVM) is *not* installed on the DB instance, there is a brief outage while the `SPATIAL` option is removed. There is no outage if Oracle Java Virtual Machine (JVM) is already installed on the DB instance. After you remove the `SPATIAL` option, you don't need to restart your DB instance.
**To drop the `SPATIAL` option**
1. Back up your data.
**Warning**
If the instance uses data types that were enabled as part of the option, and if you remove the `SPATIAL` option, you can lose data. For more information, see [Backing up, restoring, and exporting data](CHAP_CommonTasks.BackupRestore.md).
1. Check whether any existing objects reference data types or features of the `SPATIAL` option.
If `SPATIAL` options exist, the instance can get stuck when applying the new option group that doesn't have the `SPATIAL` option. You can identify the objects by using the following queries:
```
SELECT OWNER, SEGMENT_NAME, TABLESPACE_NAME, BYTES/1024/1024 mbytes
FROM DBA_SEGMENTS
WHERE SEGMENT_TYPE LIKE '%TABLE%'
AND (OWNER, SEGMENT_NAME) IN
(SELECT DISTINCT OWNER, TABLE_NAME
FROM DBA_TAB_COLUMNS
WHERE DATA_TYPE='SDO_GEOMETRY'
AND OWNER <> 'MDSYS')
ORDER BY 1,2,3,4;
SELECT OWNER, TABLE_NAME, COLUMN_NAME
FROM DBA_TAB_COLUMNS
WHERE DATA_TYPE = 'SDO_GEOMETRY'
AND OWNER <> 'MDSYS'
ORDER BY 1,2,3;
```
1. Drop any objects that reference data types or features of the `SPATIAL` option.
1. Do one of the following:
+ Remove the `SPATIAL` option from the option group it belongs to. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ Modify the DB instance and specify a different option group that doesn't include the `SPATIAL` option. This change affects a single DB instance. You can specify the default (empty) option group, or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle SQLT
Amazon RDS supports Oracle SQLTXPLAIN (SQLT) through the use of the SQLT option. You can use SQLT with any edition of Oracle Database 19c and higher.
The Oracle `EXPLAIN PLAN` statement can determine the execution plan of a SQL statement. It can verify whether the Oracle optimizer chooses a certain execution plan, such as a nested loops join. It also helps you understand the optimizer's decisions, such as why it chose a nested loops join over a hash join. So `EXPLAIN PLAN` helps you understand the statement's performance.
SQLT is an Oracle utility that produces a report. The report includes object statistics, object metadata, optimizer-related initialization parameters, and other information that a database administrator can use to tune a SQL statement for optimal performance. SQLT produces an HTML report with hyperlinks to all of the sections in the report.
Unlike Automatic Workload Repository or Statspack reports, SQLT works on individual SQL statements. SQLT is a collection of SQL, PL/SQL, and SQL\$1Plus files that collect, store, and display performance data.
Following are the supported Oracle versions for each SQLT version.
****
| SQLT version | Oracle Database 21c | Oracle Database 19c |
| --- | --- | --- |
| 2018-07-25.v1 | Supported | Supported |
| 2018-03-31.v1 | Not supported | Not supported |
| 2016-04-29.v1 | Not supported | Not supported |
To download SQLT and access instructions for using it:
+ Log in to your My Oracle Support account, and open the following documents:
+ To download SQLT: [Document 215187.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=215187.1)
+ For SQLT usage instructions: [Document 1614107.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=1614107.1)
+ For frequently asked questions about SQLT: [Document 1454160.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=1454160.1)
+ For information about reading SQLT output: [Document 1456176.1](https://support.oracle.com/epmos/main/downloadattachmentprocessor?parent=DOCUMENT&sourceId=1456176.1&attachid=1456176.1:58&clickstream=yes)
+ For interpreting the Main report: [Document 1922234.1](https://support.oracle.com/epmos/faces/DocumentDisplay?parent=DOCUMENT&sourceId=215187.1&id=1922234.1)
Amazon RDS doesn't support the following SQLT methods:
+ `XPLORE`
+ `XHUME`
## Prerequisites for SQLT
The following are prerequisites for using SQLT:
+ You must remove users and roles that are required by SQLT, if they exist.
The SQLT option creates the following users and roles on a DB instance:
+ `SQLTXPLAIN` user
+ `SQLTXADMIN` user
+ `SQLT_USER_ROLE` role
If your DB instance has any of these users or roles, log in to the DB instance using a SQL client, and drop them using the following statements:
```
DROP USER SQLTXPLAIN CASCADE;
DROP USER SQLTXADMIN CASCADE;
DROP ROLE SQLT_USER_ROLE CASCADE;
```
+ You must remove tablespaces that are required by SQLT, if they exist.
The SQLT option creates the following tablespaces on a DB instance:
+ `RDS_SQLT_TS`
+ `RDS_TEMP_SQLT_TS`
If your DB instance has these tablespaces, log in to the DB instance using a SQL client, and drop them.
## SQLT option settings
SQLT can work with licensed features that are provided by the Oracle Tuning Pack and the Oracle Diagnostics Pack. The Oracle Tuning Pack includes the SQL Tuning Advisor, and the Oracle Diagnostics Pack includes the Automatic Workload Repository. The SQLT settings enable or disable access to these features from SQLT.
Amazon RDS supports the following settings for the SQLT option.
****
| Option setting | Valid values | Default value | Description |
| --- | --- | --- | --- |
| `LICENSE_PACK` | `T`, `D`, `N` | `N` | The Oracle Management Packs that you want to access with SQLT. Enter one of the following values: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Oracle.Options.SQLT.html) Amazon RDS does not provide licenses for these Oracle Management Packs. If you indicate that you want to use a pack that is not included in your DB instance, you can use SQLT with the DB instance. However, SQLT can't access the pack, and the SQLT report doesn't include the data for the pack. For example, if you specify `T`, but the DB instance doesn't include the Oracle Tuning Pack, SQLT works on the DB instance, but the report it generates doesn't contain data related to the Oracle Tuning Pack. |
| `VERSION` | `2016-04-29.v1` `2018-03-31.v1` `2018-07-25.v1` | `2016-04-29.v1` | The version of SQLT that you want to install. For Oracle Database 19c and 21c, the only supported version is `2018-07-25.v1`. This version is the default for these releases. |
## Adding the SQLT option
The following is the general process for adding the SQLT option to a DB instance:
1. Create a new option group, or copy or modify an existing option group.
1. Add the SQLT option to the option group.
1. Associate the option group with the DB instance.
After you add the SQLT option, as soon as the option group is active, SQLT is active.
**To add the SQLT option to a DB instance**
1. Determine the option group that you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine**, choose the Oracle edition that you want to use. The SQLT option is supported on all editions.
1. For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **SQLT** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
1. (Optional) Verify the SQLT installation on each DB instance with the SQLT option.
1. Use a SQL client to connect to the DB instance as the master user.
For information about connecting to an Oracle DB instance using a SQL client, see [Connecting to your Oracle DB instance](USER_ConnectToOracleInstance.md).
1. Run the following query:
```
SELECT sqltxplain.sqlt$a.get_param('tool_version') sqlt_version FROM DUAL;
```
The query returns the current version of the SQLT option on Amazon RDS. `12.1.160429` is an example of a version of SQLT that is available on Amazon RDS.
1. Change the passwords of the users that are created by the SQLT option.
1. Use a SQL client to connect to the DB instance as the master user.
1. Run the following SQL statement to change the password for the `SQLTXADMIN` user:
```
ALTER USER SQLTXADMIN IDENTIFIED BY new_password ACCOUNT UNLOCK;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
1. Run the following SQL statement to change the password for the `SQLTXPLAIN` user:
```
ALTER USER SQLTXPLAIN IDENTIFIED BY new_password ACCOUNT UNLOCK;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
**Note**
Upgrading SQLT requires uninstalling an older version of SQLT and then installing the new version. So, all SQLT metadata can be lost when you upgrade SQLT. A major version upgrade of a database also uninstalls and re-installs SQLT. An example of a major version upgrade is an upgrade from Oracle Database 19c to Oracle Database 21c.
## Using SQLT
SQLT works with the Oracle SQL\$1Plus utility.
**To use SQLT**
1. Download the SQLT .zip file from [Document 215187.1](https://support.oracle.com/epmos/faces/DocumentDisplay?id=215187.1) on the My Oracle Support site.
**Note**
You can't download SQLT 12.1.160429 from the My Oracle Support site. Oracle has deprecated this older version.
1. Unzip the SQLT .zip file.
1. From a command prompt, change to the `sqlt/run` directory on your file system.
1. From the command prompt, open SQL\$1Plus, and connect to the DB instance as the master user.
For information about connecting to a DB instance using SQL\$1Plus, see [Connecting to your Oracle DB instance](USER_ConnectToOracleInstance.md).
1. Get the SQL ID of a SQL statement:
```
SELECT SQL_ID FROM V$SQL WHERE SQL_TEXT='sql_statement';
```
Your output is similar to the following:
```
SQL_ID
-------------
chvsmttqjzjkn
```
1. Analyze a SQL statement with SQLT:
```
START sqltxtract.sql sql_id sqltxplain_user_password
```
For example, for the SQL ID `chvsmttqjzjkn`, enter the following:
```
START sqltxtract.sql chvsmttqjzjkn sqltxplain_user_password
```
SQLT generates the HTML report and related resources as a .zip file in the directory from which the SQLT command was run.
1. (Optional) To enable application users to diagnose SQL statements with SQLT, grant `SQLT_USER_ROLE` to each application user with the following statement:
```
GRANT SQLT_USER_ROLE TO application_user_name;
```
**Note**
Oracle does not recommend running SQLT with the `SYS` user or with users that have the `DBA` role. It is a best practice to run SQLT diagnostics using the application user's account, by granting `SQLT_USER_ROLE` to the application user.
## Upgrading the SQLT option
With Amazon RDS for Oracle, you can upgrade the SQLT option from your existing version to a higher version. To upgrade the SQLT option, complete steps 1–3 in [Using SQLT](#Oracle.Options.SQLT.Using) for the new version of SQLT. Also, if you granted privileges for the previous version of SQLT in step 7 of that section, grant the privileges again for the new SQLT version.
Upgrading the SQLT option results in the loss of the older SQLT version's metadata. The older SQLT version's schema and related objects are dropped, and the newer version of SQLT is installed. For more information about the changes in the latest SQLT version, see [Document 1614201.1](https://support.oracle.com/epmos/faces/DocumentDisplay?parent=DOCUMENT&sourceId=215187.1&id=1614201.1) on the My Oracle Support site.
**Note**
Version downgrades are not supported.
## Modifying SQLT settings
After you enable SQLT, you can modify the `LICENSE_PACK` and `VERSION` settings for the option.
For more information about how to modify option settings, see [Modifying an option setting](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.ModifyOption). For more information about each setting, see [SQLT option settings](#Oracle.Options.SQLT.Options).
## Removing the SQLT option
You can remove SQLT from a DB instance.
To remove SQLT from a DB instance, do one of the following:
+ To remove SQLT from multiple DB instances, remove the SQLT option from the option group to which the DB instances belong. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ To remove SQLT from a single DB instance, modify the DB instance and specify a different option group that doesn't include the SQLT option. You can specify the default (empty) option group or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
# Oracle Statspack
The Oracle Statspack option installs and enables the Oracle Statspack performance statistics feature. Oracle Statspack is a collection of SQL, PL/SQL, and SQL\$1Plus scripts that collect, store, and display performance data. For information about using Oracle Statspack, see [Oracle Statspack](http://docs.oracle.com/cd/E13160_01/wli/docs10gr3/dbtuning/statsApdx.html) in the Oracle documentation.
**Note**
Oracle Statspack is no longer supported by Oracle and has been replaced by the more advanced Automatic Workload Repository (AWR). AWR is available only for Oracle Enterprise Edition customers who have purchased the Diagnostics Pack. You can use Oracle Statspack with any Oracle DB engine on Amazon RDS. You can't run Oracle Statspack on Amazon RDS read replicas.
## Setting up Oracle Statspack
To run Statspack scripts, you must add the Statspack option.
**To set up Oracle Statspack**
1. In a SQL client, log in to the Oracle DB with an administrative account.
1. Do either of the following actions, depending on whether Statspack is installed:
+ If Statspack is installed, and the `PERFSTAT` account is associated with Statspack, skip to Step 4.
+ If Statspack is not installed, and the `PERFSTAT` account exists, drop the account as follows:
```
DROP USER PERFSTAT CASCADE;
```
Otherwise, attempting to add the Statspack option generates an error and `RDS-Event-0058`.
1. Add the Statspack option to an option group. See [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
Amazon RDS automatically installs the Statspack scripts on the DB instance and then sets up the `PERFSTAT` account.
1. Reset the password using the following SQL statement, replacing *pwd* with your new password:
```
ALTER USER PERFSTAT IDENTIFIED BY pwd ACCOUNT UNLOCK;
```
You can log in using the `PERFSTAT` user account and run the Statspack scripts.
1. Grant the `CREATE JOB` privilege to the `PERFSTAT` account using the following statement:
```
GRANT CREATE JOB TO PERFSTAT;
```
1. Ensure that idle wait events in the `PERFSTAT.STATS$IDLE_EVENT` table are populated.
Because of Oracle Bug 28523746, the idle wait events in `PERFSTAT.STATS$IDLE_EVENT` may not be populated. To ensure all idle events are available, run the following statement:
```
INSERT INTO PERFSTAT.STATS$IDLE_EVENT (EVENT)
SELECT NAME FROM V$EVENT_NAME WHERE WAIT_CLASS='Idle'
MINUS
SELECT EVENT FROM PERFSTAT.STATS$IDLE_EVENT;
COMMIT;
```
## Generating Statspack reports
A Statspack report compares two snapshots.
**To generate Statspack reports**
1. In a SQL client, log in to the Oracle DB with the `PERFSTAT` account.
1. Create a snapshot using either of the following techniques:
+ Create a Statspack snapshot manually.
+ Create a job that takes a Statspack snapshot after a given time interval. For example, the following job creates a Statspack snapshot every hour:
```
VARIABLE jn NUMBER;
exec dbms_job.submit(:jn, 'statspack.snap;',SYSDATE,'TRUNC(SYSDATE+1/24,''HH24'')');
COMMIT;
```
1. View the snapshots using the following query:
```
SELECT SNAP_ID, SNAP_TIME FROM STATS$SNAPSHOT ORDER BY 1;
```
1. Run the Amazon RDS procedure `rdsadmin.rds_run_spreport`, replacing *begin\$1snap* and *end\$1snap* with the snapshot IDs:
```
exec rdsadmin.rds_run_spreport(begin_snap,end_snap);
```
For example, the following command creates a report based on the interval between Statspack snapshots 1 and 2:
```
exec rdsadmin.rds_run_spreport(1,2);
```
The file name of the Statspack report includes the number of the two snapshots. For example, a report file created using Statspack snapshots 1 and 2 would be named `ORCL_spreport_1_2.lst`.
1. Monitor the output for errors.
Oracle Statspack performs checks before running the report. Therefore, you could also see error messages in the command output. For example, you might try to generate a report based on an invalid range, where the beginning Statspack snapshot value is larger than the ending value. In this case, the output shows the error message, but the DB engine does not generate an error file.
```
exec rdsadmin.rds_run_spreport(2,1);
*
ERROR at line 1:
ORA-20000: Invalid snapshot IDs. Find valid ones in perfstat.stats$snapshot.
```
If you use an invalid number a Statspack snapshot, the output shows an error. For example, if you try to generate a report for snapshots 1 and 50, but snapshot 50 doesn't exist, the output shows an error.
```
exec rdsadmin.rds_run_spreport(1,50);
*
ERROR at line 1:
ORA-20000: Could not find both snapshot IDs
```
1. (Optional)
To retrieve the report, call the trace file procedures, as explained in [Working with Oracle trace files](USER_LogAccess.Concepts.Oracle.md#USER_LogAccess.Concepts.Oracle.WorkingWithTracefiles).
Alternatively, download the Statspack report from the RDS console. Go to the **Log** section of the DB instance details and choose **Download**. The following example shows `trace/ORCL_spreport_1_2.lst`
![\[Show a list of Oracle log files in the RDS console. The following trace file is circled: trace/ORCL_spreport_1_2.lst.\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/statspack1.png)
If an error occurs while generating a report, the DB engine uses the same naming conventions as for a report but with an extension of `.err`. For example, if an error occurred while creating a report using Statspack snapshots 1 and 7, the report file would be named `ORCL_spreport_1_7.err`. You can download the error report using the same techniques as for a standard Snapshot report.
## Removing Statspack snapshots
To remove a range of Oracle Statspack snapshots, use the following command:
```
exec statspack.purge(begin snap, end snap);
```
# Oracle time zone
To change the system time zone used by your Oracle DB instance, use the time zone option. For example, you might change the time zone of a DB instance to be compatible with an on-premises environment, or a legacy application. The time zone option changes the time zone at the host level. Changing the time zone impacts all date columns and values, including `SYSDATE` and `SYSTIMESTAMP`.
The time zone option differs from the `rdsadmin_util.alter_db_time_zone` command. The `alter_db_time_zone` command changes the time zone only for certain data types. The time zone option changes the time zone for all date columns and values. For more information about `alter_db_time_zone`, see [Setting the database time zone](Appendix.Oracle.CommonDBATasks.TimeZoneSupport.md). For more information about upgrade considerations, see [Time zone considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.DST).
## Restrictions for setting the time zone
The time zone option is a permanent and persistent option. Therefore, you can't do the following:
+ Remove the option from an option group after you add the time zone option.
+ Remove the option group from a DB instance after you add the group.
+ Modify the time zone setting of the option to a different time zone.
## Recommendations for setting the time zone
Before you add the time zone option to your production database, we strongly recommend that you do the following:
+ Take a snapshot of your DB instance. If you accidentally set the time zone incorrectly, you must recover your DB instance to its previous time zone setting. For more information, see [Creating a DB snapshot for a Single-AZ DB instance for Amazon RDS](USER_CreateSnapshot.md).
+ Add the time zone option to a test DB instance. Adding the time zone option can cause problems with tables that use the system date to add dates or times. We recommend that you analyze your data and applications on the test instance. This way you can assess the impact of changing the time zone on your production instance.
If your DB instance uses the default option group, then follow these steps:
1. Take a snapshot of your DB instance.
1. Add the time zone option to your DB instance.
If your DB instance currently uses a nondefault option group, then follow these steps:
1. Take a snapshot of your DB instance.
1. Create a new option group.
1. Add the time zone option to it, along with all other options that are currently associated with the existing option group.
This prevents the existing options from being uninstalled while enabling the time zone option.
1. Add the option group to your DB instance.
## Time zone option settings
Amazon RDS supports the following settings for the time zone option.
****
| Option setting | Valid values | Description |
| --- | --- | --- |
| `TIME_ZONE` | One of the available time zones. For the full list, see [Available time zones](#Appendix.Oracle.Options.Timezone.Zones). | The new time zone for your DB instance. |
## Adding the time zone option
Complete the following steps to add the time zone option to your DB instance:
1. (Recommended) Take a snapshot of your DB instance.
1. Do one of the following tasks:
+ Create a new option group from scratch. For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
+ Copy an existing option group using the AWS CLI or API. For more information, see [Copying an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Copy).
+ Reuse an existing non-default option group. A best practice is to use an option group that isn't currently associated with any DB instances or snapshots.
1. Add the new option to the option group from the preceding step.
1. If the option group that is currently associated with your DB instance has options enabled, add these options to your new option group. This strategy prevents the existing options from being uninstalled while enabling the new option.
1. Add the new option group to your DB instance.
When you add the time zone option, a brief outage occurs while your DB instance is automatically restarted.
### Console
**To add the time zone option to an option group and associate it with a DB instance**
1. In the RDS console, choose **Option groups.**
1. Choose the name of the option group to which you want to add the option.
1. Choose **Add option**.
1. For **Option name**, choose **Timezone**, and then configure the option settings.
1. Associate the option group with a new or existing DB instance:
+ For a new DB instance, apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, apply the option group by modifying the instance and attaching the new option group. When you add the new option to an existing DB instance, a brief outage occurs while your DB instance is automatically restarted. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
### AWS CLI
The following example uses the AWS CLI [add-option-to-option-group](https://docs.aws.amazon.com/cli/latest/reference/rds/add-option-to-option-group.html) command to add the `Timezone` option and the `TIME_ZONE` option setting to an option group called `myoptiongroup`. The time zone is set to `Africa/Cairo`.
For Linux, macOS, or Unix:
```
aws rds add-option-to-option-group \
--option-group-name "myoptiongroup" \
--options "OptionName=Timezone,OptionSettings=[{Name=TIME_ZONE,Value=Africa/Cairo}]" \
--apply-immediately
```
For Windows:
```
aws rds add-option-to-option-group ^
--option-group-name "myoptiongroup" ^
--options "OptionName=Timezone,OptionSettings=[{Name=TIME_ZONE,Value=Africa/Cairo}]" ^
--apply-immediately
```
## Modifying time zone settings
The time zone option is a permanent and persistent option. You can't remove the option from an option group after you add it. You can't remove the option group from a DB instance after you add it. You can't modify the time zone setting of the option to a different time zone. If you set the time zone incorrectly, restore a snapshot of your DB instance from before you added the time zone option.
## Removing the time zone option
The time zone option is a permanent and persistent option. You can't remove the option from an option group after you add it. You can't remove the option group from a DB instance after you add it. To remove the time zone option, restore a snapshot of your DB instance from before you added the time zone option.
## Available time zones
You can use the following values for the time zone option.
****
| Zone | Time zone |
| --- | --- |
| Africa | Africa/Cairo, Africa/Casablanca, Africa/Harare, Africa/Lagos, Africa/Luanda, Africa/Monrovia, Africa/Nairobi, Africa/Tripoli, Africa/Windhoek |
| America | America/Araguaina, America/Argentina/Buenos\$1Aires, America/Asuncion, America/Bogota, America/Caracas, America/Chicago, America/Chihuahua, America/Cuiaba, America/Denver, America/Detroit, America/Fortaleza, America/Godthab, America/Guatemala, America/Halifax, America/Lima, America/Los\$1Angeles, America/Manaus, America/Matamoros, America/Mexico\$1City, America/Monterrey, America/Montevideo, America/New\$1York, America/Phoenix, America/Santiago, America/Sao\$1Paulo, America/Tijuana, America/Toronto |
| Asia | Asia/Amman, Asia/Ashgabat, Asia/Baghdad, Asia/Baku, Asia/Bangkok, Asia/Beirut, Asia/Calcutta, Asia/Damascus, Asia/Dhaka, Asia/Hong\$1Kong, Asia/Irkutsk, Asia/Jakarta, Asia/Jerusalem, Asia/Kabul, Asia/Karachi, Asia/Kathmandu, Asia/Kolkata, Asia/Krasnoyarsk, Asia/Magadan, Asia/Manila, Asia/Muscat, Asia/Novosibirsk, Asia/Rangoon, Asia/Riyadh, Asia/Seoul, Asia/Shanghai, Asia/Singapore, Asia/Taipei, Asia/Tehran, Asia/Tokyo, Asia/Ulaanbaatar, Asia/Vladivostok, Asia/Yakutsk, Asia/Yerevan |
| Atlantic | Atlantic/Azores, Atlantic/Cape\$1Verde |
| Australia | Australia/Adelaide, Australia/Brisbane, Australia/Darwin, Australia/Eucla, Australia/Hobart, Australia/Lord\$1Howe, Australia/Perth, Australia/Sydney |
| Brazil | Brazil/DeNoronha, Brazil/East |
| Canada | Canada/Newfoundland, Canada/Saskatchewan |
| Etc | Etc/GMT-3 |
| Europe | Europe/Amsterdam, Europe/Athens, Europe/Berlin, Europe/Dublin, Europe/Helsinki, Europe/Kaliningrad, Europe/London, Europe/Madrid, Europe/Moscow, Europe/Paris, Europe/Prague, Europe/Rome, Europe/Sarajevo |
| Pacific | Pacific/Apia, Pacific/Auckland, Pacific/Chatham, Pacific/Fiji, Pacific/Guam, Pacific/Honolulu, Pacific/Kiritimati, Pacific/Marquesas, Pacific/Samoa, Pacific/Tongatapu, Pacific/Wake |
| US | US/Alaska, US/Central, US/East-Indiana, US/Eastern, US/Pacific |
| UTC | UTC |
# Oracle time zone file autoupgrade
With the `TIMEZONE_FILE_AUTOUPGRADE` option, you can upgrade the current time zone file to the latest version on your RDS for Oracle DB instance.
**Topics**
+ [
# Overview of Oracle time zone files
](Appendix.Oracle.Options.Timezone-file-autoupgrade.tz-overview.md)
+ [
# Strategies for updating your time zone file
](Appendix.Oracle.Options.Timezone-file-autoupgrade.strategies.md)
+ [
# Downtime during the time zone file update
](Appendix.Oracle.Options.Timezone-file-autoupgrade.considerations.md)
+ [
# Preparing to update the time zone file
](Appendix.Oracle.Options.Timezone-file-autoupgrade.preparing.md)
+ [
# Adding the time zone file autoupgrade option
](Appendix.Oracle.Options.Timezone-file-autoupgrade.adding.md)
+ [
# Checking your data after the update of the time zone file
](Appendix.Oracle.Options.Timezone-file-autoupgrade.checking.md)
# Overview of Oracle time zone files
An Oracle Database *time zone file* stores the following information:
+ Offset from Coordinated Universal Time (UTC)
+ Transition times for Daylight Saving Time (DST)
+ Abbreviations for standard time and DST
Oracle Database supplies multiple versions of time zone files. When you create an Oracle database in an on-premises environment, you choose the time zone file version. For more information , see [Choosing a Time Zone File](https://docs.oracle.com/en/database/oracle/oracle-database/19/nlspg/datetime-data-types-and-time-zone-support.html#GUID-805AB986-DE12-4FEA-AF56-5AABCD2132DF) in the *Oracle Database Globalization Support Guide*.
If the rules change for DST, Oracle publishes new time zone files. Oracle releases these new time zone files independently of the schedule for quarterly Release Updates (RUs) and Release Update Revisions (RURs). The time zone files reside on the database host in the directory `$ORACLE_HOME/oracore/zoneinfo/`. The time zone file names use the format DSTv*version*, as in DSTv35.
## How the time zone file affects data transfer
In Oracle Database, the `TIMESTAMP WITH TIME ZONE` data type stores time stamp and time zone data. Data with the `TIMESTAMP WITH TIME ZONE` data type uses the rules in the associated time zone file version. Thus, existing `TIMESTAMP WITH TIME ZONE` data is affected when you update the time zone file.
Problems can occur when you transfer data between databases that use different versions of the time zone file. For example, if you import data from a source database with a higher time zone file version than the target database, the database issues the `ORA-39405` error. Previously, you had to work around this error by using either of the following techniques:
+ Create an RDS for Oracle DB instance with the desired time zone file, export data from your source database, and then import it into the new database.
+ Use AWS DMS or logical replication to migrate your data.
## Automatic updates using the TIMEZONE\$1FILE\$1AUTOUPGRADE option
When the option group attached to your RDS for Oracle DB instance includes the `TIMEZONE_FILE_AUTOUPGRADE` option, RDS updates your time zone files automatically. By ensuring that your Oracle databases use the same time zone file version, you avoid time-consuming manual techniques when you move data between different environments. The `TIMEZONE_FILE_AUTOUPGRADE` option is supported for both container databases (CDBs) and non-CDBs.
When you add the `TIMEZONE_FILE_AUTOUPGRADE` option to your option group, you can choose whether to add the option immediately or during the maintenance window. After your DB instance applies the new option, RDS checks whether it can install a newer DSTv*version* file. The target DSTv*version* depends on the following:
+ The minor engine version that your DB instance is currently running
+ The minor engine version to which you want to upgrade your DB instance
For example, your current time zone file version might be DSTv33. When RDS applies the update to your option group, it might determine that DSTv34 is currently available on your DB instance file system. RDS will then update your time zone file to DSTv34 automatically.
To find the available DST versions in the supported RDS release updates, look at the patches in [Release notes for Amazon Relational Database Service (Amazon RDS) for Oracle](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html). For example, [version 19.0.0.0.ru-2022-10.rur-2022-10.r1](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/oracle-version-19-0.html#oracle-version-RU-RUR.19.0.0.0.ru-2022-10.rur-2022-10.r1) lists patch 34533061: RDBMS - DSTV39 UPDATE - TZDATA2022C.
# Strategies for updating your time zone file
Upgrading your DB engine and adding the `TIMEZONE_FILE_AUTOUPGRADE` option to an option group are separate operations. Adding the `TIMEZONE_FILE_AUTOUPGRADE` option initiates the update of your time zone file if a more current one is available. You run the following commands (only relevant options are shown) either immediately or at the next maintenance window:
+ Upgrade your DB engine only using the following RDS CLI command:
```
modify-db-instance --engine-version name ...
```
+ Add the `TIMEZONE_FILE_AUTOUPGRADE` option only using the following CLI command:
```
add-option-to-option-group --option-group-name name --options OptionName=TIMEZONE_FILE_AUTOUPGRADE ...
```
+ Upgrade your DB engine and add a new option group to your instance using the following CLI command:
```
modify-db-instance --engine-version name --option-group-name name ...
```
Your update strategy depends on whether you want to upgrade your database and time zone file together or perform just one of these operations. Keep in mind that if you update your option group and then upgrade your DB engine in separate API operations, it's possible for a time zone file update to be currently in progress when you upgrade your DB engine.
The examples in this section assume the following:
+ You have not yet added `TIMEZONE_FILE_AUTOUPGRADE` to the option group currently associated with your DB instance.
+ Your DB instance uses database version 19.0.0.0.ru-2019-07.rur-2019-07.r1 and time zone file DSTv33.
+ Your DB instance file system includes file DSTv34.
+ Release update 19.0.0.0.ru-2022-10.rur-2022-10.r1 includes DSTv35.
To update your time zone file, you can use the following strategies.
**Topics**
+ [
## Update the time zone file without upgrading the engine
](#Appendix.Oracle.Options.Timezone-file-autoupgrade.strategies.no-upgrade)
+ [
## Upgrade the time zone file and DB engine version
](#Appendix.Oracle.Options.Timezone-file-autoupgrade.strategies.upgrade)
+ [
## Upgrade your DB engine version without updating the time zone file
](#Appendix.Oracle.Options.Timezone-file-autoupgrade.strategies.upgrade-only)
## Update the time zone file without upgrading the engine
In this scenario, your database is using DSTv33, but DSTv34 is available on your DB instance file system. You want to update the time zone file used by your DB instance from DSTv33 to DSTv34, but you don't want to upgrade your engine to a new minor version, which includes DSTv35.
In an `add-option-to-option-group` command, add `TIMEZONE_FILE_AUTOUPGRADE` to the option group used by your DB instance. Specify whether to add the option immediately or defer it to the maintenance window. After applying the `TIMEZONE_FILE_AUTOUPGRADE` option, RDS does the following:
1. Checks for a new DST version.
1. Determines that DSTv34 is available on the file system.
1. Updates the time zone file immediately.
## Upgrade the time zone file and DB engine version
In this scenario, your database is using DSTv33, but DSTv34 is available on your DB instance file system. You want to upgrade your DB engine to minor version 19.0.0.0.ru-2022-10.rur-2022-10.r1, which includes DSTv35, and update your time zone file to DSTv35 during the engine upgrade. Thus, your goal is to skip DSTv34 and update your time zone files directly to DSTv35.
To upgrade the engine and time zone file together, run `modify-db-instance` with the `--option-group-name` and `--engine-version` options. You can run the command immediately or defer it to maintenance window. `In --option-group-name`, specify an option group that includes the `TIMEZONE_FILE_AUTOUPGRADE` option. For example:
```
aws rds modify-db-instance
--db-instance-identifier my-instance \
--engine-version new-version \
----option-group-name og-with-timezone-file-autoupgrade \
--apply-immediately
```
RDS begins upgrading your engine to 19.0.0.0.ru-2022-10.rur-2022-10.r1. After applying the `TIMEZONE_FILE_AUTOUPGRADE` option, RDS checks for a new DST version, sees that DSTv35 is available in 19.0.0.0.ru-2022-10.rur-2022-10.r1, and immediately starts the update to DSTv35.
To upgrade your engine immediately and then upgrade your a timezone file, perform the operations in sequence:
1. Upgrade your DB engine only using the following CLI command:
```
aws rds modify-db-instance \
--db-instance-identifier my-instance \
--engine-version new-version \
--apply-immediately
```
1. Add the `TIMEZONE_FILE_AUTOUPGRADE` option to the option group attached to your instance using the following CLI command:
```
aws rds add-option-to-option-group \
--option-group-name og-in-use-by-your-instance \
--options OptionName=TIMEZONE_FILE_AUTOUPGRADE \
--apply-immediately
```
## Upgrade your DB engine version without updating the time zone file
In this scenario, your database is using DSTv33, but DSTv34 is available on your DB instance file system. You want to upgrade your DB engine to version 19.0.0.0.ru-2022-10.rur-2022-10.r1, which includes DSTv35, but retain time zone file DSTv33. You might choose this strategy for the following reasons:
+ Your data doesn't use the `TIMESTAMP WITH TIME ZONE` data type.
+ Your data uses the `TIMESTAMP WITH TIME ZONE` data type, but your data is not affected by the time zone changes.
+ You want to postpone updating the time zone file because you can't tolerate the extra downtime.
Your strategy depends on which of the following possibilities are true:
+ Your DB instance isn't associated with an option group that includes `TIMEZONE_FILE_AUTOUPGRADE`. In your `modify-db-instance` command, don't specify a new option group so that RDS doesn't update your time zone file.
+ Your DB instance is currently associated with an option group that includes `TIMEZONE_FILE_AUTOUPGRADE`. Within a single `modify-db-instance` command, associate your DB instance with an option group that doesn't include `TIMEZONE_FILE_AUTOUPGRADE` and upgrade your DB engine to 19.0.0.0.ru-2022-10.rur-2022-10.r1.
# Downtime during the time zone file update
When RDS updates your time zone file, existing data that uses `TIMESTAMP WITH TIME ZONE` might change. In this case, your primary consideration is downtime.
**Warning**
If you add the `TIMEZONE_FILE_AUTOUPGRADE` option, your engine upgrade might have prolonged downtime. Updating time zone data for a large database might take hours or even days.
The length of the time zone file update depends on factors such as the following:
+ The amount of `TIMESTAMP WITH TIME ZONE` data in your database
+ The DB instance configuration
+ The DB instance class
+ The storage configuration
+ The database configuration
+ The database parameter settings
Additional downtime can occur when you do the following:
+ Add the option to the option group when the DB instance uses an outdated time zone file
+ Upgrade the Oracle database engine when the new engine version contains a new version of the time zone file
**Note**
During the time zone file update, RDS for Oracle calls `PURGE DBA_RECYCLEBIN`.
# Preparing to update the time zone file
A time zone file upgrade has two separate phases: prepare and upgrade. While not required, we strongly recommend that you perform the prepare step. In this step, you find out which data will be affected by running the PL/SQL procedure `DBMS_DST.FIND_AFFECTED_TABLES`. For more information about the prepare window, see [Upgrading the Time Zone File and Timestamp with Time Zone Data](https://docs.oracle.com/en/database/oracle/oracle-database/19/nlspg/datetime-data-types-and-time-zone-support.html#GUID-B0ACDB2E-4B49-4EB4-B4CC-9260DAE1567A) in the Oracle Database documentation.
**To prepare to update the time zone file**
1. Connect to your Oracle database using a SQL client.
1. Determine the current timezone file version used.
```
SELECT * FROM V$TIMEZONE_FILE;
```
1. Determine the latest timezone file version available on your DB instance.
```
SELECT DBMS_DST.GET_LATEST_TIMEZONE_VERSION FROM DUAL;
```
1. Determine the total size of tables that have columns of type `TIMESTAMP WITH LOCAL TIME ZONE` or `TIMESTAMP WITH TIME ZONE`.
```
SELECT SUM(BYTES)/1024/1024/1024 "Total_size_w_TSTZ_columns_GB"
FROM DBA_SEGMENTS
WHERE SEGMENT_TYPE LIKE 'TABLE%'
AND (OWNER, SEGMENT_NAME) IN
(SELECT OWNER, TABLE_NAME
FROM DBA_TAB_COLUMNS
WHERE DATA_TYPE LIKE 'TIMESTAMP%TIME ZONE');
```
1. Determine the names and sizes of segments that have columns of type `TIMESTAMP WITH LOCAL TIME ZONE` or `TIMESTAMP WITH TIME ZONE`.
```
SELECT OWNER, SEGMENT_NAME, SUM(BYTES)/1024/1024/1024 "SEGMENT_SIZE_W_TSTZ_COLUMNS_GB"
FROM DBA_SEGMENTS
WHERE SEGMENT_TYPE LIKE 'TABLE%'
AND (OWNER, SEGMENT_NAME) IN
(SELECT OWNER, TABLE_NAME
FROM DBA_TAB_COLUMNS
WHERE DATA_TYPE LIKE 'TIMESTAMP%TIME ZONE')
GROUP BY OWNER, SEGMENT_NAME;
```
1. Run the prepare step.
+ The procedure `DBMS_DST.CREATE_AFFECTED_TABLE` creates a table to store any affected data. You pass the name of this table to the `DBMS_DST.FIND_AFFECTED_TABLES` procedure. For more information, see [CREATE\$1AFFECTED\$1TABLE Procedure](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_DST.html#GUID-C53BAABA-914A-404C-9CD5-823257BE0B00) in the Oracle Database documentation.
+ This procedure `CREATE_ERROR_TABLE` creates a table to log errors. For more information, see [CREATE\$1ERROR\$1TABLE Procedure](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_DST.html#GUID-6A7EA024-B02D-4486-B1D6-EF6ABF5DE507) in the Oracle Database documentation.
The following example creates the affected data and error tables, and finds all affected tables.
```
EXEC DBMS_DST.CREATE_ERROR_TABLE('my_error_table')
EXEC DBMS_DST.CREATE_AFFECTED_TABLE('my_affected_table')
EXEC DBMS_DST.BEGIN_PREPARE(new_version);
EXEC DBMS_DST.FIND_AFFECTED_TABLES('my_affected_table', TRUE, 'my_error_table');
EXEC DBMS_DST.END_PREPARE;
SELECT * FROM my_affected_table;
SELECT * FROM my_error_table;
```
1. Query the affected and error tables.
```
SELECT * FROM my_affected_table;
SELECT * FROM my_error_table;
```
# Adding the time zone file autoupgrade option
When you add the option to an option group, the option group is in one of the following states:
+ An existing option group is currently attached to at least one DB instance. When you add the option, all DB instances that use this option group automatically restart. This causes a brief outage.
+ An existing option group is not attached to any DB instance. You plan to add the option and then associate the existing option group with existing DB instances or with a new DB instance.
+ You create a new option group and add the option. You plan to associate the new option group with existing DB instances or with a new DB instance.
## Console
**To add the time zone file autoupgrade option to a 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 **Option groups**.
1. Determine the option group you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine** choose the Oracle Database edition for your DB instance.
1. For **Major engine version** choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Choose the option group that you want to modify, and then choose **Add option**.
1. In the **Add option** window, do the following:
1. Choose **TIMEZONE\$1FILE\$1AUTOUPGRADE**.
1. To enable the option on all associated DB instances as soon as you add it, for **Apply Immediately**, choose **Yes**. If you choose **No** (the default), the option is enabled for each associated DB instance during its next maintenance window.
1. When the settings are as you want them, choose **Add option**.
## AWS CLI
The following example uses the AWS CLI [add-option-to-option-group](https://docs.aws.amazon.com/cli/latest/reference/rds/add-option-to-option-group.html) command to add the `TIMEZONE_FILE_AUTOUPGRADE` option to an option group called `myoptiongroup`.
For Linux, macOS, or Unix:
```
aws rds add-option-to-option-group \
--option-group-name "myoptiongroup" \
--options "OptionName=TIMEZONE_FILE_AUTOUPGRADE" \
--apply-immediately
```
For Windows:
```
aws rds add-option-to-option-group ^
--option-group-name "myoptiongroup" ^
--options "OptionName=TIMEZONE_FILE_AUTOUPGRADE" ^
--apply-immediately
```
# Checking your data after the update of the time zone file
We recommend that you check your data after you update the time zone file. During the prepare step, RDS for Oracle automatically creates the following tables:
+ `rdsadmin.rds_dst_affected_tables` – Lists the tables that contain data affected by the update
+ `rdsadmin.rds_dst_error_table` – Lists the errors generated during the update
These tables are independent of any tables that you create in the prepare window. To see the results of the update, query the tables as follows.
```
SELECT * FROM rdsadmin.rds_dst_affected_tables;
SELECT * FROM rdsadmin.rds_dst_error_table;
```
For more information about the schema for the affected data and error tables, see [FIND\$1AFFECTED\$1TABLES Procedure](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_DST.html#GUID-1F977505-671C-4D5B-8570-86956F136199) in the Oracle documentation.
# Oracle Transparent Data Encryption
Amazon RDS supports Oracle Transparent Data Encryption (TDE), a feature of the Oracle Advanced Security option available in Oracle Enterprise Edition. This feature automatically encrypts data before it is written to storage and automatically decrypts data when the data is read from storage. This option is only supported for the Bring Your Own License (BYOL) model.
TDE is useful in scenarios where you need to encrypt sensitive data in case data files and backups are obtained by a third party. TDE is also useful when you need to comply with security-related regulations.
A detailed explanation about TDE in Oracle Database is beyond the scope of this guide. For information, see the following Oracle Database resources:
+ [Introduction to Transparent Data Encryption](https://docs.oracle.com/en/database/oracle/oracle-database/19/asoag/introduction-to-transparent-data-encryption.html#GUID-62AA9447-FDCD-4A4C-B563-32DE04D55952) in the Oracle Database documentation
+ [Oracle advanced security](https://www.oracle.com/security/database-security/) in the Oracle Database documentation
+ [Oracle advanced security Transparent Data Encryption best practices](https://www.oracle.com/br/a/tech/docs/technical-resources/twp-transparent-data-encryption-bestpractices.pdf), which is an Oracle whitepaper
For more information about using TDE with RDS for Oracle, see the following blogs:
+ [Oracle Database Encryption Options on Amazon RDS](https://aws.amazon.com/blogs/apn/oracle-database-encryption-options-on-amazon-rds/)
+ [Migrate a cross-account TDE-enabled Amazon RDS for Oracle DB instance with reduced downtime using AWS DMS](https://aws.amazon.com/blogs/database/migrate-a-cross-account-tde-enabled-amazon-rds-for-oracle-db-instance-with-reduced-downtime-using-aws-dms/)
## TDE encryption modes
Oracle Transparent Data Encryption supports two encryption modes: TDE tablespace encryption and TDE column encryption. TDE tablespace encryption is used to encrypt entire application tables. TDE column encryption is used to encrypt individual data elements that contain sensitive data. You can also apply a hybrid encryption solution that uses both TDE tablespace and column encryption.
**Note**
Amazon RDS manages the Oracle Wallet and TDE master key for the DB instance. You do not need to set the encryption key using the command `ALTER SYSTEM set encryption key`.
After you enable the `TDE` option, you can check the status of the Oracle Wallet by using the following command:
```
SELECT * FROM v$encryption_wallet;
```
To create an encrypted tablespace, use the following command:
```
CREATE TABLESPACE encrypt_ts ENCRYPTION DEFAULT STORAGE (ENCRYPT);
```
To specify the encryption algorithm, use the following command:
```
CREATE TABLESPACE encrypt_ts ENCRYPTION USING 'AES256' DEFAULT STORAGE (ENCRYPT);
```
The previous statements for encrypting a tablespace are the same as you would use on an on-premises Oracle database.
## Restrictions for the TDE option
The TDE option is permanent and persistent. After you associate your DB instance with an option group that has the TDE option enabled, you can't do the following actions:
+ Disable the `TDE` option in the currently associated option group.
+ Associate your DB instance with a different option group that doesn't include the `TDE` option.
+ Share a DB snapshot that uses the `TDE` option. For more information about sharing DB snapshots, see [Sharing a DB snapshot for Amazon RDS](USER_ShareSnapshot.md).
For more information about persistent and permanent options, see [Persistent and permanent options](USER_WorkingWithOptionGroups.md#Overview.OptionGroups.Permanent).
## Determining whether your DB instance is using TDE
You might want to determine whether your DB instance is associated with an option group that has the `TDE` option enabled. To view the option group that a DB instance is associated with, use the RDS console, the [describe-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) AWS CLI command, or the API operation [DescribeDBInstances](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBInstances.html).
## Adding the TDE option
To add the `TDE` option to your DB instance, complete the following steps:
1. (Recommended) Take a snapshot of your DB instance.
1. Do one of the following tasks:
+ Create a new option group from scratch. For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
+ Copy an existing option group using the AWS CLI or API. For more information, see [Copying an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Copy).
+ Reuse an existing non-default option group. A best practice is to use an option group that isn't currently associated with any DB instances or snapshots.
1. Add the new option to the option group from the preceding step.
1. If the option group that is currently associated with your DB instance has options enabled, add these options to your new option group. This strategy prevents the existing options from being uninstalled while enabling the new option.
1. Add the new option group to your DB instance.
### Console
**To add the TDE option to an option group and associate it with your DB instance**
1. In the RDS console, choose **Option groups.**
1. Choose the name of the option group to which you want to add the option.
1. Choose **Add option**.
1. For **Option name**, choose **TDE**, and then configure the option settings.
1. Choose **Add option**.
**Important**
If you add the **TDE** option to an option group that is currently attached to one or more DB instances, a brief outage occurs while all the DB instances are automatically restarted.
For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Associate the option group with a new or existing DB instance:
+ For a new DB instance, apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, apply the option group by modifying the instance and attaching the new option group. The DB instance doesn't restart as part of this operation. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
### AWS CLI
In the following example, you use the AWS CLI [add-option-to-option-group](https://docs.aws.amazon.com/cli/latest/reference/rds/add-option-to-option-group.html) command to add the `TDE` option to an option group called `myoptiongroup`. For more information, see [Getting started: Flink 1.13.2 ](https://docs.aws.amazon.com/managed-flink/latest/java/earlier.html#getting-started-1-13).
For Linux, macOS, or Unix:
```
aws rds add-option-to-option-group \
--option-group-name "myoptiongroup" \
--options "OptionName=TDE" \
--apply-immediately
```
For Windows:
```
aws rds add-option-to-option-group ^
--option-group-name "myoptiongroup" ^
--options "OptionName=TDE" ^
--apply-immediately
```
## Copying your data to a DB instance that doesn't include the TDE option
You can't remove the TDE option from a DB instance or associate it with an option group that doesn't include the TDE option. To migrate your data to an instance that doesn't include the TDE option, do the following:
1. Decrypt the data on your DB instance.
1. Copy the data to a new DB instance that is not associated with an option group that has `TDE` enabled.
1. Delete your original DB instance.
You can use the same name for the new instance as the previous DB instance.
## Considerations when using TDE with Oracle Data Pump
You can use Oracle Data Pump to import or export encrypted dump files. Amazon RDS supports the password encryption mode `(ENCRYPTION_MODE=PASSWORD)` for Oracle Data Pump. Amazon RDS does not support transparent encryption mode `(ENCRYPTION_MODE=TRANSPARENT)` for Oracle Data Pump. For more information, see [Importing using Oracle Data Pump](Oracle.Procedural.Importing.DataPump.md).
# Oracle UTL\$1MAIL
Amazon RDS supports Oracle UTL\$1MAIL through the use of the UTL\$1MAIL option and SMTP servers. You can send email directly from your database by using the UTL\$1MAIL package. Amazon RDS supports UTL\$1MAIL for the following versions of Oracle:
+ Oracle Database 21c (21.0.0.0), all versions
+ Oracle Database 19c (19.0.0.0), all versions
The following are some limitations to using UTL\$1MAIL:
+ UTL\$1MAIL does not support Transport Layer Security (TLS) and therefore emails are not encrypted.
To connect securely to remote SSL/TLS resources by creating and uploading custom Oracle wallets, follow the instructions in [Configuring UTL\$1HTTP access using certificates and an Oracle wallet](Oracle.Concepts.ONA.md).
The specific certificates that are required for your wallet vary by service. For AWS services, these can typically be found in the [Amazon trust services repository](https://www.amazontrust.com/repository/).
+ UTL\$1MAIL does not support authentication with SMTP servers.
+ You can only send a single attachment in an email.
+ You can't send attachments larger than 32 K.
+ You can only use ASCII and Extended Binary Coded Decimal Interchange Code (EBCDIC) character encodings.
+ SMTP port (25) is throttled based on the elastic network interface owner's policies.
When you enable UTL\$1MAIL, only the master user for your DB instance is granted the execute privilege. If necessary, the master user can grant the execute privilege to other users so that they can use UTL\$1MAIL.
**Important**
We recommend that you enable Oracle's built-in auditing feature to track the use of UTL\$1MAIL procedures.
## Prerequisites for Oracle UTL\$1MAIL
The following are prerequisites for using Oracle UTL\$1MAIL:
+ One or more SMTP servers, and the corresponding IP addresses or public or private Domain Name Server (DNS) names. For more information about private DNS names resolved through a custom DNS server, see [Setting up a custom DNS server](Appendix.Oracle.CommonDBATasks.System.md#Appendix.Oracle.CommonDBATasks.CustomDNS).
## Adding the Oracle UTL\$1MAIL option
The general process for adding the Oracle UTL\$1MAIL option to a DB instance is the following:
1. Create a new option group, or copy or modify an existing option group.
1. Add the option to the option group.
1. Associate the option group with the DB instance.
After you add the UTL\$1MAIL option, as soon as the option group is active, UTL\$1MAIL is active.
**To add the UTL\$1MAIL option to a DB instance**
1. Determine the option group you want to use. You can create a new option group or use an existing option group. If you want to use an existing option group, skip to the next step. Otherwise, create a custom DB option group with the following settings:
1. For **Engine**, choose the edition of Oracle you want to use.
1. For **Major engine version**, choose the version of your DB instance.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create).
1. Add the **UTL\$1MAIL** option to the option group. For more information about adding options, see [Adding an option to an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.AddOption).
1. Apply the option group to a new or existing DB instance:
+ For a new DB instance, you apply the option group when you launch the instance. For more information, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
+ For an existing DB instance, you apply the option group by modifying the instance and attaching the new option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Using Oracle UTL\$1MAIL
After you enable the UTL\$1MAIL option, you must configure the SMTP server before you can begin using it.
You configure the SMTP server by setting the SMTP\$1OUT\$1SERVER parameter to a valid IP address or public DNS name. For the SMTP\$1OUT\$1SERVER parameter, you can specify a comma-separated list of the addresses of multiple servers. If the first server is unavailable, UTL\$1MAIL tries the next server, and so on.
You can set the default SMTP\$1OUT\$1SERVER for a DB instance by using a [DB parameter group](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html). You can set the SMTP\$1OUT\$1SERVER parameter for a session by running the following code on your database on your DB instance.
```
1. ALTER SESSION SET smtp_out_server = mailserver.domain.com:25;
```
After the UTL\$1MAIL option is enabled, and your SMTP\$1OUT\$1SERVER is configured, you can send mail by using the `SEND` procedure. For more information, see [UTL\$1MAIL](http://docs.oracle.com/cd/B19306_01/appdev.102/b14258/u_mail.htm#BABFJJBD) in the Oracle documentation.
## Removing the Oracle UTL\$1MAIL option
You can remove Oracle UTL\$1MAIL from a DB instance.
To remove UTL\$1MAIL from a DB instance, do one of the following:
+ To remove UTL\$1MAIL from multiple DB instances, remove the UTL\$1MAIL option from the option group they belong to. This change affects all DB instances that use the option group. For more information, see [Removing an option from an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.RemoveOption).
+ To remove UTL\$1MAIL from a single DB instance, modify the DB instance and specify a different option group that doesn't include the UTL\$1MAIL option. You can specify the default (empty) option group, or a different custom option group. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
## Troubleshooting
The following are issues you might encounter when you use UTL\$1MAIL with Amazon RDS.
+ Throttling. SMTP port (25) is throttled based on the elastic network interface owner's policies. If you can successfully send email by using UTL\$1MAIL, and you see the error `ORA-29278: SMTP transient error: 421 Service not available`, you are possibly being throttled. If you experience throttling with email delivery, we recommend that you implement a backoff algorithm. For more information about backoff algorithms, see [Error retries and exponential backoff in AWS](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) and [How to handle a "throttling – Maximum sending rate exceeded" error](https://aws.amazon.com/blogs/ses/how-to-handle-a-throttling-maximum-sending-rate-exceeded-error/).
You can request that this throttle be removed. For more information, see [How do I remove the throttle on port 25 from my EC2 instance?](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/).
# Oracle XML DB
Oracle XML DB adds native XML support to your DB instance. With XML DB, you can store and retrieve structured or unstructured XML and relational data. The XML DB protocol server isn't supported on RDS for Oracle.
XML DB is preinstalled on Oracle Database 12c and higher. Thus, you don't need to use an option group to explicitly install XML DB as an additional feature.
To learn how to configure and use XML DB, see [Oracle XML DB Developer's Guide](https://docs.oracle.com/en/database/oracle/oracle-database/19/adxdb/) in the Oracle Database documentation.
# Upgrading the RDS for Oracle DB engine
When Amazon RDS supports a new version of Oracle Database, you can upgrade your DB instances to the new version. For information about which Oracle versions are available on Amazon RDS, see [https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html).
**Important**
RDS for Oracle Databases 11g, 12c, and 18c are no longer supported. If you maintain Oracle Database 11g, 12c, or 18c snapshots, you can upgrade them to a later release. For more information, see [Upgrading an Oracle DB snapshot](USER_UpgradeDBSnapshot.Oracle.md).
**Topics**
+ [
# Overview of RDS for Oracle engine upgrades
](USER_UpgradeDBInstance.Oracle.Overview.md)
+ [
# Oracle major version upgrades
](USER_UpgradeDBInstance.Oracle.Major.md)
+ [
# Oracle minor version upgrades
](USER_UpgradeDBInstance.Oracle.Minor.md)
+ [
# Considerations for Oracle database upgrades
](USER_UpgradeDBInstance.Oracle.OGPG.md)
+ [
# Testing an Oracle DB upgrade
](USER_UpgradeDBInstance.Oracle.UpgradeTesting.md)
+ [
# Upgrading the version of an RDS for Oracle DB instance
](USER_UpgradeDBInstance.Oracle.Upgrading.md)
+ [
# Upgrading an Oracle DB snapshot
](USER_UpgradeDBSnapshot.Oracle.md)
# Overview of RDS for Oracle engine upgrades
Before upgrading your RDS for Oracle DB instance, familiarize yourself with the following concepts.
**Topics**
+ [
## Major and minor version upgrades
](#USER_UpgradeDBInstance.Oracle.Overview.versions)
+ [
## Support dates and mandatory upgrades for RDS for Oracle
](#Aurora.VersionPolicy.MajorVersionLifetime)
+ [
## Oracle engine version management
](#Oracle.Concepts.Patching)
+ [
## Automatic snapshots during engine upgrades
](#USER_UpgradeDBInstance.Oracle.Overview.snapshots)
+ [
## Oracle upgrades in a Multi-AZ deployment
](#USER_UpgradeDBInstance.Oracle.Overview.multi-az)
+ [
## Oracle upgrades of read replicas
](#USER_UpgradeDBInstance.Oracle.Overview.read-replicas)
## Major and minor version upgrades
Major versions are major releases of Oracle Database that occur every 1-2 years. Oracle Database 19c and Oracle Database 21c are major releases.
Every quarter, RDS for Oracle releases new minor engine versions for every supported major engine. A Release Update (RU) engine version incorporates bug fixes from Oracle by including the RU patches for the specified quarter. For example, 21.0.0.0.ru-2024-10.rur-2024-10.r1 is a minor version of Oracle Database 21c that incorporates the October 2024 RU.
A Spatial Patch Bundle (SPB) engine version contains RU patches and patches specific to Oracle Spatial. For example, 19.0.0.0.ru-2025-01.spb-1.r1 is a minor engine version that contains the RU patches in engine version 19.0.0.0.ru-2025-01.rur-2025-01.r1 plus Spatial patches. Typically, RDS for Oracle releases SPBs 2–3 weeks after the corresponding RU. For an explanation of the differences between RUs and SPBs, see [Release Updates (RUs) and Spatial Patch Bundles (SPBs)](USER_UpgradeDBInstance.Oracle.Minor.md#RUs-and-SPBs). For information about supported RUs and SPBs, see [Release notes for Amazon Relational Database Service (Amazon RDS) for Oracle](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes).
RDS for Oracle supports the following upgrades to a DB instance.
| Upgrade type | Application compatibility | Upgrade methods | Sample upgrade path |
| --- | --- | --- | --- |
| Major version | A major version upgrade can introduce changes that aren't compatible with existing applications. | Manual only | From Oracle Database 19c to Oracle Database 21c |
| Minor version | A minor version upgrade includes only changes that are backward-compatible with existing applications. | Automatic or manual | From 21.0.0.0.ru-2023-07.rur-2022-07.r1 to 21.0.0.0.ru-2023-10.rur-2022-10.r1 |
**Important**
When you upgrade your DB engine, an outage occurs. The duration of the outage depends on your engine version and DB instance size.
Make sure that you thoroughly test any upgrade to verify that your applications work correctly before applying the upgrade to your production databases. For more information, see [Testing an Oracle DB upgrade](USER_UpgradeDBInstance.Oracle.UpgradeTesting.md).
## Support dates and mandatory upgrades for RDS for Oracle
Database versions of RDS for Oracle have expected support dates. When a major or minor version of an RDS for Oracle DB engine nears its end-of-support date, RDS begins mandatory upgrades, also known as *forced upgrades*. RDS publishes the following information:
+ A recommendation for you to begin manually upgrading instances on deprecated versions to supported versions
+ A date after which you can no longer create instances on the unsupported versions
+ A date on which RDS begins to upgrade your instances to supported versions automatically during maintenance windows
+ A date on which RDS begins to upgrade your instances to supported versions automatically outside of maintenance windows
**Important**
Forced upgrades can have unexpected consequences for CloudFormation stacks. If you rely on RDS to upgrade your DB instances automatically, you might encounter issues with CloudFormation.
This section contains the following topics:
**Topics**
+ [
### Support dates for major releases of RDS for Oracle
](#oracle-major-support-dates)
+ [
### Support dates for minor versions of RDS for Oracle
](#oracle-minor-support-dates)
### Support dates for major releases of RDS for Oracle
RDS for Oracle major versions remain available at least until the end of support date for the corresponding Oracle Database release version. You can use the following dates to plan your testing and upgrade cycles. These dates represent the earliest date that an upgrade to a newer version might be required. If Amazon extends support for an RDS for Oracle version for longer than originally stated, we plan to update this table to reflect the later date.
**Note**
You can view the major versions of your Oracle databases by running the [describe-db-major-engine-versions](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-major-engine-versions.html) AWS CLI command or by using the [DescribeDBMajorEngineVersions](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBMajorEngineVersions.html) RDS API operation.
| Oracle Database major release version | Expected date for upgrading to a newer version |
| --- | --- |
| Oracle Database 19c | December 31, 2029 with BYOL Premier Support (fees waived for Extended Support) December 31, 2032 with BYOL Extended Support (extra cost) or an Unlimited License Agreement December 31, 2029 with License Included (LI) |
| Oracle Database 21c | July 31, 2027 (not available for Extended Support) |
RDS notifies you at least 12 months before you need to upgrade to a newer major version. The notification describes the upgrade process, including the timing of important milestones, the effect on your DB instances, and recommended actions. We recommend that you thoroughly test your applications with new RDS for Oracle versions before you upgrade your database to a major version.
After this advance notification period, an automatic upgrade to the subsequent major version might be applied to any RDS for Oracle DB instance still running the older version. If so, the upgrade is started during scheduled maintenance windows.
For more information, see [ Release Schedule of Current Database Releases](https://support.oracle.com/knowledge/Oracle%20Database%20Products/742060_1.html) in My Oracle Support.
### Support dates for minor versions of RDS for Oracle
In some cases, we end support for minor versions of major releases in RDS for Oracle. RDS notifies you at least 6 months before you need to upgrade to a newer minor version. The notification describes the upgrade process, including the timing of important milestones, the effect on the DB instances running the deprecated minor version, and recommended actions. We recommend that you thoroughly test your applications with new RDS for Oracle versions before you upgrade your database to a new minor version.
For more information about deprecated and desupported minor versions, see [Release notes for Amazon Relational Database Service (Amazon RDS) for Oracle](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html).
## Oracle engine version management
With DB engine version management, you control when and how the database engine is patched and upgraded. You get the flexibility to maintain compatibility with database engine patch versions. You can also test new patch versions of RDS for Oracle to ensure they work with your application before deploying them in production. In addition, you upgrade the versions on your own terms and timelines.
**Note**
Amazon RDS periodically aggregates official Oracle database patches using an Amazon RDS-specific DB engine version. To see a list of which Oracle patches are contained in an Amazon RDS Oracle-specific engine version, go to [https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html).
## Automatic snapshots during engine upgrades
During upgrades of an Oracle DB instance, snapshots offer protection against upgrade issues. If the backup retention period for your DB instance is greater than 0, Amazon RDS takes the following DB snapshots during the upgrade:
1. A snapshot of the DB instance before any upgrade changes have been made. If the upgrade fails, you can restore this snapshot to create a DB instance running the old version.
1. A snapshot of the DB instance after the upgrade completes.
**Note**
To change your backup retention period, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
After an upgrade, you can't revert to the previous engine version. However, you can create a new Oracle DB instance by restoring the pre-upgrade snapshot.
## Oracle upgrades in a Multi-AZ deployment
If your DB instance is in a Multi-AZ deployment, Amazon RDS upgrades both the primary and standby replicas. If no operating system updates are required, the primary and standby upgrades occur simultaneously. The instances are not available until the upgrade completes.
If operating system updates are required in a Multi-AZ deployment, Amazon RDS applies the updates when you request the database upgrade. Amazon RDS performs the following steps:
1. Updates the operating system on the current standby DB instance.
1. Fails over the primary DB instance to the standby DB instance.
1. Upgrades the database version on the new primary DB instance, which was formerly the standby instance. The primary database is unavailable during the upgrade.
1. Updates the operating system on the new standby DB instance, which was formerly the primary DB instance.
1. Upgrades the database version on the new standby DB instance.
1. Fails over the new primary DB instance back to the original primary DB instance, and the new standby DB instance back to the original standby DB instance. Thus, Amazon RDS returns the replication configuration to its original state.
## Oracle upgrades of read replicas
The Oracle DB engine version of the source DB instance and all of its read replicas must be the same. Amazon RDS performs the upgrade in the following stages:
1. Upgrades the source DB instance. The read replicas are available during this stage.
1. Upgrades the read replicas in parallel, regardless of the replica maintenance windows. The source DB is available during this stage.
For major version upgrades of cross-Region read replicas, Amazon RDS performs additional actions:
+ Generates an option group for the target version automatically
+ Copies all options and option settings from the original option group to the new option group
+ Associates the upgraded cross-Region read replica with the new option group
# Oracle major version upgrades
To perform a major version upgrade, modify the DB instance manually. Major version upgrades don't occur automatically.
**Important**
Make sure that you thoroughly test any upgrade to verify that your applications work correctly before applying the upgrade to your production databases. For more information, see [Testing an Oracle DB upgrade](USER_UpgradeDBInstance.Oracle.UpgradeTesting.md).
**Topics**
+ [
## Supported versions for major upgrades
](#USER_UpgradeDBInstance.Oracle.Major.supported-versions)
+ [
## Supported instance classes for major upgrades
](#USER_UpgradeDBInstance.Oracle.Major.instance-classes)
+ [
## Gathering statistics before major upgrades
](#USER_UpgradeDBInstance.Oracle.Major.gathering-stats)
+ [
## Allowing major upgrades
](#USER_UpgradeDBInstance.Oracle.Major.allowing-upgrades)
## Supported versions for major upgrades
Amazon RDS supports the following major version upgrades.
****
| Current version | Upgrade supported |
| --- | --- |
| 19.0.0.0 using the CDB architecture | 21.0.0.0 |
A major version upgrade of Oracle Database must upgrade to a Release Update (RU) that was released in the same month or later. Major version downgrades aren't supported for any Oracle Database versions.
## Supported instance classes for major upgrades
Your current Oracle DB instance might run on a DB instance class that isn't supported for the version to which you are upgrading. In this case, before you upgrade, migrate the DB instance to a supported DB instance class. For more information about the supported DB instance classes for each version and edition of Amazon RDS for Oracle, see [DB instance classes](Concepts.DBInstanceClass.md).
## Gathering statistics before major upgrades
Before you perform a major version upgrade, Oracle recommends that you gather optimizer statistics on the DB instance that you are upgrading. This action can reduce DB instance downtime during the upgrade.
To gather optimizer statistics, connect to the DB instance as the master user, and run the `DBMS_STATS.GATHER_DICTIONARY_STATS` procedure, as in the following example.
```
EXEC DBMS_STATS.GATHER_DICTIONARY_STATS;
```
For more information, see [ GATHER\$1DICTIONARY\$1STATS Procedure](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_STATS.html?source=%3Aso%3Atw%3Aor%3Aawr%3Aodv%3A%3A#GUID-867989C7-ADFC-4464-8981-437CEA7F331E) in the Oracle documentation.
## Allowing major upgrades
A major engine version upgrade might be incompatible with your application. The upgrade is irreversible. If you specify a major version for the EngineVersion parameter that is different from the current major version, you must allow major version upgrades.
If you upgrade a major version using the CLI command [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html), specify `--allow-major-version-upgrade`. This setting isn't persistent, so you must specify `--allow-major-version-upgrade` whenever you perform a major upgrade. This parameter has no impact on upgrades of minor engine versions. For more information, see [Upgrading a DB instance engine version](USER_UpgradeDBInstance.Upgrading.md).
If you upgrade a major version using the console, you don't need to choose an option to allow the upgrade. Instead, the console displays a warning that major upgrades are irreversible.
# Oracle minor version upgrades
In RDS for Oracle, a minor version upgrade is an update to a major DB engine version. In RDS, a minor engine version is either a Release Update (RU) or Spatial Patch Bundle (SPB). For example, if your DB instance runs major version Oracle Database 19c and minor version 19.0.0.0.ru-2025-10.rur-2025-10.r1, you can upgrade your DB engine to minor version 19.0.0.0.ru-2026-01.rur-2026-01.r1. RDS for Oracle doesn't support minor version downgrades.
You can upgrade your DB engine to a minor version manually or automatically. To learn how to upgrade manually, see [Manually upgrading the engine version](USER_UpgradeDBInstance.Upgrading.md#USER_UpgradeDBInstance.Upgrading.Manual). To learn how to configure automatic upgrades, see [Automatically upgrading the minor engine version](USER_UpgradeDBInstance.Upgrading.md#USER_UpgradeDBInstance.Upgrading.AutoMinorVersionUpgrades). Whether you upgrade manually or automatically, a minor version upgrade entails downtime. Consider this downtime when you plan your upgrades.
Amazon RDS also supports upgrade rollout policy to manage automatic minor version upgrades across multiple database resources and AWS accounts. For more information, see [Using AWS Organizations upgrade rollout policy for automatic minor version upgrades](RDS.Maintenance.AMVU.UpgradeRollout.md).
**Important**
Make sure that you thoroughly test any upgrade to verify that your applications work correctly before applying the upgrade to your production databases. For more information, see [Testing an Oracle DB upgrade](USER_UpgradeDBInstance.Oracle.UpgradeTesting.md).
**Topics**
+ [
## Release Updates (RUs) and Spatial Patch Bundles (SPBs)
](#RUs-and-SPBs)
+ [
## Turning on automatic minor version upgrades for Oracle
](#oracle-minor-version-upgrade-tuning-on)
+ [
## Using AWS Organizations upgrade rollout policy for automatic minor version upgrades
](#oracle-minor-version-upgrade-rollout)
+ [
## Notification of automatic minor version upgrades in RDS for Oracle
](#oracle-minor-version-upgrade-advance)
+ [
## How Amazon RDS schedules automatic minor version upgrades
](#oracle-minor-version-upgrade-scheduled)
+ [
## Managing an automatic minor version upgrade in RDS for Oracle
](#oracle-minor-version-upgrade-managing)
## Release Updates (RUs) and Spatial Patch Bundles (SPBs)
In RDS, a release update (RU) is a quarterly minor engine version that includes security fixes, bug fixes, and new features for Oracle Database. A Spatial Patch Bundle (SPB) is an RU engine version that includes patches designed for the Oracle Spatial option. For example, the SPB named 19.0.0.0.ru-2025-01.spb-1.r1 includes all patches in the corresponding RU 19.0.0.0.ru-2025-01.rur-2025-01.r1 plus patches specific to Spatial. SPBs are supported only for Oracle Database 19c.
When your instance is configured for automatic minor version upgrades, RUs and SPBs are on separate upgrade paths. Typically, an SPB is released 2–3 weeks after its corresponding RU. The following table shows sample minor versions for Oracle Database 19c.
| Standard RU upgrade path | SPB upgrade path |
| --- | --- |
| 19.0.0.0.ru-2025-01.rur-2025-01.r1 | 19.0.0.0.ru-2025-01.spb-1.r1 |
| 19.0.0.0.ru-2025-04.rur-2025-04.r1 | 19.0.0.0.ru-2025-04.spb-1.r1 |
| 19.0.0.0.ru-2025-07.rur-2025-07.r1 | 19.0.0.0.ru-2025-07.spb-1.r1 |
| 19.0.0.0.ru-2025-10.rur-2025-10.r1 | 19.0.0.0.ru-2025-10.spb-1.r1 |
If your DB instance is configured for automatic upgrades, your instance is on the upgrade path corresponding to your current version. For example, if your DB instance runs version 19.0.0.0.ru-2025-01.rur-2025-01.r1, then when 19.0.0.0.ru-2025-04.rur-2025-04.r1 is released, your instance automatically upgrades to this RU. Similarly, if your DB instance runs 19.0.0.0.ru-2025-01.spb-1.r1, then when 19.0.0.0.ru-2025-04.spb-1.r1 is released, your instance automatically upgrades to this SPB. An instance running 19.0.0.0.ru-2025-01.rur-2025-01.r1, which is an RU, won't automatically upgrade to 19.0.0.0.ru-2025-04.spb-1.r1, which is an SPB on a separate upgrade path.
You can upgrade your DB instance to SPBs even if your instance doesn't use Spatial, but the Spatial patches apply only to Oracle Spatial. You can upgrade manually from an RU to an SPB at the same engine version or higher. For example, you can upgrade your instance from 19.0.0.0.ru-2025-01.rur-2025-01.r1 to either of the following engine versions:
+ 19.0.0.0.ru-2025-01.spb-1.r1
+ 19.0.0.0.ru-2025-04.spb-1.r1
You can upgrade your instance from an SPB to an RU only if the RU is a higher engine version. For example, you can upgrade from SPB version 19.0.0.0.ru-2025-04.spb-1.r1 to a higher RU version 19.0.0.0.ru-2025-07.rur-2025-07.r1 but not to the same RU version 19.0.0.0.ru-2025-04.rur-2025-04.r1.
If your DB instance is configured for automatic minor version upgrades, and you manually upgrade from an RU to an SPB or from an SPB to an RU, your automatic upgrade path changes. Suppose that you manually upgrade from RU version 19.0.0.0.ru-2025-01.rur-2025-01.r1 to SPB version 19.0.0.0.ru-2025-01.spb-1.r1. Your next automatic minor version upgrade will be to SPB version 19.0.0.0.ru-2025-04.spb-1.r1.
Because SPBs function as RUs, the RDS APIs for upgrading your instance to RUs and SPBs are identical. The following commands demonstrate upgrading to an RU and to an SPB.
```
aws rds modify-db-instance \
--db-instance-identifier mydbinstance \
--engine-version 19.0.0.0.ru-2025-01.rur-2025-01.r1
aws rds modify-db-instance \
--db-instance-identifier mydbinstance \
--engine-version 19.0.0.0.ru-2025-01.spb-1.r1
```
For more information about the Oracle Spatial option, see [How Spatial Patch Bundles (SPBs) work](Oracle.Options.Spatial.md#Oracle.Options.Spatial.SPBs). For supported RUs and SPBs for Oracle Database 19c, see [Amazon RDS for Oracle Database 19c (19.0.0.0)](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/oracle-version-19-0.html).
## Turning on automatic minor version upgrades for Oracle
In an automatic minor version upgrade, RDS applies the latest available minor version to your Oracle database without manual intervention. An Amazon RDS for Oracle DB instance schedules your upgrade during the next maintenance window in the following circumstances:
+ Your DB instance has the **Auto minor version upgrade** option turned on.
+ Your DB instance isn't already running the latest minor DB engine version.
To learn how to turn on automatic upgrades, see [Automatically upgrading the minor engine version](USER_UpgradeDBInstance.Upgrading.md#USER_UpgradeDBInstance.Upgrading.AutoMinorVersionUpgrades).
## Using AWS Organizations upgrade rollout policy for automatic minor version upgrades
Amazon RDS for Oracle supports AWS Organizations upgrade rollout policy to manage automatic minor version upgrades across multiple database resources and AWS accounts. This policy eliminates the operational overhead of coordinating automatic minor version upgrades either manually or through custom tools, while ensuring upgrades are first applied in non-production environments before being rolled out to production. When a new minor engine version becomes available, Amazon RDS upgrades your DB instances based on their configured upgrade rollout order:
| Upgrade Rollout Order | Typical Use Case | When Upgrade Begins |
| --- | --- | --- |
| First | Development and Test Environments | Earliest - ideal for validating new versions |
| Second | Staging and Non-critical Production Environments | After "First" phase completes |
| Last | Critical Production Environments | After "Second" phase completes |
**Important**
If you do not configure an upgrade rollout order for your DB instance, it defaults to second.
For detailed information about phase timing and duration, see [How Amazon RDS schedules automatic minor version upgrades](#oracle-minor-version-upgrade-scheduled). For information about configuring upgrade rollout policies in AWS Organizations, see [Using AWS Organizations upgrade rollout policy for automatic minor version upgrades](RDS.Maintenance.AMVU.UpgradeRollout.md).
## Notification of automatic minor version upgrades in RDS for Oracle
If automatic minor version upgrade is enabled on your DB instance, RDS for Oracle creates pending maintenance actions to notify you before applying upgrades. You can view these pending maintenance actions on the **Maintenance & backups** tab of your database details page in the Amazon RDS console.
When a new minor version becomes available, RDS for Oracle publishes an early notification (pending maintenance action). The early notification has the following format:
```
An automatic minor version upgrade to engine-version will be applied during your maintenance window on apply-date based on the upgrade rollout order rollout-order. You can change the upgrade rollout order or apply this upgrade manually at any time before the scheduled date through the AWS console or AWS CLI.
```
`apply-date` in the early notification is the date when Amazon RDS will upgrade your DB instance. `rollout-order` is your upgrade rollout order (first, second, or last). If you have not configured an upgrade rollout policy, this value is second by default. For more information, see [Using AWS Organizations upgrade rollout policy for automatic minor version upgrades](RDS.Maintenance.AMVU.UpgradeRollout.md).
When the upgrade rollout phase begins, the pending maintenance action message changes to the following format:
```
Automatic minor version upgrade to engine-version
```
This message indicates that the upgrade has been scheduled and will be applied during your maintenance window on the scheduled apply date. You can check the scheduled apply date on the **Maintenance & backups** tab of your database details page in the Amazon RDS console or in the `CurrentApplyDate` field of the `describe-pending-maintenance-actions` API response.
The following example shows you can get the details about pending maintenance actions by using the `describe-pending-maintenance-actions` command in the AWS CLI:
```
aws rds describe-pending-maintenance-actions
"PendingMaintenanceActions": [
{
"ResourceIdentifier": "arn:aws:rds:us-east-1:123456789012:db:orclinst1",
"PendingMaintenanceActionDetails": [
{
"Action": "db-upgrade",
"Description": "Automatic minor version upgrade to 21.0.0.0.ru-2024-07.rur-2024-07.r1",
"CurrentApplyDate": "2024-12-02T08:10:00Z"
}
]
}, ...
```
For more information about [describe-pending-maintenance-actions](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-pending-maintenance-actions.html), see the *AWS CLI Command Reference*.
## How Amazon RDS schedules automatic minor version upgrades
When you use AWS Organizations upgrade rollout policy, Amazon RDS upgrades DB instances in phases based on their configured rollout order. This section describes the timing and duration of each phase.
**Phase 0: Early Notification**
When RDS for Oracle releases a new minor version (typically 3 to 4 weeks after Oracle's quarterly RU release), all DB instances with auto minor version upgrade enabled receive an early notification. This notification appears on the **Maintenance & backups** tab of the database details page in the Amazon RDS console and in the `describe-pending-maintenance-actions` API response. The early notification phase lasts 2 weeks. During this phase, no automatic upgrades occur.
**Phase 1: Upgrade Rollout Order First**
At the end of the early notification phase, RDS for Oracle begins upgrading DB instances with the upgrade rollout order first. This phase lasts 2 to 3 weeks for the January, April, July quarterly minor versions, and 7 to 8 weeks for the October quarterly minor version. The extended period for the October minor version provides sufficient time to test the new minor version during the year-end holiday season. New DB instances created during this phase with the upgrade rollout order first will be upgraded automatically.
**Phase 2: Upgrade Rollout Order Second**
At the end of phase 1, RDS for Oracle begins upgrading DB instances with upgrade rollout order second. This phase lasts 2 weeks for all quarterly minor versions. New DB instances created with upgrade rollout order first or second during this phase will be upgraded automatically.
**Phase 3: Upgrade Rollout Order Last**
At the end of Phase 2, RDS for Oracle begins upgrading DB instances with upgrade rollout order last. This phase lasts until the next quarterly minor version release. New DB instances created with upgrade rollout order first, second, or last during this phase will be upgraded automatically.
| Phase | When it starts | Duration | Pending maintenance action message |
| --- | --- | --- | --- |
| Phase 0: Early Notification | When RDS for Oracle releases a new minor version | 2 weeks | An automatic minor version upgrade to engine-version will be applied during your maintenance window on apply-date based on the upgrade rollout order rollout-order. You can change the upgrade rollout order or apply this upgrade manually at any time before the scheduled date through the AWS console or AWS CLI. |
| Phase 1: Upgrade Rollout Order First | End of early notification phase | 2 to 4 weeks for January/April/July minor versions, 7 to 9 weeks for October minor version | Automatic minor version upgrade to engine-version |
| Phase 2: Upgrade Rollout Order Second | End of Phase 1 | 2 weeks | Automatic minor version upgrade to engine-version |
| Phase 3: Upgrade Rollout Order Last | End of Phase 2 | Until the next quarterly minor version release | Automatic minor version upgrade to engine-version |
## Managing an automatic minor version upgrade in RDS for Oracle
When auto minor version upgrade is enabled on your DB instance, Amazon RDS automatically upgrades your DB instance to the latest minor version during your maintenance window. However, you can choose to apply the upgrade manually before the scheduled date using the AWS CLI or on the **Maintenance & backups** tab of the database details page.
To upgrade your DB instance immediately instead of waiting for the scheduled maintenance window:
```
aws rds apply-pending-maintenance-action \
--resource-identifier arn:aws:rds:us-east-1:123456789012:db:orclinst1 \
--apply-action db-upgrade \
--opt-in-type immediate
```
To apply the upgrade during your next maintenance window instead of the scheduled apply date:
```
aws rds apply-pending-maintenance-action \
--resource-identifier arn:aws:rds:us-east-1:123456789012:db:orclinst1 \
--apply-action db-upgrade \
--opt-in-type next-maintenance
```
To opt out of an automatic minor version upgrade, modify your DB instance and turn off the automatic minor version upgrade option. This unschedules any pending automatic upgrade.
To learn more about how to turn off automatic minor version upgrade, see [Automatically upgrading the minor engine version](USER_UpgradeDBInstance.Upgrading.md#USER_UpgradeDBInstance.Upgrading.AutoMinorVersionUpgrades). If you need assistance with turning off automatic minor version upgrade, please reach out to the AWS Support.
Sometimes a new minor version becomes available before RDS applies a previous minor version. For example, your instance is running on `21.0.0.0.ru-2025-07.rur-2025-07.r1` when `both 21.0.0.0.ru-2025-10.rur-2025-10.r1` and `21.0.0.0.ru-2026-01.rur-2026-01.r1` are available as upgrade targets. In this situation, to avoid unnecessary downtime for your DB instances, RDS schedules the automatic minor version upgrade to the most recent version, skipping the upgrade to the previous version. In this example, RDS upgrades your instance from `21.0.0.0.ru-2025-07.rur-2025-07.r1` directly to `21.0.0.0.ru-2026-01.rur-2026-01.r1`.
# Considerations for Oracle database upgrades
Before you upgrade your Oracle instance, review the following information.
**Topics**
+ [
## Oracle Multitenant considerations
](#USER_UpgradeDBInstance.Oracle.multi)
+ [
## Option group considerations
](#USER_UpgradeDBInstance.Oracle.OGPG.OG)
+ [
## Parameter group considerations
](#USER_UpgradeDBInstance.Oracle.OGPG.PG)
+ [
## Time zone considerations
](#USER_UpgradeDBInstance.Oracle.OGPG.DST)
+ [
## Spatial Patch Bundle (SPB) considerations
](#USER_UpgradeDBInstance.Oracle.SPB)
## Oracle Multitenant considerations
The following table describes the Oracle Database architectures supported in different releases.
| Oracle Database release | RDS support status | Architecture |
| --- | --- | --- |
| Oracle Database 21c | Supported | CDB only |
| Oracle Database 19c | Supported | CDB or non-CDB |
The following table describes supported and unsupported upgrade paths.
| Upgrade path | Supported? |
| --- | --- |
| CDB to CDB | Yes |
| Non-CDB to CDB | No, but you can convert a non-CDB to a CDB and then upgrade it |
| CDB to non-CDB | No |
For more information about Oracle Multitenant in RDS for Oracle, see [Single-tenant configuration of the CDB architecture](Oracle.Concepts.CDBs.md#Oracle.Concepts.single-tenant).
## Option group considerations
If your DB instance uses a custom option group, sometimes Amazon RDS can't automatically assign a new option group. For example, this situation occurs when you upgrade to a new major version. In such cases, specify a new option group when you upgrade. We recommend that you create a new option group, and add the same options to it as in your existing custom option group.
For more information, see [Creating an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Create) or [Copying an option group](USER_WorkingWithOptionGroups.md#USER_WorkingWithOptionGroups.Copy).
If your DB instance uses a custom option group that contains the `APEX` and `APEX-DEV` options, you can sometimes reduce the upgrade time. To do this, upgrade your version of Oracle APEX at the same time as your DB instance. For more information, see [Upgrading the Oracle APEX version](Appendix.Oracle.Options.APEX.UpgradeandRemove.md#Appendix.Oracle.Options.APEX.Upgrade).
## Parameter group considerations
If your DB instance uses a custom parameter group, sometimes Amazon RDS can't automatically assign your DB instance a new parameter group. For example, this situation occurs when you upgrade to a new major version. In such cases, make sure to specify a new parameter group when you upgrade. We recommend that you create a new parameter group, and configure the parameters as in your existing custom parameter group.
For more information, see [Creating a DB parameter group in Amazon RDS](USER_WorkingWithParamGroups.Creating.md) or [Copying a DB parameter group in Amazon RDS](USER_WorkingWithParamGroups.Copying.md).
## Time zone considerations
You can use the time zone option to change the *system time zone* used by your Oracle DB instance. For example, you might change the time zone of a DB instance to be compatible with an on-premises environment, or a legacy application. The time zone option changes the time zone at the host level. Amazon RDS for Oracle updates the system time zone automatically throughout the year. For more information about the system time zone, see [Oracle time zone](Appendix.Oracle.Options.Timezone.md).
When you create an Oracle DB instance, the database automatically sets the *database time zone*. The database time zone is also known as the Daylight Saving Time (DST) time zone. The database time zone is distinct from the system time zone.
Between Oracle Database releases, patch sets or individual patches may include new DST versions. These patches reflect the changes in transition rules for various time zone regions. For example, a government might change when DST takes effect. Changes to DST rules may affect existing data of the `TIMESTAMP WITH TIME ZONE` data type.
If you upgrade an RDS for Oracle DB instance, Amazon RDS doesn't upgrade the database time zone file automatically. To upgrade the time zone file automatically, you can include the `TIMEZONE_FILE_AUTOUPGRADE` option in the option group associated with your DB instance during or after the engine version upgrade. For more information, see [Oracle time zone file autoupgrade](Appendix.Oracle.Options.Timezone-file-autoupgrade.md).
Alternatively, to upgrade the database time zone file manually, create a new Oracle DB instance that has the desired DST patch. However, we recommend that you upgrade the database time zone file using the `TIMEZONE_FILE_AUTOUPGRADE` option.
After upgrading the time zone file, migrate the data from your current instance to the new instance. You can migrate data using several techniques, including the following:
+ AWS Database Migration Service
+ Oracle GoldenGate
+ Oracle Data Pump
+ Original Export/Import (desupported for general use)
**Note**
When you migrate data using Oracle Data Pump, the utility raises the error ORA-39405 when the target time zone version is lower than the source time zone version.
For more information, see [TIMESTAMP WITH TIMEZONE restrictions](https://docs.oracle.com/en/database/oracle/oracle-database/19/sutil/oracle-data-pump-overview.html#GUID-9B6C92EE-860E-43DD-9728-735B17B9DA89) in the Oracle documentation.
## Spatial Patch Bundle (SPB) considerations
In RDS for Oracle, release update (RU) is a minor engine version that includes security fixes, bug fixes, and new features for Oracle Database. A Spatial Patch Bundle (SPB) is minor engine version that also includes patches designed for the Oracle Spatial option. For example, 19.0.0.0.ru-2025-01.spb-1.r1 is a minor engine version that contains the RU patches in engine version 19.0.0.0.ru-2025-01.rur-2025-01.r1 plus Spatial patches.
When you upgrade your database to SPBs, consider the following:
+ SPBs are supported only for Oracle Database 19c.
+ Typically, an SPB is released 2–3 weeks after its corresponding quarterly RU.
+ You can upgrade your DB instance to an SPB even if the instance doesn't use the Oracle Spatial option, but the Spatial patches in the engine version apply only to Oracle Spatial. You can create a new instance on an SPB and install the Oracle Spatial option later.
+ If you enable automatic minor version upgrade for your DB instance, your upgrade path depends on whether your instance currently uses an SPB or RU. If your instance uses an SPB, RDS automatically upgrades your instance to the latest SPB. If your instance uses an RU, RDS automatically upgrades your instance to the latest RU.
+ You can manually upgrade your DB instance from an RU to an SPB only if the SPB is the same engine version or higher as your current RU.
+ You can manually upgrade your DB instance from an SPB to an RU only if the RU is a higher version.
# Testing an Oracle DB upgrade
Before you upgrade your DB instance to a major version, thoroughly test your database and all applications that access the database for compatibility with the new version. We recommend that you use the following procedure.
**To test a major version upgrade**
1. Review the Oracle upgrade documentation for the new version of the database engine to see if there are compatibility issues that might affect your database or applications. For more information, see [Database Upgrade Guide](https://docs.oracle.com/database/121/UPGRD/toc.htm) in the Oracle documentation.
1. If your DB instance uses a custom option group, create a new option group compatible with the new version you are upgrading to. For more information, see [Option group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.OG).
1. If your DB instance uses a custom parameter group, create a new parameter group compatible with the new version you are upgrading to. For more information, see [Parameter group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.PG).
1. Create a DB snapshot of the DB instance to be upgraded. For more information, see [Creating a DB snapshot for a Single-AZ DB instance for Amazon RDS](USER_CreateSnapshot.md).
1. Restore the DB snapshot to create a new test DB instance. For more information, see [Restoring to a DB instance](USER_RestoreFromSnapshot.md).
1. Modify this new test DB instance to upgrade it to the new version, by using one of the following methods:
+ [Console](USER_UpgradeDBInstance.Upgrading.md#USER_UpgradeDBInstance.Upgrading.Manual.Console)
+ [AWS CLI](USER_UpgradeDBInstance.Upgrading.md#USER_UpgradeDBInstance.Upgrading.Manual.CLI)
+ [RDS API](USER_UpgradeDBInstance.Upgrading.md#USER_UpgradeDBInstance.Upgrading.Manual.API)
1. Perform testing:
+ Run as many of your quality assurance tests against the upgraded DB instance as needed to ensure that your database and application work correctly with the new version.
+ Implement any new tests needed to evaluate the impact of any compatibility issues that you identified in step 1.
+ Test all stored procedures, functions, and triggers.
+ Direct test versions of your applications to the upgraded DB instance. Verify that the applications work correctly with the new version.
+ Evaluate the storage used by the upgraded instance to determine if the upgrade requires additional storage. You might need to choose a larger instance class to support the new version in production. For more information, see [DB instance classes](Concepts.DBInstanceClass.md).
1. If all tests pass, upgrade your production DB instance. We recommend that you confirm that the DB instance working correctly before allowing write operations to the DB instance.
# Upgrading the version of an RDS for Oracle DB instance
To manually upgrade the DB engine version of an RDS for Oracle DB instance,use the AWS Management Console, the AWS CLI, or the RDS API. For general information about database upgrades in RDS, see [Upgrading the version of an RDS for Oracle DB instance](#USER_UpgradeDBInstance.Oracle.Upgrading). To get valid upgrade targets, use the AWS CLI [ describe-db-engine-versions](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-engine-versions.html) command.
## Console
**To upgrade the engine version of an RDS for Oracle DB instance by using the console**
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 DB instance that you want to upgrade.
1. Choose **Modify**.
1. For **DB engine version**, choose a higher database version.
1. Choose **Continue** and check the summary of modifications. Make sure that you understand the implications of a database version upgrade. You can't convert an upgraded DB instance back to the previous version. Make sure you have tested both your database and your application with the new version before continuing.
1. Decide when to schedule your DB instance upgrade. To apply the changes immediately, choose **Apply immediately**. Choosing this option can cause an outage in some cases. For more information, see [Using the schedule modifications setting](USER_ModifyInstance.ApplyImmediately.md).
1. On the confirmation page, review your changes. If they are correct, choose **Modify DB instance** to save your changes.
Alternatively, choose **Back** to edit your changes, or choose **Cancel** to cancel your changes.
## AWS CLI
To upgrade the engine version of an RDS for Oracle DB instance, you can use the CLI [modify-db-instance](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-instance.html) command. Specify the following parameters:
+ `--db-instance-identifier` – the name of the RDS for Oracle DB instance.
+ `--engine-version` – the version number of the database engine to upgrade to.
For information about valid engine versions, use the AWS CLI [ describe-db-engine-versions](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-engine-versions.html) command.
+ `--allow-major-version-upgrade` – to upgrade the DB engine version.
+ `--no-apply-immediately` – to apply changes during the next maintenance window. To apply changes immediately, use `--apply-immediately`.
**Example**
The following example upgrades a CDB instance named `myorainst` from its current version of `19.0.0.0.ru-2024-01.rur-2024-01.r1` to version `21.0.0.0.ru-2024-04.rur-2024-04.r1`.
For Linux, macOS, or Unix:
```
1. aws rds modify-db-instance \
2. --db-instance-identifier myorainst \
3. --engine-version 21.0.0.0.ru-2024-04.rur-2024-04.r1 \
4. --allow-major-version-upgrade \
5. --no-apply-immediately
```
For Windows:
```
1. aws rds modify-db-instance ^
2. --db-instance-identifier myorainst ^
3. --engine-version 21.0.0.0.ru-2024-04.rur-2024-04.r1 ^
4. --allow-major-version-upgrade ^
5. --no-apply-immediately
```
## RDS API
To upgrade an RDS for Oracle DB instance, use the [ ModifyDBInstance](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBInstance.html) action. Specify the following parameters:
+ `DBInstanceIdentifier` – the name of the DB instance, for example *`myorainst`*.
+ `EngineVersion` – the version number of the database engine to upgrade to. For information about valid engine versions, use the [ DescribeDBEngineVersions](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBEngineVersions.html) operation.
+ `AllowMajorVersionUpgrade` – whether to allow a major version upgrade. To do so, set the value to `true`.
+ `ApplyImmediately` – whether to apply changes immediately or during the next maintenance window. To apply changes immediately, set the value to `true`. To apply changes during the next maintenance window, set the value to `false`.
# Upgrading an Oracle DB snapshot
Upgrading your Oracle DB snapshots in Amazon RDS ensures that your database remains secure, compatible, and fully supported. As older Oracle versions reach the end of patch support, you can upgrade any manual DB snapshots tied to these versions to avoid potential vulnerabilities or service limitations. For more information, see [Oracle engine version management](USER_UpgradeDBInstance.Oracle.Overview.md#Oracle.Concepts.Patching).
Amazon RDS supports upgrading snapshots in all AWS Regions.
## Console
**To upgrade an Oracle DB snapshot**
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 **Snapshots**, and then select the DB snapshot that you want to upgrade.
1. For **Actions**, choose **Upgrade snapshot**. The **Upgrade snapshot** page appears.
1. Choose the **New engine version** to upgrade the snapshot to.
1. (Optional) For **Option group**, choose the option group for the upgraded DB snapshot. The same option group considerations apply when upgrading a DB snapshot as when upgrading a DB instance. For more information, see [Option group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.OG).
1. Choose **Save changes** to save your changes.
During the upgrade process, all snapshot actions are disabled for this DB snapshot. Also, the DB snapshot status changes from **available** to **upgrading**, and then changes to **active** upon completion. If the DB snapshot can't be upgraded because of snapshot corruption issues, the status changes to **unavailable**. You can't recover the snapshot from this state.
**Note**
If the DB snapshot upgrade fails, the snapshot is rolled back to the original state with the original version.
## AWS CLI
To upgrade an Oracle DB snapshot by using the AWS CLI, call the [modify-db-snapshot](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-snapshot.html) command with the following parameters:
+ `--db-snapshot-identifier` – The name of the DB snapshot.
+ `--engine-version` – The version to upgrade the snapshot to.
You might also need to include the following parameter. The same option group considerations apply when upgrading a DB snapshot as when upgrading a DB instance. For more information, see [Option group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.OG).
+ `--option-group-name` – The option group for the upgraded DB snapshot.
**Example**
The following example upgrades a DB snapshot.
For Linux, macOS, or Unix:
```
aws rds modify-db-snapshot \
--db-snapshot-identifier mydbsnapshot \
--engine-version 19.0.0.0.ru-2020-10.rur-2020-10.r1 \
--option-group-name default:oracle-se2-19
```
For Windows:
```
aws rds modify-db-snapshot ^
--db-snapshot-identifier mydbsnapshot ^
--engine-version 19.0.0.0.ru-2020-10.rur-2020-10.r1 ^
--option-group-name default:oracle-se2-19
```
## RDS API
To upgrade an Oracle DB snapshot by using the Amazon RDS API, call the [ModifyDBSnapshot](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBSnapshot.html) operation with the following parameters:
+ `DBSnapshotIdentifier` – The name of the DB snapshot.
+ `EngineVersion` – The version to upgrade the snapshot to.
You might also need to include the `OptionGroupName` parameter. The same option group considerations apply when upgrading a DB snapshot as when upgrading a DB instance. For more information, see [Option group considerations](USER_UpgradeDBInstance.Oracle.OGPG.md#USER_UpgradeDBInstance.Oracle.OGPG.OG).
# Using third-party software with your RDS for Oracle DB instance
You can host an RDS for Oracle DB instance that supports tools and third-party software.
**Topics**
+ [
# Using Oracle GoldenGate with Amazon RDS for Oracle
](Appendix.OracleGoldenGate.md)
+ [
# Using the Oracle Repository Creation Utility on RDS for Oracle
](Oracle.Resources.RCU.md)
+ [
# Configuring Oracle Connection Manager on an Amazon EC2 instance
](oracle-cman.md)
+ [
# Installing a Siebel database on Oracle on Amazon RDS
](Oracle.Resources.Siebel.md)
# Using Oracle GoldenGate with Amazon RDS for Oracle
Oracle GoldenGate collects, replicates, and manages transactional data between databases. It is a log-based change data capture (CDC) and replication software package used with databases for online transaction processing (OLTP) systems. Oracle GoldenGate creates trail files that contain the most recent changed data from the source database. It then pushes these files to the server, where a process converts the trail file into standard SQL to be applied to the target database.
Oracle GoldenGate with RDS for Oracle supports the following features:
+ Active-Active database replication
+ Disaster recovery
+ Data protection
+ In-Region and cross-Region replication
+ Zero-downtime migration and upgrades
+ Data replication between an RDS for Oracle DB instance and a non-Oracle database
**Note**
For a list of supported databases, see [Oracle Fusion Middleware Supported System Configurations](https://www.oracle.com/middleware/technologies/fusion-certification.html) in the Oracle documentation.
You can use Oracle GoldenGate with RDS for Oracle to upgrade to major versions of Oracle Database. For example, you can use Oracle GoldenGate to upgrade from an Oracle Database 11g on-premises database to Oracle Database 19c on an Amazon RDS DB instance.
**Topics**
+ [
## Supported versions and licensing options for Oracle GoldenGate
](#Appendix.OracleGoldenGate.licensing)
+ [
## Requirements and limitations for Oracle GoldenGate
](#Appendix.OracleGoldenGate.requirements)
+ [
# Oracle GoldenGate architecture
](Appendix.OracleGoldenGate.Overview.md)
+ [
# Setting up Oracle GoldenGate
](Appendix.OracleGoldenGate.setting-up.md)
+ [
# Working with the EXTRACT and REPLICAT utilities of Oracle GoldenGate
](Appendix.OracleGoldenGate.ExtractReplicat.md)
+ [
# Monitoring Oracle GoldenGate
](Appendix.OracleGoldenGate.Monitoring.md)
+ [
# Troubleshooting Oracle GoldenGate
](Appendix.OracleGoldenGate.Troubleshooting.md)
## Supported versions and licensing options for Oracle GoldenGate
You can use Standard Edition 2 (SE2) or Enterprise Edition (EE) of RDS for Oracle with Oracle GoldenGate version 12c and higher. You can use the following Oracle GoldenGate features:
+ Oracle GoldenGate Remote Capture (extract) is supported.
+ Capture (extract) is supported on RDS for Oracle DB instances that use the traditional non-CDB database architecture. Oracle GoldenGate Remote PDB capture is supported on CDBs running Oracle Database 21c or Oracle Database 19c version 19.0.0.0.ru-2024-04.rur-2024-04.r1 or higher.
+ Oracle GoldenGate Remote Delivery (replicat) is supported on RDS for Oracle DB instances that use either the non-CDB or CDB architectures. Remote Delivery supports Integrated Replicat, Parallel Replicat, Coordinated Replicat, and classic Replicat.
+ RDS for Oracle supports the Classic and Microservices architectures of Oracle GoldenGate.
+ Oracle GoldenGate DDL and Sequence value replication is supported when using Integrated capture mode.
You are responsible for managing Oracle GoldenGate licensing (BYOL) for use with Amazon RDS in all AWS Regions. For more information, see [RDS for Oracle licensing options](Oracle.Concepts.Licensing.md).
## Requirements and limitations for Oracle GoldenGate
When you're working with Oracle GoldenGate and RDS for Oracle, consider the following requirements and limitations:
+ You're responsible for setting up and managing Oracle GoldenGate for use with RDS for Oracle.
+ You're responsible for setting up an Oracle GoldenGate version that is certified with the source and the target databases. For more information, see [Oracle Fusion Middleware Supported System Configurations](https://www.oracle.com/middleware/technologies/fusion-certification.html) in the Oracle documentation.
+ You can use Oracle GoldenGate on many different AWS environments for many different use cases. If you have a support-related issue relating to Oracle GoldenGate, contact Oracle Support Services.
+ You can use Oracle GoldenGate on RDS for Oracle DB instances that use Oracle Transparent Data Encryption (TDE). To maintain the integrity of replicated data, configure encryption on the Oracle GoldenGate hub using Amazon EBS encrypted volumes or trail file encryption. Also configure encryption for data sent between the Oracle GoldenGate hub and the source and target database instances. RDS for Oracle DB instances support encryption with [Oracle Secure Sockets Layer](Appendix.Oracle.Options.SSL.md) or [Oracle native network encryption](Appendix.Oracle.Options.NetworkEncryption.md).
# Oracle GoldenGate architecture
The Oracle GoldenGate architecture for use with Amazon RDS consists of the following decoupled modules:
Source database
Your source database can be either an on-premises Oracle database, an Oracle database on an Amazon EC2 instance, or an Oracle database on an Amazon RDS DB instance.
Oracle GoldenGate hub
An Oracle GoldenGate hub moves transaction information from the source database to the target database. Your hub can be either of the following:
+ An Amazon EC2 instance with Oracle Database and Oracle GoldenGate installed
+ An on-premises Oracle installation
You can have more than one Amazon EC2 hub. We recommend that you use two hubs if you use Oracle GoldenGate for cross-Region replication.
Target database
Your target database can be on either an Amazon RDS DB instance, an Amazon EC2 instance, or an on-premises location.
The following sections describe common scenarios for Oracle GoldenGate on Amazon RDS.
**Topics**
+ [
## On-premises source database and Oracle GoldenGate hub
](#Appendix.OracleGoldenGate.on-prem-source-gg-hub)
+ [
## On-premises source database and Amazon EC2 hub
](#Appendix.OracleGoldenGate.on-prem-source-ec2-hub)
+ [
## Amazon RDS source database and Amazon EC2 hub
](#Appendix.OracleGoldenGate.rds-source-ec2-hub)
+ [
## Amazon EC2 source database and Amazon EC2 hub
](#Appendix.OracleGoldenGate.ec2-source-ec2-hub)
+ [
## Amazon EC2 hubs in different AWS Regions
](#Appendix.OracleGoldenGate.cross-region-hubs)
## On-premises source database and Oracle GoldenGate hub
In this scenario, an on-premises Oracle source database and on-premises Oracle GoldenGate hub provides data to a target Amazon RDS DB instance.
![\[Oracle GoldenGate configuration 0 using Amazon RDS\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-gg0.png)
## On-premises source database and Amazon EC2 hub
In this scenario, an on-premises Oracle database acts as the source database. It's connected to an Amazon EC2 instance hub. This hub provides data to a target RDS for Oracle DB instance.
![\[Oracle GoldenGate configuration 1 using Amazon RDS\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-gg1.png)
## Amazon RDS source database and Amazon EC2 hub
In this scenario, an RDS for Oracle DB instance acts as the source database. It's connected to an Amazon EC2 instance hub. This hub provides data to a target RDS for Oracle DB instance.
![\[Oracle GoldenGate configuration 2 using Amazon RDS\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-gg2.png)
## Amazon EC2 source database and Amazon EC2 hub
In this scenario, an Oracle database on an Amazon EC2 instance acts as the source database. It's connected to an Amazon EC2 instance hub. This hub provides data to a target RDS for Oracle DB instance.
![\[Oracle GoldenGate configuration 3 using Amazon RDS\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-gg3.png)
## Amazon EC2 hubs in different AWS Regions
In this scenario, an Oracle database on an Amazon RDS DB instance is connected to an Amazon EC2 instance hub in the same AWS Region. The hub is connected to an Amazon EC2 instance hub in a different AWS Region. This second hub provides data to the target RDS for Oracle DB instance in the same AWS Region as the second Amazon EC2 instance hub.
![\[Oracle GoldenGate configuration 4 using Amazon RDS\]](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/images/oracle-gg4.png)
**Note**
Any issues that affect running Oracle GoldenGate on an on-premises environment also affect running Oracle GoldenGate on AWS. We strongly recommend that you monitor the Oracle GoldenGate hub to ensure that `EXTRACT` and `REPLICAT` are resumed if a failover occurs. Because the Oracle GoldenGate hub is run on an Amazon EC2 instance, Amazon RDS does not manage the Oracle GoldenGate hub and cannot ensure that it is running.
# Setting up Oracle GoldenGate
To set up Oracle GoldenGate using Amazon RDS, configure the hub on an Amazon EC2 instance, and then configure the source and target databases. The following sections give an example of how to set up Oracle GoldenGate for use with Amazon RDS for Oracle.
**Topics**
+ [
## Setting up an Oracle GoldenGate hub on Amazon EC2
](#Appendix.OracleGoldenGate.Hub)
+ [
## Setting up a source database for use with Oracle GoldenGate on Amazon RDS
](#Appendix.OracleGoldenGate.Source)
+ [
## Setting up a target database for use with Oracle GoldenGate on Amazon RDS
](#Appendix.OracleGoldenGate.Target)
## Setting up an Oracle GoldenGate hub on Amazon EC2
To create an Oracle GoldenGate hub on an Amazon EC2 instance, you first create an Amazon EC2 instance with a full client installation of Oracle RDBMS. The Amazon EC2 instance must also have Oracle GoldenGate software installed. The Oracle GoldenGate software versions depend on the source and target database versions. For more information about installing Oracle GoldenGate, see the [Oracle GoldenGate documentation](https://docs.oracle.com/en/middleware/goldengate/core/index.html).
The Amazon EC2 instance that serves as the Oracle GoldenGate hub stores and processes the transaction information from the source database into trail files. To support this process, make sure that you meet the following requirements:
+ You have allocated enough storage for the trail files.
+ The Amazon EC2 instance has enough processing power to manage the amount of data.
+ The EC2 instance has enough memory to store the transaction information before it's written to the trail file.
**To set up an Oracle GoldenGate classic architecture hub on an Amazon EC2 instance**
1. Create subdirectories in the Oracle GoldenGate directory.
In the Amazon EC2 command line shell, start `ggsci`, the Oracle GoldenGate command interpreter. The `CREATE SUBDIRS` command creates subdirectories under the `/gg` directory for parameter, report, and checkpoint files.
```
prompt$ cd /gg
prompt$ ./ggsci
GGSCI> CREATE SUBDIRS
```
1. Configure the `mgr.prm` file.
The following example adds lines to the `$GGHOME/dirprm/mgr.prm` file.
```
PORT 8199
PurgeOldExtracts ./dirdat/*, UseCheckpoints, MINKEEPDAYS 5
```
1. Start the manager.
The following example starts `ggsci` and runs the `start mgr` command.
```
GGSCI> start mgr
```
The Oracle GoldenGate hub is now ready for use.
## Setting up a source database for use with Oracle GoldenGate on Amazon RDS
Complete the following tasks to set up a source database for use with Oracle GoldenGate.
**Topics**
+ [
### Step 1: Turn on supplemental logging on the source database
](#Appendix.OracleGoldenGate.Source.Logging)
+ [
### Step 2: Set the ENABLE\$1GOLDENGATE\$1REPLICATION initialization parameter to true
](#Appendix.OracleGoldenGate.Source.enable-gg-rep)
+ [
### Step 3: Set the log retention period on the source database
](#Appendix.OracleGoldenGate.Source.Retention)
+ [
### Step 4: Create an Oracle GoldenGate user account on the source database
](#Appendix.OracleGoldenGate.Source.Account)
+ [
### Step 5: Grant user account privileges on the source database
](#Appendix.OracleGoldenGate.Source.Privileges)
+ [
### Step 6: Add a TNS alias for the source database
](#Appendix.OracleGoldenGate.Source.TNS)
### Step 1: Turn on supplemental logging on the source database
To turn on the minimum database-level supplemental logging, run the following PL/SQL procedure:
```
EXEC rdsadmin.rdsadmin_util.alter_supplemental_logging(p_action => 'ADD')
```
### Step 2: Set the ENABLE\$1GOLDENGATE\$1REPLICATION initialization parameter to true
When you set the `ENABLE_GOLDENGATE_REPLICATION` initialization parameter to `true`, it allows database services to support logical replication. If your source database is on an Amazon RDS DB instance, make sure that you have a parameter group assigned to the DB instance with the `ENABLE_GOLDENGATE_REPLICATION` initialization parameter set to `true`. For more information about the `ENABLE_GOLDENGATE_REPLICATION` initialization parameter, see the [Oracle Database documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/refrn/ENABLE_GOLDENGATE_REPLICATION.html).
### Step 3: Set the log retention period on the source database
Make sure that you configure the source database to retain archived redo logs. Consider the following guidelines:
+ Specify the duration for log retention in hours. The minimum value is one hour.
+ Set the duration to exceed any potential downtime of the source DB instance, any potential period of communication, and any potential period of networking issues for the source instance. Such a duration lets Oracle GoldenGate recover logs from the source instance as needed.
+ Ensure that you have sufficient storage on your instance for the files.
For example, set the retention period for archived redo logs to 24 hours.
```
EXEC rdsadmin.rdsadmin_util.set_configuration('archivelog retention hours',24)
```
If you don't have log retention enabled, or if the retention value is too small, you receive an error message similar to the following.
```
2022-03-06 06:17:27 ERROR OGG-00446 error 2 (No such file or directory)
opening redo log /rdsdbdata/db/GGTEST3_A/onlinelog/o1_mf_2_9k4bp1n6_.log for sequence 1306
Not able to establish initial position for begin time 2022-03-06 06:16:55.
```
Because your DB instance retains your archived redo logs, make sure that you have sufficient space for the files. To see how much space you have used in the last *num\$1hours* hours, run the following query, replacing *num\$1hours* with the number of hours.
```
SELECT SUM(BLOCKS * BLOCK_SIZE) BYTES FROM V$ARCHIVED_LOG
WHERE NEXT_TIME>=SYSDATE-num_hours/24 AND DEST_ID=1;
```
### Step 4: Create an Oracle GoldenGate user account on the source database
Oracle GoldenGate runs as a database user and requires the appropriate database privileges to access the redo and archived redo logs for the source database. To provide these, create a user account on the source database. For more information about the permissions for an Oracle GoldenGate user account, see the [Oracle documentation](https://docs.oracle.com/en/middleware/goldengate/core/19.1/oracle-db/establishing-oracle-goldengate-credentials.html#GUID-79122058-27B0-4FB6-B3DC-B7D1B67EB053).
The following statements create a user account named `oggadm1`.
```
CREATE TABLESPACE administrator;
CREATE USER oggadm1 IDENTIFIED BY "password"
DEFAULT TABLESPACE ADMINISTRATOR TEMPORARY TABLESPACE TEMP;
ALTER USER oggadm1 QUOTA UNLIMITED ON administrator;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
### Step 5: Grant user account privileges on the source database
In this task, you grant necessary account privileges for database users on your source database.
**To grant account privileges on the source database**
1. Grant the necessary privileges to the Oracle GoldenGate user account using the SQL command `grant` and the `rdsadmin.rdsadmin_util` procedure `grant_sys_object`. The following statements grant privileges to a user named `oggadm1`.
```
GRANT CREATE SESSION, ALTER SESSION TO oggadm1;
GRANT RESOURCE TO oggadm1;
GRANT SELECT ANY DICTIONARY TO oggadm1;
GRANT FLASHBACK ANY TABLE TO oggadm1;
GRANT SELECT ANY TABLE TO oggadm1;
GRANT SELECT_CATALOG_ROLE TO rds_master_user_name WITH ADMIN OPTION;
EXEC rdsadmin.rdsadmin_util.grant_sys_object ('DBA_CLUSTERS', 'OGGADM1');
GRANT EXECUTE ON DBMS_FLASHBACK TO oggadm1;
GRANT SELECT ON SYS.V_$DATABASE TO oggadm1;
GRANT ALTER ANY TABLE TO oggadm1;
```
1. Grant the privileges needed by a user account to be an Oracle GoldenGate administrator. Run the following PL/SQL program.
```
EXEC rdsadmin.rdsadmin_dbms_goldengate_auth.grant_admin_privilege (
grantee => 'OGGADM1',
privilege_type => 'capture',
grant_select_privileges => true,
do_grants => TRUE);
```
To revoke privileges, use the procedure `revoke_admin_privilege` in the same package.
### Step 6: Add a TNS alias for the source database
Add the following entry to `$ORACLE_HOME/network/admin/tnsnames.ora` in the Oracle home to be used by the `EXTRACT` process. For more information on the `tnsnames.ora` file, see the [Oracle documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/netrf/local-naming-parameters-in-tns-ora-file.html#GUID-7F967CE5-5498-427C-9390-4A5C6767ADAA).
```
OGGSOURCE=
(DESCRIPTION=
(ENABLE=BROKEN)
(ADDRESS_LIST=
(ADDRESS=(PROTOCOL=TCP)(HOST=goldengate-source.abcdef12345.us-west-2.rds.amazonaws.com)(PORT=8200)))
(CONNECT_DATA=(SERVICE_NAME=ORCL))
)
```
## Setting up a target database for use with Oracle GoldenGate on Amazon RDS
In this task, you set up a target DB instance for use with Oracle GoldenGate.
**Topics**
+ [
### Step 1: Set the ENABLE\$1GOLDENGATE\$1REPLICATION initialization parameter to true
](#Appendix.OracleGoldenGate.Target.enable-gg-rep)
+ [
### Step 2: Create an Oracle GoldenGate user account on the target database
](#Appendix.OracleGoldenGate.Target.User)
+ [
### Step 3: Grant account privileges on the target database
](#Appendix.OracleGoldenGate.Target.Privileges)
+ [
### Step 4: Add a TNS alias for the target database
](#Appendix.OracleGoldenGate.Target.TNS)
### Step 1: Set the ENABLE\$1GOLDENGATE\$1REPLICATION initialization parameter to true
When you set the `ENABLE_GOLDENGATE_REPLICATION` initialization parameter is to `true`, it allows database services to support logical replication. If your source database is on an Amazon RDS DB instance, make sure that you have a parameter group assigned to the DB instance with the `ENABLE_GOLDENGATE_REPLICATION` initialization parameter set to `true`. For more information about the `ENABLE_GOLDENGATE_REPLICATION` initialization parameter, see the [Oracle Database documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/refrn/ENABLE_GOLDENGATE_REPLICATION.html).
### Step 2: Create an Oracle GoldenGate user account on the target database
Oracle GoldenGate runs as a database user and requires the appropriate database privileges. To make sure it has these privileges, create a user account on the target database.
The following statement creates a user named `oggadm1`.
```
CREATE TABLESPSACE administrator;
CREATE USER oggadm1 IDENTIFIED BY "password"
DEFAULT TABLESPACE administrator
TEMPORARY TABLESPACE temp;
ALTER USER oggadm1 QUOTA UNLIMITED ON administrator;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
### Step 3: Grant account privileges on the target database
In this task, you grant necessary account privileges for database users on your target database.
**To grant account privileges on the target database**
1. Grant necessary privileges to the Oracle GoldenGate user account on the target database. In the following example, you grant privileges to `oggadm1`.
```
GRANT CREATE SESSION TO oggadm1;
GRANT ALTER SESSION TO oggadm1;
GRANT CREATE CLUSTER TO oggadm1;
GRANT CREATE INDEXTYPE TO oggadm1;
GRANT CREATE OPERATOR TO oggadm1;
GRANT CREATE PROCEDURE TO oggadm1;
GRANT CREATE SEQUENCE TO oggadm1;
GRANT CREATE TABLE TO oggadm1;
GRANT CREATE TRIGGER TO oggadm1;
GRANT CREATE TYPE TO oggadm1;
GRANT SELECT ANY DICTIONARY TO oggadm1;
GRANT CREATE ANY TABLE TO oggadm1;
GRANT ALTER ANY TABLE TO oggadm1;
GRANT LOCK ANY TABLE TO oggadm1;
GRANT SELECT ANY TABLE TO oggadm1;
GRANT INSERT ANY TABLE TO oggadm1;
GRANT UPDATE ANY TABLE TO oggadm1;
GRANT DELETE ANY TABLE TO oggadm1;
```
1. Grant the privileges needed by a user account to be an Oracle GoldenGate administrator. Run the following PL/SQL program.
```
EXEC rdsadmin.rdsadmin_dbms_goldengate_auth.grant_admin_privilege (
grantee => 'OGGADM1',
privilege_type => 'apply',
grant_select_privileges => true,
do_grants => TRUE);
```
To revoke privileges, use the procedure `revoke_admin_privilege` in the same package.
### Step 4: Add a TNS alias for the target database
Add the following entry to `$ORACLE_HOME/network/admin/tnsnames.ora` in the Oracle home to be used by the `REPLICAT` process. For Oracle Multitenant databases, make sure that the TNS alias points to the service name of the PDB. For more information on the `tnsnames.ora` file, see the [Oracle documentation](https://docs.oracle.com/en/database/oracle/oracle-database/19/netrf/local-naming-parameters-in-tns-ora-file.html#GUID-7F967CE5-5498-427C-9390-4A5C6767ADAA).
```
OGGTARGET=
(DESCRIPTION=
(ENABLE=BROKEN)
(ADDRESS_LIST=
(ADDRESS=(PROTOCOL=TCP)(HOST=goldengate-target.abcdef12345.us-west-2.rds.amazonaws.com)(PORT=8200)))
(CONNECT_DATA=(SERVICE_NAME=ORCL))
)
```
# Working with the EXTRACT and REPLICAT utilities of Oracle GoldenGate
The Oracle GoldenGate utilities `EXTRACT` and `REPLICAT` work together to keep the source and target databases in sync via incremental transaction replication using trail files. All changes that occur on the source database are automatically detected by `EXTRACT`, then formatted and transferred to trail files on the Oracle GoldenGate on-premises or Amazon EC2 instance hub. After initial load is completed, the data is read from these files and replicated to the target database by the `REPLICAT` utility.
## Running the Oracle GoldenGate EXTRACT utility
The `EXTRACT` utility retrieves, converts, and outputs data from the source database to trail files. The basic process is as follows:
1. `EXTRACT` queues transaction details to memory or to temporary disk storage.
1. The source database commits the transaction.
1. `EXTRACT` writes the transaction details to a trail file.
1. The trail file routes these details to the Oracle GoldenGate on-premises or the Amazon EC2 instance hub and then to the target database.
The following steps start the `EXTRACT` utility, capture the data from `EXAMPLE.TABLE` in source database `OGGSOURCE`, and create the trail files.
**To run the EXTRACT utility**
1. Configure the `EXTRACT` parameter file on the Oracle GoldenGate hub (on-premises or Amazon EC2 instance). The following listing shows an example `EXTRACT` parameter file named `$GGHOME/dirprm/eabc.prm`.
```
EXTRACT EABC
USERID oggadm1@OGGSOURCE, PASSWORD "my-password"
EXTTRAIL /path/to/goldengate/dirdat/ab
IGNOREREPLICATES
GETAPPLOPS
TRANLOGOPTIONS EXCLUDEUSER OGGADM1
TABLE EXAMPLE.TABLE;
```
1. On the Oracle GoldenGate hub, log in to the source database and launch the Oracle GoldenGate command line interface `ggsci`. The following example shows the format for logging in.
```
dblogin oggadm1@OGGSOURCE
```
1. Add transaction data to turn on supplemental logging for the database table.
```
add trandata EXAMPLE.TABLE
```
1. Using the `ggsci` command line, enable the `EXTRACT` utility using the following commands.
```
add extract EABC tranlog, INTEGRATED tranlog, begin now
add exttrail /path/to/goldengate/dirdat/ab
extract EABC,
MEGABYTES 100
```
1. Register the `EXTRACT` utility with the database so that the archive logs are not deleted. This task allows you to recover old, uncommitted transactions if necessary. To register the `EXTRACT` utility with the database, use the following command.
```
register EXTRACT EABC, DATABASE
```
1. Start the `EXTRACT` utility with the following command.
```
start EABC
```
## Running the Oracle GoldenGate REPLICAT utility
The `REPLICAT` utility "pushes" transaction information in the trail files to the target database.
The following steps enable and start the `REPLICAT` utility so that it can replicate the captured data to the table `EXAMPLE.TABLE` in target database `OGGTARGET`.
**To run the REPLICATE utility**
1. Configure the `REPLICAT` parameter file on the Oracle GoldenGate hub (on-premises or EC2 instance). The following listing shows an example `REPLICAT` parameter file named `$GGHOME/dirprm/rabc.prm`.
```
REPLICAT RABC
USERID oggadm1@OGGTARGET, password "my-password"
ASSUMETARGETDEFS
MAP EXAMPLE.TABLE, TARGET EXAMPLE.TABLE;
```
**Note**
Specify a password other than the prompt shown here as a security best practice.
1. Log in to the target database and launch the Oracle GoldenGate command line interface (`ggsci`). The following example shows the format for logging in.
```
dblogin userid oggadm1@OGGTARGET
```
1. Using the `ggsci` command line, add a checkpoint table. The user indicated should be the Oracle GoldenGate user account, not the target table schema owner. The following example creates a checkpoint table named `gg_checkpoint`.
```
add checkpointtable oggadm1.oggchkpt
```
1. To enable the `REPLICAT` utility, use the following command.
```
add replicat RABC EXTTRAIL /path/to/goldengate/dirdat/ab CHECKPOINTTABLE oggadm1.oggchkpt
```
1. Start the `REPLICAT` utility by using the following command.
```
start RABC
```
# Monitoring Oracle GoldenGate
When you use Oracle GoldenGate for replication, make sure that the Oracle GoldenGate process is up and running and the source and target databases are synchronized. You can use the following monitoring tools:
+ [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) is a monitoring service that is used in this pattern to monitor GoldenGate error logs.
+ [Amazon SNS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/US_SetupSNS.html) is a message notification service that is used in this pattern to send email notifications.
For detailed instructions, see [Monitor Oracle GoldenGate logs by using Amazon CloudWatch](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/monitor-oracle-goldengate-logs-by-using-amazon-cloudwatch.html).
# Troubleshooting Oracle GoldenGate
This section explains the most common issues when using Oracle GoldenGate with Amazon RDS for Oracle.
**Topics**
+ [
## Error opening an online redo log
](#Appendix.OracleGoldenGate.Troubleshooting.Logs)
+ [
## Oracle GoldenGate appears to be properly configured but replication is not working
](#Appendix.OracleGoldenGate.Troubleshooting.Replication)
+ [
## Integrated REPLICAT slow due to query on SYS."\$1DBA\$1APPLY\$1CDR\$1INFO"
](#Appendix.OracleGoldenGate.IR)
## Error opening an online redo log
Make sure that you configure your databases to retain archived redo logs. Consider the following guidelines:
+ Specify the duration for log retention in hours. The minimum value is one hour.
+ Set the duration to exceed any potential downtime of the source DB instance, any potential period of communication, and any potential period of networking issues for the source DB instance. Such a duration lets Oracle GoldenGate recover logs from the source DB instance as needed.
+ Ensure that you have sufficient storage on your instance for the files.
If you don't have log retention enabled, or if the retention value is too small, you receive an error message similar to the following.
```
2022-03-06 06:17:27 ERROR OGG-00446 error 2 (No such file or directory)
opening redo log /rdsdbdata/db/GGTEST3_A/onlinelog/o1_mf_2_9k4bp1n6_.log for sequence 1306
Not able to establish initial position for begin time 2022-03-06 06:16:55.
```
## Oracle GoldenGate appears to be properly configured but replication is not working
For pre-existing tables, you must specify the SCN that Oracle GoldenGate works from.
**To fix this issue**
1. Log in to the source database and launch the Oracle GoldenGate command line interface (`ggsci`). The following example shows the format for logging in.
```
dblogin userid oggadm1@OGGSOURCE
```
1. Using the `ggsci` command line, set up the start SCN for the `EXTRACT` process. The following example sets the SCN to 223274 for the `EXTRACT`.
```
ALTER EXTRACT EABC SCN 223274
start EABC
```
1. Log in to the target database. The following example shows the format for logging in.
```
dblogin userid oggadm1@OGGTARGET
```
1. Using the `ggsci` command line, set up the start SCN for the `REPLICAT` process. The following example sets the SCN to 223274 for the `REPLICAT`.
```
start RABC atcsn 223274
```
## Integrated REPLICAT slow due to query on SYS."\$1DBA\$1APPLY\$1CDR\$1INFO"
Oracle GoldenGate Conflict Detection and Resolution (CDR) provides basic conflict resolution routines. For example, CDR can resolve a unique conflict for an `INSERT` statement.
When CDR resolves a collision, it can insert records into the exception table `_DBA_APPLY_CDR_INFO` temporarily. Integrated `REPLICAT` deletes these records later. In a rare scenario, the integrated `REPLICAT` can process a large number of collisions, but a new integrated `REPLICAT` does not replace it. Instead of being removed, the existing rows in `_DBA_APPLY_CDR_INFO` are orphaned. Any new integrated `REPLICAT` processes slow down because they are querying orphaned rows in `_DBA_APPLY_CDR_INFO`.
To remove all rows from `_DBA_APPLY_CDR_INFO`, use the Amazon RDS procedure `rdsadmin.rdsadmin_util.truncate_apply$_cdr_info`. This procedure is released as part of the October 2020 release and patch update. The procedure is available in the following database versions:
+ [ Version 21.0.0.0.ru-2022-01.rur-2022-01.r1](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/oracle-version-21-0.html#oracle-version-RU-RUR.21.0.0.0.ru-2022-01.rur-2022-01.r1) and higher
+ [ Version 19.0.0.0.ru-2020-10.rur-2020-10.r1](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/oracle-version-19-0.html#oracle-version-RU-RUR.19.0.0.0.ru-2020-10.rur-2020-10.r1) and higher
The following example truncates the table `_DBA_APPLY_CDR_INFO`.
```
SET SERVEROUTPUT ON SIZE 2000
EXEC rdsadmin.rdsadmin_util.truncate_apply$_cdr_info;
```
# Using the Oracle Repository Creation Utility on RDS for Oracle
You can use Amazon RDS to host an RDS for Oracle DB instance that holds the schemas to support your Oracle Fusion Middleware components. Before you can use Fusion Middleware components, create and populate schemas for them in your database. You create and populate the schemas by using the Oracle Repository Creation Utility (RCU).
## Supported versions and licensing options for RCU
Amazon RDS supports Oracle Repository Creation Utility (RCU) version 12c only. You can use the RCU in the following configurations:
+ RCU 12c with Oracle Database 21c
+ RCU 12c with Oracle Database 19c
Before you can use RCU, make sure that you do the following:
+ Obtain a license for Oracle Fusion Middleware.
+ Follow the Oracle licensing guidelines for the Oracle database that hosts the repository. For more information, see [ Oracle Fusion Middleware Licensing Information User Manual](https://docs.oracle.com/en/middleware/fusion-middleware/fmwlc/) in the Oracle documentation.
Fusion MiddleWare supports repositories on Oracle Database Enterprise Edition and Standard Edition 2. Oracle recommends Enterprise Edition for production installations that require partitioning and installations that require online index rebuild.
Before you create your RDS for Oracle instance, confirm the Oracle database version that you need to support the components that you want to deploy. To find the requirements for the Fusion Middleware components and versions you want to deploy, use the Certification Matrix. For more information, see [Oracle Fusion Middleware Supported System Configurations](http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html) in the Oracle documentation.
Amazon RDS supports Oracle database version upgrades as needed. For more information, see [Upgrading a DB instance engine version](USER_UpgradeDBInstance.Upgrading.md).
## Requirements and limitations for RCU
To use RCU, you need an Amazon VPC. Your Amazon RDS DB instance must be available only to your Fusion Middleware components, and not to the public Internet. Thus, host your Amazon RDS DB instance in a private subnet, which provides greater security. You also need an RDS for Oracle DB instance. For more information, see [Creating and connecting to an Oracle DB instance](CHAP_GettingStarted.CreatingConnecting.Oracle.md).
You can store the schemas for any Fusion Middleware components in your Amazon RDS DB instance. The following schemas have been verified to install correctly:
+ Analytics (ACTIVITIES)
+ Audit Services (IAU)
+ Audit Services Append (IAU\$1APPEND)
+ Audit Services Viewer (IAU\$1VIEWER)
+ Discussions (DISCUSSIONS)
+ Metadata Services (MDS)
+ Oracle Business Intelligence (BIPLATFORM)
+ Oracle Platform Security Services (OPSS)
+ Portal and Services (WEBCENTER)
+ Portlet Producers (PORTLET)
+ Service Table (STB)
+ SOA Infrastructure (SOAINFRA)
+ User Messaging Service (UCSUMS)
+ WebLogic Services (WLS)
## Guidelines for using RCU
The following are some recommendations for working with your DB instance in this scenario:
+ We recommend that you use Multi-AZ for production workloads. For more information about working with multiple Availability Zones, see [Regions, Availability Zones, and Local Zones](Concepts.RegionsAndAvailabilityZones.md).
+ For additional security, Oracle recommends that you use Transparent Data Encryption (TDE) to encrypt your data at rest. If you have an Enterprise Edition license that includes the Advanced Security Option, you can enable encryption at rest by using the TDE option. For more information, see [Oracle Transparent Data Encryption](Appendix.Oracle.Options.AdvSecurity.md).
Amazon RDS also provides an encryption at rest option for all database editions. For more information, see [Encrypting Amazon RDS resources](Overview.Encryption.md).
+ Configure your VPC Security Groups to allow communication between your application servers and your Amazon RDS DB instance. The application servers that host the Fusion Middleware components can be on Amazon EC2 or on-premises.
## Running RCU
To create and populate the schemas to support your Fusion Middleware components, use the Oracle Repository Creation Utility (RCU). You can run RCU in different ways.
**Topics**
+ [
### Running RCU using the command line in one step
](#Oracle.Resources.RCU.SilentSingle)
+ [
### Running RCU using the command line in multiple steps
](#Oracle.Resources.RCU.SilentMulti)
+ [
### Running RCU in interactive mode
](#Oracle.Resources.RCU.Interactive)
### Running RCU using the command line in one step
If you don't need to edit any of your schemas before populating them, you can run RCU in a single step. Otherwise, see the following section for running RCU in multiple steps.
You can run the RCU in silent mode by using the command-line parameter `-silent`. When you run RCU in silent mode, you can avoid entering passwords on the command line by creating a text file containing the passwords. Create a text file with the password for `dbUser` on the first line, and the password for each component on subsequent lines. You specify the name of the password file as the last parameter to the RCU command.
**Example**
The following example creates and populates schemas for the SOA Infrastructure component (and its dependencies) in a single step.
For Linux, macOS, or Unix:
```
export ORACLE_HOME=/u01/app/oracle/product/12.2.1.0/fmw
export JAVA_HOME=/usr/java/jdk1.8.0_65
${ORACLE_HOME}/oracle_common/bin/rcu \
-silent \
-createRepository \
-connectString ${dbhost}:${dbport}:${dbname} \
-dbUser ${dbuser} \
-dbRole Normal \
-honorOMF \
-schemaPrefix ${SCHEMA_PREFIX} \
-component MDS \
-component STB \
-component OPSS \
-component IAU \
-component IAU_APPEND \
-component IAU_VIEWER \
-component UCSUMS \
-component WLS \
-component SOAINFRA \
-f < /tmp/passwordfile.txt
```
For more information, see [ Running Repository Creation Utility from the command line](https://docs.oracle.com/middleware/1221/core/RCUUG/GUID-0D3A2959-7CC8-4001-997E-718ADF04C5F2.htm#RCUUG248) in the Oracle documentation.
### Running RCU using the command line in multiple steps
To manually edit your schema scripts, run RCU in multiple steps:
1. Run RCU in **Prepare Scripts for System Load** mode by using the `-generateScript` command-line parameter to create the scripts for your schemas.
1. Manually edit and run the generated script `script_systemLoad.sql`.
1. Run RCU again in **Perform Product Load** mode by using the `-dataLoad` command-line parameter to populate the schemas.
1. Run the generated cleanup script `script_postDataLoad.sql`.
To run RCU in silent mode, specify the command-line parameter `-silent`. When you run RCU in silent mode, you can avoid typing passwords on the command line by creating a text file containing the passwords. Create a text file with the password for `dbUser` on the first line, and the password for each component on subsequent lines. Specify the name of the password file as the last parameter to the RCU command.
**Example**
The following example creates schema scripts for the SOA Infrastructure component and its dependencies.
For Linux, macOS, or Unix:
```
export ORACLE_HOME=/u01/app/oracle/product/12.2.1.0/fmw
export JAVA_HOME=/usr/java/jdk1.8.0_65
${ORACLE_HOME}/oracle_common/bin/rcu \
-silent \
-generateScript \
-connectString ${dbhost}:${dbport}:${dbname} \
-dbUser ${dbuser} \
-dbRole Normal \
-honorOMF \
[-encryptTablespace true] \
-schemaPrefix ${SCHEMA_PREFIX} \
-component MDS \
-component STB \
-component OPSS \
-component IAU \
-component IAU_APPEND \
-component IAU_VIEWER \
-component UCSUMS \
-component WLS \
-component SOAINFRA \
-scriptLocation /tmp/rcuscripts \
-f < /tmp/passwordfile.txt
```
Now you can edit the generated script, connect to your Oracle DB instance, and run the script. The generated script is named `script_systemLoad.sql`. For information about connecting to your Oracle DB instance, see [Step 3: Connect your SQL client to an Oracle DB instance](CHAP_GettingStarted.CreatingConnecting.Oracle.md#CHAP_GettingStarted.Connecting.Oracle).
The following example populates the schemas for the SOA Infrastructure component (and its dependencies).
For Linux, macOS, or Unix:
```
export JAVA_HOME=/usr/java/jdk1.8.0_65
${ORACLE_HOME}/oracle_common/bin/rcu \
-silent \
-dataLoad \
-connectString ${dbhost}:${dbport}:${dbname} \
-dbUser ${dbuser} \
-dbRole Normal \
-honorOMF \
-schemaPrefix ${SCHEMA_PREFIX} \
-component MDS \
-component STB \
-component OPSS \
-component IAU \
-component IAU_APPEND \
-component IAU_VIEWER \
-component UCSUMS \
-component WLS \
-component SOAINFRA \
-f < /tmp/passwordfile.txt
```
To finish, you connect to your Oracle DB instance, and run the clean-up script. The script is named `script_postDataLoad.sql`.
For more information, see [ Running Repository Creation Utility from the command line](https://docs.oracle.com/middleware/1221/core/RCUUG/GUID-0D3A2959-7CC8-4001-997E-718ADF04C5F2.htm#RCUUG248) in the Oracle documentation.
### Running RCU in interactive mode
To use the RCU graphical user interface, run RCU in interactive mode. Include the `-interactive` parameter and omit the `-silent` parameter. For more information, see [ Understanding Repository Creation Utility screens](https://docs.oracle.com/middleware/1213/core/RCUUG/rcu_screens.htm#RCUUG143) in the Oracle documentation.
**Example**
The following example starts RCU in interactive mode and pre-populates the connection information.
For Linux, macOS, or Unix:
```
export ORACLE_HOME=/u01/app/oracle/product/12.2.1.0/fmw
export JAVA_HOME=/usr/java/jdk1.8.0_65
${ORACLE_HOME}/oracle_common/bin/rcu \
-interactive \
-createRepository \
-connectString ${dbhost}:${dbport}:${dbname} \
-dbUser ${dbuser} \
-dbRole Normal
```
## Troubleshooting RCU
Be mindful of the following issues.
**Topics**
+ [
### Oracle Managed Files (OMF)
](#Oracle.Resources.RCU.KnownIssues.OMF)
+ [
### Object privileges
](#Oracle.Resources.RCU.KnownIssues.object-privs)
+ [
### Enterprise Scheduler Service
](#Oracle.Resources.RCU.KnownIssues.Scheduler)
### Oracle Managed Files (OMF)
Amazon RDS uses OMF data files to simplify storage management. You can customize tablespace attributes, such as size and extent management. However, if you specify a data file name when you run RCU, the tablespace code fails with `ORA-20900`. You can use RCU with OMF in the following ways:
+ In RCU 12.2.1.0 and later, use the `-honorOMF` command-line parameter.
+ In RCU 12.1.0.3 and later, use multiple steps and edit the generated script. For more information, see [Running RCU using the command line in multiple steps](#Oracle.Resources.RCU.SilentMulti).
### Object privileges
Because Amazon RDS is a managed service, you don't have full `SYSDBA` access to your RDS for Oracle DB instance. However, RCU 12c supports users with lower privileges. In most cases, the master user privilege is sufficient to create repositories.
The master account can directly grant privileges that it has already been granted `WITH GRANT OPTION`. In some cases, when you attempt to grant `SYS` object privileges, the RCU might fail with `ORA-01031`. You can retry and run the `rdsadmin_util.grant_sys_object` stored procedure, as shown in the following example:
```
BEGIN
rdsadmin.rdsadmin_util.grant_sys_object('GV_$SESSION','MY_DBA','SELECT');
END;
/
```
If you attempt to grant `SYS` privileges on the object `SCHEMA_VERSION_REGISTRY`, the operation might fail with `ORA-20199: Error in rdsadmin_util.grant_sys_object`. You can qualify the table `SCHEMA_VERSION_REGISTRY$` and the view `SCHEMA_VERSION_REGISTRY` with the schema owner name, which is `SYSTEM`, and retry the operation. Or, you can create a synonym. Log in as the master user and run the following statements:
```
CREATE OR REPLACE VIEW SYSTEM.SCHEMA_VERSION_REGISTRY
AS SELECT * FROM SYSTEM.SCHEMA_VERSION_REGISTRY$;
CREATE OR REPLACE PUBLIC SYNONYM SCHEMA_VERSION_REGISTRY FOR SYSTEM.SCHEMA_VERSION_REGISTRY;
CREATE OR REPLACE PUBLIC SYNONYM SCHEMA_VERSION_REGISTRY$ FOR SCHEMA_VERSION_REGISTRY;
```
### Enterprise Scheduler Service
When you use the RCU to drop an Enterprise Scheduler Service repository, the RCU might fail with `Error: Component drop check failed`.
# Configuring Oracle Connection Manager on an Amazon EC2 instance
Oracle Connection Manager (CMAN) is a proxy server that forwards connection requests to database servers or other proxy servers. You can use CMAN to configure the following:
Access control
You can create rules that filter out user-specified client requests and accept others.
Session multiplexing
You can funnel multiple client sessions through a network connection to a shared server destination.
Typically, CMAN resides on a host separate from the database server and client hosts. For more information, see [Configuring Oracle Connection Manager](https://docs.oracle.com/en/database/oracle/oracle-database/19/netag/configuring-oracle-connection-manager.html#GUID-AF8A511E-9AE6-4F4D-8E58-F28BC53F64E4) in the Oracle Database documentation.
**Topics**
+ [
## Supported versions and licensing options for CMAN
](#oracle-cman.Versions)
+ [
## Requirements and limitations for CMAN
](#oracle-cman.requirements)
+ [
## Configuring CMAN
](#oracle-cman.configuring-cman)
## Supported versions and licensing options for CMAN
CMAN supports the Enterprise Edition of all versions of Oracle Database that Amazon RDS supports. For more information, see [RDS for Oracle releases](Oracle.Concepts.database-versions.md).
You can install Oracle Connection Manager on a separate host from the host where Oracle Database is installed. You don't need a separate license for the host that runs CMAN.
## Requirements and limitations for CMAN
To provide a fully managed experience, Amazon RDS restricts access to the operating system. You can't modify database parameters that require operating system access. Thus, Amazon RDS doesn't support features of CMAN that require you to log in to the operating system.
## Configuring CMAN
When you configure CMAN, you perform most of the work outside of your RDS for Oracle database.
**Topics**
+ [
### Step 1: Configure CMAN on an Amazon EC2 instance in the same VPC as the RDS for Oracle instance
](#oracle-cman.configuring-cman.vpc)
+ [
### Step 2: Configure database parameters for CMAN
](#oracle-cman.configuring-cman.parameters)
+ [
### Step 3: Associate your DB instance with the parameter group
](#oracle-cman.configuring-cman.parameter-group)
### Step 1: Configure CMAN on an Amazon EC2 instance in the same VPC as the RDS for Oracle instance
To learn how to set up CMAN, follow the detailed instructions in the blog post [Configuring and using Oracle Connection Manager on Amazon EC2 for Amazon RDS for Oracle](https://aws.amazon.com/blogs/database/configuring-and-using-oracle-connection-manager-on-amazon-ec2-for-amazon-rds-for-oracle/).
### Step 2: Configure database parameters for CMAN
For CMAN features such as Traffic Director Mode and session multiplexing, set `REMOTE_LISTENER` parameter to the address of CMAN instance in a DB parameter group. Consider the following scenario:
+ The CMAN instance resides on a host with IP address `10.0.159.100` and uses port `1521`.
+ The databases `orcla`, `orclb`, and `orclc` reside on separate RDS for Oracle DB instances.
The following table shows how to set the `REMOTE_LISTENER` value. The `LOCAL_LISTENER` value is set automatically by Amazon RDS.
| DB instance name | DB instance IP | Local listener value (set automatically) | Remote listener value (set by user) |
| --- | --- | --- | --- |
| orcla | 10.0.159.200 | ( address=
(protocol=tcp)
(host=10.0.159.200)
(port=1521)
)
| 10.0.159.100:1521 |
| orclb | 10.0.159.300 | ( address=
(protocol=tcp)
(host=10.0.159.300)
(port=1521)
)
| 10.0.159.100:1521 |
| orclc | 10.0.159.400 | ( address=
(protocol=tcp)
(host=10.0.159.400)
(port=1521)
)
| 10.0.159.100:1521 |
### Step 3: Associate your DB instance with the parameter group
Create or modify your DB instance to use the parameter group that you configured in [Step 2: Configure database parameters for CMAN](#oracle-cman.configuring-cman.parameters). For more information, see [Associating a DB parameter group with a DB instance in Amazon RDS](USER_WorkingWithParamGroups.Associating.md).
# Installing a Siebel database on Oracle on Amazon RDS
You can use Amazon RDS to host a Siebel Database on an Oracle DB instance. The Siebel Database is part of the Siebel Customer Relationship Management (CRM) application architecture. For an illustration, see [ Generic architecture of Siebel business application](https://docs.oracle.com/cd/E63029_01/books/PerformTun/performtun_archinfra.htm#i1043361).
Use the following topic to help set up a Siebel Database on an Oracle DB instance on Amazon RDS. You can also find out how to use Amazon Web Services to support the other components required by the Siebel CRM application architecture.
**Note**
To install a Siebel Database on Oracle on Amazon RDS, you need to use the master user account. You don't need `SYSDBA` privilege; master user privilege is sufficient. For more information, see [Master user account privileges](UsingWithRDS.MasterAccounts.md).
## Licensing and versions
To install a Siebel Database on Amazon RDS, you must use your own Oracle Database license, and your own Siebel license. You must have the appropriate Oracle Database license (with Software Update License and Support) for the DB instance class and Oracle Database edition. For more information, see [RDS for Oracle licensing options](Oracle.Concepts.Licensing.md).
Oracle Database Enterprise Edition is the only edition certified by Siebel for this scenario. Amazon RDS supports Siebel CRM version 15.0 or 16.0.
Amazon RDS supports database version upgrades. For more information, see [Upgrading a DB instance engine version](USER_UpgradeDBInstance.Upgrading.md).
## Before you begin
Before you begin, you need an Amazon VPC. Because your Amazon RDS DB instance needs to be available only to your Siebel Enterprise Server, and not to the public Internet, your Amazon RDS DB instance is hosted in a private subnet, providing greater security. For information about how to create an Amazon VPC for use with Siebel CRM, see [Creating and connecting to an Oracle DB instance](CHAP_GettingStarted.CreatingConnecting.Oracle.md).
Before you begin, you also need an Oracle DB instance. For information about how to create an Oracle DB instance for use with Siebel CRM, see [Creating an Amazon RDS DB instance](USER_CreateDBInstance.md).
## Installing and configuring a Siebel database
After you create your Oracle DB instance, you can install your Siebel Database. You install the database by creating table owner and administrator accounts, installing stored procedures and functions, and then running the Siebel Database Configuration Wizard. For more information, see [ Installing the Siebel database on the RDBMS](https://docs.oracle.com/cd/E63029_01/books/SiebInstWIN/SiebInstCOM_ConfigDB.html).
To run the Siebel Database Configuration Wizard, you need to use the master user account. You don't need `SYSDBA` privilege; master user privilege is sufficient. For more information, see [Master user account privileges](UsingWithRDS.MasterAccounts.md).
## Using other Amazon RDS features with a Siebel database
After you create your Oracle DB instance, you can use additional Amazon RDS features to help you customize your Siebel Database.
### Collecting statistics with the Oracle Statspack option
You can add features to your DB instance through the use of options in DB option groups. When you created your Oracle DB instance, you used the default DB option group. If you want to add features to your database, you can create a new option group for your DB instance.
If you want to collect performance statistics on your Siebel Database, you can add the Oracle Statspack feature. For more information, see [Oracle Statspack](Appendix.Oracle.Options.Statspack.md).
Some option changes are applied immediately, and some option changes are applied during the next maintenance window for the DB instance. For more information, see [Working with option groups](USER_WorkingWithOptionGroups.md). After you create a customized option group, modify your DB instance to attach it. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
### Performance tuning with parameters
You manage your DB engine configuration through the use of parameters in a DB parameter group. When you created your Oracle DB instance, you used the default DB parameter group. If you want to customize your database configuration, you can create a new parameter group for your DB instance.
When you change a parameter, depending on the type of the parameter, the changes are applied either immediately or after you manually reboot the DB instance. For more information, see [Parameter groups for Amazon RDS](USER_WorkingWithParamGroups.md). After you create a customized parameter group, modify your DB instance to attach it. For more information, see [Modifying an Amazon RDS DB instance](Overview.DBInstance.Modifying.md).
To optimize your Oracle DB instance for Siebel CRM, you can customize certain parameters. The following table shows some recommended parameter settings. For more information about performance tuning Siebel CRM, see [Siebel CRM Performance Tuning Guide](https://docs.oracle.com/cd/E63029_01/books/PerformTun/toc.htm).
****
| Parameter name | Default value | Guidance for optimal Siebel CRM performance |
| --- | --- | --- |
| \$1always\$1semi\$1join | `CHOOSE` | `OFF` |
| \$1b\$1tree\$1bitmap\$1plans | `TRUE` | `FALSE` |
| \$1like\$1with\$1bind\$1as\$1equality | `FALSE` | `TRUE` |
| \$1no\$1or\$1expansion | `FALSE` | `FALSE` |
| \$1optimizer\$1join\$1sel\$1sanity\$1check | `TRUE` | `TRUE` |
| \$1optimizer\$1max\$1permutations | 2000 | 100 |
| \$1optimizer\$1sortmerge\$1join\$1enabled | `TRUE` | `FALSE` |
| \$1partition\$1view\$1enabled | `TRUE` | `FALSE` |
| open\$1cursors | `300` | At least **2000**. |
### Creating snapshots
After you create your Siebel Database, you can copy the database by using the snapshot features of Amazon RDS. For more information, see [Creating a DB snapshot for a Single-AZ DB instance for Amazon RDS](USER_CreateSnapshot.md) and [Restoring to a DB instance](USER_RestoreFromSnapshot.md).
## Support for other Siebel CRM components
In addition to your Siebel Database, you can also use Amazon Web Services to support the other components of your Siebel CRM application architecture. You can find more information about the support provided by Amazon AWS for additional Siebel CRM components in the following table.
****
| Siebel CRM component | Amazon AWS Support |
| --- | --- |
| Siebel Enterprise(with one or more Siebel Servers) | You can host your Siebel Servers on Amazon Elastic Compute Cloud (Amazon EC2) instances. You can use Amazon EC2 to launch as many or as few virtual servers as you need. Using Amazon EC2, you can scale up or down easily to handle changes in requirements. For more information, see [What is Amazon EC2?](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/concepts.html) You can put your servers in the same VPC with your DB instance and use the VPC security group to access the database. For more information, see [Working with a DB instance in a VPC](USER_VPC.WorkingWithRDSInstanceinaVPC.md). |
| Web Servers(with Siebel Web Server Extensions) | You can install multiple Web Servers on multiple EC2 instances. You can then use Elastic Load Balancing to distribute incoming traffic among the instances. For more information, see [What is Elastic Load Balancing?](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/elastic-load-balancing.html) |
| Siebel Gateway Name Server | You can host your Siebel Gateway Name Server on an EC2 instance. You can then put your server in the same VPC with the DB instance and use the VPC security group to access the database. For more information, see [Working with a DB instance in a VPC](USER_VPC.WorkingWithRDSInstanceinaVPC.md). |
# Oracle Database engine release notes
Updates to your Amazon RDS for Oracle DB instances keep them current. If you apply updates, you can be confident that your DB instance is running a version of the database software that has been tested by both Oracle and Amazon. We don't support applying one-off patches to individual RDS for Oracle DB instances.
You can specify any currently supported Oracle Database version when you create a new DB instance. You can specify the major version, such as Oracle Database 19c, and any supported minor version for the specified major version. If no version is specified, Amazon RDS defaults to a supported version, typically the most recent version. If a major version is specified but a minor version is not, Amazon RDS defaults to a recent release of the major version that you have specified. To see a list of supported versions and defaults for newly created DB instances, use the [https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-engine-versions.html](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-engine-versions.html) AWS CLI command.
For details about the Oracle Database versions that Amazon RDS supports, see the [https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html](https://docs.aws.amazon.com/AmazonRDS/latest/OracleReleaseNotes/Welcome.html).