Welcome to node-oracledb’s documentation

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

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. Getting Started
  • 1.2. Architecture
    • 1.2.1. node-oracledb Thin Mode Architecture
    • 1.2.2. node-oracledb Thick Mode Architecture
  • 1.3. 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. Installing Configuration Provider Modules for node-oracledb
    • 2.11.1. Install Modules for Azure App Configuration Provider
    • 2.11.2. Install Modules for OCI Object Storage Configuration Provider
  • 2.12. Installing Cloud Native Authentication Modules for node-oracledb
    • 2.12.1. Install Modules for the OCI Cloud Native Authentication Plugin
    • 2.12.2. Install Modules for the Azure Cloud Native Authentication Plugin
• 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.3. Oracle Environment Variables for node-oracledb
    • 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. Oracle Net Services Connection Strings
    • 4.2.1. Easy Connect Syntax for Connection Strings
    • 4.2.2. Connect Descriptors
    • 4.2.3. TNS Aliases 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. Connection Hook Functions
    • 4.5.1. Using oracledb.registerProcessConfigurationHook()
  • 4.6. Connecting Using Proxy Authentication
  • 4.7. Connecting Using External Authentication
    • 4.7.1. External Authentication Using TLS
  • 4.8. Token-Based Authentication
    • 4.8.1. OAuth 2.0 Token-Based Authentication
    • 4.8.2. IAM Token-Based Authentication
  • 4.9. Database Resident Connection Pooling (DRCP)
  • 4.10. Implicit Connection Pooling
  • 4.11. Privileged Connections
  • 4.12. Securely Encrypting Network Traffic to Oracle Database
    • 4.12.1. Native Network Encryption
  • 4.13. Changing Passwords and Connecting with an Expired Password
    • 4.13.1. Changing Passwords
    • 4.13.2. Connecting with an Expired Password
  • 4.14. Connections and High Availability
    • 4.14.1. Preventing Premature Connection Closing
    • 4.14.2. Fast Application Notification (FAN)
    • 4.14.3. Runtime Load Balancing (RLB)
    • 4.14.4. Application Continuity
    • 4.14.5. Database Call Timeouts
  • 4.15. Connecting to Oracle Real Application Clusters (RAC)
  • 4.16. Connecting to Oracle Cloud Autonomous Databases
    • 4.16.1. One-way TLS Connection to Oracle Autonomous Database
    • 4.16.2. Mutual TLS connections to Oracle Cloud Autonomous Database
  • 4.17. Connecting using Multiple Wallets
  • 4.18. Connecting Using Centralized Configuration Providers
    • 4.18.1. Azure App Configuration Provider
    • 4.18.2. OCI Object Storage Configuration Provider
  • 4.19. Connecting to Oracle Globally Distributed Database
    • 4.19.1. Examples to Connect to a Globally Distributed Database 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. Advanced Network Compression
  • 10.4. Statement Caching
    • 10.4.1. Setting the Statement Cache
    • 10.4.2. Tuning the Statement Cache
    • 10.4.3. Disabling the Statement Cache
  • 10.5. Client Result Caching (CRC)
    • 10.5.1. Configuring CRC
    • 10.5.2. Using CRC
    • 10.5.3. Verifying CRC
• 11. Using CLOB, NCLOB, BLOB, and BFILE Data
  • 11.1. Simple Insertion of LOBs
    • 11.1.1. Inserting CLOBs and BLOBs
    • 11.1.2. Inserting BFILEs
  • 11.2. Simple LOB Queries and PL/SQL OUT Binds
    • 11.2.1. Fetching CLOBs, BLOBs, and NCLOBs
    • 11.2.2. Fetching BFILEs
  • 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. JSON-Relational Duality Views
  • 12.9. Portable JSON
• 13. Using INTERVAL Data
  • 13.1. Using INTERVAL YEAR TO MONTH Data
    • 13.1.1. Inserting INTERVAL YEAR TO MONTH
    • 13.1.2. Fetching INTERVAL YEAR TO MONTH
  • 13.2. Using INTERVAL DAY TO SECOND Data
    • 13.2.1. Inserting INTERVAL DAY TO SECOND
    • 13.2.2. Fetching INTERVAL DAY TO SECOND
