24. Upgrading to the Latest node-oracledb Releases
24.1. Upgrading from node-oracledb 6.3 to 6.4
Review the node-oracledb Release Notes and take advantage of new features.
By setting the new
oracledb.future.oldJsonColumnAsObj
property to true, you can fetch the BLOB columns which have the theIS JSON FORMAT OSON
constraint enabled in the same way as columns of type JSON. See Using BLOB columns with OSON Storage Format in node-oracledb for more information. In a future version of node-oracledb, the setting of this attribute will no longer be required since this will become the default behavior.With the new
connection.encodeOSON()
andconnection.decodeOSON()
methods, you can fetch and insert into columns which have theIS JSON FORMAT OSON
constraint enabled.The new metadata information attribute
isOson
indicates whether the fetched column contains binary encoded OSON data.The
lob.getData()
now accepts theoffset
andamount
as input parameters.The
connection.execute()
now accepts an object as an input parameter. The object is returned from the third-party sql-template-tag module and exposesstatement
andvalues
properties to retrieve SQL string and bind values.The new
dbObject.toMap()
method returns a map object for the collection types indexed by PLS_INTEGER.Using the new
oracledb.poolPingTimeout
andpool.poolPingTimeout
properties, you can now limit theconnection.ping()
call time.Using the new warning property of the result object in
connection.executeMany()
, your application can manually check for database warnings such as PL/SQL Compilation Warnings.In node-oracledb Thick mode, the SodaDocumentCursor class now supports asynchronous iteration.
24.2. Upgrading from node-oracledb 6.2 to 6.3
Review the node-oracledb Release Notes and take advantage of new features.
Using the new warning property of the result object in
connection.execute()
, your application can manually check for database warnings such as PL/SQL Compilation Warnings.The new
connection.warning
property can be used to check for warnings that are generated during connection such as the password being in the grace period.By setting the new
oracledb.future.oldJsonColumnAsObj
property to true, you can fetch the VARCHAR2 and LOB columns which contain JSON in the same way as columns of type JSON. See Using the Oracle Database 12c JSON Type in node-oracledb for more information. In a future version of node-oracledb, the setting of this attribute will no longer be required since this will become the default behavior.With the new oracledb.DB_TYPE_XMLTYPE constant, you can now represent data of type
SYS.XMLTYPE
in thefetchType
anddbType
metadata information attributes.node-oracledb now supports using Azure and Oracle Cloud Infrastructure (OCI) Software Development Kits (SDKs) to generate authentication tokens.
With the new connection properties
connection.dbDomain
,connection.dbName
,connection.maxOpenCursors
,connection.serviceName
andconnection.transactionInProgress
, you can identify the database domain name, database instance name, maximum number of cursors that can be opened per connection, database service name, and status of any ongoing transactions on the connection respectively.The new metadata information attribute
isJson
indicates whether the fetched column contains JSON data.The new metadata information attributes
annotations
,domainName
, anddomainSchema
identifies the annotations object, the name of the SQL domain, and the schema name of the SQL domain associated with the fetched column. Annotations and SQL domains are supported from Oracle Database 23c onwards. For node-oracledb Thick mode, Oracle Client 23c is also required.In node-oracledb Thin mode,
SYS.XMLTYPE
data can now be fetched as strings.
24.3. 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:
You can now fetch all the current indexes from a SODA collection using the new
sodaCollection.listIndexes()
method.You can disable modification of SODA documents by other connections using the new
sodaOperation.lock()
method.
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.
24.4. Upgrading from node-oracledb 6.0 to 6.1
Review the node-oracledb Release Notes and take advantage of new features.
With the new Advanced Queuing (AQ) features in node-oracledb Thick mode:
You can now enqueue and dequeue AQ messages as JSON.
The
queue.enqOne()
andqueue.enqMany()
methods now return a message object with which you can view the unique identifier of each message.
With the new
connection.instanceName
property, you can identify the Oracle Database instance name associated with a connection.
24.5. 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 ofresult.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 neworacledb.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.
24.5.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.
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.
If you are upgrading from node-oracledb 5.5, then review Upgrading from node-oracledb 5.5 to 6.0.
Remove all calls to
oracledb.initOracleClient()
from the application since this enables the node-oracledb Thick mode.If the
configDir
parameter ofinitOracleClient()
had been used, then set theconfigDir
attribute of anyoracledb.getConnection()
ororacledb.createPool()
calls.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 Clientnetwork/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.The node-oracledb Thin mode does not support
sqlnet.ora
files. Some of these parameters can be set asgetConnection()
orcreatePool()
attributes, or in an Easy Connect string, or in thetnsnames.ora
file connect descriptors.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.Remove calls to
oracledb.oracleclientVersion()
andoracledb.oracleclientVersionString
which are only available in the node-oracledb Thick mode. Oracle Client libraries are not used in Thin mode.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 attributepool.connectionsOpen
will change over time and will not be equal topool.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 thepool.poolMin
connections were created.Make any additional code changes required for Error Handling differences, or Character Sets and Localization differences.
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.
24.6. 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.
24.7. Upgrading from node-oracledb 5.3 to 5.4
Review the node-oracledb Release Notes and take advantage of new features.
With the
connection.isHealthy()
function, you can perform a local connection health check.Take advantage of token-based authentication when establishing pool based connections and standalone connections.
The new
stack
property in Error object aids in diagnosis of errors.
24.8. Upgrading from node-oracledb 5.2 to 5.3
Review the node-oracledb Release Notes and take advantage of new features.
Using the
keepInStmtCache
option in execute(), executeMany(), and queryStream(), you can control whether executed statements should be retained in the Statement Cache.The connection pool statistics is encapsulated in a PoolStatistics Class. The
poolstatistics.logStatistics()
function is added which is equivalent to the existingpool.logStatistics()
function. The exposed pool properties areuser
,connectString
,edition
,events
,externalAuth
, andhomogeneous
on the Pool and PoolStatistics classes.Take advantage of the Two-Phase Commit feature.
24.9. Upgrading from node-oracledb 5.1 to 5.2
Review the node-oracledb Release Notes and take advantage of new features.
Review the dead connection detection changes and adjust any application error checks to look for the new error DPI-1080.
Replace obsolete uses of
_enableStats
and_logStats()
with the new functionality enableStatistics,getStatistics()
, andlogStatistics()
.
24.10. 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.
24.11. 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) andfinish
event (for writeable streams) instead of depending on theclose
event. Applications should migrate to the Node.js 8destroy()
method instead of the deprecated node-oracledbclose()
method. Note that unlikeclose()
, thedestroy()
method does not take a callback parameter. Ifdestroy()
is given an error argument, anerror
event is emitted with this error.
24.12. 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.
24.13. 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.
24.14. 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.