Documentation update on new macOS ARM64 support and Implicit Connection Pooling

sharadraju · sharadraju · commit 660a144bd731 · 2024-07-15T12:22:25.000+05:30
diff --git a/doc/src/user_guide/connection_handling.rst b/doc/src/user_guide/connection_handling.rst
@@ -2875,9 +2875,10 @@ servers in :ref:`DRCP <drcp>` or Oracle Connection Manager in Traffic Director
 Mode's (CMAN-TDM) `Proxy Resident Connection Pooling (PRCP)
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-E0032017-03B1-
 4F14-AF9B-BCC87C982DA8>`__. Applications do not need to be modified. The
-feature can be enabled by altering the application's :ref:`connection string
-<connectionstrings>`. Applications do not need to explicitly acquire, or
-release, connections to be able use a DRCP or PRCP pool.
+feature is enabled by adding a ``POOL_BOUNDARY`` parameter to the
+application's :ref:`connection string <connectionstrings>`. Applications do
+not need to explicitly acquire, or release, connections to be able use a DRCP
+or PRCP pool.
 
 Implicit connection pooling is available in node-oracledb Thin and
 :ref:`Thick <enablingthick>` modes. It requires Oracle Database
@@ -2890,11 +2891,9 @@ DRCP or PRCP pool when they are actually used by the application to do database
 work. They are internally released back to pool when not in use. This may
 occur between the application's explicit :meth:`oracledb.getConnection()` call
 and :meth:`connection.close()` (or the application's equivalent connection
-release at end-of-scope).
-
-The internal connection release can be controlled by setting a value in the
-``POOL_BOUNDARY`` parameter in the :ref:`Easy Connect string <easyconnect>` or
-the :ref:`Connect Descriptor string <embedtns>`. The value can be either:
+release at end-of-scope). The internal connection release can be controlled by
+the value of the ``POOL_BOUNDARY`` connection string parameter, which can be
+either:
 
 - *STATEMENT*: If this boundary value is specified, then the connection is
   released back to the DRCP or PRCP pool when the connection is implicitly
@@ -2915,8 +2914,20 @@ the :ref:`Connect Descriptor string <embedtns>`. The value can be either:
   - Run queries that fetch :ref:`LOB <lobhandling>` and
     :ref:`JSON <jsondatatype>` data
 
+Inline with DRCP and PRCP best practices regarding session sharing across
+differing applications, you should add a connection string
+``POOL_CONNECTION_CLASS`` parameter, using the same value for all applications
+that are alike.
+
+The DRCP and PRCP "purity" used by Implicit Connection Pooling defaults to
+SELF, which allows reuse of the server process session memory for best
+performance. Adding the connection string parameter ``POOL_PURITY=NEW`` will
+change this and cause each use of a connection to recreate the session memory.
+
 .. _useimplicitconnpool:
 
+**Configuring Implicit Connection Pooling**
+
 To use implicit connection pooling in node-oracledb with DRCP:
 
 1. Enable DRCP in the database. For example in SQL*Plus::
@@ -2954,32 +2965,54 @@ To use implicit connection pooling in node-oracledb with DRCP:
      transaction boundary to release the connections back to the DRCP or PRCP
      pool.
 
-If you specify an invalid ``POOL_BOUNDARY`` in the
-:ref:`Easy Connect string <easyconnect>` or the
-:ref:`Connect Descriptor string <embedtns>`, then the following error is
-returned::
+     .. note::
 
-    ORA-24545: invalid value of POOL_BOUNDARY specified in connect
-    string
+        Implicit connection pooling is not enabled if the application sets the
+        ``POOL_BOUNDARY`` attribute to *TRANSACTION* or *STATEMENT* but does
+        not set the ``SERVER=POOLED`` attribute in the connection string.
 
-.. note::
+   If you specify an invalid ``POOL_BOUNDARY`` in the
+   :ref:`Easy Connect string <easyconnect>` or the
+   :ref:`Connect Descriptor string <embedtns>`, then the following error is
+   returned::
+
+    ORA-24545: invalid value of POOL_BOUNDARY specified in connect string
+
+3. Set the connection class in:
+
+   - The ``connectString`` property of :meth:`oracledb.getConnection()` or
+     :meth:`oracledb.createPool()` in the
+     :ref:`Easy Connect string <easyconnect>`. For example, to use a class
+     name 'myapp':
+
+     .. code-block:: javascript
+
+        const connection = await oracledb.getConnection({
+            user          : "hr",
+            password      : mypw,  // mypw contains the hr schema password
+            connectString : "mydbmachine.example.com:1521/orclpdb1:pooled?pool_boundary=statement&pool_connection_class=myapp"
+        });
+
+   - Or the ``CONNECT_DATA`` section of the :ref:`Connect Descriptor string
+     <embedtns>`. For example, to use a class name 'myapp'::
+
+        tnsalias = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=mymachine.example.com)
+                    (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=orcl)
+                    (SERVER=POOLED)(POOL_BOUNDARY=TRANSACTION)
+                    (POOL_CONNECTION_CLASS=myapp)))
 
-    - Implicit connection pooling is disabled if the application sets the
-      ``POOL_BOUNDARY`` attribute to *TRANSACTION* or *STATEMENT* but
-      does not set the ``SERVER=POOLED`` attribute in the connection string.
+   Use the same connection class name for application processes of the same
+   type where you want session memory to be reused for connections.
 
-    - For all the ``POOL_BOUNDARY`` options, the default purity is set to
-      *SELF*. You can specify the purity using the ``POOL_PURITY`` parameter
-      in the connection string to override the default purity value.
+   The pool purity can also optionally be changed by adding ``POOL_PURITY=NEW``
+   to the connection string or descriptor.
 
 Similar steps can be used with PRCP. For general information on PRCP, see the
 technical brief `CMAN-TDM — An Oracle Database connection proxy for scalable
 and highly available applications <https://download.oracle.com/
 ocomdocs/global/CMAN_TDM_Oracle_DB_Connection_Proxy_for_scalable_apps.pdf>`__.
 
-It is recommended to use node-oracledb's local :ref:`connpooling` where
-possible instead of implicit connection pooling. This gives multi-user
-applications more control over pooled server reuse.
+**Implicit Pooling Notes**
 
 You should thoroughly test your application when using implicit connection
 pooling to ensure that the internal reuse of database servers does not cause
@@ -2990,6 +3023,10 @@ lifetime of the application connection because different servers may be used
 at different times. Another example is when using a statement boundary of
 *transaction*. In this scenario, any commit can invalidate open cursors.
 
+It is recommended to use node-oracledb's local :ref:`connpooling` where
+possible instead of implicit connection pooling. This gives multi-user
+applications more control over pooled server reuse.
+
 .. _privconn:
 
 Privileged Connections
diff --git a/doc/src/user_guide/initialization.rst b/doc/src/user_guide/initialization.rst
@@ -194,7 +194,7 @@ On macOS, the alternative ways to enable Thick mode are:
   .. code-block:: javascript
 
         const oracledb = require('oracledb');
-        oracledb.initOracleClient({libDir: process.env.HOME + '/Downloads/instantclient_19_16'});
+        oracledb.initOracleClient({libDir: process.env.HOME + '/Downloads/instantclient_23_3'});
 
   This directory should contain the libraries from an unzipped `Instant
   Client 'Basic' or 'Basic Light' <https://www.oracle.com/database/
