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.

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
  • 2.11. Troubleshooting
    • 2.11.1. Installation Troubleshooting
    • 2.11.2. Runtime Error Troubleshooting
• 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.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. Mutal 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 19 or Earlier
  • 12.2. Using the Oracle Database 12c JSON Type in node-oracledb
  • 12.3. IN Bind Type Mapping
  • 12.4. Query and OUT Bind Type Mapping
  • 12.5. SQL/JSON Path Expressions
  • 12.6. Accessing Relational Data as JSON
  • 12.7. Portable JSON
• 13. Using XMLType Data
• 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. SODA Text Searches
  • 15.8. SODA Client-Assigned Keys and Collection Metadata
  • 15.9. JSON Data Guides in SODA
  • 15.10. Using the SODA Metadata Cache
• 16. Using Oracle Advanced Queuing (AQ)
  • 16.1. Sending Simple AQ Messages
  • 16.2. Sending Oracle Database Object AQ Messages
  • 16.3. Changing AQ options
  • 16.4. Enqueuing and Dequeuing Multiple Messages
  • 16.5. Advanced Queuing Notifications
  • 16.6. 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. Upgrading to the Latest node-oracledb Releases
  • 23.1. Upgrading from node-oracledb 5.5 to 6.0
    • 23.1.1. Changing Applications to Use node-oracledb Thin Mode
  • 23.2. Upgrading from node-oracledb 5.4 to 5.5
  • 23.3. Upgrading from node-oracledb 5.3 to 5.4
  • 23.4. Upgrading from node-oracledb 5.2 to 5.3
  • 23.5. Upgrading from node-oracledb 5.1 to 5.2
  • 23.6. Upgrading from node-oracledb 4.2 to 5.0
  • 23.7. Upgrading from node-oracledb 4.1 to 4.2
  • 23.8. Upgrading from node-oracledb 4.0 to 4.1
  • 23.9. Upgrading from node-oracledb 3.1 to 4.0
  • 23.10. Earlier node-oracledb Versions
• 24. Node.js Programming Styles
  • 24.1. Using Node.js Async/Await with node-oracledb
  • 24.2. Using Node.js Promises with node-oracledb
    • 24.2.1. Custom Promise Libraries
  • 24.3. Using Node.js Callbacks with node-oracledb
• 25. Useful Resources for node-oracledb
• 26. Appendix A: The node-oracledb Thin and Thick Modes
  • 26.1. Oracle Database Features Supported by node-oracledb
  • 26.2. Differences between the node-oracledb Thin and Thick Modes
    • 26.2.1. Connection Handling Differences between Thin and Thick Modes
    • 26.2.2. Connection Pooling Differences between Thin and Thick Modes
    • 26.2.3. Query Metadata in Thin and Thick Modes
    • 26.2.4. Error Handling in Thin and Thick Modes
    • 26.2.5. Globalization in Thin and Thick Modes
    • 26.2.6. Tracing in Thin and Thick Modes
    • 26.2.7. Data Type Conversion in Thin and Thick Modes
    • 26.2.8. Supported Database Data Types in Thin and Thick Modes
  • 26.3. Testing Which Mode Is in Use
  • 26.4. Frameworks, SQL Generators, and ORMs

API Manual

• 1. API: Oracledb Class
  • 1.1. Oracledb Constants
  • 1.2. Oracledb Properties
  • 1.3. Oracledb Methods
• 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
  • 9.3. SodaOperation Class
• 10. API: SodaDatabase Class
  • 10.1. SodaDatabase Methods
• 11. API: SodaDocument Class
  • 11.1. SodaDocument Properties
  • 11.2. SodaDocument Methods
• 12. API: SodaDocumentCursor Class
  • 12.1. SodaDocumentCursor Methods
• 13. API: Errors
  • 13.1. Error Properties
• 14. Deprecated and Desupported Features

• node-oracledb Release Notes
• License

Indices and tables

• Index

• Search Page