25. Upgrading to the Latest node-oracledb Releases

25.1. Upgrading from node-oracledb 6.4 to 6.5

  • Review the node-oracledb Release Notes and take advantage of new features.

  • The new oracledb.JsonId class represents JSON ID values returned by SODA in Oracle Database 23ai and later in the _id attribute of documents stored in native collections.

  • You can now pass BigInt values as binds to connection.execute() and connection.executeMany().

  • With the new oracledb.DB_TYPE_VECTOR constant, you can now represent Oracle Database 23ai data type VECTOR with the vectorDimensions and vectorFormat metadata information attributes.

  • In node-oracledb Thin mode, a subset of pool creation properties can be changed without restarting the pool or application using the pool.reconfigure() method.

  • In node-oracledb Thin mode, you can now use Oracle Database 23ai’s Implicit Connection Pooling feature with Database Resident Connection Pooling (DRCP) and Proxy Resident Connection Pooling (PRCP).

25.2. Upgrading from node-oracledb 6.3 to 6.4

25.3. Upgrading from node-oracledb 6.2 to 6.3

25.4. Upgrading from node-oracledb 6.1 to 6.2

  • Review the node-oracledb Release Notes and take advantage of new features.

  • With the new SODA features in node-oracledb Thick mode:

  • Using the new binaryDir property in node-oracledb Thick mode, you can now specify the directory that is added to the start of the default search path used by initOracleClient() to load the Thick mode binary module.

  • Using the new packageName property in DbObject class, you can identify the name of the package if the type refers to a PL/SQL type.

25.5. Upgrading from node-oracledb 6.0 to 6.1

25.6. Upgrading from node-oracledb 5.5 to 6.0

  • Review the node-oracledb Release Notes and take advantage of new features.

  • To use node-oracledb 6.0, you need Node.js 14.6 or later versions. Update your Node.js version, if necessary.

  • With node-oracledb 6.0, connections to Oracle Database can be established in one of the two modes:

    • Thin mode: By default, node-oracledb operates in this mode and connects directly to Oracle Database. This mode does not require Oracle Client libraries.

    • Thick mode: When Oracle Client libraries are used, then node-oracledb is in Thick mode. You must call oracledb.initOracleClient() to enable Thick mode. See Enabling node-oracledb Thick Mode.

  • Review the updated node-oracledb installation instructions and initialization options.

  • The Oracle Database features supported by the node-oracledb Thin and Thick modes and the notable differences between these two modes are detailed here.

  • If your application currently uses Thick mode, and you want to use the Thin mode, see Changing Applications to Use node-oracledb Thin Mode.

  • Note that the Oracle Database Type constants were changed to database type objects in node-oracledb 6.0. When comparing fetch types, ensure that you are using the database type object name instead of the the database type number. For example, use result.metadata[0].fetchType == oracledb.DB_TYPE_VARCHAR instead of result.metadata[0].fetchType == 2001.

  • Oracle Database DATE and TIMESTAMP types are now returned as JavaScript date types in the application’s timezone. These database types are no longer fetched or bound as TIMESTAMP WITH LOCAL TIME ZONE. The connection session time zone does not impact these database types. There is no change to the handling of TIMESTAMP WITH TIMEZONE and TIMESTAMP WITH LOCAL TIMEZONE types.

  • The execution option attribute fetchInfo was deprecated. You can use the Using Fetch Type Handlers functionality instead which has introduced a new oracledb.fetchTypeHandler and equivalent execution option which allows you to alter the queried data before it is returned to the application.

  • The previously deprecated Token-Based Authentication accessTokenCallback attribute has been removed. Use accessToken instead.

  • Extended metadata is now always returned for queries. The oracledb.extendedMetaData and equivalent execution attribute values are ignored.

  • The node-oracledb Thin and Thick modes may return different errors in some scenarios. See Error Handling.

  • The node-oracledb Thick mode uses Oracle Database’s National Language Support (NLS) functionality to assist in globalizing applications. The node-oracledb Thin mode uses Node.js localization functions. See Character Sets and Localization.

25.6.1. Changing Applications to Use node-oracledb Thin Mode

