Welcome to node-oracledb’s documentation!

The node-oracledb add-on for Node.js powers high performance Oracle Database applications.

node-oracledb is distributed under an open-source license. Changes in the node-oracledb releases can be found in the release notes.

This module is currently tested with Node.js 16, 18, and 20 against Oracle Database 23c, 21c, 19c, 12c, and 11gR2.

You can use assistive technology products, such as screen readers, while you work with the node-oracledb documentation. You can also use the keyboard instead of the mouse.

User Guide

• 1. Introduction to the node-oracledb Driver for Oracle Database
  • 1.1. Architecture
    • 1.1.1. node-oracledb Thin Mode Architecture
    • 1.1.2. node-oracledb Thick Mode Architecture
  • 1.2. Feature Highlights of node-oracledb
• 2. Installing node-oracledb
  • 2.1. Quick Start node-oracledb Installation
    • 2.1.1. Example: A SQL SELECT statement in Node.js
    • 2.1.2. Example: Simple Oracle Document Access (SODA) in Node.js
  • 2.2. Supported Oracle Database Versions
  • 2.3. Installation Requirements
  • 2.4. Installing Node.js and node-oracledb on Linux
    • 2.4.1. Install Node.js
    • 2.4.2. Install node-oracledb
    • 2.4.3. Install Oracle Client to use Thick Mode
    • 2.4.4. Installing Node.js and node-oracledb RPMs from yum.oracle.com
  • 2.5. Installing Node.js and node-oracledb on Apple macOS
    • 2.5.1. Install Node.js
    • 2.5.2. Install node-oracledb
    • 2.5.3. Install Oracle Client to use Thick Mode
  • 2.6. Installing Node.js and node-oracledb on Microsoft Windows
    • 2.6.1. Install Node.js
    • 2.6.2. Install node-oracledb
    • 2.6.3. Install Oracle Client to use Thick Mode
  • 2.7. Installing node-oracledb Without Internet Access
  • 2.8. Installing node-oracledb from Source Code
    • 2.8.1. Installing GitHub Clones and ZIP Files
    • 2.8.2. Installing using GitHub Branches and Tags
    • 2.8.3. Installing from a Source Package
    • 2.8.4. Installing from Oracle’s Repository
    • 2.8.5. Creating a node-oracledb Package from Source Code
  • 2.9. Hosting Your Own node-oracledb Packages
  • 2.10. Using node-oracledb in Docker
    • 2.10.1. Installing Node.js in Docker
    • 2.10.2. Installing node-oracledb and Your Application
    • 2.10.3. Installing Instant Client in Docker
    • 2.10.4. Using Oracle Net configuration Files and Oracle Wallets
• 3. Initializing node-oracledb
  • 3.1. Enabling node-oracledb Thick Mode
    • 3.1.1. Enabling node-oracledb Thick Mode on Windows
    • 3.1.2. Enabling node-oracledb Thick Mode on macOS
    • 3.1.3. Enabling node-oracledb Thick Mode on Linux and Related Platforms
    • 3.1.4. Tracing Oracle Client Libraries Loading
  • 3.2. Optional Oracle Configuration Files
    • 3.2.1. Optional Oracle Net Configuration Files
    • 3.2.2. Optional Oracle Client Configuration File
    • 3.2.3. Using Optional Oracle Configuration Files
    • 3.2.4. Using the Optional Time Zone File
  • 3.3. Oracle Environment Variables for node-oracledb Thick Mode
    • 3.3.1. Scripts for Setting the Default Environment in a Database Installation
  • 3.4. Other node-oracledb Thick Mode Initialization
