17 Support for Pluggable Databases
The multitenant architecture enables an Oracle database to contain a portable collection of schemas, schema objects, and nonschema objects that appear to an Oracle client as a separate database.
A multitenant container database (CDB) is an Oracle database that includes one or more pluggable databases (PDBs).
OCI clients can connect to a PDB using a service whose pluggable database property has been set to the relevant PDB.
-
Enhancements on OCI API Calls with Multitenant Container Databases (CDB) in General
-
Restrictions on OCI API Calls with Multitenant Container Databases (CDB) in General
-
Restrictions on OCI Calls with ALTER SESSION SWITCH CONTAINER SWITCH SERVICE
See Also:
Oracle Database Administrator’s Guide for more information about PDBs and for more details about configuring the services to connect to various PDBs
17.1 Enhancements on OCI API Calls with Multitenant Container Databases (CDB) in General
These enhancements are the result of restrictions that are now removed for Oracle Database 12c Release 2 (12.2) and later.
The following enhancements are the result of restrictions that are now removed for Oracle Database 12c Release 2 (12.2) and later.
-
Client result cache works with connections to Pluggable Databases.
17.2 OCI Enhancements for ALTER SESSION SET CONTAINER
Some OCI restrictions about using the ALTER SESSION SET CONTAINER
statement are removed.
The client must be Oracle Database Release 12c Release 2 (12.2) to perform these operations. Lower version clients are returned an error if any of the following operations is attempted.
-
The
ALTER SESSION SET CONTAINER
statement supports applications that useTIMESTAMP WITH TIMEZONE
orTIMESTAMP WITH LOCAL TIMEZONE
data types in OCI. The semantics of these types are preserved when the application switches between pluggable databases having different database time zone settings or different database time zone file version settings. -
The
ALTER SESSION SET CONTAINER
statement supports the use of this command to switch an OCI connection between any two pluggable databases whose character sets are different.
17.3 Restrictions on OCI API Calls with Multitenant Container Databases (CDB) in General
Descriptions general restrictions.
-
An attempt to logon in
OCI_PRELIM_AUTH
mode when connected to any container other thanCDB$ROOT
will result in anORA-24542
error. -
An attempt to issue
OCIDBStartup()
when connected to any container other thanCDB$ROOT
results in anORA-24543
error. -
An attempt to issue
OCIDBShutdown()
when connected to any container other thanCDB$ROOT
results in anORA-24543
error. WhenOCIDBShutdown()
is issued connected toCDB$ROOT
, it brings down the whole instance. -
OCI Continuous Query Notification (CQN) is not supported with CDB.
-
OCI applications linked against a client library older than release 12.1 or higher and connecting to a pluggable database will not be able to utilize Fast Application Notification (FAN) High Availability (HA) functionality when connected as a normal (non-common) user. As a workaround, such applications should connect as a common user. This restriction does not exist for release 12.1 or higher OCI clients.
See Also:
17.4 Restrictions on OCI Calls with ALTER SESSION SET CONTAINER
Describes specific restrictions.
The ALTER SESSION SET CONTAINER
statement can be used to switch an OCI connection from one pluggable database to another. However, applications that use the ALTER SESSION SET CONTAINER
statement to switch between pluggable databases need to ensure that their usage is consistent with the OCI restrictions described as follows.
-
The
ALTER SESSION SET CONTAINER
statement is disallowed for OCI migratable sessions (such as sessions created withOCI_MIGRATE
mode during logon) and the combination results in anORA-65135
error. -
The
ALTER SESSION SET CONTAINER
statement is not supported with OCI connection pool (which is the old OCI connection pool API) and the combination results in anORA-65135
error. -
The
ALTER SESSION SET CONTAINER
statement is not supported in conjunction with OCI session switching (wherein multiple OCI user handles share the same OCI server handle). -
If the client initially connects to a container with a
EXTENDED MAX_STRING_SIZE
setting, and then within the same session switches to a container (using anALTER SESSION SET CONTAINER
statement) with anSTANDARD MAX_STRING_SIZE
setting, then a subsequentOCIStmtExecute()
call will result in anORA-14697
error if an attempt is made to use any bind variables of size greater than 4000 bytes. -
An attempt to fetch from an OCI statement handle using
OCIStmtFetch()
orOCIStmtFetch2()
in the context of a different container than the one in which it was executed will result in anORA-65108
error. -
OCI client result cache is disabled if an
ALTER SESSION SET CONTAINER
statement is done in OCI. -
Fast Application Notification (FAN) and Runtime Connection Load Balancing notifications are not supported for applications that switch connections between pluggable databases using an
ALTER SESSION SET CONTAINER
statement. -
The
ALTER SESSION SET CONTAINER
statement sets the current transaction, if any, to read only and any attempt to perform any of the OCI transaction calls (OCITransStart()
,OCITransDetach()
,OCITransCommit()
,OCITransRollback()
,OCITransPrepare()
,OCITransMultiPrepare()
,OCITransForget()
) will return an error in the new container. In order to issue any of these calls, you need to switch back to the original container. -
If an
OCISubscriptionUnRegister()
call is attempted in the context of an incorrect container (different from the container on which the correspondingOCISubscriptionRegister()
call was done), then anORA-24950
is returned. -
A
OCIDescribeAny()
call withOCI_PTYPE_DATABASE
describes the database to which the connection is connected. After anALTER SESSION SET CONTAINER
statement is done, if the application wants to see the current database description, theOCIDescribeAny()
call will need to be reissued. -
Calls to any OCI Any Data, collection, or object functions that are used to manipulate an object from a different container are not supported.
-
An
OCIObjectFlush()
call is supported only in the container where the object instance was created with anOCIObjectNew()
call. -
Oracle recommends that
OCIObjectFlush()
be called prior to switching containers with anALTER SESSION SET CONTAINER
statement. Note that anOCIObjectFlush()
call will start a transaction if one is not already started. -
An
OCIObjectFlush()
call done after switching containers may return an error if a transaction was already started earlier on another container by the same session (either as a result of explicit DMLs or as a result of anOCIObjectFlush()
call). -
An
OCIObjectFlush()
call only flushes objects dirtied in the context of the container in which theOCIObjectFlush()
call is issued. -
Various session attributes may change on an
ALTER SESSION SET CONTAINER
statement. If an application caches these attributes, their settings may no longer be the same after anALTER SESSION SET CONTAINER
statement. Examples of attributes that can be obtained with anOCIAttrGet()
call and which can change on anALTER SESSION SET CONTAINER
statement include the following:
See Also:
-
Oracle Database SQL Language Reference for more information about
MAX_STRING_SIZE
-
OCITransStart(), OCITransDetach(), OCITransCommit(), OCITransRollback(), OCITransPrepare(), OCITransMultiPrepare() , OCITransForget()
17.5 Restrictions on OCI Calls with ALTER SESSION SWITCH CONTAINER SWITCH SERVICE
Describes a restriction on OCI calls with the ALTER SESSION SWITCH CONTAINER SWITCH SERVICE
statement.
Beginning with Oracle Database 12c Release 2 (12.2), the ALTER SESSION SWITCH CONTAINER SWITCH SERVICE
statement is added, which may result in a change of service attributes if the new service is configured differently than when connected to the original service. However, OCI will not alter its processing based on the new settings with this statement; instead, it will continue to use the original settings as when connected to the original service. For example, FAN on/off, TAF on/off settings, and so forth will remain the same as when first connected to the original service. This is considered the desired behavior after the switch as the normal use case for the ALTER SESSION SWITCH CONTAINER SWITCH SERVICE
statement is in a multitenant environment with the same application being in use after the switch.