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