EASY CONNECT PLUS - EZCONNECT

Oracle Database 19c introduces a significantly enhanced connection string syntax called Easy Connect Plus.

By reducing the need for external configuration files, Easy Connect Plus makes it easier to use features such as TLS connections, wallets, load balancing, connection timeouts, and to tune network buffer sizes.

Easy Connect Plus can be used in JDBC and .NET applications. It is also usable in applications and drivers built on the C language Oracle Call Interface (OCI) such as the Oracle Database drivers for Python, Node.js, PHP, Ruby, and Go.

Easy connect background

An Easy Connect string includes a host name, an optional port, and the database service name:

database_host[:port][/[service_name]

Easy connect plus syntax

The Oracle Database 19c enhanced Easy Connect Plus syntax is a superset of Easy Connect that supports more connection options. The syntax is available in Oracle Database drivers (JDBC, ODP.Net, cx_Oracle, node-oracledb etc) that use Oracle Client 19c and connect to Oracle Database 11.2 or later.


The Oracle Database 19c Easy Connect PLUS syntax is

[[protocol:]//]host1{,host2}[:port1]{,host2:port2}[/[service_name]
[:server_type][/instance_name]][?parameter_name=value{&parameter_name=value}]

For more information read:

Oracle-Net-19c-Easy-Connect-Plus

Understanding the Easy Connect Naming Method

Examples

1. Using protocol

tnsping tcp://joords1:1521/sales.us.example.com

Converts into the following descriptor

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

2. With multiple hosts

tnsping //joords1,joords2:1521/sales.us.example.com

Converts into the following descriptor

(DESCRIPTION=
(LOAD_BALANCE=ON)
(ADDRESS=(PROTOCOL=tcp)(HOST=joords1)(PORT=1521))
(ADDRESS=(PROTOCOL=tcp)(HOST=joords2)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

3. Using multiple hosts and ports

tnsping //joords1:1521,joords2,joords3:1522/sales.us.example.com

Converts into the following descriptor

(DESCRIPTION=
(LOAD_BALANCE=ON)
(ADDRESS=(PROTOCOL=tcp)(HOST=joords1)(PORT=1521))
(ADDRESS=(PROTOCOL=tcp)(HOST=joords2)(PORT=1522))
(ADDRESS=(PROTOCOL=tcp)(HOST=joords3)(PORT=1522))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

4. Using IPv6 address as the host

tnsping //[2606:b400:41c:8a19:f816:3eff:fe8f:e3ef]:1521/sales.us.example.com

Converts into the following descriptor

(DESCRIPTION=
(ADDRESS=(PROTOCOL=tcp)(HOST=2606:b400:41c:8a19:f816:3eff:fe8f:e3ef)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

5. With (UR=A)

tnsping //joords1/CDB1)(UR=A

Converts into the following descriptor

(DESCRIPTION=
(ADDRESS=(HOST=Joords1)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=CDB1)(UR=A)))

6. With a wallet location clause

tnsping tcps://joords1:1521/sales.us.example.com?wallet_location="/tmp/oracle"

Converts into the following descriptor

(DESCRIPTION=
(ADDRESS=(PROTOCOL=tcps)(HOST=joords1)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
(SECURITY=(MY_WALLET_DIRECTORY=/tmp/oracle)(SSL_SERVER_DN_MATCH=ON)))

7. Adding a session Data Unit

tnsping //joords1:1521/sales.us.example.com?sdu=16384

Converts into the following descriptor

(DESCRIPTION=
(SDU=16384)
(ADDRESS=(PROTOCOL=tcp)(HOST=joords1)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

8. With the connect timeout clause

tnsping //joords1:1521/sales.us.example.com?connect_timeout=60&transport_connect_timeout=30&retry_count=3

Converts into the following descriptor

(DESCRIPTION=
(RETRY_COUNT=3)(CONNECT_TIMEOUT=60)(TRANSPORT_CONNECT_TIMEOUT=30)
(ADDRESS=(PROTOCOL=tcp)(HOST=joords1)(PORT=1521))
(CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

9. Quoting Easy Connect Strings

Quoting of parameters may be required in some tools and environments.
The following example invokes SQL*Plus 19c in a Linux shell.
This illustrates the placement of single and double quotes to escape interpretation of special characters by the shell:

sqlplus scott@'tcps://joords1:1521/sales.us.example.com?ssl_server_cert_dn="cn=sales,cn=Oracle Context Server,dc=us,dc=example,dc=com"&sdu=8128&connect_timeout=60'