About External Databases

You can manage and monitor Oracle Databases that are located outside of Oracle Cloud Infrastructure (OCI) using external databases. External database enables you use cloud-based tools such as Database Management with your external databases. External database can be used with both single-instance Oracle Databases and Oracle RAC instances.

To manage an external database, you create an OCI resource known as a "handle" that represents the external database within your tenancy. After creating a handle for your database, you create a second resource called a database connection. The connection stores the information required for your OCI tenancy to connect to the external database. After creating the connection resource and connecting the OCI handle to your external database instance, you can enable the Database Management service to monitor the health and performance of your database.

For more information, see:

The OCI Database Management service also facilitates the monitoring of the external database ecosystem, the discovery of external Oracle Database systems, and the monitoring and management of database system components.

For more information, see:

OCI External Database Handle

You can create an OCI external database handle for the following types of external databases:

  • External container databases
  • External pluggable databases
  • External non-container databases

The handle stores a few pieces of metadata that enable you to manage your database instance within OCI. This metadata includes the following information related to managing the handle in OCI:

  • An Oracle Cloud ID (OCID), which enables the external database instance to be identified and managed within OCI.
  • An OCI display name.
  • Compartment assignment information (optional).
  • Tags (optional).

For more information, see:

In addition to the OCI-related metadata, the handle stores metadata derived from the database instance. This includes the database unique name, the Oracle Database software edition and version, and other details. All of this information stored by the handle can be viewed in the OCI Console or retrieved using the API. Metadata derived from the external database instance (such as database unique name) is only populated in the handle after a database connection is established between the handle and the instance.

Scanning an External Container Database to Discover Pluggable Databases

After you create and connect an external container database handle, you can use the handle to scan the external container database and discover pluggable databases that have not been connected to OCI. If any pluggable databases are discovered that are not connected to OCI, the connection details for these databases are listed in the work request generated by the scan operation.

For more information, see:

OCI Database Connection Resource

The OCI database connection resource stores details about how a specific handle connects to an external Oracle Database instance. These details include the following:

  • Connection type and OCI agent ID
  • User credentials and role
  • Connection strings information, including the following:
    • DNS hostname, single-client access name (SCAN), or virtual IP (VIP) address
    • Port
    • Service name
    • Network protocol (TCP or TCPS)

      • TCPS is TCP/IP with SSL. This protocol enables an Oracle application on a client to communicate with remote databases through TCP/IP and SSL. Using SSL provides higher security than TCP alone. For more information, see TCP/IP with SSL Protocol in Database Net Services Administrator's Guide.
      • If you use TCPS, you must provide a database user password and password secret, along with the following:
        • regular database credentials
        • the ssl key and trust store wallet locations on the management agent and their passwords
        • distinguished name values.

        All SSL details are accepted through the secret resource.

You can create an OCI external database connection resource for the following types of external databases:

  • External container databases
  • External pluggable databases
  • External non-container databases

For more information, see:


To use the OCI external database, you will need the following:

  • An OCI tenancy.
  • One or more external databases located outside of OCI. OCI external database supports container databases, pluggable databases, and non-container databases that use the following Oracle Database software versions: 11gR2, 12cR1, 12cR2, 18c, and 19c.
  • A Management Agent service agent with source credentials.

Using the OCI external database with database clones, standby databases, or databases with high availability or disaster recovery is currently not supported.

For more information, see:

Required IAM Policy for Management Agent Communication

The OCI Management Agent is required to create a connection with an external database. It is also required to enable the communication and data collection between an external database and other OCI services such as Database Management, Operations Insights, and the Monitoring service.

A Management Agent permission is required to allow a user in a particular user group to manage the management-agents resource-type in a specific compartment:

ALLOW GROUP <group_name> TO MANAGE management-agents IN COMPARTMENT <compartment_name>

In addition, you must create a dynamic group for all the management agents to be used by the external database. This is required to allow the external database to interact with the OCI service endpoints. A dynamic group is created using the IAM service from the OCI Console.

When creating a dynamic group, you can define a rule that will ensure that all the management agents in a compartment or in the tenancy are added to the dynamic group. This will ensure that this step is a one-time setup step and any new management agent being installed will automatically belong to the dynamic group.

Example: Create a dynamic group named Management_Agent_Dynamic_Group with the following under Rule 1:

ALL {resource.type='managementagent', resource.compartment.id='ocid1.compartment.oc1.examplecompartmentid'}

Where resource.type='managementagent' is the management agent resource-type definition for Management Agent at the dynamic group level, and resource.compartment.id value is the compartment OCID.

This can also be created more generically to cover agents from all compartments of the tenancy:

ALL {resource.type='managementagent'}

Once the dynamic group is created, you must create policies to allow the management agents to interact with the Management Agent service and to allow the management agents to upload data to OCI Monitoring service.

Table 1-1 Policies

Policy Statement Description
ALLOW DYNAMIC-GROUP <dynamic_group_name> TO MANAGE management-agents IN COMPARTMENT <compartment_name> Allows management agents to interact with Management Agent cloud service in the specific compartment.
ALLOW DYNAMIC-GROUP <dynamic_group_name> TO USE METRICS IN COMPARTMENT <compartment_name> where target.metrics.namespace='oracle_oci_database' Allows management agents to upload data to OCI Monitoring service in the specific compartment.
ALLOW DYNAMIC-GROUP <dynamic_group_name> TO USE tag-namespaces in compartment <compartment_name> Optional. Required only if you specify tags at the time of the management agent installation.

Example: The following commands allow Management_Agent_Dynamic_Group dynamic group to interact with the Management Agent service in Agents_Compartment compartment, and upload data to the Monitoring service.

ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO MANAGE management-agents IN COMPARTMENT Agents_Compartment
ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO USE METRICS IN COMPARTMENT Agents_Compartment

You may need to add similar policies if your service expects the management agent to deposit data to different services. For more information about service-specific requirements, see service-specific documentation.