Added support for caching the database version in pooled connections

with Oracle Client 19 and earlier (later Oracle Clients handle this
caching internally). This optimization eliminates a round-trip
previously often required when reusing a pooled connection.

Author: anthony-tuininga

doc/src/releasenotes.rst

@@ -4,6 +4,10 @@ ODPI-C Release notes
 Version 4.2.1 (TBD)
 -------------------
 
+#)  Added support for caching the database version in pooled connections with
+    Oracle Client 19 and earlier (later Oracle Clients handle this caching
+    internally). This optimization eliminates a round-trip previously often
+    required when reusing a pooled connection.
 #)  All errors identified as causing a dead connection now populate
     :member:`dpiErrorInfo.sqlState` with the value `01002` instead of only a
     hard-coded list of errors.

doc/src/user_guide/round_trips.rst

@@ -88,12 +88,15 @@ back.
       - Maybe
       - The first call when requesting the release string always requires a
         round-trip. If the release string is not requested and Oracle Client
-        20.3 or higher is being used, no round-trip is required; otherwise, a
-        round-trip is required. Subsequent calls with any client version do not
-        require a round-trip.
+        20.3 or higher is being used, no round-trip is required. Similarly for
+        earlier versions, if the release string is not requested and a pooled
+        connection is used that previously had a call to this function made, no
+        round-trip is required; otherwise, a round-trip is required. Subsequent
+        calls with any client version do not require a round-trip.
     * - :func:`dpiConn_getSodaDb()`
-      - No
-      -
+      - Maybe
+      - An internal call to check the server version is made. The notes on the
+        function :func:`dpiConn_getServerVersion()` apply.
     * - :func:`dpiConn_getStmtCacheSize()`
       - No
       -

src/dpiConn.c

@@ -695,24 +695,44 @@ int dpiConn__getServerVersion(dpiConn *conn, int wantReleaseString,
         dpiError *error)
 {
     char buffer[512], *releaseString;
+    dpiVersionInfo *tempVersionInfo;
     uint32_t serverRelease, mode;
     uint32_t releaseStringLength;
+    int ociCanCache;
 
     // nothing to do if the server version has been cached earlier
     if (conn->releaseString ||
             (conn->versionInfo.versionNum > 0 && !wantReleaseString))
         return DPI_SUCCESS;
 
-    // the server version is not available in the cache so a call is required
-    // to get it; as of Oracle Client 20.3, a special mode is available that
-    // causes OCI to cache server version information; this mode can be used
-    // exclusively once 20.3 is the minimum version supported by ODPI-C; until
-    // that time, since ODPI-C already caches server version information
-    // itself, this mode is only used when the release string is not requested,
-    // in order to avoid the round-trip in that particular case
-    if ((conn->env->versionInfo->versionNum > 20 ||
+    // the server version is not available in the cache so it must be
+    // determined; as of Oracle Client 20.3, a special mode is available that
+    // causes OCI to cache the server version information, so this mode can be
+    // used if the release string information is not desired and the client
+    // supports it
+    ociCanCache = ((conn->env->versionInfo->versionNum > 20 ||
             (conn->env->versionInfo->versionNum == 20 &&
-             conn->env->versionInfo->releaseNum >= 3)) && !wantReleaseString) {
+             conn->env->versionInfo->releaseNum >= 3)) && !wantReleaseString);
+
+    // for earlier versions where the OCI cache is not available, pooled
+    // connections can cache the information on the session in order to avoid
+    // the round trip, but again only if the release string is not desired;
+    // nothing further needs to be done if this cache is present
+    if (conn->pool && !ociCanCache && !wantReleaseString) {
+        tempVersionInfo = NULL;
+        if (dpiOci__contextGetValue(conn, DPI_CONTEXT_SERVER_VERSION,
+                (uint32_t) (sizeof(DPI_CONTEXT_SERVER_VERSION) - 1),
+                (void**) &tempVersionInfo, 1, error) < 0)
+            return DPI_FAILURE;
+        if (tempVersionInfo) {
+            memcpy(&conn->versionInfo, tempVersionInfo,
+                    sizeof(conn->versionInfo));
+            return DPI_SUCCESS;
+        }
+    }
+
+    // calculate the server version by making the appropriate call
+    if (ociCanCache) {
         mode = DPI_OCI_SRVRELEASE2_CACHED;
         releaseString = NULL;
         releaseStringLength = 0;
@@ -756,6 +776,21 @@ int dpiConn__getServerVersion(dpiConn *conn, int wantReleaseString,
                     conn->versionInfo.portReleaseNum,
                     conn->versionInfo.portUpdateNum);
 
+    // for earlier versions where the OCI cache is not available, store the
+    // version information on the session in order to avoid the round-trip the
+    // next time the pooled session is acquired from the pool
+    if (conn->pool && !ociCanCache) {
+        if (dpiOci__memoryAlloc(conn, (void**) &tempVersionInfo,
+                sizeof(conn->versionInfo), 1, error) < 0)
+            return DPI_FAILURE;
+        memcpy(tempVersionInfo, &conn->versionInfo, sizeof(conn->versionInfo));
+        if (dpiOci__contextSetValue(conn, DPI_CONTEXT_SERVER_VERSION,
+                (uint32_t) (sizeof(DPI_CONTEXT_SERVER_VERSION) - 1),
+                tempVersionInfo, 1, error) < 0) {
+            dpiOci__memoryFree(conn, tempVersionInfo, error);
+        }
+    }
+
     return DPI_SUCCESS;
 }
 

src/dpiImpl.h

@@ -84,6 +84,9 @@ extern unsigned long dpiDebugLevel;
 // define context name for ping interval
 #define DPI_CONTEXT_LAST_TIME_USED                  "DPI_LAST_TIME_USED"
 
+// define context name for server version information
+#define DPI_CONTEXT_SERVER_VERSION                  "DPI_SERVER_VERSION"
+
 // define size of buffer used for numbers transferred to/from Oracle as text
 #define DPI_NUMBER_AS_TEXT_CHARS                    172