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