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. Oracle recommends that you use a user-friendly name to help you easily identify the resource.
  7. Select a connector type. For TCPS, select MACS (OCI Management Agent Cloud Service).
  8. Select a Connector agent ID from the menu. See Management Agent for more information about this Oracle Cloud Infrastructure feature.
  9. Specify connection string information for the connection.
    1. 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 the Oracle Cloud Infrastructure.
    2. Enter the port being used by the database outside Oracle Cloud Infrastructure for database connections.
    3. Enter the service name for the database outside Oracle Cloud Infrastructure to be used by the connection.
    4. Select the Protocol: either TCP or TCPS from the menu.
      Note

      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 theTCPS explanation in the Oracle Database Net Services Administrator's Guide.
  10. Enter the database connection credentials.
    1. Enter the Username for the database credentials to be used by this connection.
    2. Enter the Password for the database credentials to be used by this connection.
    3. 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.
    4. Enter the Role for the database credentials to be used by this connection.
      Note

      If needed, you can change the connection credentials. See To update the connection credentials of an external database handle.
  11. 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.

  12. 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 Container Database.

    The Connect to an External Container Database dialog box opens.

  6. Enter a connector display name. Oracle recommends that you use a user-friendly name to help you easily identify the resource.
  7. Select a connector type. For TCPS, select MACS (OCI Management Agent Cloud Service).
  8. Select a Connector agent ID from the menu. See Management Agent for more information about this Oracle Cloud Infrastructure feature.
  9. Specify connection string information for the connection.
    1. 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.
    2. Enter the port being used by the database outside of Oracle Cloud Infrastructure for database connections.
    3. Enter the service name for the database outside of Oracle Cloud Infrastructure to be used by the connection.
    4. Select the Protocol: either TCP or TCPS from the menu.
      Note

      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.
  10. Enter the database connection credentials.
    1. Enter the Username for the database credentials to be used by this connection.
    2. Enter the Password for the database credentials to be used by this connection.
    3. 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.
    4. Enter the Role for the database credentials to be used by this connection.
      Note

      If needed, you can change the connection credentials. See To update the connection credentials of an external database handle.
  11. 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.

  12. Click Connect to External Container 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 Oracle Cloud Infrastructure (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 external non-container database dialog box opens.

  6. Enter a connection display name. Oracle recommends that you use a user-friendly name to help you easily identify the resource.
  7. Select a connector type. For TCPS, select MACS (OCI Management Agent Cloud Service).
  8. Select a Connector agent ID from the menu. See Management Agent for more information about this Oracle Cloud Infrastructure feature.
  9. Specify connection string information for the connection.
    1. 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.
    2. Enter the port being used by the database outside of Oracle Cloud Infrastructure for database connections.
    3. Enter the service name for the database outside of Oracle Cloud Infrastructure to be used by the connection.
    4. Select the Protocol: either TCP or TCPS from the menu.
      Note

      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 theTCPS explanation in the Oracle Database Net Services Administrator's Guide.
  10. Enter the database connection credentials.
    1. Enter the Username for the database credentials to be used by this connection.
    2. Enter the Password for the database credentials to be used by this connection.
    3. 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.
    4. Enter the Role for the database credentials to be used by this connection.
  11. 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.

  12. 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 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 box, optionally edit or enter any or all the following information:

    • Username
    • Password
    • Role
    • Secret (if the connector was created using TCPS)
      • Click either Select a new secret or Modify current secret.
      • If you click Select a new secret, use the menu to display the existing secrets and click the wanted secret name.
      • If you click Modify current secret, the Modify current secret dialog box is displayed.
      • Enter the following information:
        • SSL Trust Store Type
        • SSL Trust Store Location
        • SSL Trust Store Password
        • SSL Key Store Type
        • SSL Key Store Location
        • SSL Key Store Password
        • SSL Server Certificate Distinguished Name
      • Click Modify current secret.
  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 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
    • Protocol - read-only. The protocol is set when you create a connection and cannot be changed.
  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.