@@ -224,20 +224,14 @@ On macOS, the alternative ways to enable Thick mode are:
   in the ``node_modules/oracledb/build/Release`` directory where the
   ``oracledb*.node`` binary is. For example::
 
-        ln -s ~/Downloads/instantclient_19_16/libclntsh.dylib node_modules/oracledb/build/Release
+        ln -s ~/Downloads/instantclient_23_3/libclntsh.dylib node_modules/oracledb/build/Release
 
   This can be added to your ``package.json`` files::
 
         "scripts": {
             "postinstall": "ln -s $HOME/Downloads/instantclient_19_16/libclntsh.dylib $(npm root)/oracledb/build/Release"
         },
 
-  Instead of linking, you can also copy all the required OCI libraries,
-  for example::
-
-        cp ~/Downloads/instantclient_19_16/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libnnz19.dylib,libociei.dylib} node_modules/oracledb/build/Release
-        cd node_modules/oracledb/build/Release/ && ln -s libclntsh.dylib.19.1 libclntsh.dylib
-
   With the libraries in place, your application can then enable Thick mode:
 
   .. code:: javascript
@@ -251,13 +245,7 @@ On macOS, the alternative ways to enable Thick mode are:
   it. For example::
 
         mkdir /usr/local/lib
-        ln -s ~/Downloads/instantclient_19_16/libclntsh.dylib/usr/local/lib
-
-  Instead of linking, you can also copy all the required OCI libraries,
-  for example::
-
-        mkdir /usr/local/lib
-        cp ~/Downloads/instantclient_19_16/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libnnz19.dylib,libociei.dylib} /usr/local/lib/
+        ln -s ~/Downloads/instantclient_23_3/libclntsh.dylib /usr/local/lib
 
   With the libraries in place, your application can then enable Thick mode:
 
