Oracle Cloud Infrastructure Documentation

DBMS_CLOUD_LINK_ADMIN Package

The DBMS_CLOUD_LINK_ADMIN package allows the ADMIN user to enable a database user to register data sets or to access registered data sets for a given Autonomous Database instance, subject to the access restrictions as defined with the granted scope.

Privileges can also be disabled for a user that has the privileges set to register data sets or access registered data sets.

DBMS_CLOUD_LINK_ADMIN Overview

Describes use of the DBMS_CLOUD_LINK_ADMIN package.

Cloud Links provide a cloud-based method to remotely access read only data on an Autonomous Database instance. The DBMS_CLOUD_LINK_ADMIN package leverages Oracle Cloud Infrastructure access mechanisms to make data sets accessible within a specific scope and in addition there is a optional authorization step.

Summary of DBMS_CLOUD_LINK_ADMIN Subprograms

This table summarizes the subprograms included in the DBMS_CLOUD_LINK_ADMIN package.

Subprogram Description

ADD_SERVICE_MAPPING Procedure

The procedure associates a Cloud Links consumer database with a database service.
GRANT_AUTHORIZE Procedure

Grants a user the permission to invoke DBMS_CLOUD_LINK.GRANT_AUTHORIZATION and DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION procedures.

GRANT_READ Procedure

Allows a user to read registered data sets, subject to access restrictions imposed on data sets at registration.

GRANT_REGISTER Procedure

Allows a user to register a data set for remote access.

REMOVE_SERVICE_MAPPING Procedure

Remove a service mapping for a specified database.

REVOKE_AUTHORIZE Procedure

Revokes a user's permission to invoke DBMS_CLOUD_LINK.GRANT_AUTHORIZATION and DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION procedures.

REVOKE_READ Procedure

Disallows a user from accessing registered data sets of the Autonomous Database instance.

REVOKE_REGISTER Procedure

Disallows a user from registering data sets for remote access. Data sets that were already registered by the user are unaffected.

ADD_SERVICE_MAPPING Procedure

The procedure DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING associates a consumer database with a database service.

Syntax

DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING(
      database_id        IN   VARCHAR2,
      service_name       IN   VARCHAR2
);

Parameters

Parameter Description

database_id

Specifies the database ID for an Autonomous Database instance that is a Cloud Link consumer. Use DBMS_CLOUD_LINK.GET_DATABASE_ID to obtain the database ID.

The value "ANY" associates the specified service_name value with all consumer databases that do not have an entry that matches their database identifier. That is, any database_id whose service_name has not been set with DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING.

Valid values: a database ID or "ANY".

service_name

Specifies the database service name.

Valid values are: TP, TPURGENT, HIGH, MEDIUM, LOW.

Usage Notes

  • Only the ADMIN user and schemas with PDB_DBA role can run DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING.

  • You must run DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING on the data set owner's Autonomous Database instance.

GRANT_AUTHORIZE Procedure

The procedure grants a user permission to invoke the DBMS_CLOUD_LINK.GRANT_AUTHORIZATION and DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION procedures.

Syntax

DBMS_CLOUD_LINK_ADMIN.GRANT_AUTHORIZE(
      username        IN   VARCHAR2
);

Parameters

Parameter Description

username

Specifies a username.

Usage Notes

  • To enable authorization for a data set with DBMS_CLOUD_LINK.GRANT_AUTHORIZATION, you have to have granted the privilege with DBMS_CLOUD_LINK_ADMIN.GRANT_AUTHORIZE. This is true for ADMIN user as well; however ADMIN user can grant this privilege to themself.

GRANT_READ Procedure

The procedure allows a user to read registered data sets, subject to the access restrictions imposed on data sets when a data set is registered using DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER.

Syntax

DBMS_CLOUD_LINK_ADMIN.GRANT_READ(
      username        IN   VARCHAR2
);

Parameters

Parameter Description

username

Specifies a username.

Usage Notes

  • To read data sets, you have to have granted the privilege with DBMS_CLOUD_LINK_ADMIN.GRANT_READ. This is true for ADMIN user as well; however ADMIN user can grant this privilege to themself.

  • A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') to check if they are enabled for READ access to a data set.

    For example, the following query:

    SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') FROM DUAL;

    Returns 'YES' or 'NO'.

GRANT_REGISTER Procedure

The procedure allows a user to register a data set for remote access.

Syntax

DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER(
      username        IN   VARCHAR2,
      scope           IN   CLOB
);

Parameters

Parameter Description

username

Specifies a user name.

scope

Specifies the scope in which permissions to publish are to be granted to the specified user.

Valid values are:

  • 'MY$REGION'
  • 'MY$TENANCY'
  • 'MY$COMPARTMENT'

Usage Notes

  • To register data sets, you have to have granted the privilege with DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER. This is true for ADMIN user as well; however ADMIN user can grant this privilege to themself.

  • A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') to check if they are enabled for registering data sets.

    For example, the following query:

    SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') FROM DUAL;

    Returns 'YES' or 'NO'.

REMOVE_SERVICE_MAPPING Procedure

The procedure DBMS_CLOUD_LINK_ADMIN.REMOVE_SERVICE_MAPPING removes a service mapping for a specified database.

Syntax

DBMS_CLOUD_LINK_ADMIN.REMOVE_SERVICE_MAPPING(
      database_id        IN   VARCHAR2
);

Parameters

Parameter Description

database_id

Specifies the database ID for an Autonomous Database instance. Use DBMS_CLOUD_LINK.GET_DATABASE_ID to obtain the database ID.

The value "ANY" removes any specified service_name value with all consumer databases that do not have an entry that matches their database identifier. That is, any database_id whose service_name has not been set with DBMS_CLOUD_LINK_ADMIN.ADD_SERVICE_MAPPING.

Valid values: a database ID or "ANY".

Usage Note

Only the ADMIN user and schemas with PDB_DBA role can run DBMS_CLOUD_LINK_ADMIN.REMOVE_SERVICE_MAPPING.

REVOKE_AUTHORIZE Procedure

This procedure disallows a user from invoking DBMS_CLOUD_LINK.GRANT_AUTHORIZATION and DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION procedures.

Syntax

DBMS_CLOUD_LINK_ADMIN.REVOKE_AUTHORIZE(
      username        IN   VARCHAR2
);

Parameters

Parameter Description

username

Specifies a username.

REVOKE_READ Procedure

This procedure disallows a user from accessing registered data sets on the Autonomous Database instance.

Syntax

DBMS_CLOUD_LINK_ADMIN.REVOKE_READ(
      username        IN   VARCHAR2
);

Parameters

Parameter Description

username

Specifies a username.

Usage Note

  • A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') to check if they are enabled for READ access to a data set.

    For example, the following query:

    SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') FROM DUAL;

    Returns 'YES' or 'NO'.

REVOKE_REGISTER Procedure

The procedure disallows a user from registering data sets for remote access. Data sets that were already registered by the user are unaffected.

Syntax

DBMS_CLOUD_LINK_ADMIN.REVOKE_REGISTER(
      username        IN   VARCHAR2
);

Parameters

Parameter Description

username

Specifies a user name.

Usage Note

  • A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') to check if they are enabled for registering data sets.

    For example, the following query:

    SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') FROM DUAL;

    Returns 'YES' or 'NO'.