From 4dd4721814723dc3280d32511ebe9a26f74c6ddd Mon Sep 17 00:00:00 2001 From: Sharad Chandran R Date: Mon, 11 Mar 2024 12:46:16 +0530 Subject: [PATCH] Copyright updates, documentation and test case additions --- .npmignore | 2 - doc/api.md | 534 +++++++++---------- doc/src/api_manual/sodacollection.rst | 687 ++----------------------- doc/src/api_manual/sodaoperation.rst | 616 ++++++++++++++++++++++ doc/src/index.rst | 1 + lib/constants.js | 2 +- lib/dbObject.js | 2 +- lib/errors.js | 2 +- lib/lob.js | 2 +- lib/pool.js | 2 +- lib/poolStatistics.js | 2 +- lib/settings.js | 2 +- lib/thin/connection.js | 2 +- lib/thin/dbObject.js | 2 +- lib/thin/lob.js | 2 +- lib/thin/pool.js | 2 +- lib/thin/protocol/buffer.js | 2 +- lib/thin/protocol/capabilities.js | 2 +- lib/thin/protocol/constants.js | 2 +- lib/thin/protocol/messages/base.js | 2 +- lib/thin/protocol/messages/dataType.js | 2 +- lib/thin/protocol/messages/withData.js | 2 +- lib/thin/sqlnet/networkSession.js | 2 +- lib/thin/statement.js | 2 +- lib/transformer.js | 2 +- lib/types.js | 2 +- lib/version.js | 2 +- test/dbObject20.js | 10 +- test/jsonDualityViews6.js | 16 +- test/list.txt | 33 +- test/sqlParser.js | 19 +- 31 files changed, 989 insertions(+), 973 deletions(-) create mode 100644 doc/src/api_manual/sodaoperation.rst diff --git a/.npmignore b/.npmignore index 11c6350b..f8044b87 100644 --- a/.npmignore +++ b/.npmignore @@ -13,8 +13,6 @@ Makefile.win32 /examples/* !/examples/example.js !/examples/dbconfig.js -!/examples/vectortype1.js -!/examples/vectortype2.js /test /build/Release/oracledb.node /build/oracledb.target.mk diff --git a/doc/api.md b/doc/api.md index a5432a61..fcd842ca 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1318,7 +1318,7 @@ The input value or variable to be used for an IN or IN OUT bind variable. [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaCollection.createIndex) -#### 10.2.2 `sodaCollection.drop()` +#### 11.2.2 `sodaCollection.drop()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaCollection.drop) @@ -1350,78 +1350,6 @@ The input value or variable to be used for an IN or IN OUT bind variable. [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaCollection.find) -##### 11.2.4.1 SodaOperation Class - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaoperationclass) - -##### 11.2.4.1.1 Non-terminal SodaOperation Methods - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaoperationclassnonterm) - -###### 11.2.4.1.1.1 `sodaOperation.fetchArraySize()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.fetchArraySize) - -###### 11.2.4.1.1.2 `sodaOperation.filter()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.filter) - -###### 11.2.4.1.1.3 `sodaOperation.hint()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.hint) - -###### 11.2.4.1.1.4 `sodaOperation.key()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.key) - -###### 11.2.4.1.1.5 `sodaOperation.keys()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.keys) - -###### 11.2.4.1.1.6 `sodaOperation.limit()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.limit) - -###### 11.2.4.1.1.7 `sodaOperation.skip()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.skip) - -###### 11.2.4.1.1.8 `sodaOperation.version()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.version) - -##### 11.2.4.1.2 Terminal SodaOperation Methods - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaoperationclassterm) - -###### 11.2.4.1.2.1 `sodaOperation.count()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.count) - -###### 11.2.4.1.2.2 `sodaOperation.getCursor()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.getCursor) - -###### 11.2.4.1.2.3 `sodaOperation.getDocuments()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.getDocuments) - -###### 11.2.4.1.2.4 `sodaOperation.getOne()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.getOne) - -###### 11.2.4.1.2.5 `sodaOperation.remove()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.remove) - -###### 11.2.4.1.2.6 `sodaOperation.replaceOne()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.replaceOne) - -###### 11.2.4.1.2.7 `sodaOperation.replaceOneAndGet()` - -[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaOperation.replaceOneAndGet) - #### 11.2.5 `sodaCollection.getDataGuide()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaCollection.getDataGuide) @@ -1482,229 +1410,301 @@ The input value or variable to be used for an IN or IN OUT bind variable. [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacollection.html#sodaCollection.truncate) -## 12. SodaDatabase Class +## 12 SodaOperation Class + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaoperationclass) + +### 12.1 Non-terminal SodaOperation Methods + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaoperationclassnonterm) + +#### 12.1.1 `sodaOperation.fetchArraySize()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.fetchArraySize) + +#### 12.1.2 `sodaOperation.filter()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.filter) + +#### 12.1.3 `sodaOperation.hint()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.hint) + +#### 12.1.4 `sodaOperation.key()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.key) + +#### 12.1.5 `sodaOperation.keys()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.keys) + +#### 12.1.6 `sodaOperation.limit()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.limit) + +#### 12.1.7 `sodaOperation.skip()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.skip) + +#### 12.1.8 `sodaOperation.version()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.version) + +### 12.2 Terminal SodaOperation Methods + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaoperationclassterm) + +#### 12.2.1 `sodaOperation.count()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.count) + +#### 12.2.2 `sodaOperation.getCursor()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.getCursor) + +#### 12.2.3 `sodaOperation.getDocuments()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.getDocuments) + +#### 12.2.4 `sodaOperation.getOne()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.getOne) + +#### 12.2.5 `sodaOperation.remove()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.remove) + +#### 12.2.6 `sodaOperation.replaceOne()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.replaceOne) + +#### 12.2.7 `sodaOperation.replaceOneAndGet()` + +[View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodaoperation.html#sodaOperation.replaceOneAndGet) + +## 13. SodaDatabase Class [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodadatabaseclass) -#### 12.1 SodaDatabase Methods +### 13.1 SodaDatabase Methods [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodadatabasemethods) -#### 12.1.1 `sodaDatabase.createCollection()` +#### 13.1.1 `sodaDatabase.createCollection()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodaDatabase.createCollection) -##### 12.1.1.1 `createCollection(): collectionName` +##### 13.1.1.1 `createCollection(): collectionName` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#createcoll) -##### 12.1.1.2 `createCollection(): options` +##### 13.1.1.2 `createCollection(): options` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#createcoll) -###### 12.1.1.2.1 `metaData` +###### 13.1.1.2.1 `metaData` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodadbcreatecollectionoptions) -###### 12.1.1.2.2 `mode` +###### 13.1.1.2.2 `mode` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodadbcreatecollectionoptions) -##### 12.1.1.3 `createCollection()`: Callback Function +##### 13.1.1.3 `createCollection()`: Callback Function [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodaDatabase.createCollection) -#### 12.1.2 `sodaDatabase.createDocument()` +#### 13.1.2 `sodaDatabase.createDocument()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodaDatabase.createDocument) -##### 12.1.2.1 `createDocument(): content` +##### 13.1.2.1 `createDocument(): content` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#createdocument) -##### 12.1.2.2 `createDocument(): options` +##### 13.1.2.2 `createDocument(): options` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#createdocument) -###### 12.1.2.2.1 `key` +###### 13.1.2.2.1 `key` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodadbcreatedocumentoptions) -###### 12.1.2.2.2 `mediaType` +###### 13.1.2.2.2 `mediaType` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodadbcreatedocumentoptions) -#### 12.1.3 `sodaDatabase.getCollectionNames()` +#### 13.1.3 `sodaDatabase.getCollectionNames()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodaDatabase.getCollectionNames) -##### 12.1.3.1 `getCollectionNames()`: Parameters +##### 13.1.3.1 `getCollectionNames()`: Parameters [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#getcollectionnames) -###### 12.1.3.1.1 `options` +###### 13.1.3.1.1 `options` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#getcollectionnamesoptions) -##### 12.1.3.2 `getCollectionNames()`: Callback Function +##### 13.1.3.2 `getCollectionNames()`: Callback Function [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodaDatabase.getCollectionNames) -#### 12.1.4 `sodaDatabase.openCollection()` +#### 13.1.4 `sodaDatabase.openCollection()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodaDatabase.openCollection) -##### 12.1.4.1 `openCollection()`: Parameters +##### 13.1.4.1 `openCollection()`: Parameters [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#opencoll) -###### 12.1.4.1.1 `collectionName` +###### 13.1.4.1.1 `collectionName` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#opencoll) -##### 12.1.4.2 `openCollection()`: Callback Function +##### 13.1.4.2 `openCollection()`: Callback Function [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadb.html#sodaDatabase.openCollection) -## 13. SodaDocument Class +## 14. SodaDocument Class [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadocument.html#sodadocumentclass) -### 13.1 SodaDocument Properties +### 14.1 SodaDocument Properties [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadocument.html#sodadocumentproperties) -### 13.2 SodaDocument Methods +### 14.2 SodaDocument Methods [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadocument.html#sodadocumentmethods) -#### 13.2.1 `sodaDocument.getContent()` +#### 14.2.1 `sodaDocument.getContent()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadocument.html#sodaDocument.getContent) -#### 13.2.2 `sodaDocument.getContentAsBuffer()` +#### 14.2.2 `sodaDocument.getContentAsBuffer()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadocument.html#sodaDocument.getContentAsBuffer) -#### 13.2.3 `sodaDocument.getContentAsString()` +#### 14.2.3 `sodaDocument.getContentAsString()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodadocument.html#sodaDocument.getContentAsString) -## 14. SodaDocumentCursor Class +## 15. SodaDocumentCursor Class [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacursor.html#sodadocumentcursorclass) -### 14.1 SodaDocumentCursor Methods +### 15.1 SodaDocumentCursor Methods [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacursor.html#sodadoccursormethods) -#### 14.1.1 `sodaDocumentCursor.close()` +#### 15.1.1 `sodaDocumentCursor.close()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacursor.html#sodaDocumentCursor.close) -#### 13.1.2 `sodaDocumentCursor.getNext()` +#### 15.1.2 `sodaDocumentCursor.getNext()` [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/api_manual/sodacursor.html#sodaDocumentCursor.getNext) ## NODE-ORACLEDB USER MANUAL -## 15. Initializing Node-oracledb +## 16. Initializing Node-oracledb [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#initnodeoracledb) -### 15.1 Setting the Oracle Client Library Directory +### 16.1 Setting the Oracle Client Library Directory [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#oracleclientloading) -#### 15.1.1 Setting the Oracle Client Directory on Windows +#### 16.1.1 Setting the Oracle Client Directory on Windows [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#oracleclientloadingwindows) -#### 15.1.2 Setting the Oracle Client Directory on macOS +#### 16.1.2 Setting the Oracle Client Directory on macOS [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#oracleclientloadingmacos) -#### 15.1.3 Setting the Oracle Client Directory on Linux and Related Platforms +#### 16.1.3 Setting the Oracle Client Directory on Linux and Related Platforms [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#oracleclientloadinglinux) -#### 15.1.4 Calling `initOracleClient()` to set the Oracle Client Directory +#### 16.1.4 Calling `initOracleClient()` to set the Oracle Client Directory [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#oracleclientcallinginit) -### 15.2 Optional Oracle Net Configuration +### 16.2 Optional Oracle Net Configuration [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#tnsadmin) -### 15.3 Optional Oracle Client Configuration +### 16.3 Optional Oracle Client Configuration [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#oraaccess) -### 15.4 Oracle Environment Variables +### 16.4 Oracle Environment Variables [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#environmentvariables) -### 15.5 Other Node-oracledb Initialization +### 16.5 Other Node-oracledb Initialization [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/initialization.html#otherinit) -## 16. Connection Handling +## 17. Connection Handling [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionhandling) -### 16.1 Connection Strings +### 17.1 Connection Strings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionstrings) -#### 16.1.1 Easy Connect Syntax for Connection Strings +#### 17.1.1 Easy Connect Syntax for Connection Strings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#easyconnect) -#### 16.1.2 Embedded Connect Descriptor Strings +#### 17.1.2 Embedded Connect Descriptor Strings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#embedtns) -#### 16.1.3 Net Service Names for Connection Strings +#### 17.1.3 Net Service Names for Connection Strings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#tnsnames) -#### 16.1.4 JDBC and Oracle SQL Developer Connection Strings +#### 17.1.4 JDBC and Oracle SQL Developer Connection Strings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#notjdbc) -### 16.2 Connections, Threads, and Parallelism +### 17.2 Connections, Threads, and Parallelism [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#numberofthreads) -#### 16.2.1 Connections and Worker Threads +#### 17.2.1 Connections and Worker Threads [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#workerthreads) -#### 16.2.2 Parallelism on Each Connection +#### 17.2.2 Parallelism on Each Connection [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#parallelism) -### 16.3 Connection Pooling +### 17.3 Connection Pooling [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connpooling) -#### 16.3.1 Connection Pool Sizing +#### 17.3.1 Connection Pool Sizing [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#conpoolsizing) -#### 16.3.2 Connection Pool Closing and Draining +#### 17.3.2 Connection Pool Closing and Draining [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#conpooldraining) -#### 16.3.3 Connection Pool Cache +#### 17.3.3 Connection Pool Cache [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connpoolcache) -#### 16.3.4 Connection Pool Queue +#### 17.3.4 Connection Pool Queue [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connpoolqueue) -#### 16.3.5 Connection Pool Monitoring +#### 17.3.5 Connection Pool Monitoring [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connpoolmonitor) @@ -1712,383 +1712,383 @@ The input value or variable to be used for an IN or IN OUT bind variable. [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#poolstats) -#### 16.3.6 Connection Pool Pinging +#### 17.3.6 Connection Pool Pinging [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connpoolpinging) -#### 16.3.7 Connection Tagging and Session State +#### 17.3.7 Connection Tagging and Session State [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connpooltagging) -##### 16.3.7.1 Node.js Session Callback +##### 17.3.7.1 Node.js Session Callback [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#sessionfixupnode) -##### 16.3.7.2 Node.js Session Tagging Callback +##### 17.3.7.2 Node.js Session Tagging Callback [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#sessiontaggingnode) -##### 16.3.7.3 PL/SQL Session Tagging Callback +##### 17.3.7.3 PL/SQL Session Tagging Callback [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#sessiontaggingplsql) -#### 16.3.8 Heterogeneous Connection Pools and Pool Proxy Authentication +#### 17.3.8 Heterogeneous Connection Pools and Pool Proxy Authentication [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connpoolproxy) -### 16.4 External Authentication +### 17.4 External Authentication [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#extauth) -### 16.5 Token-Based Authentication +### 17.5 Token-Based Authentication [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#tokenbasedauthentication) -#### 16.5.1 OAuth 2.0 Token-Based Authentication +#### 17.5.1 OAuth 2.0 Token-Based Authentication [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#oauthtokenbasedauthentication) -##### 16.5.1.1 OAuth 2.0 Token Generation +##### 17.5.1.1 OAuth 2.0 Token Generation [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#oauthtokengeneration) -##### 16.5.1.2 OAuth 2.0 Standalone Connections +##### 17.5.1.2 OAuth 2.0 Standalone Connections [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#oauthstandalone) -##### 16.5.1.3 OAuth 2.0 Connection Pooling +##### 17.5.1.3 OAuth 2.0 Connection Pooling [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#oauthpool) -##### 16.5.1.4 OAuth 2.0 Connection Strings +##### 17.5.1.4 OAuth 2.0 Connection Strings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#oauthconnectstring) -#### 16.5.2 IAM Token-Based Authentication +#### 17.5.2 IAM Token-Based Authentication [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#iamtokenbasedauthentication) -##### 16.5.2.1 IAM Token Generation +##### 17.5.2.1 IAM Token Generation [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#iamtokengeneration) -##### 16.5.2.2 IAM Token and Private Key Extraction +##### 17.5.2.2 IAM Token and Private Key Extraction [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#iamtokenextraction) -##### 16.5.2.3 IAM Standalone Connections +##### 17.5.2.3 IAM Standalone Connections [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#iamstandalone) -##### 16.5.2.4 IAM Connection Pooling +##### 17.5.2.4 IAM Connection Pooling [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#iampool) -##### 16.5.2.5 IAM Connection Strings +##### 17.5.2.5 IAM Connection Strings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#iamconnectstring) -### 16.6 Database Resident Connection Pooling (DRCP) +### 17.6 Database Resident Connection Pooling (DRCP) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#drcp) -### 16.7 Privileged Connections +### 17.7 Privileged Connections [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#privconn) -### 16.8 Securely Encrypting Network Traffic to Oracle Database +### 17.8 Securely Encrypting Network Traffic to Oracle Database [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#securenetwork) -### 16.9 Changing Passwords and Connecting with an Expired Password +### 17.9 Changing Passwords and Connecting with an Expired Password [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#changingpassword) -### 16.10 Connections and High Availability +### 17.10 Connections and High Availability [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionha) -#### 16.10.1 Preventing Premature Connection Closing +#### 17.10.1 Preventing Premature Connection Closing [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionpremclose) -#### 16.10.2 Fast Application Notification (FAN) +#### 17.10.2 Fast Application Notification (FAN) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionfan) -#### 16.10.3 Runtime Load Balancing (RLB) +#### 17.10.3 Runtime Load Balancing (RLB) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionrlb) -#### 16.10.4 Application Continuity +#### 17.10.4 Application Continuity [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#appcontinuity) -#### 16.10.5 Database Call Timeouts +#### 17.10.5 Database Call Timeouts [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#dbcalltimeouts) -### 16.11 Connecting to Oracle Real Application Clusters (RAC) +### 17.11 Connecting to Oracle Real Application Clusters (RAC) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionrac) -### 16.12 Connecting to Oracle Cloud Autonomous Databases +### 17.12 Connecting to Oracle Cloud Autonomous Databases [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionadb) -#### 16.12.1 TLS Connections to Oracle Cloud Autonomous Database +#### 17.12.1 TLS Connections to Oracle Cloud Autonomous Database [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionadbtls) -#### 16.12.2 Mutal TLS connections to Oracle Cloud Autonomous Database +#### 17.12.2 Mutal TLS connections to Oracle Cloud Autonomous Database [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#connectionadbmtls) -### 16.13 Connecting to Sharded Databases +### 17.13 Connecting to Sharded Databases [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html#sharding) -## 17. SQL Execution +## 18. SQL Execution [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#sqlexecution) -### 17.1 SELECT Statements +### 18.1 SELECT Statements [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#select) -#### 17.1.1 Fetching Rows with Direct Fetches +#### 18.1.1 Fetching Rows with Direct Fetches [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchingrows) -#### 17.1.2 Fetching Rows with Result Sets +#### 18.1.2 Fetching Rows with Result Sets [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#resultsethandling) -#### 17.1.3 Query Streaming +#### 18.1.3 Query Streaming [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#streamingresults) -#### 17.1.4 Query Output Formats +#### 18.1.4 Query Output Formats [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#queryoutputformats) -#### 17.1.5 Fetching Nested Cursors +#### 18.1.5 Fetching Nested Cursors [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#nestedcursors) -#### 17.1.6 Query Column Metadata +#### 18.1.6 Query Column Metadata [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#querymeta) -#### 17.1.7 Query Result Type Mapping +#### 18.1.7 Query Result Type Mapping [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#typemap) -##### 17.1.7.1 Fetching CHAR, VARCHAR2, NCHAR and NVARCHAR +##### 18.1.7.1 Fetching CHAR, VARCHAR2, NCHAR and NVARCHAR [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#stringhandling) -##### 17.1.7.2 Fetching Numbers +##### 18.1.7.2 Fetching Numbers [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#numberhandling) -##### 17.1.7.3 Fetching Dates and Timestamps +##### 18.1.7.3 Fetching Dates and Timestamps [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#datehandling) -##### 17.1.7.4 Fetching Numbers and Dates as String +##### 18.1.7.4 Fetching Numbers and Dates as String [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchasstringhandling) -##### 17.1.7.5 Fetching BLOB, CLOB and NCLOB +##### 18.1.7.5 Fetching BLOB, CLOB and NCLOB [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchlob) -##### 17.1.7.6 Fetching LONG and LONG RAW +##### 18.1.7.6 Fetching LONG and LONG RAW [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchlong) -##### 17.1.7.7 Fetching ROWID and UROWID +##### 18.1.7.7 Fetching ROWID and UROWID [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchrowid) -##### 17.1.7.8 Fetching XMLType +##### 18.1.7.8 Fetching XMLType [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchxml) -##### 17.1.7.9 Fetching RAW +##### 18.1.7.9 Fetching RAW [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchraw) -##### 17.1.7.10 Fetching Oracle Database Objects and Collections +##### 18.1.7.10 Fetching Oracle Database Objects and Collections [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#fetchobjects) -#### 17.1.8 Limiting Rows and Creating Paged Datasets +#### 18.1.8 Limiting Rows and Creating Paged Datasets [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#pagingdata) -#### 17.1.9 Auto-Increment Columns +#### 18.1.9 Auto-Increment Columns [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#autoincrement) -### 17.2 Cursor Management +### 18.2 Cursor Management [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/sql_execution.html#cursors1000) -## 18. PL/SQL Execution +## 19. PL/SQL Execution [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#plsqlexecution) -### 18.1 PL/SQL Stored Procedures +### 19.1 PL/SQL Stored Procedures [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#plsqlproc) -### 18.2 PL/SQL Stored Functions +### 19.2 PL/SQL Stored Functions [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#plsqlfunc) -### 18.3 PL/SQL Anonymous PL/SQL Blocks +### 19.3 PL/SQL Anonymous PL/SQL Blocks [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#plsqlanon) -### 18.4 Using DBMS_OUTPUT +### 19.4 Using DBMS_OUTPUT [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#dbmsoutput) -### 18.5 Edition-Based Redefinition +### 19.5 Edition-Based Redefinition [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#ebr) -### 18.6 Implicit Results +### 19.6 Implicit Results [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#implicitresults) -### 18.7 Creating PL/SQL Procedures and Functions +### 19.7 Creating PL/SQL Procedures and Functions [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#plsqlcreate) -#### 18.7.1 PL/SQL Compilation Warnings +#### 19.7.1 PL/SQL Compilation Warnings [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#plsqlcompwarnings) -## 19. Working with CLOB, NCLOB and BLOB Data +## 20. Working with CLOB, NCLOB and BLOB Data [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#lobhandling) -### 19.1 Simple Insertion of LOBs +### 20.1 Simple Insertion of LOBs [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#basiclobinsert) -### 19.2 Simple LOB Queries and PL/SQL OUT Binds +### 20.2 Simple LOB Queries and PL/SQL OUT Binds [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#queryinglobs) -### 19.3 Streaming Lobs +### 20.3 Streaming Lobs [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#streamsandlobs) -### 19.4 Using RETURNING INTO to Insert into LOBs +### 20.4 Using RETURNING INTO to Insert into LOBs [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#lobinsertdiscussion) -### 19.5 Getting LOBs as Streams from Oracle Database +### 20.5 Getting LOBs as Streams from Oracle Database [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#loboutstream) -### 19.6 Using `createLob()` for PL/SQL IN Binds +### 20.6 Using `createLob()` for PL/SQL IN Binds [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#templobdiscussion) -### 19.7 Closing Lobs +### 20.7 Closing Lobs [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/lob_data.html#closinglobs) -## 20. Oracle Database JSON Data Type +## 21. Oracle Database JSON Data Type [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/json_data_type.html#jsondatatype) -## 21. Working with XMLType +## 22. Working with XMLType [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/xml_data_type.html#xmltype) -## 22. Bind Parameters for Prepared Statements +## 23. Bind Parameters for Prepared Statements [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#bind) -### 22.1 IN Bind Parameters +### 23.1 IN Bind Parameters [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#inbind) -### 22.2 OUT and IN OUT Bind Parameters +### 23.2 OUT and IN OUT Bind Parameters [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#outbind) -### 22.3 DML RETURNING Bind Parameters +### 23.3 DML RETURNING Bind Parameters [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#dmlreturn) -### 22.4 REF CURSOR Bind Parameters +### 23.4 REF CURSOR Bind Parameters [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#refcursors) -### 22.5 LOB Bind Parameters +### 23.5 LOB Bind Parameters [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#lobbinds) -### 22.6 Binding Multiple Values to a SQL `WHERE IN` Clause +### 23.6 Binding Multiple Values to a SQL `WHERE IN` Clause [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#sqlwherein) -### 22.7 Binding in a `LIKE` or `REGEXP_LIKE` Clause +### 23.7 Binding in a `LIKE` or `REGEXP_LIKE` Clause [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#sqlbindlike) -### 22.8 Binding Column and Table Names in Queries +### 23.8 Binding Column and Table Names in Queries [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/bind.html#sqlbindtablename) -## 23. Oracle Database Objects and Collections +## 24. Oracle Database Objects and Collections [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#objects) -### 23.1 Inserting Objects +### 24.1 Inserting Objects [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#objectinsert) -### 23.2 Fetching Objects +### 24.2 Fetching Objects [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#objectfetch) -### 23.3 PL/SQL Collection Types +### 24.3 PL/SQL Collection Types [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#plsqlcollections) -#### 23.3.1 PL/SQL Collection Associative Arrays (Index-by) +#### 24.3.1 PL/SQL Collection Associative Arrays (Index-by) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#plsqlindexbybinds) -#### 23.3.2 PL/SQL Collection VARRAY Types +#### 24.3.2 PL/SQL Collection VARRAY Types [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#plsqlvarray) -#### 23.3.3 PL/SQL Collection Nested Tables +#### 24.3.3 PL/SQL Collection Nested Tables [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#plsqlnestedtables) -### 23.4 PL/SQL RECORD Types +### 24.4 PL/SQL RECORD Types [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#plsqlrecords) -### 23.5 Inserting or Passing Multiple Objects of the Same Type +### 24.5 Inserting or Passing Multiple Objects of the Same Type [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#objexecmany) -### 23.6 Oracle Database Object Type Limitations +### 24.6 Oracle Database Object Type Limitations [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/objects.html#objectlimitations) -## 24. Batch Statement Execution and Bulk Loading +## 25. Batch Statement Execution and Bulk Loading [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/batch_statement.html#batchexecution) @@ -2100,47 +2100,47 @@ The input value or variable to be used for an IN or IN OUT bind variable. [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/batch_statement.html#executemanyobjects) -## 25. Transaction Management +## 26. Transaction Management [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/txn_management.html#transactionmgt) -## 26. Continuous Query Notification (CQN) +## 27. Continuous Query Notification (CQN) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/cqn.html#cqn) -## 27. Oracle Advanced Queuing (AQ) +## 28. Oracle Advanced Queuing (AQ) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aq) -### 27.1 Sending Simple AQ Messages +### 28.1 Sending Simple AQ Messages [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqrawexample) -### 27.2 Sending Oracle Database Object AQ Messages +### 28.2 Sending Oracle Database Object AQ Messages [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqobjexample) -### 27.3 Changing AQ options +### 28.3 Changing AQ options [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqoptions) -### 27.4 Enqueuing and Dequeuing Multiple Messages +### 28.4 Enqueuing and Dequeuing Multiple Messages [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqmultiplemessages) -### 27.5 Advanced Queuing Notifications +### 28.5 Advanced Queuing Notifications [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqnotifications) -### 27.6 Recipient Lists +### 28.6 Recipient Lists [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/aq.html#aqrecipientlists) -## 28. Globalization and National Language Support (NLS) +## 29. Globalization and National Language Support (NLS) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/globalization.html#nls) -## 29. End-to-end Tracing, Mid-tier Authentication, and Auditing +## 30. End-to-end Tracing, Mid-tier Authentication, and Auditing [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tracing.html#endtoend) @@ -2148,130 +2148,130 @@ The input value or variable to be used for an IN or IN OUT bind variable. [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tracing.html#drivernameview) -## 30. Simple Oracle Document Access (SODA) +## 31. Simple Oracle Document Access (SODA) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodaoverview) -### 30.1 Node-oracledb SODA Requirements +### 31.1 Node-oracledb SODA Requirements [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodarequirements) -### 30.2 Creating and Dropping SODA Collections +### 31.2 Creating and Dropping SODA Collections [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#creatingsodacollections) -### 30.3 Creating and Accessing SODA documents +### 31.3 Creating and Accessing SODA documents [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#accessingsodadocuments) -### 30.4 SODA Query-by-Example Searches for JSON Documents +### 31.4 SODA Query-by-Example Searches for JSON Documents [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodaqbesearches) -### 30.5 SODA Text Searches +### 31.5 SODA Text Searches [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodatextsearches) -### 30.6 SODA Client-Assigned Keys and Collection Metadata +### 31.6 SODA Client-Assigned Keys and Collection Metadata [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodaclientkeys) -### 30.7 JSON Data Guides in SODA +### 31.7 JSON Data Guides in SODA [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodajsondataguide) -#### 30.8 Using the SODA Metadata Cache +#### 31.8 Using the SODA Metadata Cache [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodamdcache) -## 31. Database Start Up and Shut Down +## 32. Database Start Up and Shut Down [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/startup.html#startupshutdown) -### 31.1 Simple Database Start Up and Shut Down +### 32.1 Simple Database Start Up and Shut Down [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/startup.html#startupshutdownsimple) -### 31.2 Flexible Database Start Up and Shut Down +### 32.2 Flexible Database Start Up and Shut Down [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/startup.html#startupshutdownflexible) -### 31.3 Oracle Multitenant Pluggable and Container Databases +### 32.3 Oracle Multitenant Pluggable and Container Databases [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/startup.html#startupshutdownpdb) -## 32. Node-oracledb Tuning +## 33. Node-oracledb Tuning [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tuning.html#tuning) -#### 32.1 Tuning Fetch Performance +#### 33.1 Tuning Fetch Performance [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tuning.html#rowfetching) -### 32.2 Database Round-trips +### 33.2 Database Round-trips [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tuning.html#roundtrips) -### 32.3. Statement Caching +### 33.3 Statement Caching [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tuning.html#stmtcache) -### 32.4 Client Result Caching (CRC) +### 33.4 Client Result Caching (CRC) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tuning.html#clientresultcache) -## 33. Tracing SQL and PL/SQL Statements +## 34. Tracing SQL and PL/SQL Statements [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/tracingsql.html#tracingsql) -## 34. Two-Phase Commits (TPC) +## 35. Two-Phase Commits (TPC) [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/two_phase_commit.html#twopc) -## 35. Node.js Programming Styles and node-oracledb +## 36. Node.js Programming Styles and node-oracledb [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/pgmstyle.html#programstyles) -### 35.1 Callbacks and node-oracledb +### 36.1 Callbacks and node-oracledb [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/pgmstyle.html#callbackoverview) -### 35.2 Promises and node-oracledb +### 36.2 Promises and node-oracledb [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/pgmstyle.html#promiseoverview) -#### 35.2.1 Custom Promise Libraries +#### 36.2.1 Custom Promise Libraries [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/pgmstyle.html#custompromises) -### 35.3 Async/Await and node-oracledb +### 36.3 Async/Await and node-oracledb [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/pgmstyle.html#asyncawaitoverview) -## 36. Migrating from Previous node-oracledb Releases +## 37. Migrating from Previous node-oracledb Releases [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/migrate.html#migrate) -### 36.1 Migrating from node-oracledb 3.1 to node-oracledb 4.0 +### 37.1 Migrating from node-oracledb 3.1 to node-oracledb 4.0 [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/migrate.html#migratev31v40) -### 36.2 Migrating from node-oracledb 4.0 to node-oracledb 4.1 +### 37.2 Migrating from node-oracledb 4.0 to node-oracledb 4.1 [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/migrate.html#migratev40v41) -### 36.3 Migrating from node-oracledb 4.1 to node-oracledb 4.2 +### 37.3 Migrating from node-oracledb 4.1 to node-oracledb 4.2 [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/migrate.html#migratev41v42) -### 36.4 Migrating from node-oracledb 4.2 to node-oracledb 5.0 +### 37.4 Migrating from node-oracledb 4.2 to node-oracledb 5.0 [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/migrate.html#migratev42v50) -### 36.5 Migrating from node-oracledb 5.1 to node-oracledb 5.2 +### 37.5 Migrating from node-oracledb 5.1 to node-oracledb 5.2 [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/migrate.html#migratev51v52) -## 37. Useful Resources for Node-oracledb +## 38. Useful Resources for Node-oracledb [View latest documentation](https://node-oracledb.readthedocs.io/en/latest/user_guide/resources.html#otherresources) diff --git a/doc/src/api_manual/sodacollection.rst b/doc/src/api_manual/sodacollection.rst index 0b3e7b6b..3d1eb71b 100644 --- a/doc/src/api_manual/sodacollection.rst +++ b/doc/src/api_manual/sodacollection.rst @@ -273,653 +273,6 @@ SodaCollection Methods See :ref:`Simple Oracle Document Access (SODA) ` for more examples. -.. method:: sodaCollection.listIndexes() - - .. versionadded:: 6.2 - - **Promise:**:: - - promise = listIndexes(); - - Retrieves all the indexes from a SODA collection. This method returns an - array of objects that contains the index specifications. - - This method requires Oracle Client 21.3 or later (or Oracle Client 19 from - 19.13). - - **Callback:** - - If you are using the callback programming style:: - - listIndexes(function(Error error, Array listIndexes){}); - - The parameters of the callback function - ``function(Error error, Array listIndexes)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``listIndexes()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. - * - Array ``listIndexes`` - - An array of objects, each containing the index specifications of the SODA collection. - - See :ref:`Retrieving All Index Specifications ` for an example. - -.. _sodaoperationclass: - -SodaOperation Class -=================== - -You can chain together SodaOperation methods to specify read or write -operations against a collection. - -Non-terminal SodaOperation methods return the same object on which they -are invoked, allowing them to be chained together. - -A terminal SodaOperation method always appears at the end of a method -chain to execute the operation. - -A SodaOperation object is an internal object. You should not directly -modify its properties. - -.. _sodaoperationclassnonterm: - -Non-terminal SodaOperation Methods ----------------------------------- - -Non-terminal SodaOperation methods are chained together to set criteria -that documents must satisfy. At the end of the chain, a single terminal -method specifies the operation to be performed on the matching -documents. - -When a non-terminal method is repeated, the last one overrides the -earlier one. For example if ``find().key("a").key("b")...`` was used, -then only documents with the key “b” are matched. If -``find().keys(["a","b"]).key("c")...`` is used, then only the document -with the key “c” is matched. - -.. method:: sodaOperation.fetchArraySize() - - .. versionadded:: 5.0 - - .. code-block:: javascript - - fetchArraySize(Number size) - - Sets the size of an internal buffer used for fetching - documents from a collection with the terminal SodaOperation methods - :meth:`~sodaOperation.getCursor()` and - :meth:`~sodaOperation.getDocuments()`. Changing - ``size`` may affect performance but does not affect how many documents - are returned. - - If ``fetchArraySize()`` is not used, the size defaults to the current - value of :attr:`oracledb.fetchArraySize`. - - For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for - JSON Documents `. - - It requires Oracle Client 19.5 or later, and Oracle Database 18.3 or later. - -.. method:: sodaOperation.filter() - - .. versionadded:: 3.0 - - .. code-block:: javascript - - filter(Object filterSpec) - - Sets a filter specification for the operation, allowing for complex - document queries and ordering of JSON documents. Filter specifications - can include comparisons, regular expressions, logical, and spatial - operators, among others. See `Overview of SODA Filter Specifications - (QBEs) `__ and `SODA Filter Specifications - (Reference) `__. - - For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for JSON - Documents `. - -.. method:: sodaOperation.hint() - - .. versionadded:: 5.2 - - .. code-block:: javascript - - hint(String hint) - - The ``hint()`` value can be used to pass an Oracle hint to :ref:`terminal - SodaOperation Methods `. It is string in the - same format as a `SQL - hint `__ - but without any comment characters, for example ``hint("MONITOR")``. - Pass only the hint ``"MONITOR"`` (turn on monitoring) or - ``"NO_MONITOR"`` (turn off monitoring). See the Oracle Database SQL - Tuning Guide documentation `MONITOR and NO_MONITOR - Hints `__ and `Monitoring Database - Operations `__ for more information. - - It requires Oracle Client 21.3 or higher (or Oracle Client 19 from - 19.11). - -.. method:: sodaOperation.key() - - .. versionadded:: 3.0 - - .. code-block:: javascript - - key(String value) - - Sets the key value to be used to match a document for the operation. Any - previous calls made to this method or :meth:`~sodaOperation.keys()` - will be ignored. - - SODA document keys are unique. - -.. method:: sodaOperation.keys() - - .. versionadded:: 3.0 - - .. code-block:: javascript - - keys(Array value) - - Sets the keys to be used to match multiple documents for the operation. - Any previous calls made to this method or :meth:`sodaOperation.key()` - will be ignored. - - SODA document keys are unique. - - A maximum of 1000 keys can be used. - -.. method:: sodaOperation.limit() - - .. versionadded:: 3.0 - - .. code-block:: javascript - - limit(Number n) - - Sets the maximum number of documents that a terminal method will apply - to. The value of ``n`` must be greater than 0. The limit is applied to - documents that match the other SodaOperation criteria. The ``limit()`` - method only applies to SodaOperation read operations like - ``getCursor()`` and ``getDocuments()``. If a filter ``$orderby`` is not - used, the document order is internally defined. - - The ``limit()`` method cannot be used in conjunction with - :meth:`~sodaOperation.count()`. - -.. method:: sodaOperation.lock() - - .. versionadded:: 6.2 - - .. code-block:: javascript - - lock() - - Locks the documents fetched from the collection. - - Using ``lock()`` allows for pessimistic locking, that is, only the current - user that performed the lock can modify the documents in the collection. - Other users can only perform operations on these documents once they are - unlocked. The functionality of this method is equivalent to the - ``SELECT FOR UPDATE`` clause. - - The documents can be unlocked with an explicit call to - :meth:`~connection.commit()` or :meth:`~connection.rollback()` on the - connection. Ensure that the :attr:`oracledb.autoCommit` is - set to *false* for the connection. Otherwise, the documents will be - unlocked immediately after the operation is complete. - - This method should only be used with read operations (other than - :meth:`~sodaOperation.count()`), and should not be used in conjunction - with non-terminal methods :meth:`~sodaOperation.skip()` and - :meth:`~sodaOperation.limit()`. - - If this method is specified in conjunction with a write operation, then - this method is ignored. - - This method requires Oracle Client 21.3 or later (or Oracle Client 19 from - 19.11). - -.. method:: sodaOperation.skip() - - .. versionadded:: 3.0 - - .. code-block:: javascript - - skip(Number n) - - Sets the number of documents that will be skipped before the terminal - method is applied. The value of ``n`` must be greater or equal to 0. The - skip applies to documents that match the other SodaOperation criteria. - - If a filter ``$orderby`` is not used, the document order (and hence - which documents are skipped) is internally defined. - - The ``skip()`` method only applies to SodaOperation read operations like - ``getDocuments()``. It cannot be used with - :meth:`~sodaOperation.count()`. - -.. method:: sodaOperation.version() - - .. versionadded:: 3.0 - - .. code-block:: javascript - - version(String value) - - Sets the document version that documents must have. - - This is typically used in conjunction with a key, for example - ``collection.find().key("k").version("v").replaceOne(doc)``. - - Using ``version()`` allows for optimistic locking, so that the - subsequent SodaOperation terminal method does not affect a document that - someone else has already modified. If the requested document version is - not matched, then your terminal operation will not impact any document. - The application can then query to find the latest document version and - apply any desired change. - -.. _sodaoperationclassterm: - -Terminal SodaOperation Methods ------------------------------- - -A terminal SodaOperation method operates on the set of documents that -satisfy the criteria specified by previous non-terminal methods in the -method chain. Only one terminal method can be used in each chain. - -.. method:: sodaOperation.count() - - .. versionadded:: 3.0 - - **Promise**:: - - promise = count(); - - Finds the number of documents matching the given SodaOperation query - criteria. - - If ``skip()`` or ``limit()`` are set, then ``count()`` will return an - error. - - If :attr:`oracledb.autoCommit` is *true*, and ``count()`` succeeds, - then any open transaction on the connection is committed. - - **Callback**: - - If you are using the callback programming style:: - - count(function (Error error, Object result){}); - - The parameters of the callback function - ``function (Error error, Object result)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``count()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. - * - Object ``result`` - - The `result` object contains one attribute:: - - Number count - - The number of documents matching the SodaOperation criteria. - - Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if more rows exist. Larger values will wrap. - -.. method:: sodaOperation.getCursor() - - .. versionadded:: 3.0 - - **Promise**:: - - promise = getCursor() - - Returns a :ref:`SodaDocumentCursor ` for - documents that match the SodaOperation query criteria. The cursor can be - iterated over with :meth:`sodaDocumentCursor.getNext()` to access - each :ref:`SodaDocument `. - - When the application has completed using the cursor it must be closed - with :meth:`sodaDocumentCursor.close()`. - - If the number of documents is known to be small, it is recommended to - use :meth:`sodaOperation.getDocuments()` instead. - - If :attr:`oracledb.autoCommit` is *true*, and - ``getCursor()`` succeeds, then any open transaction on the connection is - committed. - - **Callback**: - - If you are using the callback programming style:: - - getCursor(function(Error error, SodaDocumentCursor cursor){}); - - The parameters of the callback function - ``function(Error error, SodaDocumentCursor cursor)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``getCursor()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. - * - SodaDocumentCursor ``cursor`` - - A cursor that can be iterated over to access SodaDocument objects matching the SodaOperation search criteria. - -.. method:: sodaOperation.getDocuments() - - .. versionadded:: 3.0 - - **Promise**:: - - promise = getDocuments(); - - Gets an array of :ref:`SodaDocuments ` matching the - SodaOperation query criteria. An empty array will be returned when no - documents match. - - Where the number of matching documents is known to be small, this API - should be used in preference to :meth:`sodaOperation.getCursor()`. - - If :attr:`oracledb.autoCommit` is *true*, and ``getDocuments()`` - succeeds, then any open transaction on the connection is committed. - - **Callback**: - - If you are using the callback programming style:: - - getDocuments(function(Error error, Array documents){}); - - The parameters of the callback function - ``function(Error error, Array documents)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``getDocuments()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. - * - Array ``documents`` - - An array of SodaDocuments that match the SodaOperation query criteria. - -.. method:: sodaOperation.getOne() - - .. versionadded:: 3.0 - - **Promise**:: - - promise = getOne(); - - Obtains one document matching the SodaOperation query criteria. If the - criteria match more than one document, then only the first is returned. - - Typically ``getone()`` should be used with ``key(k)`` or - ``key(k).version(v)`` to ensure only one document is matched. - - If :attr:`oracledb.autoCommit` is *true*, and ``getOne()`` succeeds, then - any open transaction on the connection is committed. - - **Callback**: - - If you are using the callback programming style:: - - getOne(function(Error error, SodaDocument document){}); - - The parameters of the callback function - ``function(Error error, SodaDocument document)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``getOne()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. - * - SodaDocument ``document`` - - One SodaDocument that matches the sodaOperation query criteria. If no document is found, then ``document`` will be undefined. - -.. method:: sodaOperation.remove() - - .. versionadded:: 3.0 - - **Promise**:: - - promise = remove(); - - Removes a set of documents matching the SodaOperation query criteria. - - Note settings from ``skip()`` and ``limit()`` non-terminals are ignored - because they only apply to read operations. - - If :attr:`oracledb.autoCommit` is *true*, and ``remove()`` succeeds, then - removal and any open transaction on the connection is committed. - - **Callback**: - - If you are using the callback programming style:: - - remove(function(Error error, Object result){}); - - The parameters of the callback function - ``function(Error error, Object result)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``remove()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. - * - Object ``result`` - - The `result` object contains one attribute:: - - result.count - - The number of documents removed from the collection. - - Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if Oracle Database removed more rows. Larger values will wrap. - -.. method:: sodaOperation.replaceOne() - - .. versionadded:: 3.0 - - **Promise**:: - - promise = replaceOne(Object newDocumentContent); - promise = replaceOne(SodaDocument newSodaDocument); - - Replaces a document in a collection. The input document can be either a - JavaScript object representing the data content, or it can be an - existing :ref:`SodaDocument `. - - The ``mediaType`` document component and content of the document that - matches the SodaOperation query criteria will be replaced by the content - and any ``mediaType`` document component of the new document. Any other - document components will not be affected. The ``lastModified`` and - ``version`` document components of the replaced document will be - updated. - - The ``key()`` non-terminal must be used when using ``replaceOne()``. - - No error is reported if the operation criteria do not match any - document. - - Note settings from ``skip()`` and ``limit()`` non-terminals are ignored - because they only apply to read operations. - - If :attr:`oracledb.autoCommit` is *true*, and ``replaceOne()`` succeeds, - then any open transaction on the connection is committed. - - The parameters of the ``sodaOperation.replaceOne()`` method are: - - .. _replaceone: - - .. list-table-with-summary:: sodaOperation.replaceOne() Parameters - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 10 10 30 - :summary: The first column displays the parameter. The second column - displays the data type of the parameter. The third column displays - the description of the parameter. - - * - Parameter - - Data Type - - Description - * - ``newDocumentContent`` or ``newSodaDocument`` - - Object or SodaDocument - - The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document. - - **Callback**: - - If you are using the callback programming style:: - - replaceOne(Object newDocumentContent, function(Error error, Object result){}); - replaceOne(SodaDocument newSodaDocument, function(Error error, Object result){}); - - See :ref:`replaceone` for information on the parameters. - - The parameters of the callback function - ``function(Error error, Object result)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``replaceOne()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message. - * - Object ``result`` - - The `result` object contains one attribute:: - - result.replaced - - This attribute will be *true* if the document was successfully replaced, *false* otherwise. - -.. method:: sodaOperation.replaceOneAndGet() - - .. versionadded:: 3.0 - - **Promise**:: - - promise = replaceOneAndGet(Object newDocumentContent); - promise = replaceOneAndGet(SodaDocument newSodaDocument); - - Replaces a document in a collection similar to - :meth:`sodaOperation.replaceOne()`, but also returns - the result document which contains all :ref:`SodaDocument - ` components (key, version, etc.) - except for content. Content itself is not returned for performance - reasons. The result document has new values for components that are - updated as part of the replace operation (such as version, last-modified - timestamp, and media type) - - If :attr:`oracledb.autoCommit` is *true*, and ``replaceOneAndGet()`` - succeeds, then any open transaction on the connection is committed. - - The parameters of the ``sodaOperation.replaceOneAndGet()`` method are: - - .. _replaceoneandget: - - .. list-table-with-summary:: sodaOperation.replaceOneAndGet() Parameters - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 10 10 30 - :summary: The first column displays the parameter. The second column - displays the data type of the parameter. The third column displays - the description of the parameter. - - * - Parameter - - Data Type - - Description - * - ``newDocumentContent`` or ``newSodaDocument`` - - Object or SodaDocument - - The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document. - - **Callback**: - - If you are using the callback programming style:: - - replaceOneAndGet(Object newDocumentContent, function(Error error, SodaDocument updatedDocument){}); - replaceOneAndGet(SodaDocument newSodaDocument, function(Error error, SodaDocument updatedDocument){}); - - See :ref:`replaceoneandget` for information on the parameters. - - The parameters of the callback function - ``function(Error error, SodaDocument updatedDocument)`` are: - - .. list-table-with-summary:: - :header-rows: 1 - :class: wy-table-responsive - :align: center - :widths: 15 30 - :summary: The first column displays the callback function parameter. - The second column displays the description of the parameter. - - * - Callback Function Parameter - - Description - * - Error ``error`` - - If ``replaceOneAndGet()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message. - * - SodaDocument ``updatedDocument`` - - The updated :ref:`SodaDocument ` if replacement was successful, otherwise ``updatedDocument`` will be undefined. - - The ``lastModified`` and ``version`` attributes of the stored SodaDocument will be updated. The ``mediaType`` attribute and the content will be replaced. Other attributes of ``newSodaDocument`` are ignored. - - Note for performance reasons, ``updatedDocument`` will not have document content and cannot itself be passed directly to SODA insert or replace methods. - .. method:: sodaCollection.getDataGuide() .. versionadded:: 3.0 @@ -1207,6 +560,46 @@ method chain. Only one terminal method can be used in each chain. Note for performance reasons, ``document`` will not have document content and cannot itself be passed directly to SODA insert or replace methods. +.. method:: sodaCollection.listIndexes() + + .. versionadded:: 6.2 + + **Promise:**:: + + promise = listIndexes(); + + Retrieves all the indexes from a SODA collection. This method returns an + array of objects that contains the index specifications. + + This method requires Oracle Client 21.3 or later (or Oracle Client 19 from + 19.13). + + **Callback:** + + If you are using the callback programming style:: + + listIndexes(function(Error error, Array listIndexes){}); + + The parameters of the callback function + ``function(Error error, Array listIndexes)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``listIndexes()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. + * - Array ``listIndexes`` + - An array of objects, each containing the index specifications of the SODA collection. + + See :ref:`Retrieving All Index Specifications ` for an example. + .. method:: sodaCollection.save() .. versionadded:: 5.0 diff --git a/doc/src/api_manual/sodaoperation.rst b/doc/src/api_manual/sodaoperation.rst new file mode 100644 index 00000000..f1439019 --- /dev/null +++ b/doc/src/api_manual/sodaoperation.rst @@ -0,0 +1,616 @@ +.. _sodaoperationclass: + +************************ +API: SodaOperation Class +************************ + +You can chain together SodaOperation methods to specify read or write +operations against a collection. + +.. note:: + + In this release, SODA is only supported in the node-oracledb Thick mode. + See :ref:`enablingthick`. + +SODA can be used with Oracle Database 18.3 and above, when node-oracledb +uses Oracle Client 18.5 or Oracle Client 19.3, or later. + +:ref:`Non-terminal SodaOperation methods ` return +the same object on which they are invoked, allowing them to be chained +together. + +A :ref:`terminal SodaOperation method ` always appears +at the end of a method chain to execute the operation. + +A SodaOperation object is an internal object. You should not directly +modify its properties. + +.. _sodaoperationclassnonterm: + +Non-terminal SodaOperation Methods +================================== + +Non-terminal SodaOperation methods are chained together to set criteria +that documents must satisfy. At the end of the chain, a single terminal +method specifies the operation to be performed on the matching +documents. + +When a non-terminal method is repeated, the last one overrides the +earlier one. For example if ``find().key("a").key("b")...`` was used, +then only documents with the key “b” are matched. If +``find().keys(["a","b"]).key("c")...`` is used, then only the document +with the key “c” is matched. + +.. method:: sodaOperation.fetchArraySize() + + .. versionadded:: 5.0 + + .. code-block:: javascript + + fetchArraySize(Number size) + + Sets the size of an internal buffer used for fetching + documents from a collection with the terminal SodaOperation methods + :meth:`~sodaOperation.getCursor()` and + :meth:`~sodaOperation.getDocuments()`. Changing + ``size`` may affect performance but does not affect how many documents + are returned. + + If ``fetchArraySize()`` is not used, the size defaults to the current + value of :attr:`oracledb.fetchArraySize`. + + For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for + JSON Documents `. + + It requires Oracle Client 19.5 or later, and Oracle Database 18.3 or later. + +.. method:: sodaOperation.filter() + + .. versionadded:: 3.0 + + .. code-block:: javascript + + filter(Object filterSpec) + + Sets a filter specification for the operation, allowing for complex + document queries and ordering of JSON documents. Filter specifications + can include comparisons, regular expressions, logical, and spatial + operators, among others. See `Overview of SODA Filter Specifications + (QBEs) `__ and `SODA Filter Specifications + (Reference) `__. + + For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for JSON + Documents `. + +.. method:: sodaOperation.hint() + + .. versionadded:: 5.2 + + .. code-block:: javascript + + hint(String hint) + + The ``hint()`` value can be used to pass an Oracle hint to :ref:`terminal + SodaOperation Methods `. It is string in the + same format as a `SQL + hint `__ + but without any comment characters, for example ``hint("MONITOR")``. + Pass only the hint ``"MONITOR"`` (turn on monitoring) or + ``"NO_MONITOR"`` (turn off monitoring). See the Oracle Database SQL + Tuning Guide documentation `MONITOR and NO_MONITOR + Hints `__ and `Monitoring Database + Operations `__ for more information. + + It requires Oracle Client 21.3 or higher (or Oracle Client 19 from + 19.11). + +.. method:: sodaOperation.key() + + .. versionadded:: 3.0 + + .. code-block:: javascript + + key(String value) + + Sets the key value to be used to match a document for the operation. Any + previous calls made to this method or :meth:`~sodaOperation.keys()` + will be ignored. + + SODA document keys are unique. + +.. method:: sodaOperation.keys() + + .. versionadded:: 3.0 + + .. code-block:: javascript + + keys(Array value) + + Sets the keys to be used to match multiple documents for the operation. + Any previous calls made to this method or :meth:`sodaOperation.key()` + will be ignored. + + SODA document keys are unique. + + A maximum of 1000 keys can be used. + +.. method:: sodaOperation.limit() + + .. versionadded:: 3.0 + + .. code-block:: javascript + + limit(Number n) + + Sets the maximum number of documents that a terminal method will apply + to. The value of ``n`` must be greater than 0. The limit is applied to + documents that match the other SodaOperation criteria. The ``limit()`` + method only applies to SodaOperation read operations like + ``getCursor()`` and ``getDocuments()``. If a filter ``$orderby`` is not + used, the document order is internally defined. + + The ``limit()`` method cannot be used in conjunction with + :meth:`~sodaOperation.count()`. + +.. method:: sodaOperation.lock() + + .. versionadded:: 6.2 + + .. code-block:: javascript + + lock() + + Locks the documents fetched from the collection. + + Using ``lock()`` allows for pessimistic locking, that is, only the current + user that performed the lock can modify the documents in the collection. + Other users can only perform operations on these documents once they are + unlocked. The functionality of this method is equivalent to the + ``SELECT FOR UPDATE`` clause. + + The documents can be unlocked with an explicit call to + :meth:`~connection.commit()` or :meth:`~connection.rollback()` on the + connection. Ensure that the :attr:`oracledb.autoCommit` is + set to *false* for the connection. Otherwise, the documents will be + unlocked immediately after the operation is complete. + + This method should only be used with read operations (other than + :meth:`~sodaOperation.count()`), and should not be used in conjunction + with non-terminal methods :meth:`~sodaOperation.skip()` and + :meth:`~sodaOperation.limit()`. + + If this method is specified in conjunction with a write operation, then + this method is ignored. + + This method requires Oracle Client 21.3 or later (or Oracle Client 19 from + 19.11). + +.. method:: sodaOperation.skip() + + .. versionadded:: 3.0 + + .. code-block:: javascript + + skip(Number n) + + Sets the number of documents that will be skipped before the terminal + method is applied. The value of ``n`` must be greater or equal to 0. The + skip applies to documents that match the other SodaOperation criteria. + + If a filter ``$orderby`` is not used, the document order (and hence + which documents are skipped) is internally defined. + + The ``skip()`` method only applies to SodaOperation read operations like + ``getDocuments()``. It cannot be used with + :meth:`~sodaOperation.count()`. + +.. method:: sodaOperation.version() + + .. versionadded:: 3.0 + + .. code-block:: javascript + + version(String value) + + Sets the document version that documents must have. + + This is typically used in conjunction with a key, for example + ``collection.find().key("k").version("v").replaceOne(doc)``. + + Using ``version()`` allows for optimistic locking, so that the + subsequent SodaOperation terminal method does not affect a document that + someone else has already modified. If the requested document version is + not matched, then your terminal operation will not impact any document. + The application can then query to find the latest document version and + apply any desired change. + +.. _sodaoperationclassterm: + +Terminal SodaOperation Methods +============================== + +A terminal SodaOperation method operates on the set of documents that +satisfy the criteria specified by previous non-terminal methods in the +method chain. Only one terminal method can be used in each chain. + +.. method:: sodaOperation.count() + + .. versionadded:: 3.0 + + **Promise**:: + + promise = count(); + + Finds the number of documents matching the given SodaOperation query + criteria. + + If ``skip()`` or ``limit()`` are set, then ``count()`` will return an + error. + + If :attr:`oracledb.autoCommit` is *true*, and ``count()`` succeeds, + then any open transaction on the connection is committed. + + **Callback**: + + If you are using the callback programming style:: + + count(function (Error error, Object result){}); + + The parameters of the callback function + ``function (Error error, Object result)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``count()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. + * - Object ``result`` + - The `result` object contains one attribute:: + + Number count + + The number of documents matching the SodaOperation criteria. + + Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if more rows exist. Larger values will wrap. + +.. method:: sodaOperation.getCursor() + + .. versionadded:: 3.0 + + **Promise**:: + + promise = getCursor() + + Returns a :ref:`SodaDocumentCursor ` for + documents that match the SodaOperation query criteria. The cursor can be + iterated over with :meth:`sodaDocumentCursor.getNext()` to access + each :ref:`SodaDocument `. + + When the application has completed using the cursor it must be closed + with :meth:`sodaDocumentCursor.close()`. + + If the number of documents is known to be small, it is recommended to + use :meth:`sodaOperation.getDocuments()` instead. + + If :attr:`oracledb.autoCommit` is *true*, and + ``getCursor()`` succeeds, then any open transaction on the connection is + committed. + + **Callback**: + + If you are using the callback programming style:: + + getCursor(function(Error error, SodaDocumentCursor cursor){}); + + The parameters of the callback function + ``function(Error error, SodaDocumentCursor cursor)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``getCursor()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. + * - SodaDocumentCursor ``cursor`` + - A cursor that can be iterated over to access SodaDocument objects matching the SodaOperation search criteria. + +.. method:: sodaOperation.getDocuments() + + .. versionadded:: 3.0 + + **Promise**:: + + promise = getDocuments(); + + Gets an array of :ref:`SodaDocuments ` matching the + SodaOperation query criteria. An empty array will be returned when no + documents match. + + Where the number of matching documents is known to be small, this API + should be used in preference to :meth:`sodaOperation.getCursor()`. + + If :attr:`oracledb.autoCommit` is *true*, and ``getDocuments()`` + succeeds, then any open transaction on the connection is committed. + + **Callback**: + + If you are using the callback programming style:: + + getDocuments(function(Error error, Array documents){}); + + The parameters of the callback function + ``function(Error error, Array documents)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``getDocuments()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. + * - Array ``documents`` + - An array of SodaDocuments that match the SodaOperation query criteria. + +.. method:: sodaOperation.getOne() + + .. versionadded:: 3.0 + + **Promise**:: + + promise = getOne(); + + Obtains one document matching the SodaOperation query criteria. If the + criteria match more than one document, then only the first is returned. + + Typically ``getone()`` should be used with ``key(k)`` or + ``key(k).version(v)`` to ensure only one document is matched. + + If :attr:`oracledb.autoCommit` is *true*, and ``getOne()`` succeeds, then + any open transaction on the connection is committed. + + **Callback**: + + If you are using the callback programming style:: + + getOne(function(Error error, SodaDocument document){}); + + The parameters of the callback function + ``function(Error error, SodaDocument document)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``getOne()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. + * - SodaDocument ``document`` + - One SodaDocument that matches the sodaOperation query criteria. If no document is found, then ``document`` will be undefined. + +.. method:: sodaOperation.remove() + + .. versionadded:: 3.0 + + **Promise**:: + + promise = remove(); + + Removes a set of documents matching the SodaOperation query criteria. + + Note settings from ``skip()`` and ``limit()`` non-terminals are ignored + because they only apply to read operations. + + If :attr:`oracledb.autoCommit` is *true*, and ``remove()`` succeeds, then + removal and any open transaction on the connection is committed. + + **Callback**: + + If you are using the callback programming style:: + + remove(function(Error error, Object result){}); + + The parameters of the callback function + ``function(Error error, Object result)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``remove()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message. + * - Object ``result`` + - The `result` object contains one attribute:: + + result.count + + The number of documents removed from the collection. + + Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if Oracle Database removed more rows. Larger values will wrap. + +.. method:: sodaOperation.replaceOne() + + .. versionadded:: 3.0 + + **Promise**:: + + promise = replaceOne(Object newDocumentContent); + promise = replaceOne(SodaDocument newSodaDocument); + + Replaces a document in a collection. The input document can be either a + JavaScript object representing the data content, or it can be an + existing :ref:`SodaDocument `. + + The ``mediaType`` document component and content of the document that + matches the SodaOperation query criteria will be replaced by the content + and any ``mediaType`` document component of the new document. Any other + document components will not be affected. The ``lastModified`` and + ``version`` document components of the replaced document will be + updated. + + The ``key()`` non-terminal must be used when using ``replaceOne()``. + + No error is reported if the operation criteria do not match any + document. + + Note settings from ``skip()`` and ``limit()`` non-terminals are ignored + because they only apply to read operations. + + If :attr:`oracledb.autoCommit` is *true*, and ``replaceOne()`` succeeds, + then any open transaction on the connection is committed. + + The parameters of the ``sodaOperation.replaceOne()`` method are: + + .. _replaceone: + + .. list-table-with-summary:: sodaOperation.replaceOne() Parameters + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 10 10 30 + :summary: The first column displays the parameter. The second column + displays the data type of the parameter. The third column displays + the description of the parameter. + + * - Parameter + - Data Type + - Description + * - ``newDocumentContent`` or ``newSodaDocument`` + - Object or SodaDocument + - The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document. + + **Callback**: + + If you are using the callback programming style:: + + replaceOne(Object newDocumentContent, function(Error error, Object result){}); + replaceOne(SodaDocument newSodaDocument, function(Error error, Object result){}); + + See :ref:`replaceone` for information on the parameters. + + The parameters of the callback function + ``function(Error error, Object result)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``replaceOne()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message. + * - Object ``result`` + - The `result` object contains one attribute:: + + result.replaced + + This attribute will be *true* if the document was successfully replaced, *false* otherwise. + +.. method:: sodaOperation.replaceOneAndGet() + + .. versionadded:: 3.0 + + **Promise**:: + + promise = replaceOneAndGet(Object newDocumentContent); + promise = replaceOneAndGet(SodaDocument newSodaDocument); + + Replaces a document in a collection similar to + :meth:`sodaOperation.replaceOne()`, but also returns + the result document which contains all :ref:`SodaDocument + ` components (key, version, etc.) + except for content. Content itself is not returned for performance + reasons. The result document has new values for components that are + updated as part of the replace operation (such as version, last-modified + timestamp, and media type) + + If :attr:`oracledb.autoCommit` is *true*, and ``replaceOneAndGet()`` + succeeds, then any open transaction on the connection is committed. + + The parameters of the ``sodaOperation.replaceOneAndGet()`` method are: + + .. _replaceoneandget: + + .. list-table-with-summary:: sodaOperation.replaceOneAndGet() Parameters + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 10 10 30 + :summary: The first column displays the parameter. The second column + displays the data type of the parameter. The third column displays + the description of the parameter. + + * - Parameter + - Data Type + - Description + * - ``newDocumentContent`` or ``newSodaDocument`` + - Object or SodaDocument + - The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document. + + **Callback**: + + If you are using the callback programming style:: + + replaceOneAndGet(Object newDocumentContent, function(Error error, SodaDocument updatedDocument){}); + replaceOneAndGet(SodaDocument newSodaDocument, function(Error error, SodaDocument updatedDocument){}); + + See :ref:`replaceoneandget` for information on the parameters. + + The parameters of the callback function + ``function(Error error, SodaDocument updatedDocument)`` are: + + .. list-table-with-summary:: + :header-rows: 1 + :class: wy-table-responsive + :align: center + :widths: 15 30 + :summary: The first column displays the callback function parameter. + The second column displays the description of the parameter. + + * - Callback Function Parameter + - Description + * - Error ``error`` + - If ``replaceOneAndGet()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message. + * - SodaDocument ``updatedDocument`` + - The updated :ref:`SodaDocument ` if replacement was successful, otherwise ``updatedDocument`` will be undefined. + + The ``lastModified`` and ``version`` attributes of the stored SodaDocument will be updated. The ``mediaType`` attribute and the content will be replaced. Other attributes of ``newSodaDocument`` are ignored. + + Note for performance reasons, ``updatedDocument`` will not have document content and cannot itself be passed directly to SODA insert or replace methods. diff --git a/doc/src/index.rst b/doc/src/index.rst index 5c6a20a1..f850018f 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -66,6 +66,7 @@ API Manual api_manual/statistics.rst api_manual/resultset.rst api_manual/sodacollection.rst + api_manual/sodaoperation.rst api_manual/sodadb.rst api_manual/sodadocument.rst api_manual/sodacursor.rst diff --git a/lib/constants.js b/lib/constants.js index b4baf2df..6106b8cd 100644 --- a/lib/constants.js +++ b/lib/constants.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/dbObject.js b/lib/dbObject.js index e1e53a5a..58d19679 100644 --- a/lib/dbObject.js +++ b/lib/dbObject.js @@ -1,4 +1,4 @@ -// Copyright (c) 2019, 2023, Oracle and/or its affiliates. +// Copyright (c) 2019, 2024, Oracle and/or its affiliates. //---------------------------------------------------------------------------- // diff --git a/lib/errors.js b/lib/errors.js index dd73216f..a52b4824 100644 --- a/lib/errors.js +++ b/lib/errors.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/lob.js b/lib/lob.js index 385cbb8a..bac80c90 100644 --- a/lib/lob.js +++ b/lib/lob.js @@ -1,4 +1,4 @@ -// Copyright (c) 2016, 2023, Oracle and/or its affiliates. +// Copyright (c) 2016, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/pool.js b/lib/pool.js index 3c15899c..b5711569 100644 --- a/lib/pool.js +++ b/lib/pool.js @@ -1,4 +1,4 @@ -// Copyright (c) 2016, 2022, Oracle and/or its affiliates. +// Copyright (c) 2016, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/poolStatistics.js b/lib/poolStatistics.js index 2b595d66..a674ac81 100644 --- a/lib/poolStatistics.js +++ b/lib/poolStatistics.js @@ -1,4 +1,4 @@ -// Copyright (c) 2021, 2023, Oracle and/or its affiliates. +// Copyright (c) 2021, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/settings.js b/lib/settings.js index 114c7956..99873e77 100644 --- a/lib/settings.js +++ b/lib/settings.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/connection.js b/lib/thin/connection.js index 4ade931f..9961107a 100644 --- a/lib/thin/connection.js +++ b/lib/thin/connection.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/dbObject.js b/lib/thin/dbObject.js index 3d38d0c8..c3569d68 100644 --- a/lib/thin/dbObject.js +++ b/lib/thin/dbObject.js @@ -1,4 +1,4 @@ -// Copyright (c) 2023, Oracle and/or its affiliates. +// Copyright (c) 2023, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/lob.js b/lib/thin/lob.js index 6dedfb4b..4e3eb5a0 100644 --- a/lib/thin/lob.js +++ b/lib/thin/lob.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/pool.js b/lib/thin/pool.js index 2517fae2..fd3ed9c7 100644 --- a/lib/thin/pool.js +++ b/lib/thin/pool.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/protocol/buffer.js b/lib/thin/protocol/buffer.js index 1fc3fb4f..06a582be 100644 --- a/lib/thin/protocol/buffer.js +++ b/lib/thin/protocol/buffer.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/protocol/capabilities.js b/lib/thin/protocol/capabilities.js index aeb15351..77325c0d 100644 --- a/lib/thin/protocol/capabilities.js +++ b/lib/thin/protocol/capabilities.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/protocol/constants.js b/lib/thin/protocol/constants.js index da320b2f..c9dc1713 100644 --- a/lib/thin/protocol/constants.js +++ b/lib/thin/protocol/constants.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/protocol/messages/base.js b/lib/thin/protocol/messages/base.js index f9ed62eb..e56921fe 100644 --- a/lib/thin/protocol/messages/base.js +++ b/lib/thin/protocol/messages/base.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/protocol/messages/dataType.js b/lib/thin/protocol/messages/dataType.js index 34bf15cf..dec084b5 100644 --- a/lib/thin/protocol/messages/dataType.js +++ b/lib/thin/protocol/messages/dataType.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/protocol/messages/withData.js b/lib/thin/protocol/messages/withData.js index 56cff580..ff495dfe 100644 --- a/lib/thin/protocol/messages/withData.js +++ b/lib/thin/protocol/messages/withData.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/sqlnet/networkSession.js b/lib/thin/sqlnet/networkSession.js index d4db3ce5..bebd4c44 100644 --- a/lib/thin/sqlnet/networkSession.js +++ b/lib/thin/sqlnet/networkSession.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/thin/statement.js b/lib/thin/statement.js index 7ca5d18b..d56f00b8 100644 --- a/lib/thin/statement.js +++ b/lib/thin/statement.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/transformer.js b/lib/transformer.js index e91c7760..e9c7da24 100644 --- a/lib/transformer.js +++ b/lib/transformer.js @@ -1,4 +1,4 @@ -// Copyright (c) 2023, Oracle and/or its affiliates. +// Copyright (c) 2023, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/types.js b/lib/types.js index 48c12601..0918f7e6 100644 --- a/lib/types.js +++ b/lib/types.js @@ -1,4 +1,4 @@ -// Copyright (c) 2022, 2023, Oracle and/or its affiliates. +// Copyright (c) 2022, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/lib/version.js b/lib/version.js index cbf65dd7..a4670380 100644 --- a/lib/version.js +++ b/lib/version.js @@ -1,4 +1,4 @@ -// Copyright (c) 2023, Oracle and/or its affiliates. +// Copyright (c) 2023, 2024, Oracle and/or its affiliates. //----------------------------------------------------------------------------- // diff --git a/test/dbObject20.js b/test/dbObject20.js index b3cc536c..9bd51b70 100644 --- a/test/dbObject20.js +++ b/test/dbObject20.js @@ -1,4 +1,4 @@ -/* Copyright (c) 2019, 2023, Oracle and/or its affiliates. */ +/* Copyright (c) 2019, 2024, Oracle and/or its affiliates. */ /****************************************************************************** * @@ -864,10 +864,10 @@ describe('290. dbObject20.js', () => { describe(`290.4 db Object tests with Invalid values to attributes`, () => { let conn; - const TYPE1 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL_LINE'; - const TYPE2 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL'; - const TYPE3 = 'NODB_TEST_INVALID_VALUES_OBJ'; - const TYPE4 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL_VARCHAR'; + const TYPE1 = 'NODB_TEST_INV_OBJ_TBL_LINE'; + const TYPE2 = 'NODB_TEST_INV_OBJ_TBL'; + const TYPE3 = 'NODB_TEST_INV_OBJ'; + const TYPE4 = 'NODB_TEST_INV_OBJ_TBL_VARCHAR'; const maxVarCharLen = 4; const maxVarNCharLen = 4; const maxVarRawLen = 10; diff --git a/test/jsonDualityViews6.js b/test/jsonDualityViews6.js index 23d26822..1beb8555 100644 --- a/test/jsonDualityViews6.js +++ b/test/jsonDualityViews6.js @@ -1,4 +1,4 @@ -/* Copyright (c) 2023, Oracle and/or its affiliates. */ +/* Copyright (c) 2023, 2024, Oracle and/or its affiliates. */ /****************************************************************************** * @@ -236,7 +236,7 @@ describe('277. jsonDualityView6.js', function() { ); }); - describe('277.1.2 Queries(SNT,SNT+where clause)', function() { + describe('277.2 Queries(SNT,SNT+where clause)', function() { before (async function() { await connection.execute(`CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW student_ov AS @@ -249,7 +249,7 @@ describe('277. jsonDualityView6.js', function() { `); }); - it('277.1.2.1 With SNT', async function() { + it('277.2.1 With SNT', async function() { let result = await connection.execute(`select o.data.StudentId as name from student_ov o order by o.data.StudentId`); assert.deepStrictEqual(result.rows, [[1], [2], [3]]); @@ -274,7 +274,7 @@ describe('277. jsonDualityView6.js', function() { assert.deepStrictEqual(result.rows, [[1, 1], [2, 2], [3, 3]]); }); - it('277.1.2.2 SNT+where clause)', async function() { + it('277.2.2 SNT+where clause', async function() { let result = await connection.execute(`select o.data.StudentId from student_ov o where o.data.StudentId in (1,3) order by 1`); assert.deepStrictEqual(result.rows, [[1], [3]]); @@ -302,7 +302,7 @@ describe('277. jsonDualityView6.js', function() { }); }); }); - describe('277.2 PK-PK-FK', function() { + describe('277.3 PK-PK-FK', function() { before(async function() { // create the student table await connection.execute(` @@ -337,7 +337,7 @@ describe('277. jsonDualityView6.js', function() { await connection.execute(`drop table student PURGE`); }); - it('277.2.1 Insert data in table and views', async function() { + it('277.3.1 Insert data in table and views', async function() { await connection.execute(`insert into student values (1, 'Ajit')`); await connection.execute(`insert into student values (2, 'Tirthankar')`); await connection.execute(`insert into student values (3, 'Shashank')`); @@ -379,7 +379,7 @@ describe('277. jsonDualityView6.js', function() { "StudentId": 1, "Class": [{"ClassId": 1, "Name": "CS101"}]}]); }); - it('277.2.2 Sanity DMLs', async function() { + it('277.3.2 Sanity DMLs', async function() { await connection.execute(` insert into student_ov values ('{"StudentId":4, "StudentName":"Abcd","StudentClass":[{"StudentClassId":1, @@ -412,7 +412,7 @@ describe('277. jsonDualityView6.js', function() { "Class": [{"ClassId": 1, "Name": "CS101"}]}]); }); - it('277.2.3 with different keywords', async function() { + it('277.3.3 with different keywords', async function() { await connection.execute(`CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW student_ov AS Student @INSERT@UPDATE@DELETE diff --git a/test/list.txt b/test/list.txt index 06d6d3c1..e3a2a1a3 100755 --- a/test/list.txt +++ b/test/list.txt @@ -4272,7 +4272,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true 173.9 Negative - dropIndex() no parameter 173.10 option object of dropIndex(), basic case 173.11 option object of dropIndex(), boolean value is false - 173.12 getDataGiuide(), basic case + 173.12 getDataGuide(), basic case 174. soda6.js 174.1 filter() basic case @@ -5344,7 +5344,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true 271.22 converter function to convert column val to string 271.23 converter function with multiple columns -272. jsonDualityView1.js +272. jsonDualityViews1.js 272.1 JSON Relational Duality View 272.1.1 fetch results 272.1.2 update query @@ -5389,7 +5389,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true 272.3.11.1 Query with test1 user 272.3.11.2 Query with test2 user -273. jsonDualityView2.js +273. jsonDualityViews2.js 273.1 without base table being available (use force option at view creation) 273.2 Base table name with various sizes (128) 273.3 Perform dbms_metadata.get_ddl() and verify tags were properly added to columns and tables @@ -5413,7 +5413,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true 273.5 With Redaction on base tables 273.5.1 redaction enabled on a base table -274. jsonDualityView3.js +274. jsonDualityViews3.js 274.1 Define Columns of View with WITH READ WRITE or WITH READ ONLY annotations 274.2 Create View on Virtual columns, UNUSED columns 274.3 Have columns of all scalar types, including FLOAT, TIMESTAMP, TIMESTAMP WITH TIME ZONE @@ -5423,7 +5423,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true 274.7 Add VISIBLE | INVISIBLE options to define columns in view 274.8 Create view on NULL columns empty columns -275. jsonDualityView4.js +275. jsonDualityViews4.js 275.1 Test create table, Column defaults 275.2 Test with Table and column constraints 275.3 Test with Virtual columns @@ -5447,22 +5447,22 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true 275.11 Tests with Views 275.11.1 Object view -276. jsonDualityView5.js +276. jsonDualityViews5.js 276.1 Insert data in table and views 276.2 test with Tags in column level -277. jsonDualityView6.js +277. jsonDualityViews6.js 277.1 With tables and without constraints relationship 277.1.1 Insert data in table and views 277.1.2 Sanity DMLs 277.1.3 With Invalid tags - 277.1.2 Queries(SNT,SNT+where clause) - 277.1.2.1 With SNT - 277.1.2.2 SNT+where clause) - 277.2 PK PK FK - 277.2.1 Insert data in table and views - 277.2.2 Sanity DMLs - 277.2.3 with different keywords + 277.2 Queries(SNT,SNT+where clause) + 277.2.1 With SNT + 277.2.2 SNT+where clause + 277.3 PK PK FK + 277.3.1 Insert data in table and views + 277.3.2 Sanity DMLs + 277.3.3 with different keywords 278. Pool expansion 278.1 pool expansion when new connection created and within pool max limit @@ -5582,14 +5582,15 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true 289. sqlParser.js 289.1 parse SQL containing json_object() 289.2 bind variables between quoted string - 289.3 single line comment - 289.4 constant string + 289.3 PL/SQL - single line comment + 289.4 PL/SQL - constant string 289.5 multiple division operation 289.6 SQL statement starting with parentheses 289.7 statement containing simple strings 289.8 binds between comments 289.9 non-ascii character in the bind name 289.10 apostrophe in single line comment + 289.11 single line comment at the end 290. dbObject20.js 290.1 db Object tests with NCHAR datatype diff --git a/test/sqlParser.js b/test/sqlParser.js index 8d668068..e3a6c7f6 100644 --- a/test/sqlParser.js +++ b/test/sqlParser.js @@ -1,4 +1,4 @@ -/* Copyright (c) 2023, Oracle and/or its affiliates. */ +/* Copyright (c) 2023, 2024, Oracle and/or its affiliates. */ /****************************************************************************** * @@ -64,7 +64,7 @@ describe('289. sqlParser.js', function() { }); // 289.1 it('289.2 bind variables between quoted string', async () => { - const sql = `select + const sql = `SELECT :a, q'{This contains ' and " and : just fine}', :b, @@ -76,19 +76,19 @@ describe('289. sqlParser.js', function() { :e, q'$This contains ' and " and : just fine$', :f - from dual`; + FROM DUAL`; const info = await conn.getStatementInfo(sql); assert.deepStrictEqual(info.bindNames, ["A", "B", "C", "D", "E", "F"]); }); // 289.2 - it('289.3 single line comment', async () => { + it('289.3 PL/SQL - single line comment', async () => { const sql = `--begin :value2 := :a + :b + :c +:a +3; end; - begin :value2 := :a + :c +3; end; -- not a :bindv`; + begin :value2 := :a + :c +3; end; -- not a :bindVariable`; const info = await conn.getStatementInfo(sql); assert.deepStrictEqual(info.bindNames, ["VALUE2", "A", "C"]); }); // 289.3 - it('289.4 constant string', async () => { + it('289.4 PL/SQL - constant string', async () => { const sql = `begin :value := to_date('20021231 12:31:00', :format); end;`; @@ -142,4 +142,11 @@ describe('289. sqlParser.js', function() { const info = await conn.getStatementInfo(sql); assert.deepStrictEqual(info.bindNames, ['TEST']); }); // 289.10 + + it('289.11 single line comment at the end', async () => { + const sql = ` + SELECT :test, 'String' FROM DUAL -- not a :bindVariable`; + const info = await conn.getStatementInfo(sql); + assert.deepStrictEqual(info.bindNames, ['TEST']); + }); // 289.11 });