diff --git a/doc/src/user_guide/installation.rst b/doc/src/user_guide/installation.rst
@@ -751,9 +751,8 @@ available in :ref:`Thick mode <featuresummary>`, you need to install Oracle
 Client libraries.  Thick mode uses a binary add-on installed with node-oracledb
 that loads these libraries.  This binary is available for macOS Intel only.
 
-Download the **Basic** 64-bit DMG from `Oracle Technology Network <https://www.
-oracle.com/database/technologies/instant-client/macos-intel-x86-downloads.
-html>`__.
+You can get the libraries from either the Oracle Instant Client **Basic** or
+**Basic Light** package.  The steps below show installing **Basic**.
 
 .. note::
 
@@ -766,44 +765,89 @@ html>`__.
         const oracledb = require('oracledb');
         oracledb.initOracleClient();
 
-Manual Installation
-+++++++++++++++++++
+Instant Client Scripted Installation on macOS ARM64
++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-1. In Finder, double click on the DMG to mount it.
+Instant Client installation can be scripted. Open a terminal window and run:
 
-2. Open a terminal window and run the install script in the mounted
-   package, for example::
+.. code-block:: shell
 
-        $ /Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru/install_ic.sh
+    cd $HOME/Downloads
+    curl -O https://download.oracle.com/otn_software/mac/instantclient/233023/instantclient-basic-macos.arm64-23.3.0.23.09.dmg
+    hdiutil mount instantclient-basic-macos.arm64-23.3.0.23.09.dmg
+    /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09/install_ic.sh
+    hdiutil unmount /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09
 
-   This copies the contents to ``$HOME/Downloads/instantclient_19_8``.
-   Applications may not have access to the ``Downloads`` directory, so you
-   should move Instant Client somewhere convenient.
+Note you should use the latest DMG available.
 
-3. In Finder, eject the mounted Instant Client package.
+If you have multiple Instant Client DMG packages mounted, you only need to run
+``install_ic.sh`` once.  It will copy all mounted Instant Client DMG packages
+at the same time.
 
-4. Call :meth:`oracledb.initOracleClient()` to enable Thick mode, see
+The Instant Client directory will be like
+``$HOME/Downloads/instantclient_23_3``.  Applications may not have access to
+the ``Downloads`` directory, so you should move Instant Client somewhere
+convenient.
+
+Call :meth:`oracledb.initOracleClient()` to enable Thick mode, see
+:ref:`oracleclientloadingmacos`.
+
+If you use the optional Oracle configuration files, see
+:ref:`usingconfigfiles`.
+
+Instant Client Manual Installation on macOS ARM64
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+1. Download the latest Instant Client **Basic** ARM64 package DMG from `Oracle
+   <https://www.oracle.com/database/technologies/instant-client/macos-arm64-
+   downloads.html>`__.
+
+2. Using Finder, double-click the DMG to mount it.
+
+3. Open a terminal window and run the install script in the mounted package,
+   for example if you downloaded version 23.3:
+
+    .. code-block:: shell
+
+        /Volumes/instantclient-basic-macos.arm64-23.3.0.23.09/install_ic.sh
+
+   The Instant Client directory will be like
+   ``$HOME/Downloads/instantclient_23_3``.  Applications may not have access to
+   the ``Downloads`` directory, so you should move Instant Client somewhere
+   convenient.
+
+4. Using Finder, eject the mounted Instant Client package.
+
+5. Call :meth:`oracledb.initOracleClient()` to enable Thick mode, see
    :ref:`oracleclientloadingmacos`.
 
-5. If you use the optional Oracle configuration files, see
+6. If you use the optional Oracle configuration files, see
    :ref:`usingconfigfiles`.
 
-If you have multiple Instant Client DMG packages mounted, you only need
-to run ``install_ic.sh`` once. It will copy all mounted Instant Client
-DMG packages at the same time.
+If you have multiple Instant Client DMG packages mounted, you only need to run
+``install_ic.sh`` once.  It will copy all mounted Instant Client DMG packages
+at the same time.
+
+Instant Client Scripted Installation on macOS Intel x86-64
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Scripted Installation
-+++++++++++++++++++++
+Instant Client installation can be scripted. Open a terminal window and run:
 
-Instant Client installation can alternatively be scripted, for example::
+.. code-block:: shell
 
     cd $HOME/Downloads
-    curl -O https://download.oracle.com/otn_software/mac/instantclient/198000/instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg
-    hdiutil mount instantclient-basic-macos.x64-19.8.0.0.0dbru.dmg
-    /Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru/install_ic.sh
-    hdiutil unmount /Volumes/instantclient-basic-macos.x64-19.8.0.0.0dbru
+    curl -O https://download.oracle.com/otn_software/mac/instantclient/1916000/instantclient-basic-macos.x64-19.16.0.0.0dbru.dmg
+    hdiutil mount instantclient-basic-macos.x64-19.16.0.0.0dbru.dmg
+    /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru/install_ic.sh
+    hdiutil unmount /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru
+
+Note you should use the latest DMG available.
 
-The Instant Client directory will be ``$HOME/Downloads/instantclient_19_8``.
+If you have multiple Instant Client DMG packages mounted, you only need to run
+``install_ic.sh`` once.  It will copy all mounted Instant Client DMG packages at
+the same time.
+
+The Instant Client directory will be ``$HOME/Downloads/instantclient_19_16``.
 Applications may not have access to the ``Downloads`` directory, so you should
 move Instant Client somewhere convenient.
 
@@ -813,6 +857,37 @@ Call :meth:`oracledb.initOracleClient()` to enable Thick mode, see
 If you use the optional Oracle configuration files, see
 :ref:`usingconfigfiles`.
 
+Instant Client Manual Installation on macOS Intel x86-64
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+1. Download the latest Instant Client **Basic** Intel 64-bit package DMG from
+   `Oracle <https://www.oracle.com/database/technologies/instant-client/macos-
+   intel-x86-downloads.html>`__.
+
+2. Using Finder, double-click the DMG to mount it.
+
+3. Open a terminal window and run the install script in the mounted package, for example:
+
+    .. code-block:: shell
+
+        /Volumes/instantclient-basic-macos.x64-19.16.0.0.0dbru/install_ic.sh
+
+   The Instant Client directory will be ``$HOME/Downloads/instantclient_19_16``.
+   Applications may not have access to the ``Downloads`` directory, so you
+   should move Instant Client somewhere convenient.
+
+4. Using Finder, eject the mounted Instant Client package.
+
+5. Call :meth:`oracledb.initOracleClient()` to enable Thick mode, see
+   :ref:`oracleclientloadingmacos`.
+
+6. If you use the optional Oracle configuration files, see
+   :ref:`usingconfigfiles`.
+
+If you have multiple Instant Client DMG packages mounted, you only need to run
+``install_ic.sh`` once.  It will copy all mounted Instant Client DMG packages at
+the same time.
+
 .. _windowsinstallation:
 
 Installing Node.js and node-oracledb on Microsoft Windows
