diff --git a/docs/contribute.txt b/docs/contribute.txt index d25dda4e8d..a541b15fad 100644 --- a/docs/contribute.txt +++ b/docs/contribute.txt @@ -58,7 +58,7 @@ Contribute Code The MongoDB Ruby driver source is located `at GitHub `_. -The list of known issues in the driver is available +The list of known issues in the driver is available `in JIRA `_. We recommend creating a JIRA ticket before starting work on a bug fix or @@ -73,7 +73,7 @@ the changes to the stable branches, if needed. A MongoDB deployment is required to run the tests. Setup procedures and recommendations for various deployments, as well as how to configure the driver's test suite for the deployments, are covered in the `spec -readme `. +readme `__. The driver is tested on `Evergreen `_, MongoDB's in-house continuous integration platform. After a pull request diff --git a/docs/reference/client-side-encryption.txt b/docs/reference/client-side-encryption.txt index c27fa6c5a7..5f8a7ea2f5 100644 --- a/docs/reference/client-side-encryption.txt +++ b/docs/reference/client-side-encryption.txt @@ -74,12 +74,12 @@ enterprise-only feature. If you only intend to use explicit encryption, you may skip this step. Mongocryptd comes pre-packaged with enterprise builds of the MongoDB server -(versions 4.2 and newer). For installation instructions, see -`the MongoDB manual `_. +(versions 4.2 and newer). For installation instructions, see the +`MongoDB manual `_. In order to configure mongocryptd (for example, which port it listens on or the path used to spawn the daemon), it is necessary to pass different options to the -``Mongo::Client`` performing automatic encryption. See the `:extra_options`_ +``Mongo::Client`` performing automatic encryption. See the :ref:`:extra_options ` section of this tutorial for more information. Automatic Encryption @@ -202,11 +202,12 @@ The example above demonstrates using automatic encryption with a local master ke For more information about using the AWS Key Management Service to create a master key and create data keys, see the following sections of this tutorial: -- `Creating A Master Key`_ -- `Creating A Data Key`_ +- :ref:`Creating A Master Key ` +- :ref:`Creating A Data Key ` Explicit Encryption =================== + Explicit encryption is a feature that allows users to encrypt and decrypt individual pieces of data such as strings, integers, or symbols. Explicit encryption is a community feature and does not require an enterprise build @@ -296,8 +297,8 @@ The example above demonstrates using explicit encryption with a local master key For more information about using the AWS Key Management Service to create a master key and create data keys, see the following sections of this tutorial: -- `Creating A Master Key`_, -- `Creating A Data Key`_, +- :ref:`Creating A Master Key ` +- :ref:`Creating A Data Key ` Creating a Master Key ===================== @@ -307,8 +308,11 @@ user data. The master key can be generated in one of two ways: by creating a local key, or by creating a key in the Amazon Web Services Key Management Service (AWS KMS). +.. _local-master-key: + Local Master Key ~~~~~~~~~~~~~~~~ + A local master key is a 96-byte binary string. It should be persisted on your machine as an environment variable or in a text file. @@ -329,14 +333,25 @@ AWS Master Key It is recommended that you use Amazon's Key Management Service to create and store your master key. To do so, follow steps 1 and 2 of the :drivers:`"Convert to a Remote Master Key" section` +.. _remote-master-key: + +Remote Master Key +~~~~~~~~~~~~~~~~~ +It is recommended that you use a remote Key Management Service to create and +store your master key. To do so, follow steps of the +`"Set up a Remote Master Key" `_ in the MongoDB Client-Side Encryption documentation. For more information about creating a master key, see the :drivers:`Create a Master Key ` +`Create a Master Key `_ section of the MongoDB manual. +.. _creating-a-data-key: + Creating a Data Key =================== + Once you have created a master key, create a data key by calling the ``#create_data_key`` method on an instance of the ``Mongo::ClientEncryption`` class. This method generates a new data key and inserts it into the key vault @@ -376,8 +391,8 @@ key with the following code snippet: data_key_id = client_encryption.create_data_key('local') # => -See the `Local Master Key`_ section for more information about generating a new -local master key. +See the :ref:`Local Master Key ` section for more information +about generating a new local master key. Create a Data Key Using an AWS Master Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -423,11 +438,12 @@ generating a new master key on AWS and finding the information you need to create data keys. For more information about creating a data key, see the -:drivers:`Create a Data Encryption Key ` +`Create a Data Encryption Key `_ section of the MongoDB manual. Auto-Encryption Options ======================= + Automatic encryption can be configured on a ``Mongo::Client`` using the ``auto_encryption_options`` option ``Hash``. This section provides an overview of the fields inside ``auto_encryption_options`` and explains how to choose their @@ -435,6 +451,7 @@ values. ``:key_vault_client`` ~~~~~~~~~~~~~~~~~~~~~ + The key vault client is a ``Mongo::Client`` instance that will be used to connect to the MongoDB collection containing your encryption data keys. For example, if your key vault was hosted on a MongoDB instance at ``localhost:30000``: @@ -456,6 +473,7 @@ to insert and fetch data keys. ``:key_vault_namespace`` ~~~~~~~~~~~~~~~~~~~~~~~~ + The key vault namespace is a ``String`` in the format ``"database_name.collection_name"``, where ``database_name`` and ``collection_name`` are the name of the database and collection in which you would like to store your data keys. For example, if your data @@ -474,6 +492,7 @@ There is no default key vault namespace, and this option must be provided. ``:schema_map`` ~~~~~~~~~~~~~~~ + A schema map is a Hash with information about which fields to automatically encrypt and decrypt. @@ -549,11 +568,12 @@ When you intend to use your schema map, convert it to a Ruby ``Hash`` using the .. seealso:: - :drivers:`Specify Encrypted Fields Using JSON Schema`, + `Specify Encrypted Fields Using JSON Schema `_, :manual:`Automatic Encryption Rules` ``:bypass_auto_encryption`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The ``:bypass_auto_encryption`` option is a ``Boolean`` that specifies whether the ``Mongo::Client`` should skip encryption when writing to the database. If ``:bypass_auto_encryption`` is ``true``, the client will still perform automatic @@ -568,8 +588,11 @@ decryption of any previously-encrypted data. } ) +.. _cse-extra-options: + ``:extra_options`` ~~~~~~~~~~~~~~~~~~ + ``:extra_options`` is a ``Hash`` of options related to spawning mongocryptd. Every option in this ``Hash`` has a default value, so it is only necessary to provide the options whose defaults you want to override. diff --git a/docs/reference/connection-and-configuration.txt b/docs/reference/connection-and-configuration.txt index acc28b5250..7532e73f98 100644 --- a/docs/reference/connection-and-configuration.txt +++ b/docs/reference/connection-and-configuration.txt @@ -12,7 +12,7 @@ options the driver provides, including authentication. .. toctree:: :titlesonly: - create-client - authentication - monitoring - user-management + /reference/create-client + /reference/authentication + /reference/monitoring + /reference/user-management diff --git a/docs/reference/create-client.txt b/docs/reference/create-client.txt index b5b15ebca1..6f7abde5c4 100644 --- a/docs/reference/create-client.txt +++ b/docs/reference/create-client.txt @@ -882,6 +882,7 @@ URI options are explained in detail in the :manual:`Connection URI reference `. .. note:: + Options that are set in **milliseconds** in the URI are represented as a ``float`` in Ruby and the units are **seconds**. @@ -1321,7 +1322,7 @@ It is also possible to remove hooks from ``Mongo.tls_context_hooks`` by storing a reference to the Procs somewhere else in the application, and then using ``Array#delete_if`` to remove the desired hooks. -..warning :: +.. warning:: TLS context hooks are global and will affect every instance of ``Mongo::Client``. Any library that allows applications to enable these hooks should expose methods to diff --git a/docs/reference/crud-operations.txt b/docs/reference/crud-operations.txt index 674b70ee40..4c809cfe35 100644 --- a/docs/reference/crud-operations.txt +++ b/docs/reference/crud-operations.txt @@ -967,7 +967,7 @@ underscore one that Ruby driver uses. A Note about the BSON Symbol type ================================= -Because the BSON specification deprecated the BSON symbol type, the `bson` gem +Because the BSON specification deprecated the BSON symbol type, the ``bson`` gem will serialize Ruby symbols into BSON strings when used on its own. However, in order to maintain backwards compatibility with older datasets, the Ruby driver overrides this behavior to serialize Ruby symbols as BSON symbols. This is diff --git a/docs/reference/gridfs.txt b/docs/reference/gridfs.txt index 267c4b1552..756750b18c 100644 --- a/docs/reference/gridfs.txt +++ b/docs/reference/gridfs.txt @@ -252,7 +252,7 @@ by default into the ``fs.chunks`` collection and file metadata is inserted into client.database.fs.insert_one(file) -To insert into collections with a name prefix other than `fs`, access the +To insert into collections with a name prefix other than ``fs``, access the filesystem with a ``:fs_name`` option. .. code-block:: ruby diff --git a/docs/reference/monitoring.txt b/docs/reference/monitoring.txt index 1721feb6a6..d2f30a167a 100644 --- a/docs/reference/monitoring.txt +++ b/docs/reference/monitoring.txt @@ -137,35 +137,35 @@ can look like the following: format("SDAM | %s".freeze, message) end end - + class TopologyOpeningLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Topology type '#{event.topology.display_name}' initializing." end end - + class ServerOpeningLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Server #{event.address} initializing." end end - + class ServerDescriptionChangedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Server description for #{event.address} changed from " + "'#{event.previous_description.server_type}' to '#{event.new_description.server_type}'." end end - + class TopologyChangedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) if event.previous_topology != event.new_topology "Topology type '#{event.previous_topology.display_name}' changed to " + @@ -176,18 +176,18 @@ can look like the following: end end end - + class ServerClosedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Server #{event.address} connection closed." end end - + class TopologyClosedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Topology type '#{event.topology.display_name}' closed." end @@ -228,7 +228,7 @@ since the events may be published during the client's construction: topology_changed_subscriber = TopologyChangedLogSubscriber.new server_closed_subscriber = ServerClosedLogSubscriber.new topology_closed_subscriber = TopologyClosedLogSubscriber.new - + sdam_proc = Proc.new do |client| client.subscribe(Mongo::Monitoring::TOPOLOGY_OPENING, topology_opening_subscriber) @@ -287,9 +287,9 @@ Server Heartbeats The application can be notified of each server heartbeat by subscribing to SERVER_HEARTBEAT topic. A server heartbeat listener must implement -three methods: `started`, `succeeded` and `failed`. Each heartbeat invokes -the `started` method on the listener, and then either `succeeded` or `failed` -method depending on the outcome of the heartbeat. +three methods: ``started``, ``succeeded`` and ``failed``. Each heartbeat +invokes the ``started`` method on the listener, and then either ``succeeded`` +or ``failed`` method depending on the outcome of the heartbeat. All heartbeat events contain the address of the server that the heartbeat was sent to. Succeeded and failed events contain the round trip time for @@ -316,9 +316,9 @@ The following is an example logging heartbeat event subscriber: def failed(event) log_debug("#{event.address} | FAILED | #{event.error.class}: #{event.error.message} | #{event.duration}s") end - + private - + def logger Mongo::Logger.logger end diff --git a/docs/reference/schema-operations.txt b/docs/reference/schema-operations.txt index 713db0afc4..6d3617302a 100644 --- a/docs/reference/schema-operations.txt +++ b/docs/reference/schema-operations.txt @@ -12,7 +12,7 @@ including managing databases, collections, indexes and users. .. toctree:: :titlesonly: - database-tasks - collection-tasks - indexing - collations + /reference/database-tasks + /reference/collection-tasks + /reference/indexing + /reference/collations diff --git a/docs/reference/working-with-data.txt b/docs/reference/working-with-data.txt index d6d76f82ed..3382428f8e 100644 --- a/docs/reference/working-with-data.txt +++ b/docs/reference/working-with-data.txt @@ -12,16 +12,16 @@ implements for inserting, updating and retrieving data from MongoDB. .. toctree:: :titlesonly: - crud-operations - bulk-operations - projection - aggregation - map-reduce - text-search - geospatial-search - query-cache - gridfs - change-streams - sessions - transactions - client-side-encryption + /reference/crud-operations + /reference/bulk-operations + /reference/projection + /reference/aggregation + /reference/map-reduce + /reference/text-search + /reference/geospatial-search + /reference/query-cache + /reference/gridfs + /reference/change-streams + /reference/sessions + /reference/transactions + /reference/client-side-encryption diff --git a/docs/release-notes.txt b/docs/release-notes.txt index 6ab0733dcd..220acdf9fa 100644 --- a/docs/release-notes.txt +++ b/docs/release-notes.txt @@ -40,6 +40,9 @@ The following non-breaking changes were made: - mapReduce command is now deprecated. - Avoid tight looping in push monitor + +.. _release-notes-2.16: + 2.16 ==== @@ -57,6 +60,8 @@ This release of the Ruby driver increases the minimum required Ruby version to 2.4 and deprecates support for MongoDB server versions below 3.6. +.. _release-notes-2.15: + 2.15 ==== @@ -105,6 +110,8 @@ The following smaller improvements have been made: - Server selection timeout for ``mongocryptd`` has been increased to 10 seconds. +.. _release-notes-2.14: + 2.14 ==== @@ -137,6 +144,8 @@ The following smaller improvements have been made: Support for Ruby versions 2.3 and 2.4 has been deprecated as of this release. +.. _release-notes-2.13: + 2.13 ==== @@ -148,7 +157,7 @@ functionality has been added: cross-driver mechanims to discover deployment topology or force direct connection. - Support for :ref:`MONGODB-AWS authentication mechanism `. -- When SCRAM authentication is used with 4.4 and newer servers, the driver will +- When SCRAM authentication is used with 4.4 and newer servers, the driver will complete authentication with fewer network roundtrips. - The driver creates an additional monitoring connection for 4.4 and newer servers, permitting the server to notify the driver when its state changes. @@ -179,6 +188,8 @@ The following smaller improvements have been made: can now be configured. +.. _release-notes-2.12: + 2.12 ==== @@ -193,6 +204,8 @@ The following smaller improvements have been made: troubleshooting. +.. _release-notes-2.11: + 2.11 ==== @@ -222,6 +235,8 @@ This release of the Ruby driver increases the minimum required Ruby version to 2.3, as well as minimum supported JRuby version to 9.2. +.. _release-notes-2.10: + 2.10 ==== @@ -247,6 +262,8 @@ The following smaller improvements have been made: Support for Ruby versions less than 2.3 is deprecated in this release. +.. _release-notes-2.9: + 2.9 === @@ -265,7 +282,7 @@ This release adds the following new features: The following smaller improvements have been made: -- Support for the ``startAfter`` option in the ``$changeStream`` +- Support for the ``startAfter`` option in the ``$changeStream`` aggregation pipeline stage. - Field order of BSON documents sent to the server changed for better logging. - Certificate paths with unescaped slashes can now be specified in diff --git a/docs/tutorials/common-errors.txt b/docs/tutorials/common-errors.txt new file mode 100644 index 0000000000..e69de29bb2