Update documentation for use of privileges with createPool function

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -2213,6 +2213,18 @@ Oracledb Methods
             See :ref:`Connection Pool Cache <connpoolcache>` for details and examples.
 
             .. versionadded:: 1.11
+        * - ``privilege``
+          - Number
+          - Thin
+          - .. _createpoolpoolattrsprivilege:
+
+            The privilege to use when establishing a connection to the database. This optional property should be one of the :ref:`privileged connection constants <oracledbconstantsprivilege>`. All privileges must be specified individually except for ``oracledb.SYSPRELIM``.
+
+            ``oracledb.SYSPRELIM`` is specified only for startup and shutdown calls and must be used in combination with ``SYSDBA`` (``oracledb.SYSDBA | oracledb.SYSPRELIM``) or ``SYSOPER`` (``oracledb.SYOPER | oracledb.SYSPRELIM``).
+
+            See :ref:`Privileged Connections <privconn>` for more information.
+
+            .. versionadded:: 6.5.1
         * - ``configDir``
           - String
           - Thin
@@ -3075,13 +3087,17 @@ Oracledb Methods
           - Both
           - .. _getconnectiondbattrsprivilege:
 
-            The privilege to use when establishing connection to the database. This optional property should be one of the :ref:`privileged connection constants <oracledbconstantsprivilege>`. Multiple privileges may be used by when required, for example ``oracledb.SYSDBA | oracledb.SYSPRELIM``.
+            The privilege to use when establishing connection to the database. This optional property should be one of the :ref:`privileged connection constants <oracledbconstantsprivilege>`. All privileges must be specified individually except for ``oracledb.SYSPRELIM``.
 
-            See :ref:`Privileged Connections <privconn>` for more information.
+            ``oracledb.SYSPRELIM`` is specified only for startup and shutdown calls and must be used in combination with ``SYSDBA`` (``oracledb.SYSDBA | oracledb.SYSPRELIM``) or ``SYSOPER`` (``oracledb.SYOPER | oracledb.SYSPRELIM``).
 
-            Note only non-pooled connections can be privileged.
+            See :ref:`Privileged Connections <privconn>` for more information.
 
             .. versionadded:: 2.1
+
+            .. versionchanged:: 6.5.1
+
+              The database privilege can be specified for pooled connections.
         * - ``shardingKey``
           - Array
           - Thick

doc/src/user_guide/appendix_a.rst

@@ -598,6 +598,12 @@ differs from the node-oracledb Thick mode in the following ways:
   The node-oracledb Thick mode does not support all the connection mode
   privileges.
 
+- In node-oracledb Thin mode, :ref:`privileged connections <privconn>` can be
+  created with homogeneous pools.
+
+  The node-oracledb Thick mode can only create privileged connections with
+  :ref:`heterogeneous pools <connpoolproxy>`.
+
 - In node-oracledb Thick mode, the worker threads can be increased by setting
   the environment variable ``UV_THREADPOOL_SIZE`` before starting Node.js. This
   is not applicable to the Thin mode since it does not use threads.

doc/src/user_guide/connection_handling.rst

@@ -2995,11 +2995,14 @@ at different times. Another example is when using a statement boundary of
 Privileged Connections
 ======================
 
-Database privileges such as ``SYSDBA`` can be obtained when using
-standalone connections. Use one of the :ref:`Privileged Connection
-Constants <oracledbconstantsprivilege>` with the connection
-:ref:`privilege <getconnectiondbattrsprivilege>` property, for
-example:
+Database privileges such as ``SYSDBA`` or ``SYSOPER`` can be associated with
+the user when creating standalone and pooled connections. You can use one of
+the :ref:`Privileged Connection Constants <oracledbconstantsprivilege>` as the
+database privilege for the user.
+
+For :ref:`standalone connections <standaloneconnection>`, you must set the
+:ref:`privilege <getconnectiondbattrsprivilege>` property in
+:meth:`oracledb.getConnection()` as shown in the example below:
 
 .. code-block:: javascript
 
@@ -3012,9 +3015,64 @@ example:
 
     console.log("I have power");
 
-Note that if node-oracledb is using the Oracle Client libraries located
-in the Oracle Database installation, that is on the same machine as the
-database and is not using Oracle Instant Client, then operating system
+For :ref:`pooled connections <connpooling>` with node-oracledb Thin mode, you
+must set the :ref:`privilege <createpoolpoolattrsprivilege>`,
+:ref:`user <createpoolpoolattrsuser>`, and
+:ref:`password <createpoolpoolattrspassword>` properties in
+:meth:`oracledb.createPool()`. For example:
+
+.. code-block:: javascript
+
+    const pool = await oracledb.createPool({
+        user          : "sys",
+        password      : "secret",
+        connectString : "localhost/orclpdb1",
+        privilege     : oracledb.SYSDBA
+        poolMin       : 2,
+        poolMax       : 10
+    });
+
+    const connection = await pool.getConnection();
+
+The ability to specify database privileges with pooled connections in Thin
+mode was introduced in node-oracledb 6.5.1.
+
+For node-oracledb Thick mode, privileged connections can only be created with
+a :ref:`heterogeneous pool <connpoolproxy>`. You must set the
+:ref:`homogeneous <createpoolpoolattrshomogeneous>` property to *false* in
+:meth:`oracledb.createPool()` to use a heterogeneous pool. You can then
+specify the :ref:`privilege <getconnectiondbattrsprivilege>`,
+:ref:`user <getconnectiondbattrsuser>`, and
+:ref:`password <getconnectiondbattrspassword>` properties in
+:meth:`pool.getConnection()`. For example:
+
+.. code-block:: javascript
+
+    const pool = await oracledb.createPool({
+        connectString : "localhost/orclpdb1",
+        homogeneous   : false,
+        poolMax       : 10
+    });
+
+    const connection = await pool.getConnection({
+        user          : "sys",
+        password      : "secret",
+        privilege     : oracledb.SYSDBA
+    })
+
+If you create a homogeneous pool with an invalid value specified in the
+:ref:`privilege <createpoolpoolattrsprivilege>` property of
+:meth:`oracledb.createPool()` in both node-oracledb Thin and Thick modes, then
+the following error is raised::
+
+    NJS-007: invalid value for "privilege" in parameter 1
+
+However, any valid ``privilege`` property value is ignored in node-oracledb
+Thick mode during homogeneous pool creation.
+
+Note that if node-oracledb Thick mode is using the Oracle Client libraries
+located in the Oracle Database installation, that is on the same machine as
+the database and is not using Oracle Instant Client, then operating system
 privileges may be used for authentication. In this case the password
 value is ignored. For example on Linux, membership of the operating
 system `dba <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=