diff --git a/INSTALL.md b/INSTALL.md
index 0d520aec..a6e4091b 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1933,6 +1933,12 @@ If creating a connection fails:
messages, the installation instructions, and see [Initializing
Node-oracledb][17].
+ Note that on Linux, calling [`initOracleClient()`](#odbinitoracleclient) is
+ not sufficient for setting the Oracle Client library path. Those libraries
+ still need to be in the operating system search path, such as from running
+ `ldconfig` or set in the environment variable `LD_LIBRARY_PATH` before your
+ Node.js process starts.
+
- If you got *DPI-1072: the Oracle Client library version is unsupported*, then
review the installation requirements. Node-oracledb needs Oracle client
libraries 11.2 or later. Note that version 19 is not supported on Windows 7.
diff --git a/doc/api.md b/doc/api.md
index 979fc9c7..09bd23eb 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -448,7 +448,11 @@ For installation information, see the [Node-oracledb Installation Instructions][
- 14.1.1 [`close()`](#sodadoccursorclose)
- 14.1.2 [`getNext()`](#sodadoccursorgetnext)
15. [Initializing Node-oracledb](#initnodeoracledb)
- - 15.1 [Locating the Oracle Client Libraries](#oracleclientloading)
+ - 15.1 [Setting the Oracle Client Library Directory](#oracleclientloading)
+ - 15.1.1 [Setting the Oracle Client Directory on Windows](#oracleclientloadingwindows)
+ - 15.1.2 [Setting the Oracle Client Directory on macOS](#oracleclientloadingmacos)
+ - 15.1.3 [Setting the Oracle Client Directory on Linux and Related Platforms](#oracleclientloadinglinux)
+ - 15.1.4 [Calling `initOracleClient()` to set the Oracle Client Directory](#oracleclientcallinginit)
- 15.2 [Optional Oracle Net Configuration](#tnsadmin)
- 15.3 [Optional Oracle Client Configuration](#oraaccess)
- 15.4 [Oracle Environment Variables](#environmentvariables)
@@ -3067,7 +3071,7 @@ Attribute | Description
`configDir` | This specifies the directory in which the [Optional Oracle Net Configuration](#tnsadmin) and [Optional Oracle Client Configuration](#oraaccess) files reside. It is equivalent to setting the Oracle environment variable `TNS_ADMIN` to this value. Any value in that environment variable prior to the call to `oracledb.initOracleClient()` is ignored. On Windows, remember to double each backslash used as a directory separator. If `configDir` is not set, Oracle's default configuration file [search heuristics](#tnsadmin) are used.
`driverName` | This specifies the driver name value shown in database views, such as `V$SESSION_CONNECT_INFO`. It can be used by applications to identify themselves for tracing and monitoring purposes. The convention is to separate the product name from the product version by a colon and single space characters. If this attribute is not specified, the value "node-oracledb : *version*" is used. See [Other Node-oracledb Initialization](#otherinit).
`errorUrl` | This specifies the URL that is included in the node-oracledb exception message if the Oracle Client libraries cannot be loaded. This allows applications that use node-oracledb to refer users to application-specific installation instructions. If this attribute is not specified, then the [node-oracledb installation instructions][2] URL is used. See [Other Node-oracledb Initialization](#otherinit).
-`libDir` | This specifies the directory containing the Oracle Client libraries. If `libDir` is not specified, the default library search mechanism is used. If your client libraries are in a full Oracle Client or Oracle Database installation, such as [Oracle Database "XE" Express Edition][130], then you must have previously set environment variables like `ORACLE_HOME` before calling `initOracleClient()`. On Windows, remember to double each backslash used as a directory separator. See [Locating the Oracle Client Libraries](#oracleclientloading).
+`libDir` | This specifies the directory containing the Oracle Client libraries. If `libDir` is not specified, the default library search mechanism is used. If your client libraries are in a full Oracle Client or Oracle Database installation, such as [Oracle Database "XE" Express Edition][130], then you must have previously set environment variables like `ORACLE_HOME` before calling `initOracleClient()`. On Windows, remember to double each backslash used as a directory separator. See [Setting the Oracle Client Library Directory](#oracleclientloading).
On Linux, ensure a `libclntsh.so` file exists. On macOS ensure a
@@ -8835,102 +8839,159 @@ the Oracle Client and Oracle Database communicate.
![node-oracledb Architecture](./images/node-oracledb-architecture.png)
-### 15.1 Locating the Oracle Client Libraries
+### 15.1 Setting the Oracle Client Library Directory
Node-oracledb dynamically loads the Oracle Client libraries using a search
-heuristic. If appropriate libraries cannot be found, node-oracledb will return
-an error like "Error: DPI-1047: Cannot locate a 64-bit Oracle Client library".
+heuristic. Only the first set of libraries found are loaded. If appropriate
+libraries cannot be found, node-oracledb will return an error like *DPI-1047:
+Cannot locate a 64-bit Oracle Client library*.
-Only the first set of libraries found are loaded. The libraries can be in an
-installation of Oracle Instant Client, in a full Oracle Client installation, or
-in an Oracle Database installation (if Node.js is running on the same machine as
-the database). The versions of Oracle Client and Oracle Database do not have to
-be the same. For certified configurations see Oracle Support's [Doc ID
-207303.1][187] and see the [node-installation instructions][2].
+The libraries can be:
-Node-oracledb looks for the Oracle Client libraries as follows:
+- in an installation of Oracle Instant Client.
-- On Windows:
+- or in a full Oracle Client installation from running the Oracle Universal
+ installer `runInstaller`.
- - In the [`libDir`](#odbinitoracleclientattrsopts) directory specified in a
- call to [`oracledb.initOracleClient()`](#odbinitoracleclient). This
- directory should contain the libraries from an unzipped Instant Client
- 'Basic' or 'Basic Light' package. If you pass the library directory from
- a full client or database installation, such as [Oracle Database "XE"
- Express Edition][130], then you will need to have previously set your
- environment to use that software installation otherwise files such as
- message files will not be located. If the Oracle Client libraries cannot
- be loaded from `libDir`, then an error is thrown.
+- or in an Oracle Database installation, if Node.js is running on the same
+ machine as the database.
- - If `libDir` was not specified, then Oracle Client libraries are looked for
- in the directory where the `oracledb*.node` binary is. For example in
- `node_modules\oracledb\build\Release`. This directory should contain the
- libraries from an unzipped Instant Client 'Basic' or 'Basic Light'
- package. If the libraries are not found, no error is thrown and the
- search continues, see next bullet point.
+The versions of Oracle Client and Oracle Database do not have to be the same.
+For certified configurations see Oracle Support's [Doc ID 207303.1][187] and
+see the [node-installation instructions][2].
- - In the directories on the system library search path, e.g. the `PATH`
- environment variable. If the Oracle Client libraries cannot be loaded,
- then an error is thrown.
+#### 15.1.1 Setting the Oracle Client Directory on Windows
-- On macOS:
+On Windows, node-oracledb looks for the Oracle Client libraries as follows:
- - In the [`libDir`](#odbinitoracleclientattrsopts) directory specified in a
- call to [`oracledb.initOracleClient()`](#odbinitoracleclient). This
- directory should contain the libraries from an unzipped Instant Client
- 'Basic' or 'Basic Light' package. If the Oracle Client libraries cannot
- be loaded from `libDir`, then an error is thrown.
+- In the [`libDir`](#odbinitoracleclientattrsopts) directory specified in a
+ call to [`oracledb.initOracleClient()`](#oracleclientcallinginit). This
+ directory should contain the libraries from an unzipped Instant Client
+ 'Basic' or 'Basic Light' package. If you pass the library directory from a
+ full client or database installation, such as [Oracle Database "XE" Express
+ Edition][130], then you will need to have previously set your environment to
+ use that software installation otherwise files such as message files will not
+ be located. If the Oracle Client libraries cannot be loaded from `libDir`,
+ then an error like *DPI-1047: Cannot locate a 64-bit Oracle Client library*
+ is thrown.
- - If `libDir` was not specified, then Oracle Client libraries are looked for
- in the directory where the `oracledb*.node` binary is. For example in
- `node_modules/oracledb/build/Release`. This directory should contain the
- libraries from an unzipped Instant Client 'Basic' or 'Basic Light'
- package. For example, use `ln -s ~/Downloads/instantclient_19_8/libclntsh.dylib
- node_modules/oracledb/build/Release/`. If the libraries are not found, no
- error is thrown and the search continues, see next bullet point.
+- If `libDir` was not specified, then Oracle Client libraries are looked for
+ in the directory where the `oracledb*.node` binary is. For example in
+ `node_modules\oracledb\build\Release`. This directory should contain the
+ libraries from an unzipped Instant Client 'Basic' or 'Basic Light'
+ package. If the libraries are not found, no error is thrown and the
+ search continues, see next bullet point.
- - In the library search path such as set in `DYLD_LIBRARY_PATH` (note this
- variable does not propagate to sub-shells) or in `/usr/local/lib`. If the
- Oracle Client libraries cannot be loaded, then an error is thrown.
+- In the directories on the system library search path, e.g. the `PATH`
+ environment variable. If the Oracle Client libraries cannot be loaded, then
+ an error like *DPI-1047: Cannot locate a 64-bit Oracle Client library* is
+ thrown.
-- On Linux and related platforms:
+#### 15.1.2 Setting the Oracle Client Directory on macOS
- - In the [`libDir`](#odbinitoracleclientattrsopts) directory specified in a
- call to [`oracledb.initOracleClient()`](#odbinitoracleclient). Note on
- Linux this is only useful to force immediate loading of the libraries
- because the libraries must also be in the system library search path,
- i.e. configured with `ldconfig` or set in `LD_LIBRARY_PATH`. This
- directory should contain the libraries from an unzipped Instant Client
- 'Basic' or 'Basic Light' package. If you pass the library directory from
- a full client or database installation, such as [Oracle Database "XE"
- Express Edition][130] then you will need to have previously set the
- `ORACLE_HOME` environment variable. If the Oracle Client libraries cannot
- be loaded from `libDir`, then an error is thrown.
+On macOS, node-oracledb looks for the Oracle Client libraries as follows:
- - If `libDir` was not specified, then Oracle Client libraries are looked for
- in the operating system library search path, such as configured with
- `ldconfig` or set in the environment variable `LD_LIBRARY_PATH`. On some
- UNIX platforms an OS specific equivalent, such as `LIBPATH` or
- `SHLIB_PATH` is used instead of `LD_LIBRARY_PATH`. If the libraries are
- not found, no error is thrown and the search continues, see next bullet
- point.
+- In the [`libDir`](#odbinitoracleclientattrsopts) directory specified in a
+ call to [`oracledb.initOracleClient()`](#oracleclientcallinginit). This
+ directory should contain the libraries from an unzipped Instant Client
+ 'Basic' or 'Basic Light' package. If the Oracle Client libraries cannot be
+ loaded from `libDir`, then an error like *DPI-1047: Cannot locate a 64-bit
+ Oracle Client library* is thrown.
- - In `$ORACLE_HOME/lib`. Note the environment variable `ORACLE_HOME` should
- only ever be set when you have a full database installation or full client
- installation. It should not be set if you are using Oracle Instant
- Client. The `ORACLE_HOME` variable, and other necessary variables, should
- be set before starting Node.js. See [Oracle Environment
- Variables](#environmentvariables). If the Oracle Client libraries cannot
- be loaded, then an error is thrown.
+- If `libDir` was not specified, then Oracle Client libraries are looked for
+ in the directory where the `oracledb*.node` binary is. For example in
+ `node_modules/oracledb/build/Release`. This directory should contain the
+ libraries from an unzipped Instant Client 'Basic' or 'Basic Light'
+ package. For example, use `ln -s ~/Downloads/instantclient_19_8/libclntsh.dylib
+ node_modules/oracledb/build/Release/`. If the libraries are not found, no
+ error is thrown and the search continues, see next bullet point.
+
+- In the library search path such as set in `DYLD_LIBRARY_PATH` (note this
+ variable does not propagate to sub-shells) or in `/usr/local/lib`. If the
+ Oracle Client libraries cannot be loaded, then an error like *DPI-1047:
+ Cannot locate a 64-bit Oracle Client library* is thrown.
+
+#### 15.1.3 Setting the Oracle Client Directory on Linux and Related Platforms
+
+On Linux and related platforms, node-oracledb looks for the Oracle Client
+libraries as follows:
+
+- In the [`libDir`](#odbinitoracleclientattrsopts) directory specified in a
+ call to [`oracledb.initOracleClient()`](#oracleclientcallinginit). This
+ directory should contain the libraries from an unzipped Instant Client
+ 'Basic' or 'Basic Light' package. If you pass the library directory from a
+ full client or database installation, such as [Oracle Database "XE" Express
+ Edition][130] then you will need to have previously set the `ORACLE_HOME`
+ environment variable. If the Oracle Client libraries cannot be loaded from
+ `libDir`, then an error is thrown.
+
+ **Note on Linux `initOracleClient()` is only useful to force immediate
+ loading of the libraries because the libraries must also be in the system
+ library search path, i.e. configured with `ldconfig` or set in
+ `LD_LIBRARY_PATH`, before Node.js is started**.
+
+- If `libDir` was not specified, then Oracle Client libraries are looked for
+ in the operating system library search path, such as configured with
+ `ldconfig` or set in the environment variable `LD_LIBRARY_PATH`. On some
+ UNIX platforms an OS specific equivalent, such as `LIBPATH` or
+ `SHLIB_PATH` is used instead of `LD_LIBRARY_PATH`. If the libraries are
+ not found, no error is thrown and the search continues, see next bullet
+ point.
+
+- In `$ORACLE_HOME/lib`. Note the environment variable `ORACLE_HOME` should
+ only ever be set when you have a full database installation or full client
+ installation. It should not be set if you are using Oracle Instant Client.
+ The `ORACLE_HOME` variable, and other necessary variables, should be set
+ before starting Node.js. See [Oracle Environment
+ Variables](#environmentvariables). If the Oracle Client libraries cannot be
+ loaded, then an error like *DPI-1047: Cannot locate a 64-bit Oracle Client
+ library* is thrown.
+
+#### 15.1.4 Calling `initOracleClient()` to set the Oracle Client Directory
+
+Applications can call the synchronous function
+[`oracledb.initOracleClient()`](#odbinitoracleclient) to specify the directory
+containing Oracle Instant Client libraries. The libraries are loaded when
+`initOracleClient()` is called. For example:
+
+```javascript
+const oracledb = require('oracledb');
+
+if (process.platform === 'win32') {
+ // Windows
+ oracledb.initOracleClient({libDir: 'C:\\oracle\\instantclient_19_6'});
+} else if (process.platform === 'darwin') {
+ // macOS
+ oracledb.initOracleClient({libDir: process.env.HOME + '/Downloads/instantclient_19_8'});
+}
+// else on other platforms like Linux the system library search path MUST always be
+// set before Node.js is started, for example with ldconfig or LD_LIBRARY_PATH.
+```
+
+If you use backslashes in the `libDir` string, you will need to double them.
+
+The `initOracleClient()` function should only be called once.
+
+**Note**: If you set `libDir` on Linux and related platforms, you must still have
+configured the system library search path to include that directory before
+starting Node.js.
+
+On any operating system, if you set `libDir` to the library directory of a full
+database or full client installation (such as from running `runInstaller`), you
+will need to have previously set the Oracle environment, for example by setting
+the `ORACLE_HOME` environment variable. Otherwise you will get errors like
+*ORA-1804*. You should set this variable, and other Oracle environment
+variables, before starting Node.js, as shown in [Oracle Environment
+Variables](#environmentvariables).
If you call `initOracleClient()` with a `libDir` attribute, the Oracle Client
libraries are loaded immediately from that directory. If you call
`initOracleClient()` but do *not* set the `libDir` attribute, the Oracle Client
-libraries are loaded immediately using the search heuristic above. If you do
-not call `initOracleClient()`, then the libraries are loaded using the search
-heuristic when the first node-oracledb function that depends on the libraries is
-called, for example when a connection pool is created. If there is a problem
-loading the libraries, then an error is thrown.
+libraries are loaded immediately using the search heuristic discussed in
+earlier sections. If you do not call `initOracleClient()`, then the libraries
+are loaded using the search heuristic when the first node-oracledb function
+that depends on the libraries is called, for example when a connection pool is
+created. If there is a problem loading the libraries, then an error is thrown.
Make sure the Node.js process has directory and file access permissions for the
Oracle Client libraries. On Linux ensure a `libclntsh.so` file exists. On
@@ -8939,6 +9000,11 @@ load `libclntsh.*.XX.1` files in `libDir` or from the directory where the
`oracledb*.node` binary is. Note other libraries used by `libclntsh*` are also
required.
+The `oracledb.initOracleClient()` method and searching of the directory where
+the `oracledb*.node` binary is located were added in node-oracledb 5.0.
+
+##### Tracing Oracle Client libraries loading
+
To trace the loading of Oracle Client libraries, the environment variable
`DPI_DEBUG_LEVEL` can be set to 64 before starting Node.js. For example, on
Linux, you might use:
@@ -8948,44 +9014,6 @@ $ export DPI_DEBUG_LEVEL=64
$ node myapp.js 2> log.txt
```
-The `oracledb.initOracleClient()` method and searching of the directory where
-the `oracledb*.node` binary is located were added in node-oracledb 5.0.
-
-##### Using `initOracleClient()` to set the Oracle Client directory
-
-Applications can call the synchronous function
-[`oracledb.initOracleClient()`](#odbinitoracleclient) to specify the directory
-containing Oracle Instant Client libraries. The Oracle Client Libraries are
-loaded when `initOracleClient()` is called. For example, if the Oracle Instant
-Client Libraries are in `C:\oracle\instantclient_19_6` on Windows, then you can
-use:
-
-```javascript
-const oracledb = require('oracledb');
-try {
- oracledb.initOracleClient({libDir: 'C:\\oracle\\instantclient_19_6'});
-} catch (err) {
- console.error('Whoops!');
- console.error(err);
- process.exit(1);
-}
-```
-
-If you use backslashes in the `libDir` string, you will need to double them.
-
-The `initOracleClient()` function should only be called once.
-
-If you set `libDir` on Linux and related platforms, you must still have
-configured the system library search path to include that directory before
-starting Node.js.
-
-On any operating system, if you set `libDir` to the library directory of a full
-database or full client installation, you will need to have previously set the
-Oracle environment, for example by setting the `ORACLE_HOME` environment
-variable. Otherwise you will get errors like *ORA-1804*. You should set this,
-and other Oracle environment variables, before starting Node.js, as shown in
-[Oracle Environment Variables](#environmentvariables).
-
### 15.2 Optional Oracle Net Configuration
Optional Oracle Net configuration files are read when node-oracledb