• 4. Connecting to Oracle Database
  • 4.1. Standalone Connections
  • 4.2. Connection Strings
    • 4.2.1. Easy Connect Syntax for Connection Strings
    • 4.2.2. Embedded Connect Descriptor Strings
    • 4.2.3. Net Service Names for Connection Strings
    • 4.2.4. JDBC and Oracle SQL Developer Connection Strings
  • 4.3. Connections, Threads, and Parallelism
    • 4.3.1. Connections and Worker Threads
    • 4.3.2. Parallelism on Each Connection
  • 4.4. Connection Pooling
    • 4.4.1. Connection Pool Sizing
    • 4.4.2. Connection Pool Closing and Draining
    • 4.4.3. Connection Pool Caching
    • 4.4.4. Connection Pool Queue
    • 4.4.5. Connection Pool Monitoring
    • 4.4.6. Connection Pool Pinging
    • 4.4.7. Connection Tagging and Session State
    • 4.4.8. Heterogeneous and Homogeneous Connection Pools
  • 4.5. Connecting Using Proxy Authentication
  • 4.6. Connecting Using External Authentication
  • 4.7. Token-Based Authentication
    • 4.7.1. OAuth 2.0 Token-Based Authentication
    • 4.7.2. IAM Token-Based Authentication
  • 4.8. Database Resident Connection Pooling (DRCP)
    • 4.8.1. Implicit Connection Pooling with DRCP and PRCP
  • 4.9. Privileged Connections
  • 4.10. Securely Encrypting Network Traffic to Oracle Database
    • 4.10.1. Native Network Encryption
  • 4.11. Changing Passwords and Connecting with an Expired Password
    • 4.11.1. Changing Passwords
    • 4.11.2. Connecting with an Expired Password
  • 4.12. Connections and High Availability
    • 4.12.1. Preventing Premature Connection Closing
    • 4.12.2. Fast Application Notification (FAN)
    • 4.12.3. Runtime Load Balancing (RLB)
    • 4.12.4. Application Continuity
    • 4.12.5. Database Call Timeouts
  • 4.13. Connecting to Oracle Real Application Clusters (RAC)
  • 4.14. Connecting to Oracle Cloud Autonomous Databases
    • 4.14.1. One-way TLS Connection to Oracle Autonomous Database
    • 4.14.2. Mutual TLS connections to Oracle Cloud Autonomous Database
  • 4.15. Connecting using Multiple Wallets
  • 4.16. Connecting to Sharded Databases
    • 4.16.1. Examples to Connect to a Shard Based on the Sharding Key Type
• 5. Executing SQL
  • 5.1. SELECT Statements
    • 5.1.1. Fetching Rows with Direct Fetches
    • 5.1.2. Fetching Rows with Result Sets
    • 5.1.3. Query Streaming
    • 5.1.4. Query Output Formats
    • 5.1.5. Fetching Nested Cursors
    • 5.1.6. Query Column Metadata
    • 5.1.7. Changing Fetched Data
    • 5.1.8. Fetching Different Data Types
    • 5.1.9. Limiting Rows and Creating Paged Datasets
    • 5.1.10. Auto-Increment Columns
  • 5.2. Cursor Management
• 6. Executing PL/SQL
  • 6.1. PL/SQL Stored Procedures
  • 6.2. PL/SQL Stored Functions
  • 6.3. PL/SQL Anonymous PL/SQL Blocks
  • 6.4. Using DBMS_OUTPUT
  • 6.5. Edition-Based Redefinition
  • 6.6. Implicit Results
  • 6.7. Creating PL/SQL Procedures and Functions
    • 6.7.1. PL/SQL Compilation Warnings
• 7. Using Bind Variables
  • 7.1. IN Bind Parameters
    • 7.1.1. Bind by Name
    • 7.1.2. Bind by Position
    • 7.1.3. Bind Data Type Notes
  • 7.2. OUT and IN OUT Bind Parameters
    • 7.2.1. Accessing OUT Bind Values
  • 7.3. DML RETURNING Bind Parameters
  • 7.4. REF CURSOR Bind Parameters
  • 7.5. LOB Bind Parameters
    • 7.5.1. Size Limits for Binding LOBs to Strings and Buffers
  • 7.6. Binding Multiple Values to a SQL WHERE IN Clause
  • 7.7. Binding in a LIKE or REGEXP_LIKE Clause
  • 7.8. Binding Column and Table Names in Queries
• 8. Executing Batch Statements and Bulk Loading
  • 8.1. Identifying Affected Rows with executeMany()
  • 8.2. Handling Data Errors with executeMany()
  • 8.3. DML RETURNING with executeMany()
  • 8.4. Calling PL/SQL with executeMany()
  • 8.5. Binding Objects with executeMany()
• 9. Managing Transactions
• 10. Tuning node-oracledb
  • 10.1. Tuning Fetch Performance
    • 10.1.1. Choosing values for fetchArraySize and prefetchRows
  • 10.2. Database Round-trips
    • 10.2.1. Finding the Number of Round-Trips
  • 10.3. Statement Caching
    • 10.3.1. Setting the Statement Cache
    • 10.3.2. Tuning the Statement Cache
    • 10.3.3. Disabling the Statement Cache
  • 10.4. Client Result Caching (CRC)
    • 10.4.1. Configuring CRC
    • 10.4.2. Using CRC
    • 10.4.3. Verifying CRC