• 14. Using XMLType Data
  • 14.1. Inserting XML
  • 14.2. Fetching XML
• 15. Using VECTOR Data
  • 15.1. Using FLOAT32, FLOAT64, and INT8 Vectors
    • 15.1.1. Inserting FLOAT32, FLOAT64, and INT8 Vectors
    • 15.1.2. Fetching FLOAT32, FLOAT64, and INT8 Vectors
  • 15.2. Using BINARY Vectors
    • 15.2.1. Inserting BINARY Vectors
    • 15.2.2. Fetching BINARY Vectors
  • 15.3. Using SPARSE Vectors
    • 15.3.1. Inserting SPARSE Vectors
    • 15.3.2. Fetching SPARSE Vectors
    • 15.3.3. Converting Sparse Vectors to Dense Vectors
• 16. Using Oracle Database Objects and Collections
  • 16.1. Inserting Objects
  • 16.2. Fetching Objects
  • 16.3. Using DbObject Type Handlers
    • 16.3.1. Using BigInt Data in DbObjects with DbObject Type Handlers
  • 16.4. PL/SQL Collection Types
    • 16.4.1. PL/SQL Collection Associative Arrays (Index-by)
    • 16.4.2. PL/SQL Collection VARRAY Types
    • 16.4.3. PL/SQL Collection Nested Tables
  • 16.5. PL/SQL RECORD Types
    • 16.5.1. PL/SQL Records with %ROWTYPE Attribute
  • 16.6. Inserting or Passing Multiple Objects of the Same Type
  • 16.7. Using XMLType Data in DbObjects
  • 16.8. Oracle Database Object Type Limitations
• 17. Working with Simple Oracle Document Access (SODA)
  • 17.1. Node-oracledb SODA Objects
  • 17.2. Committing SODA Work
  • 17.3. Node-oracledb SODA Requirements
  • 17.4. Creating and Dropping SODA Collections
  • 17.5. Creating and Accessing SODA Documents
  • 17.6. SODA Query-by-Example Searches for JSON Documents
  • 17.7. Creating and Dropping SODA Indexes
    • 17.7.1. Retrieving All Index Specifications in a Collection
  • 17.8. SODA Text Searches
  • 17.9. SODA Client-Assigned Keys and Collection Metadata
  • 17.10. JSON Data Guides in SODA
  • 17.11. Using the SODA Metadata Cache
• 18. Using Oracle Transactional Event Queues and Advanced Queuing
  • 18.1. Sending Simple AQ Messages
  • 18.2. Sending Oracle Database JSON AQ Messages
  • 18.3. Sending Oracle Database Object AQ Messages
  • 18.4. Changing AQ options
  • 18.5. Enqueuing and Dequeuing Multiple Messages
  • 18.6. Advanced Queuing Notifications
  • 18.7. Recipient Lists
• 19. Working with Continuous Query Notification (CQN)
• 20. Using Two-Phase Commits (TPC)
• 21. Starting and Stopping Oracle Database
  • 21.1. Simple Database Start Up and Shut Down
    • 21.1.1. Simple Start Up
    • 21.1.2. Simple Shut Down
  • 21.2. Flexible Database Start Up and Shut Down
    • 21.2.1. Flexible Start Up
    • 21.2.2. Flexible Shut Down
  • 21.3. Oracle Multitenant Pluggable and Container Databases
• 22. Tracing with node-oracledb
  • 22.1. Application Tracing
    • 22.1.1. End-to-End Tracing, Mid-tier Authentication, and Auditing
    • 22.1.2. Debugging PL/SQL with the Java Debug Wire Protocol
    • 22.1.3. Tracing Executed Statements
    • 22.1.4. Tracing Bind Values
    • 22.1.5. Database Views
  • 22.2. Finding the node-oracledb Mode
  • 22.3. Low Level node-oracledb Driver Tracing
