From 29d4b92650e4b1fb7618d03367abb448bc5fbe3a Mon Sep 17 00:00:00 2001 From: Christopher Jones Date: Tue, 7 May 2019 14:46:36 +1000 Subject: [PATCH] SODA can be used with Oracle Client 18.5 or 19.3 --- CHANGELOG.md | 36 +++++++++++++++++----------- doc/api.md | 66 +++++++++++++++++++++++++++++++--------------------- 2 files changed, 62 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 74f1209c..1d11c541 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,11 +29,6 @@ - CQN support and message type constants were added for database startup and shutdown events. -- Added SODA bulk insert methods - [`sodaCollection.insertMany()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollinsertmany) - and - [`sodaCollection.insertManyAndGet()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollinsertmanyandget). - - Added a `connection.currentSchema` attribute for setting the schema qualifier to be used when a qualifier is omitted in SQL statements. This is an efficient alternative to `ALTER SESSION SET @@ -52,19 +47,10 @@ - Fixed a crash occuring when draining the connection pool ([ODPI-C change](https://github.com/oracle/odpi/commit/https://github.com/oracle/odpi/commit/7666dc3208087383f7f0f5e49c1ee423cb154997)) -- Corrected processing of the `force` option in SODA `dropIndex()`. - -- Corrected the type of - [`sodaCollection.metaData`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollectionpropmetadata). - It is now an Object, as was documented. - - Corrected `pool.status` to be read-only, as was documented. - Error handling changes: - - Corrected the error message parameter number for SODA - `getCollectionNames()`. - - Corrected the error message returned when invalid types are used for boolean options. @@ -78,6 +64,28 @@ - The NJS-014 error when setting a read-only property was replaced with a standard JavaScript message. +- SODA changes: + + - Added SODA bulk insert methods + [`sodaCollection.insertMany()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollinsertmany) + and + [`sodaCollection.insertManyAndGet()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollinsertmanyandget). + + - Document that the general SODA API is out of Preview status when + using Oracle Client 18.5 or Oracle Client 19.3, or later. The + new node-oracledb 4.0 methods `sodaCollection.insertMany()` and + `sodaCollection.insertManyAndGet()` are in Preview status and + should not be used in production + + - Corrected the type of + [`sodaCollection.metaData`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollectionpropmetadata). + It is now an Object, as was documented. + + - Corrected processing of the `force` option in SODA [`sodaCollection.dropIndex()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacolldropindex). + + - Corrected the error message parameter number for SODA + [`sodaDatabase.getCollectionNames()`](https://oracle.github.io/node-oracledb/doc/api.html#sodadbgetcollectionnames). + - Updated documentation. - Added new tests. diff --git a/doc/api.md b/doc/api.md index 665c3df7..68fdc0f2 100644 --- a/doc/api.md +++ b/doc/api.md @@ -529,11 +529,12 @@ With Oracle's sample HR schema, the output is: #### 1.1.2 Example: Simple Oracle Document Access (SODA) in Node.js -Oracle Database 18c users who have been granted the SODA_APP role can -use [node-oracledb's SODA API](#sodaoverview) to store content such -as JSON. SODA support in node-oracledb is in Preview status and -should not be used in production. It will be supported with a future -version of Oracle Client libraries. +Oracle Database 18c or 19c users who have been granted the SODA_APP +role can use [node-oracledb's SODA API](#sodaoverview) to store +content such as JSON. + +SODA can be used with Oracle Client 18.5 and Oracle Client 19.3, or +later. ```javascript // mysoda.js @@ -3323,9 +3324,11 @@ This synchronous method returns a [SodaDatabase](#sodadatabaseclass). Returns a parent SodaDatabase object for use with Simple Oracle Document Access (SODA). -SODA support in node-oracledb is in Preview status and should not be -used in production. It will be supported with a future version of -Oracle Client libraries. +SODA can be used with Oracle Client 18.5 and Oracle Client 19.3, or +later. The SODA bulk insert methods +[`sodaCollection.insertMany()`](#sodacollinsertmany) and +[`sodaCollection.insertManyAndGet()`](#sodacollinsertmanyandget) +remain in Preview status. See [Simple Oracle Document Access (SODA)](#sodaoverview) for more information about using SODA in node-oracledb. @@ -4649,9 +4652,11 @@ for Node.js version 8 Stream `destroy()` method was added in node-oracledb 2.1. ## 9. SodaCollection Class -SODA support in node-oracledb is in Preview status and should not be -used in production. It will be supported with a future version of -Oracle Client libraries. +SODA can be used with Oracle Client 18.5 and Oracle Client 19.3, or +later. The SODA bulk insert methods +[`sodaCollection.insertMany()`](#sodacollinsertmany) and +[`sodaCollection.insertManyAndGet()`](#sodacollinsertmanyandget) +remain in Preview status. #### 9.1 SodaCollection Properties @@ -5516,6 +5521,8 @@ objects](#errorobj) will contain the number of documents that were successfully inserted. Subsequent documents in the input array will not be inserted. +This method is in Preview status and should not be used in production. + This method was added in node-oracledb 4.0. It requires Oracle Client 18.5 or higher. #### 9.2.7 `sodaCollection.insertManyAndGet()` @@ -5540,6 +5547,8 @@ properties, such as the keys (in default collections), can be found. When inserting multiple documents, using `insertManyAndGet()` is recommended in preference to `insertOneAndGet()`. +This method is in Preview status and should not be used in production. + This method was added in node-oracledb 4.0. It requires Oracle Client 18.5 or higher. #### 9.2.8 `sodaCollection.insertOne()` @@ -5702,15 +5711,17 @@ Callback function parameter | Description ## 10. SodaDatabase Class -SODA support in node-oracledb is in Preview status and should not be -used in production. It will be supported with a future version of -Oracle Client libraries. - The SodaDatabase class is the top level object for node-oracledb SODA operations. A 'SODA database' is an abstraction, allowing access to SODA collections in that 'SODA database', which then allow access to documents in those collections. +SODA can be used with Oracle Client 18.5 and Oracle Client 19.3, or +later. The SODA bulk insert methods +[`sodaCollection.insertMany()`](#sodacollinsertmany) and +[`sodaCollection.insertManyAndGet()`](#sodacollinsertmanyandget) +remain in Preview status. + A SODA database is equivalent to an Oracle Database user, see [Overview of SODA][117] in the Introduction to SODA manual. @@ -6012,13 +6023,15 @@ Callback function parameter | Description ## 11. SodaDocument Class -Note SODA support in node-oracledb is in Preview status and should not -be used in production. It will be supported with a future version of -Oracle Client libraries. - SodaDocuments represents the document for SODA read and write operations. +SODA can be used with Oracle Client 18.5 and Oracle Client 19.3, or +later. The SODA bulk insert methods +[`sodaCollection.insertMany()`](#sodacollinsertmany) and +[`sodaCollection.insertManyAndGet()`](#sodacollinsertmanyandget) +remain in Preview status. + SodaDocument objects can be created in three ways: - The result of @@ -11970,14 +11983,15 @@ that connection. ## 27. Simple Oracle Document Access (SODA) Oracle Database Simple Oracle Document Access (SODA) access is -available in node-oracledb version 3 through a set of NoSQL-style -APIs. Documents can be inserted, queried, and retrieved from Oracle -Database using node-oracledb methods. By default, documents are JSON -strings. +available in node-oracledb through a set of NoSQL-style APIs. +Documents can be inserted, queried, and retrieved from Oracle Database +using node-oracledb methods. By default, documents are JSON strings. -SODA support in node-oracledb is in Preview status and should not be -used in production. It will be supported with a future version of -Oracle Client libraries. +SODA can be used with Oracle Client 18.5 and Oracle Client 19.3, or +later. The SODA bulk insert methods +[`sodaCollection.insertMany()`](#sodacollinsertmany) and +[`sodaCollection.insertManyAndGet()`](#sodacollinsertmanyandget) +remain in Preview status. The [Oracle Database Introduction to SODA][103] manual contains much information relevant to using SODA. You can use Oracle SODA