Changing an existing application that currently uses Thick mode to use Thin mode may require a few changes as detailed below.

  1. Review Oracle Database Features Supported by node-oracledb and Differences between the node-oracledb Thin and Thick Modes to ensure that all the features required for your application are supported by the Thin mode.

    The node-oracledb Thin and Thick modes can both connect to on-premises databases and Oracle Cloud databases. However, the node-oracledb Thin mode does not support some of the advanced Oracle Database features such as Application Continuity (AC), Advanced Queuing (AQ), Continuous Query Notification (CQN), SODA, and Sharding.

  2. If you are upgrading from node-oracledb 5.5, then review Upgrading from node-oracledb 5.5 to 6.0.

  3. Remove all calls to oracledb.initOracleClient() from the application since this enables the node-oracledb Thick mode.

  4. If the configDir parameter of initOracleClient() had been used, then set the configDir attribute of any oracledb.getConnection() or oracledb.createPool() calls.

  5. If the application is connecting using a net service alias and is looking up that alias in a tnsnames.ora file from a “default” location such as the Instant Client network/admin/ subdirectory, in $ORACLE_HOME/network/admin/, or in $ORACLE_BASE/homes/XYZ/network/admin/ (in a read-only Oracle Database home), then the configuration file directory must now explicitly be set. See Using Optional Oracle Configuration Files.

  6. The node-oracledb Thin mode does not support sqlnet.ora files. Some of these parameters can be set as getConnection() or createPool() attributes, or in an Easy Connect string, or in the tnsnames.ora file connect descriptors.

  7. If you were using node-oracledb in an ORACLE_HOME database installation environment, you will now need to use an explicit connection string since the ORACLE_SID environment variable is not used in node-oracledb Thin mode.

  8. Remove calls to oracledb.oracleclientVersion() and oracledb.oracleclientVersionString which are only available in the node-oracledb Thick mode. Oracle Client libraries are not used in Thin mode.

  9. Ensure that any assumptions about when connections are created in the connection pool are eliminated. The node-oracledb Thin mode creates connections in an async fashion and so oracledb.createPool() will return before any, or all, minimum number of connections are created. The attribute pool.connectionsOpen will change over time and will not be equal to pool.poolMin immediately after the pool is created. In node-oracledb Thick mode and earlier node-oracledb versions, oracledb.createPool() does not return control to the application until all the pool.poolMin connections were created.

  10. Make any additional code changes required for Error Handling differences, or Character Sets and Localization differences.

  11. When you are satisfied, you can optionally remove Oracle Client libraries. For example, by deleting your Oracle Instant Client directory.

You can find the node-oracledb mode by checking node-oracledb attributes or querying the V$SESSION_CONNECT_INFO table, see Finding the node-oracledb Mode.

25.7. Upgrading from node-oracledb 5.4 to 5.5

  • Review the node-oracledb Release Notes and take advantage of new features.

  • With the new Oracle Advanced Queuing (AQ) Recipient Lists, you can now specify a list of recipients when enqueuing a message.

  • Take advantage of the new Open Authorization (OAuth 2.0) token-based authentication which allows users to authenticate to Oracle Database using Microsoft Azure Active Directory OAuth 2.0 tokens.

  • The connection pool creation attribute accessTokenCallback is deprecated. Use accessToken instead.

  • The pool.setAccessToken() method is deprecated.

25.8. Upgrading from node-oracledb 5.3 to 5.4

25.9. Upgrading from node-oracledb 5.2 to 5.3

25.10. Upgrading from node-oracledb 5.1 to 5.2

25.11. Upgrading from node-oracledb 4.2 to 5.0

  • Review the node-oracledb Release Notes and take advantage of new features.

  • Review the updated installation and initialization options in the node-oracledb installation instructions and Initializing Node-oracledb, particularly around how node-oracledb can locate Oracle Client libraries.

  • Choose a sensible value for the new Pool queueMax attribute, so that applications get the new error only under abnormal connection load. To allow all pooled connection requests to be queued (the previous behavior), set it to -1.

  • Take advantage of the new prefetchRows attribute to re-tune SQL queries.

  • Support for custom Promises was necessarily removed due to a refactoring of the module’s JavaScript layer. Code should be migrated to use the native Node.js Promise implementation.

  • The function call parameter errors NJS-005: invalid value for parameter and NJS-009: invalid number of parameters are now passed through the callback, if one is used. In earlier versions they were thrown without the ability for them to be caught.

25.12. Upgrading from node-oracledb 4.1 to 4.2

  • Review the node-oracledb Release Notes and take advantage of new features.

  • Review the updated Lob stream documentation. The best practice is to use the end event (for readable streams) and finish event (for writeable streams) instead of depending on the close event. Applications should migrate to the Node.js 8 destroy() method instead of the deprecated node-oracledb close() method. Note that unlike close(), the destroy() method does not take a callback parameter. If destroy() is given an error argument, an error event is emitted with this error.

25.13. Upgrading from node-oracledb 4.0 to 4.1

  • Review the node-oracledb Release Notes and take advantage of new features.

  • Review your application use of node-oracledb error messages since some have changed.

  • Note that the default for oracledb.events has reverted to false. If you relied on it being true, then explicitly set it.

25.14. Upgrading from node-oracledb 3.1 to 4.0

  • Review the node-oracledb Release Notes and take advantage of new features.

  • Update Node.js, if necessary. Node-oracledb 4.0 requires

    • Node.js 8.16 or higher

    • Node.js 10.16, or higher

    • Node.js 12

  • Review error handling. Some errors have changed. All exceptions are now passed through the error callback.

  • Code that relied on numeric values for the node-oracledb Type Constants and Oracle Database Type Constants will need updating. Use the constant names instead of their values.

  • To view node-oracledb class information, update code to use Object.getPrototypeOf().

  • Optionally migrate outFormat constants to the new, preferred names OUT_FORMAT_ARRAY and OUT_FORMAT_OBJECT.

25.15. Earlier node-oracledb Versions

Documentation about node-oracledb version 1 is here.

Documentation about node-oracledb version 2 is here.

Documentation about node-oracledb version 3 is here.

Documentation about node-oracledb version 4 is here.