• 11. Using CLOB, NCLOB and BLOB Data
  • 11.1. Simple Insertion of LOBs
  • 11.2. Simple LOB Queries and PL/SQL OUT Binds
    • 11.2.1. Querying LOBs
  • 11.3. Streaming Lobs
    • 11.3.1. Readable Lobs
    • 11.3.2. Writeable Lobs
  • 11.4. Using RETURNING INTO to Insert into LOBs
  • 11.5. Getting LOBs as Streams from Oracle Database
    • 11.5.1. LOB Query Example
    • 11.5.2. PL/SQL LOB Parameter Fetch Example
    • 11.5.3. Streaming Out a Lob
  • 11.6. Using createLob() for PL/SQL IN Binds
    • 11.6.1. Passing a Lob Into PL/SQL
  • 11.7. Closing Lobs
• 12. Using JSON Data
  • 12.1. Using the Oracle Database 21c JSON Type in node-oracledb
    • 12.1.1. Using Oracle Client Libraries 19c or Earlier
  • 12.2. Using the Oracle Database 12c JSON Type in node-oracledb
  • 12.3. Using BLOB columns with OSON Storage Format in node-oracledb
  • 12.4. IN Bind Type Mapping
  • 12.5. Query and OUT Bind Type Mapping
  • 12.6. SQL/JSON Path Expressions
  • 12.7. Accessing Relational Data as JSON
  • 12.8. Portable JSON
• 13. Using XMLType Data
  • 13.1. Inserting XML
  • 13.2. Fetching XML
• 14. Using Oracle Database Objects and Collections
  • 14.1. Inserting Objects
  • 14.2. Fetching Objects
  • 14.3. PL/SQL Collection Types
    • 14.3.1. PL/SQL Collection Associative Arrays (Index-by)
    • 14.3.2. PL/SQL Collection VARRAY Types
    • 14.3.3. PL/SQL Collection Nested Tables
  • 14.4. PL/SQL RECORD Types
  • 14.5. Inserting or Passing Multiple Objects of the Same Type
  • 14.6. Oracle Database Object Type Limitations
• 15. Working with Simple Oracle Document Access (SODA)
  • 15.1. Node-oracledb SODA Objects
  • 15.2. Committing SODA Work
  • 15.3. Node-oracledb SODA Requirements
  • 15.4. Creating and Dropping SODA Collections
  • 15.5. Creating and Accessing SODA Documents
  • 15.6. SODA Query-by-Example Searches for JSON Documents
  • 15.7. Creating and Dropping SODA Indexes
    • 15.7.1. Retrieving All Index Specifications in a Collection
  • 15.8. SODA Text Searches
  • 15.9. SODA Client-Assigned Keys and Collection Metadata
  • 15.10. JSON Data Guides in SODA
  • 15.11. Using the SODA Metadata Cache
• 16. Using Oracle Advanced Queuing (AQ)
  • 16.1. Sending Simple AQ Messages
  • 16.2. Sending Oracle Database JSON AQ Messages
  • 16.3. Sending Oracle Database Object AQ Messages
  • 16.4. Changing AQ options
  • 16.5. Enqueuing and Dequeuing Multiple Messages
  • 16.6. Advanced Queuing Notifications
  • 16.7. Recipient Lists
• 17. Working with Continuous Query Notification (CQN)
• 18. Using Two-Phase Commits (TPC)
• 19. Starting and Stopping Oracle Database
  • 19.1. Simple Database Start Up and Shut Down
    • 19.1.1. Simple Start Up
    • 19.1.2. Simple Shut Down
  • 19.2. Flexible Database Start Up and Shut Down
    • 19.2.1. Flexible Start Up
    • 19.2.2. Flexible Shut Down
  • 19.3. Oracle Multitenant Pluggable and Container Databases
• 20. Tracing with node-oracledb
  • 20.1. Application Tracing
    • 20.1.1. End-to-End Tracing, Mid-tier Authentication, and Auditing
    • 20.1.2. Debugging PL/SQL with the Java Debug Wire Protocol
    • 20.1.3. Tracing Executed Statements
    • 20.1.4. Tracing Bind Values
    • 20.1.5. Database Views
  • 20.2. Finding the node-oracledb Mode
  • 20.3. Low Level node-oracledb Driver Tracing
• 21. Character Sets and Localization
  • 21.1. Character Sets
    • 21.1.1. Database Character Set
    • 21.1.2. Database National Character Set
    • 21.1.3. Setting the Client Character Set
  • 21.2. Setting the Client Locale
    • 21.2.1. Thick Mode Oracle Database National Language Support (NLS)
    • 21.2.2. Thin Mode Locale-aware Number Conversion
    • 21.2.3. Thin Mode Locale-aware Date Conversion
