Active GridLink (AGL) is the data source type that provides connectivity between WebLogic Server and an Oracle Database service, which may include one or more Oracle RAC clusters or Active Data Guard sites.  As the supported topologies grow to include additional features like Global Database Services (GDS) and new features are added to the Oracle networking and database support, the complexity of the URL to access this has also gotten more complex. There are lots of examples in the documentation.  This is a short article that summarizes patterns for defining the URL string for use with AGL.

It should be obvious but let me start by saying AGL only works with the Oracle Thin Driver.

AGL data sources only support long format JDBC URLs. The supported long format pattern is basically the following (there are lots of additional properties, some of which are described below).

jdbc:oracle:thin:@(DESCRIPTION =
   (CONNECT_TIMEOUT=90)  (RETRY_COUNT=20)(RETRY_DELAY=3) (TRANSPORT_CONNECT_TIMEOUT=3) 
     (ADDRESS_LIST =
         (LOAD_BALANCE=on)
         ( ADDRESS = (PROTOCOL = TCP)(HOST=primary-scan)(PORT=primary-scan-port)))
      (ADDRESS_LIST =
         (LOAD_BALANCE=on)
         ( ADDRESS = (PROTOCOL = TCP)(HOST=secondary-scan)(PORT=secondary-scan-port)))       
    (CONNECT_DATA=(SERVICE_NAME = myservice)))

If not using SCAN, then the ADDRESS_LIST would have one or more ADDRESS attributes with HOST/PORT pairs. It’s recommended to use SCAN if possible and it’s recommended to use VIP addresses to avoid TCP/IP hangs.

Easy Connect (short) format URLs are not supported for AGL data sources. The following is an example of a Easy Connect URL pattern that is not supported for use with AGL data sources:

jdbc:oracle:thin:[SCAN_VIP]:[SCAN_PORT]/[SERVICE_NAME]

General recommendations for the URL are as follows.

– Use a single DESCRIPTION.  Avoid a DESCRIPTION_LIST to avoid connection delays.

– Use one ADDRESS_LIST per RAC cluster or Active Data Guard database.  In the example above, it assumes there are two RAC clusters.  If you have one RAC cluster, then you would have one address list.

– Put RETRY_COUNT, RETRY_DELAY, CONNECT_TIMEOUT, and TRANSPORT_CONNECT_TIMEOUT at the DESCRIPTION level so that all ADDRESS_LIST entries use the same value.  Note that these parameters are optional.  URL’s that were generated with earlier releases won’t have them.

– RETRY_DELAY specifies the delay, in seconds, between the connection retries.  It is new in the 12.1.0.2 release.

– RETRY_COUNT is used to specify the number of times an ADDRESS list is traversed before the connection attempt is terminated. The default value is 0.  When using SCAN listeners with FAILOVER = on, setting the RETRY_COUNT parameter to 2 means the three SCAN IP addresses are traversed three times each, such that there are nine connect attempts (3 * 3).

– CONNECT_TIMEOUT is used to specify the overall time used to complete the Oracle Net connect.  Set CONNECT_TIMEOUT=90 or higher to prevent logon storms.    Do not set the oracle.net.CONNECT_TIMEOUT driver property on the datasource because it is overridden by the URL property.

– For JDBC drivers up through 12c, CONNECT_TIMEOUT is also used for the TCP/IP connection timeout for each address in the URL.  This second usage is preferred to be shorter.  In 18c and later, TRANSPORT_CONNECT_TIMEOUT was introduced. 

– The service name should be a configured application service, not a PDB or administration service.

– Specify LOAD_BALANCE=on per address list to balance the SCAN addresses.