External Database Service

You can manage and monitor Oracle Databases that are located outside of Oracle Cloud Infrastructure (OCI) using OCI's External Database service. External Database allows 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.

Associated Services Available for External Databases

External databases can utilize services including Database Management, Operations Insights, and Application Performance Monitoring for analysis, management, and application monitoring.

See Managing Associated Services for External Databases for instructions on enabling and disabling these services for an external database.

Database Management Service

As a database administrator, you can use the Oracle Cloud Infrastructure Database Management service to monitor and manage your Oracle Databases. Database Management supports Oracle Database versions and later. Using Database Management you can:

  • Monitor the key performance and configuration metrics of your fleet of Oracle Databases. You can also compare and analyze database metrics over a selected period of time.
  • Group your critical Oracle Databases, which reside across compartments into a Database Group, and monitor them.
  • Create SQL jobs to perform administrative operations on a single Oracle Database or a Database Group.
  • Use Performance Hub to monitor database performance and diagnose performance issues such as determining the causes of wait time, performance degradation, and changes in database performance. For detailed information, see Using Performance Hub to Analyze Database Performance.

For complete documentation on the Database Management service, see Database Management.

Operations Insights Service

Operations Insights provides 360-degree insight into the resource utilization and capacity of databases and hosts. You can easily analyze CPU and storage resources, forecast capacity issues, and proactively identify SQL performance issues across your database fleet. See the Operations Insights documentation for complete details. Operations Insights can be enabled for external pluggable database and non-container database resources.

Stack Monitoring

By enabling Stack Monitoring for your External Database, you can get real-time information on the performance of your applications. This allows you to diagnose issues quickly across your software stack. You can set up dashboards to visualize, explore, and analyze application data in easy-to-interpret charts. The service also allows you to collect and upload key application metrics for use in creating notifications and alarms.

For complete documentation on Stack Monitoring and the associated Application Performance Monitoring service, see the following sections of the OCI user guide:

How the External Database Service Works

To manage an external database using OCI's External Database service, 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.

The OCI External Database Handle

You can create an Oracle Cloud Infrastructure 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 allow you to manage your database instance within OCI. This metadata includes the following information related to managing the handle in OCI:

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

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 Oracle Cloud Infrastructure, the connection details for these databases are listed in the work request generated by the scan operation. See To scan an external container database for pluggable databases for more information.

The 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 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 the TCPS explanation in the Oracle 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.

  • Connection type and OCI agent ID
  • User credentials and role

Creating an OCI Database Connection Resource

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


To use the External Database service, you will need the following:

  • An Oracle Cloud Infrastructure (OCI) tenancy. See Setting Up Your Tenancy for information if you do not currently use OCI.
  • One or more external databases located outside of OCI. The External Database service supports container databases, pluggable databases, and non-container databases that use the following Oracle Database software versions: 11gR2, 12cR1, 12cR2, 18c, and 19c. You can use the External Database service with database clones and with high-availability / disaster recovery databases standby databases.
  • A Management Agent Cloud Service agent with source credentials. See the Management Agent documentation for details on creating this resource in OCI.

Required IAM Policy for Management Agent Communication

The Oracle Cloud Infrastructure (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>

For more information on the Management Agent service resource-types and permissions, see the following Oracle Cloud Infrastructure Identity and Access Management (IAM) topics:

See Documentation to Use for Cloud Identity if you aren't sure whether your region uses identity domains.

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. See the following topics for information about dynamic groups and how to create them.

Regions without identity domains:

Regions with identity domains:

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.

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.

For 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

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