• 22. Error Handling
  • 22.1. Connection Identifiers
  • 22.2. Increasing the Stack Trace Limit
  • 22.3. Errors in Thin and Thick Modes
• 23. Troubleshooting Errors
  • 23.1. Installation Errors
  • 23.2. Error Messages
    • 23.2.1. DPI Error Messages
    • 23.2.2. NJS Error Messages
• 24. Upgrading to the Latest node-oracledb Releases
  • 24.1. Upgrading from node-oracledb 6.3 to 6.4
  • 24.2. Upgrading from node-oracledb 6.2 to 6.3
  • 24.3. Upgrading from node-oracledb 6.1 to 6.2
  • 24.4. Upgrading from node-oracledb 6.0 to 6.1
  • 24.5. Upgrading from node-oracledb 5.5 to 6.0
    • 24.5.1. Changing Applications to Use node-oracledb Thin Mode
  • 24.6. Upgrading from node-oracledb 5.4 to 5.5
  • 24.7. Upgrading from node-oracledb 5.3 to 5.4
  • 24.8. Upgrading from node-oracledb 5.2 to 5.3
  • 24.9. Upgrading from node-oracledb 5.1 to 5.2
  • 24.10. Upgrading from node-oracledb 4.2 to 5.0
  • 24.11. Upgrading from node-oracledb 4.1 to 4.2
  • 24.12. Upgrading from node-oracledb 4.0 to 4.1
  • 24.13. Upgrading from node-oracledb 3.1 to 4.0
  • 24.14. Earlier node-oracledb Versions
• 25. Node.js Programming Styles
  • 25.1. Using Node.js Async/Await with node-oracledb
  • 25.2. Using Node.js Promises with node-oracledb
    • 25.2.1. Custom Promise Libraries
  • 25.3. Using Node.js Callbacks with node-oracledb
• 26. Useful Resources for node-oracledb
• 27. Appendix A: The node-oracledb Thin and Thick Modes
  • 27.1. Oracle Database Features Supported by node-oracledb
  • 27.2. Differences between the node-oracledb Thin and Thick Modes
    • 27.2.1. Connection Handling Differences between Thin and Thick Modes
    • 27.2.2. Connection Pooling Differences between Thin and Thick Modes
    • 27.2.3. Query Metadata in Thin and Thick Modes
    • 27.2.4. Error Handling in Thin and Thick Modes
    • 27.2.5. Globalization in Thin and Thick Modes
    • 27.2.6. Tracing in Thin and Thick Modes
    • 27.2.7. Data Type Conversion in Thin and Thick Modes
    • 27.2.8. Supported Database Data Types in Thin and Thick Modes
  • 27.3. Testing Which Mode Is in Use
  • 27.4. Frameworks, SQL Generators, and ORMs

API Manual

• 1. API: Oracledb Class
  • 1.1. Oracledb Constants
  • 1.2. Oracledb Properties
  • 1.3. Oracledb Methods
  • 1.4. Oracledb Future Object
• 2. API: Connection Class
  • 2.1. Connection Properties
  • 2.2. Connection Methods
• 3. API: AqQueue Class
  • 3.1. AqQueue Properties
  • 3.2. AqQueue Methods
• 4. API: DbObject Class
  • 4.1. DbObject Properties
  • 4.2. DbObject Methods
• 5. API: LOB Class
  • 5.1. Lob Properties
  • 5.2. Lob Methods
• 6. API: Pool Class
  • 6.1. Pool Properties
  • 6.2. Pool Methods
• 7. API: PoolStatistics Class
  • 7.1. PoolStatistics Methods
• 8. API: ResultSet Class
  • 8.1. ResultSet Properties
  • 8.2. ResultSet Methods
• 9. API: SodaCollection Class
  • 9.1. SodaCollection Properties
  • 9.2. SodaCollection Methods
• 10. API: SodaOperation Class
  • 10.1. Non-terminal SodaOperation Methods
  • 10.2. Terminal SodaOperation Methods
• 11. API: SodaDatabase Class
  • 11.1. SodaDatabase Methods
• 12. API: SodaDocument Class
  • 12.1. SodaDocument Properties
  • 12.2. SodaDocument Methods
• 13. API: SodaDocumentCursor Class
  • 13.1. SodaDocumentCursor Methods
• 14. API: Errors
  • 14.1. Error Properties
• 15. Deprecated and Desupported Features

• node-oracledb Release Notes
• License

Indices and tables

• Index

• Search Page