Creating and Managing an External Database Connection

This topic provides information on managing Oracle Cloud Infrastructure (OCI) external database connections using the OCI Console and API. The external database connection resource allows you to connect an OCI external database handle to an Oracle Database instance located outside of OCI. See External Database Service for more information about the External Database service and the database connection resource.

Note

Currently the External Database service supports only Management Agent Cloud Service (MACS) agents for creating a connection to your external databases. Enterprise Manager Cloud Control Agents are not supported at this time.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators: The policy in Let database admins manage Oracle Cloud external database resources lets the specified group do everything with databases and related Database resources.

If you're new to policies, see Getting Started with Policies and Common Policies. For more information about writing policies for databases, see Details for the Database Service.

Using the Console

To create a connection for an OCI external pluggable database resource
  1. Open the navigation menu. Click Oracle Database, then click External Database.
  2. Choose your Compartment.
  3. Under External Databases, click Pluggable Databases.
  4. In the list of OCI external pluggable database resources (also called "handles"), click the display name of the handle you want to create a connection for.
  5. Click Connect to External Pluggable Database.

    The Connect to an external pluggable database dialog opens.

  6. Enter a connector display name. This is a user-friendly name to help you easily identify the resource.
  7. Enter a DNS hostname, single client access name (SCAN), or virtual IP (VIP) address for the database on your premises that you are connecting to Oracle Cloud Infrastructure.
  8. Enter the port being used by the database outside of Oracle Cloud Infrastructure for database connections.
  9. Enter the service name for the database outside of Oracle Cloud Infrastructure that will be used by the connection.
  10. Enter the connection agent ID. See Management Agent for more information about this Oracle Cloud Infrastructure feature.
  11. Enter the Username for the database credentials that will be used by this connection.
  12. Enter the Password for the database credentials that will be used by this connection.
  13. Enter a Credential name prefix. This string is the first part of the full credential name. Your prefix is prepended to a system-generated Credential name prefix to create the full credential name.
  14. Enter the Role for the database credentials that will be used by this connection.
  15. Click Show Advanced Options to specify the following options for the database:

    Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.

  16. Click Connect to External Pluggable Database.
To create a connection for an OCI external container database resource
  1. Open the navigation menu. Click Oracle Database, then click External Database.
  2. Choose your Compartment.
  3. Under External Databases, click Container Databases.
  4. In the list of OCI external container database resources (also called "handles"), click the display name of the handle you want to create a connection for.
  5. Click Connect to External Pluggable Database.

    The Connect to an external pluggable database dialog opens.

  6. Enter a connection display name. This is a user-friendly name to help you easily identify the resource.
  7. Enter a DNS hostname, single client access name (SCAN), or virtual IP (VIP) address for the database on your premises that you are connecting to Oracle Cloud Infrastructure.
  8. Enter the port being used by the database outside of Oracle Cloud Infrastructure for database connections.
  9. Enter the service name for the database outside of Oracle Cloud Infrastructure that will be used by the connection.
  10. Enter the connection agent ID. See Management Agent for more information about this Oracle Cloud Infrastructure feature.
  11. Enter the Username for the database credentials that will be used by this connection.
  12. Enter the Password for the database credentials that will be used by this connection.
  13. Enter a Credential name prefix. This string is the first part of the full credential name. Your prefix is prepended to a system-generated Credential name prefix to create the full credential name.
  14. Enter the Role for the database credentials that will be used by this connection.
  15. Click Show Advanced Options to specify the following options for the database:

    Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.

  16. Click Connect to External Pluggable Database.
To create a connection for an OCI external non-container database resource
  1. Open the navigation menu. Click Oracle Database, then click External Database.
  2. Choose your Compartment.
  3. Under External Databases, click Non-Container Databases.
  4. In the list of OCI external non-container database resources (also called "handles"), click the display name of the handle you want to create a connection for.
  5. Click Connect to External Non-Container Database.

    The Connect to an Connect to an external non-container database dialog opens.

  6. Enter a connection display name. This is a user-friendly name to help you easily identify the resource.
  7. Enter a DNS hostname, single client access name (SCAN), or virtual IP (VIP) address for the database on your premises that you are connecting to Oracle Cloud Infrastructure.
  8. Enter the port being used by the database outside of Oracle Cloud Infrastructure for database connections.
  9. Enter the service name for the database outside of Oracle Cloud Infrastructure that will be used by the connection.
  10. Enter the connection agent ID. See Management Agent for more information about this Oracle Cloud Infrastructure feature.
  11. Enter the Username for the database credentials that will be used by this connection.
  12. Enter the Password for the database credentials that will be used by this connection.
  13. Enter a Credential name prefix. This string is the first part of the full credential name. Your prefix is prepended to a system-generated Credential name prefix to create the full credential name.
  14. Enter the Role for the database credentials that will be used by this connection.
  15. Click Show Advanced Options to specify the following options for the database:

    Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator.

  16. Click Connect to External Non-Container Database.
To check the connection status of an external database connection
  1. Open the navigation menu. Click Oracle Database, then click External Database.
  2. Choose your Compartment.
  3. Under External Databases, click either Pluggable Database, Container Databases, or Non-Container Databases, depending on the type of external database you are using.
  4. In the list of external database handles, click the name of the handle you want to check the connection status of.
  5. On the Database Details page, under Resources, click Connections.
  6. In the list of database connections, click the name of the connection you want to check the status of.
  7. Click Check Connection Status. A "Check Connection Status" work request is created. Click on the work request name to see details of the connection status.
To update the connection credentials of an external database handle
  1. Open the navigation menu. Click Oracle Database, then click External Database.
  2. Choose your Compartment.
  3. Under External Databases, click either Pluggable Database, Container Databases, or Non-Container Databases, depending on the type of external database handle connection you are updating.
  4. In the list of external database handles, click on the name of the handle associated with the connection you want to update.
  5. On the external database details page, under Resources, click Connections.
  6. In the list of connections, click the name of the connection you want to update.
  7. On the External Connection Details page, click Update Connection Credentials.
  8. In the Update credentials dialog, enter the following information:

    • Username
    • Password
    • Role
  9. Click Update Credentials.
To update the connection strings of an external database handle
  1. Open the navigation menu. Click Oracle Database, then click External Database.
  2. Choose your Compartment.
  3. Under External Databases, click either Pluggable Database, Container Databases, or Non-Container Databases, depending on the type of external database handle connection you are updating.
  4. In the list of external database handles, click on the name of the handle associated with the connection you want to update.
  5. On the external database details page, under Resources, click Connections.
  6. In the list of connections, click the name of the connection you want to update.
  7. On the External Connection Details page, click Update Connection Strings.
  8. In the Update connection strings dialog, enter the following information:

    • DNS hostname
    • Port
    • Service
  9. Click Update Connection Strings.
To delete an external database connection
  1. Open the navigation menu. Click Oracle Database, then click External Database.
  2. Choose your Compartment.
  3. Under External Databases, click either Pluggable Database, Container Databases, or Non-Container Databases, depending on the type of external database handle you are deleting.
  4. In the list of external database handles, click on the name of the handle associated with the connection you want to delete.
  5. On the external database details page, under Resources, click Connections.
  6. In the list of connections, click the name of the connection you want to delete.
  7. On the External Connection Details page, click Delete.