/node_modules/mongoose/node_modules/mongodb/CHANGES_3.0.0.md

https://bitbucket.org/coleman333/smartsite · Markdown · 288 lines · 217 code · 71 blank · 0 comment · 0 complexity · 05f0531bb211cb0bc0bfff44151623b5 MD5 · raw file

  1. ## Features
  2. The following are new features added in MongoDB 3.6 and supported in the Node.js driver.
  3. ### Retryable Writes
  4. Support has been added for retryable writes through the connection string. MongoDB 3.6
  5. will utilize server sessions to allow some write commands to specify a transaction ID to enforce
  6. at-most-once semantics for the write operation(s) and allow for retrying the operation if the driver
  7. fails to obtain a write result (e.g. network error or "not master" error after a replica set
  8. failover)Full details can be found in the [Retryable Writes Specification](https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst).
  9. ### DNS Seedlist Support
  10. Support has been added for DNS Seedlists. Users may now configure a single domain to return a list
  11. of host names. Full details can be found in the [Seedlist Discovery Specification](https://github.com/mongodb/specifications/blob/master/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.rst).
  12. ### Change Streams
  13. Support has been added for creating a stream to track changes to a particular collection. This is a
  14. new feature in MongoDB 3.6. Full details can be found in the [Change Stream Specification](https://github.com/mongodb/specifications/blob/master/source/change-streams.rst) as
  15. well as [examples in the test directory](https://github.com/mongodb/node-mongodb-native/blob/3.0.0/test/functional/operation_changestream_example_tests.js).
  16. ### Sessions
  17. Version 3.6 of the server introduces the concept of logical sessions for clients. In this driver,
  18. `MongoClient` now tracks all sessions created on the client, and explicitly cleans them up upon
  19. client close. More information can be found in the [Driver Sessions Specification](https://github.com/mongodb/specifications/blob/master/source/sessions/driver-sessions.rst).
  20. ## API Changes
  21. We removed the following API methods.
  22. - `Db.prototype.authenticate`
  23. - `Db.prototype.logout`
  24. - `Db.prototype.open`
  25. - `Db.prototype.db`
  26. - `Db.prototype.close`
  27. - `Admin.prototype.authenticate`
  28. - `Admin.prototype.logout`
  29. - `Admin.prototype.profilingLevel`
  30. - `Admin.prototype.setProfilingLevel`
  31. - `Admin.prototype.profilingInfo`
  32. - `Cursor.prototype.nextObject`
  33. We've added the following API methods.
  34. - `MongoClient.prototype.logout`
  35. - `MongoClient.prototype.isConnected`
  36. - `MongoClient.prototype.db`
  37. - `MongoClient.prototype.close`
  38. - `MongoClient.prototype.connect`
  39. - `Db.prototype.profilingLevel`
  40. - `Db.prototype.setProfilingLevel`
  41. - `Db.prototype.profilingInfo`
  42. In core we have removed the possibility of authenticating multiple credentials against the same
  43. connection pool. This is to avoid problems with MongoDB 3.6 or higher where all users will reside in
  44. the admin database and thus database level authentication is no longer supported.
  45. The legacy construct
  46. ```js
  47. var db = var Db('test', new Server('localhost', 27017));
  48. db.open((err, db) => {
  49. // Authenticate
  50. db.admin().authenticate('root', 'root', (err, success) => {
  51. ....
  52. });
  53. });
  54. ```
  55. is replaced with
  56. ```js
  57. new MongoClient(new Server('localhost', 27017), {
  58. user: 'root'
  59. , password: 'root'
  60. , authSource: 'adming'}).connect((err, client) => {
  61. ....
  62. })
  63. ```
  64. `MongoClient.connect` works as expected but it returns the MongoClient instance instead of a
  65. database object.
  66. The legacy operation
  67. ```js
  68. MongoClient.connect('mongodb://localhost:27017/test', (err, db) => {
  69. // Database returned
  70. });
  71. ```
  72. is replaced with
  73. ```js
  74. MongoClient.connect('mongodb://localhost:27017/test', (err, client) => {
  75. // Client returned
  76. var db = client.db('test');
  77. });
  78. ```
  79. ## Other Changes
  80. Below are more updates to the driver in the 3.0.0 release.
  81. ### Connection String
  82. Following [changes to the MongoDB connection string specification](https://github.com/mongodb/specifications/commit/4631ccd4f825fb1a3aba204510023f9b4d193a05),
  83. authentication and hostname details in connection strings must now be URL-encoded. These changes
  84. reduce ambiguity in connection strings.
  85. For example, whereas before `mongodb://u$ername:pa$$w{}rd@/tmp/mongodb-27017.sock/test` would have
  86. been a valid connection string (with username `u$ername`, password `pa$$w{}rd`, host `/tmp/mongodb-27017.sock`
  87. and auth database `test`), the connection string for those details would now have to be provided to
  88. MongoClient as `mongodb://u%24ername:pa%24%24w%7B%7Drd@%2Ftmp%2Fmongodb-27017.sock/test`.
  89. Unsupported URL options in a connection string now log a warning instead of throwing an error.
  90. For more information about connection strings, read the [connection string specification](https://github.com/mongodb/specifications/blob/master/source/connection-string/connection-string-spec.rst).
  91. ### `BulkWriteResult` & `BulkWriteError`
  92. When errors occured with bulk write operations in the past, the driver would callback or reject with
  93. the first write error, as well as passing the resulting `BulkWriteResult`. For example:
  94. ```js
  95. MongoClient.connect('mongodb://localhost', function(err, client) {
  96. const collection = client.db('foo').collection('test-collection')
  97. collection
  98. .insert({ id: 1 })
  99. .then(() => collection.insertMany([ { id: 1 }, { id: 1 } ]))
  100. .then(result => /* deal with errors in `result */)
  101. .catch(err => /* no error is thrown for bulk errors */);
  102. });
  103. ```
  104. becomes:
  105. ```js
  106. MongoClient.connect('mongodb://localhost', function(err, client) {
  107. const collection = client.db('foo').collection('test-collection')
  108. collection
  109. .insert({ id: 1 })
  110. .then(() => collection.insertMany([ { id: 1 }, { id: 1 } ]))
  111. .then(() => /* this will not be called in the event of a bulk write error */)
  112. .catch(err => /* deal with errors in `err` */);
  113. });
  114. ```
  115. Where the result of the failed operation is a `BulkWriteError` which has a child value `result`
  116. which is the original `BulkWriteResult`. Similarly, the callback form no longer calls back with an
  117. `(Error, BulkWriteResult)`, but instead just a `(BulkWriteError)`.
  118. ### `mapReduce` inlined results
  119. When `Collection.prototype.mapReduce` is invoked with a callback that includes `out: 'inline'`,
  120. it would diverge from the `Promise`-based variant by returning additional data as positional
  121. arguments to the callback (`(err, result, stats, ...)`). This is no longer the case, both variants
  122. of the method will now return a single object for all results - a single value for the default case,
  123. and an object similar to the existing `Promise` form for cases where there is more data to pass to
  124. the user.
  125. ### Find
  126. `find` and `findOne` no longer support the `fields` parameter. You can achieve the same results as
  127. the `fields` parameter by using `Cursor.prototype.project` or by passing the `projection` property
  128. in on the options object . Additionally, `find` does not support individual options like `skip` and
  129. `limit` as positional parameters. You must either pass in these parameters in the `options` object,
  130. or add them via `Cursor` methods like `Cursor.prototype.skip`.
  131. ### `Collection.prototype.aggregate`
  132. `Collection.prototype.aggregate` no longer accepts variadic arguments. While this
  133. was originally added to improve compatibility with the mongo shell, it has never
  134. been a documented feature, and has led to more bugs and maintenance burden.
  135. Pipeline stages are now only accepted as an `Array` of stages as the first argument.
  136. 2.x syntax:
  137. ```js
  138. collection.prototype.aggregate(
  139. {$match: {a: 1}},
  140. {$project: {b: 1, _id: 0}},
  141. function (err, result) {
  142. ...
  143. }
  144. );
  145. ```
  146. 3.x syntax
  147. ```js
  148. collection.prototype.aggregate(
  149. [
  150. {$match: {a: 1}},
  151. {$project: {b: 1, _id: 0}}
  152. ],
  153. function (err, cursor) {
  154. ...
  155. }
  156. );
  157. ```
  158. `Collection.prototype.aggregate` now returns a cursor if a callback is provided. It used to return
  159. the resulting documents which is the same as calling `cursor.toArray()` on the cursor we now pass to
  160. the callback.
  161. 2.x syntax
  162. ```js
  163. collection.prototype.aggregate(
  164. [
  165. {$match: {a: 1}},
  166. {$project: {b: 1, _id: 0}}
  167. ],
  168. function (err, result) {
  169. console.log(result);
  170. }
  171. );
  172. ```
  173. 3.x syntax
  174. ```js
  175. collection.prototype.aggregate(
  176. [
  177. {$match: {a: 1}},
  178. {$project: {b: 1, _id: 0}}
  179. ],
  180. function (err, cursor) {
  181. cursor.toArray(function(err, result) {
  182. console.log(result);
  183. });
  184. }
  185. );
  186. ```
  187. Support added for `comment` in the aggregation command. Support also added for a `hint` field in the
  188. aggregation `options`.
  189. If you use aggregation and try to use the `explain` flag while you have a `readConcern` or
  190. `writeConcern`, your query will now fail.
  191. ### `updateOne` & `updateMany`
  192. The driver now ensures that updated documents contain atomic operators. For instance, if a user
  193. tries to update an existing document but passes in no operations (such as `$set`, `$unset`, or
  194. `$rename`), the driver will now error:
  195. ```js
  196. let testCollection = db.collection('test');
  197. testCollection.updateOne({_id: 'test'}, {});
  198. // An error is returned: The update operation document must contain at least one atomic operator.
  199. ```
  200. ### `keepAlive`
  201. Wherever it occurs, the option `keepAlive` has been changed. `keepAlive` is now a boolean that enables/disables `keepAlive`, while `keepAliveInitialDelay` specifies how long to wait before initiating keepAlive. This brings the API in line with [NodeJS's socket api](https://nodejs.org/dist/latest-v9.x/docs/api/all.html#net_socket_setkeepalive_enable_initialdelay)
  202. ### `insertMany`
  203. Now `insertMany` returns `insertedIds` in a map of the index of the inserted document to the id of the inserted document:
  204. ```js
  205. {
  206. "0": 2,
  207. "1": 3
  208. }
  209. ```
  210. Previously an array of ids was returned: `[ 2, 3 ]`. This change occurs with both ordered and unordered `insertMany` calls, see the [CRUD specifications](https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst#results) for more details.
  211. ### `geoNear` command helper
  212. The functionality of the geoNear command is duplicated elsewhere in the language, in the `$near`/`$nearSphere` query operators on unsharded collections, and in the `$geoNear` aggregation stage on all collections. Maintaining this command increases our test surface, and creates additional work when adding features that must be supported on all read commands. As a result, the command will be fully
  213. removed in the MongoDB 4.0 release, and we are choosing to remove it in this
  214. major release of the node driver.
  215. ### Tests
  216. We have updated all of the tests to use [Mocha](https://mochajs.org) and a new test runner, [`mongodb-test-runner`](https://github.com/mongodb-js/mongodb-test-runner), which
  217. sets up topologies for the test scenarios.