Connecting to a Database Service

2.3 Connecting to a Database Service

To connect to a database service, clients use a connect descriptor that provides the location of the database and the name of the database service.

The following example is an Easy Connect descriptor that connects to a database service named sales.us.example.com, and the host sales-server (the port is 1521 by default):

sales-server/sales.us.example.com

The following example shows the entry in the tnsnames.ora file for the preceding Easy Connect connect descriptor and database service:

(DESCRIPTION=
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)))

Related Topics

Understanding Naming Methods

Parent topic: Identifying and Accessing the Database

2.3.1 About Connect Descriptors

A connect descriptor is comprised of one or more protocol addresses of the listener and the connect information for the destination service in the tnsnames.ora file. Example 2-1 shows a connect descriptor mapped to the sales database.

Example 2-1 Connect Descriptor

sales=
 (DESCRIPTION= 
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))
  (CONNECT_DATA= 
     (SID=sales)
     (SERVICE_NAME=sales.us.example.com)
     (INSTANCE_NAME=sales)))

As shown in Example 2-1, the connect descriptor contains the following parameters:

The ADDRESS section contains the following:
- PROTOCOL parameter, which identifies the listener protocol address. The protocol is tcp for TCP/IP.
- HOST parameter, which identifies the host name. The host is sales-server.
- PORT parameter, which identifies the port. The port is 1521, the default port number.
- Optional HTTPS_PROXY and HTTPS_PROXY_PORT parameters, that allow the database client connection to traverse through the organization’s forward web proxy. These parameters are applicable only to the connect descriptors where PROTOCOL=TCPS.
The CONNECT_DATA section contains the following:
- SID parameter, which identifies the system identifier (SID) of the Oracle database. The SID is sales.
- SERVICE_NAME parameter, which identifies the service. The destination service name is a database service named sales.us.example.com.
  
  The value for this connect descriptor parameter comes from the SERVICE_NAMES initialization parameter (SERVICE_NAMES uses a final S) in the initialization parameter file. The SERVICE_NAMES initialization parameter is typically the global database name, which includes the database name and domain name. In the example, sales.us.example.com has a database name of sales and a domain of us.example.com.
  
  Note:
  Starting with Oracle Database 19c, customer use of the SERVICE_NAMES parameter is deprecated. To manage your services, Oracle recommends that you use the SRVCTL or GDSCTL command line utilities, or the DBMS_SERVICE package.
- INSTANCE_NAME parameter, which identifies the database instance. The instance name is optional.
  
  The INSTANCE_NAME parameter in the initialization parameter file defaults to the SID entered during installation or database creation.

About IPv6 Addresses in Connect Descriptors
A host can use IP version 4 (IPv4) and IP version 6 (IPv6) interfaces. IPv6 addresses and host names that resolve to IPv6 addresses are usable in the HOST parameter of a TNS connect address, which can be obtained through any of the supported net naming methods.

2.3.1.1 About IPv6 Addresses in Connect Descriptors

A host can use IP version 4 (IPv4) and IP version 6 (IPv6) interfaces. IPv6 addresses and host names that resolve to IPv6 addresses are usable in the HOST parameter of a TNS connect address, which can be obtained through any of the supported net naming methods.

End-to-end connectivity using IPv6 requires the following configuration:

The client TNS connect address must connect to the Oracle Net Listener on the IPv6 endpoint.
The database instance configured for Oracle Net Listener must listen for connection requests on IPv6 endpoints.

For a given host name, Oracle Net attempts to connect to all IP addresses returned by Domain Name System (DNS) name resolution until a successful connection is established or all addresses have been attempted. Suppose that in a connect descriptor, the sales-server host is an IPv4-only host that is accepting client connections. DNS maps sales-server to the following IP addresses:

IPv6 address 2001:0db8:0:0::200C:417A
IPv4 address 192.0.2.213

In this case, Oracle Net first tries to connect on the IPv6 address because it is first in the DNS list. In this example, sales-server does not support IPv6 connectivity, so this attempt fails. Oracle Net proceeds to connect to the IPv4 address, which succeeds.

Related Topics

Parent topic: About Connect Descriptors

2.3.2 About the Protocol Address

The address portion of the connect descriptor is the protocol address of the listener. To connect to a database service, clients first contact a listener process that typically resides on the database server. The listener receives incoming client connection requests and sends these requests to the database server. After the connection is established, the client and database server communicate directly.

The listener is configured to accept requests from clients at a protocol address. This address defines the protocol the listener is listening on and any other protocol-specific information. For example, the listener could be configured to listen at the following protocol address:

(DESCRIPTION=
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)))

The preceding example shows a TCP/IP protocol address that specifies the host of the listener and a port number. Client connect descriptors configured with this same protocol address can send connection requests to this listener.

Parent topic: Connecting to a Database Service

2.3.3 About Service Registration

The connect descriptor specifies the database service name with which clients seek to establish a connection. The listener knows which services can handle connection requests because Oracle Database dynamically registers this information with the listener. This process of registration is called service registration. Registration also provides the listener with information about the database instances and the service handlers available for each instance. A service handler can be a dispatcher or dedicated server.

Parent topic: Connecting to a Database Service

2.3.3.1 Specifying an Instance Name

If connecting to a specific instance of the database is required, then clients can specify the INSTANCE_NAME of a particular instance in the connect descriptor. This feature can be useful for an Oracle RAC configuration. For example, the following connect descriptor specifies the instance name sales1 that is associated with sales.us.example.com.

(DESCRIPTION=
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    (INSTANCE_NAME=sales1)))

Parent topic: About Service Registration

2.3.3.2 Specifying a Service Handler

Clients that always want to use a particular service handler type can use a connect descriptor to specify the service handler type. In the following example, the connect descriptor uses (SERVER=shared) to request a dispatcher when connecting to a database. The database may be configured to use dedicated servers by default.

(DESCRIPTION=
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
     (SERVER=shared)))

When the listener receives the client request, it selects one of the registered service handlers. Depending on the type of handler selected, the communication protocol used, and the operating system of the database server, the listener performs one of the following actions:

Hands the connect request directly off to a dispatcher.
Sends a redirect message back to the client with the location of the dispatcher or dedicated server process. The client then connects directly to the dispatcher or dedicated server process.
Spawns a dedicated server process and passes the client connection to the dedicated server process.

After the listener has completed the connection operation for the client, the client communicates directly with the Oracle database without the listener's involvement. The listener resumes listening for incoming network sessions.

The following should be considered when specifying service handlers:

If you want the client to use a dedicated server, then specify (SERVER=dedicated). If the SERVER parameter is not set, then a shared server configuration is assumed. However, the client will use a dedicated server if no dispatchers are available.
If database resident connection pooling is enabled on the server, then specify (SERVER=pooled) to get a connection from the pool. If database resident connection pooling is not enabled on the server, then the client request is rejected, and the user receives an error message.