• 23. Extending node-oracledb
  • 23.1. Oracle Cloud Infrastructure (OCI) Cloud Native Authentication Plugin
  • 23.2. Azure Cloud Native Authentication Plugin
• 24. Character Sets and Localization
  • 24.1. Character Sets
    • 24.1.1. Database Character Set
    • 24.1.2. Database National Character Set
    • 24.1.3. Setting the Client Character Set
  • 24.2. Time Zone Files
    • 24.2.1. Finding the Time Zone Files in Use
    • 24.2.2. Changing the Oracle Client Time Zone File
  • 24.3. Setting the Client Locale
    • 24.3.1. Thick Mode Oracle Database National Language Support (NLS)
    • 24.3.2. Thin Mode Locale-aware Number Conversion
    • 24.3.3. Thin Mode Locale-aware Date Conversion
• 25. Error Handling
  • 25.1. Connection Identifiers
  • 25.2. Increasing the Stack Trace Limit
  • 25.3. Errors in Thin and Thick Modes
• 26. Troubleshooting Errors
  • 26.1. Installation Errors
  • 26.2. Error Messages
    • 26.2.1. DPI Error Messages
    • 26.2.2. NJS Error Messages
    • 26.2.3. ORA Error Messages
• 27. Upgrading to the Latest node-oracledb Releases
  • 27.1. Upgrading from node-oracledb 6.7 to 6.8
  • 27.2. Upgrading from node-oracledb 6.6 to 6.7
  • 27.3. Upgrading from node-oracledb 6.5 to 6.6
  • 27.4. Upgrading from node-oracledb 6.4 to 6.5
  • 27.5. Upgrading from node-oracledb 6.3 to 6.4
  • 27.6. Upgrading from node-oracledb 6.2 to 6.3
  • 27.7. Upgrading from node-oracledb 6.1 to 6.2
  • 27.8. Upgrading from node-oracledb 6.0 to 6.1
  • 27.9. Upgrading from node-oracledb 5.5 to 6.0
    • 27.9.1. Changing Applications to Use node-oracledb Thin Mode
  • 27.10. Upgrading from node-oracledb 5.4 to 5.5
  • 27.11. Upgrading from node-oracledb 5.3 to 5.4
  • 27.12. Upgrading from node-oracledb 5.2 to 5.3
  • 27.13. Upgrading from node-oracledb 5.1 to 5.2
  • 27.14. Upgrading from node-oracledb 4.2 to 5.0
  • 27.15. Upgrading from node-oracledb 4.1 to 4.2
  • 27.16. Upgrading from node-oracledb 4.0 to 4.1
  • 27.17. Upgrading from node-oracledb 3.1 to 4.0
  • 27.18. Earlier node-oracledb Versions
• 28. Node.js Programming Styles
  • 28.1. Using Node.js Async/Await with node-oracledb
  • 28.2. Using Node.js Promises with node-oracledb
    • 28.2.1. Custom Promise Libraries
  • 28.3. Using Node.js Callbacks with node-oracledb
• 29. Useful Resources for node-oracledb
• 30. Appendix A: The node-oracledb Thin and Thick Modes
  • 30.1. Oracle Database Features Supported by node-oracledb
  • 30.2. Differences between the node-oracledb Thin and Thick Modes
    • 30.2.1. Connection Handling Differences between Thin and Thick Modes
    • 30.2.2. Connection Pooling Differences between Thin and Thick Modes
    • 30.2.3. Query Metadata in Thin and Thick Modes
    • 30.2.4. Error Handling in Thin and Thick Modes
    • 30.2.5. Globalization in Thin and Thick Modes
    • 30.2.6. Tracing in Thin and Thick Modes
    • 30.2.7. Data Type Conversion in Thin and Thick Modes
    • 30.2.8. Supported Database Data Types in Thin and Thick Modes
  • 30.3. Testing Which Mode Is in Use
  • 30.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 SparseVector Class
  • 1.5. Oracledb Future Object
  • 1.6. Oracledb IntervalYM Class
  • 1.7. Oracledb IntervalDS Class
  • 1.8. Oracledb JsonId Class
  • 1.9. Oracledb TraceHandler Interface
• 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