Merge remote-tracking branch 'upstream/master' into docsp-46362-toc-reorg

Author: mongoKart

source/connect/connection-targets.txt

@@ -9,7 +9,7 @@ Choose a Connection Target
    :values: reference
 
 .. meta::
-   :keywords: connection string, URI, server, settings, client, load balancing
+   :keywords: connection string, URI, server, settings, client, load balancing, srv, dns
 
 .. contents:: On this page
    :local:
@@ -151,11 +151,60 @@ option to ``True``. You can do this in two ways: by passing an argument to the
                 "directConnection=true")
          client = MongoClient(uri)
 
+DNS Service Discovery
+---------------------
+
+To use DNS service discovery to look up the DNS SRV record of the service you're connecting to,
+specify the SRV connection format in your connection string. Additionally, if you enable
+the SRV connection format, {+driver-short+} automatically re-scans for new hosts without
+having to change the client configuration.
+
+The following code shows a connection string that uses the SRV connection format:
+
+.. code-block:: python
+
+   uri = "mongodb+srv://<hostname>/"
+
+To learn more about the SRV connection format, see the :manual:`SRV Connection Format </reference/connection-string/#std-label-connections-dns-seedlist>`
+entry in the {+mdb-server+} manual.
+
 Troubleshooting
 ---------------
 
 .. include:: /includes/troubleshooting/connection-targets.rst
 
+Timeout When Accessing MongoDB from {+driver-short+} with Tunneling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you try to connect to a MongoDB replica set over an SSH tunnel, you
+receive the following error:
+
+.. code-block:: python
+
+   File "/Library/Python/2.7/site-packages/pymongo/collection.py", line 1560, in count
+     return self._count(cmd, collation, session)
+     File "/Library/Python/2.7/site-packages/pymongo/collection.py", line 1504, in _count
+     with self._socket_for_reads() as (connection, slave_ok):
+     File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/contextlib.py", line 17, in __enter__
+     return self.gen.next()
+     File "/Library/Python/2.7/site-packages/pymongo/mongo_client.py", line 982, in _socket_for_reads
+     server = topology.select_server(read_preference)
+     File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 224, in select_server
+     address))
+     File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 183, in select_servers
+     selector, server_timeout, address)
+     File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 199, in _select_servers_loop
+     self._error_message(selector))
+   pymongo.errors.ServerSelectionTimeoutError: localhost:27017: timed out
+
+This occurs because {+driver-short+} discovers replica set members by using the response
+from the ``isMaster`` command, which contains the addresses and ports of the other
+replica set members. However, you can't access these addresses and ports through the SSH
+tunnel.
+
+Instead, you can connect directly to a single MongoDB node by using the
+``directConnection=True`` option with SSH tunneling.
+
 API Documentation
 -----------------
 

source/connect/mongoclient.txt

@@ -199,6 +199,9 @@ child process.
    a high probability of deadlock among ``MongoClient`` instances in the child process.
    {+driver-short+} tries to issue a warning if this deadlock might occur.
 
+   For more information about deadlock in forked processes, see
+   :ref:`pymongo-fork-deadlock`.
+
 Multiprocessing
 ~~~~~~~~~~~~~~~
 
@@ -245,6 +248,70 @@ create the ``MongoClient`` object, as shown in the following example:
    from typing import Any, Dict
    client: MongoClient[Dict[str, Any]] = MongoClient()
 
+Troubleshooting
+---------------
+
+MongoClient Fails ConfigurationError
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Providing invalid keyword argument names causes the driver to raise this error.
+
+Ensure that the keyword arguments that you specify exist and are
+spelled correctly.
+
+.. _pymongo-fork-deadlock:
+
+Forking a Process Causes a Deadlock
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A ``MongoClient`` instance spawns multiple threads to run background tasks, such as
+monitoring connected servers. These threads share state that is protected by instances
+of the ``threading.Lock`` class, which are themselves
+`not fork-safe <http://bugs.python.org/issue6721>`__.
+{+driver-short+} is subject to the same limitations as any other multithreaded
+code that uses the ``threading.Lock`` class, or any mutexes.
+
+One of these limitations is that the locks become useless after calling the
+``fork()`` method. When ``fork()`` executes, the driver copies all the parent process's locks to
+the child process in the same state as they were in the parent. If they are
+locked in the parent process, they are also locked in the child process. The child process
+created by ``fork()`` has only one thread, so any locks created by
+other threads in the parent process are never released in the child process.
+The next time the child process attempts to acquire one of these locks, deadlock occurs.
+
+Starting in {+driver-short+} version 4.3, after you call the ``os.fork()`` method, the
+driver uses the ``os.register_at_fork()`` method to reset its locks and other shared state
+in the child process. Although this reduces the likelihood of a deadlock,
+{+driver-short+} depends
+on libraries that aren't fork-safe in multithreaded applications, including
+`OpenSSL <https://github.com/openssl/openssl/issues/19066>`__ and
+`getaddrinfo(3). <https://man7.org/linux/man-pages/man3/gai_strerror.3.html>`__
+Therefore, a deadlock can still occur.
+
+The Linux manual page for `fork(2) <https://man7.org/linux/man-pages/man2/fork.2.html>`__
+also imposes the following restriction:
+
+.. blockquote::
+
+   After a ``fork()``  in a multithreaded program, the child can
+   safely call only async-signal-safe functions (see
+   `signal-safety(7) <https://man7.org/linux/man-pages/man7/signal-safety.7.html>`__)
+   until such time as it calls
+   `execve(2) <https://man7.org/linux/man-pages/man2/execve.2.html>`__.
+
+Because {+driver-short+} relies on functions that are *not*
+async-signal-safe, it can cause deadlocks or crashes when running in a child
+process.
+
+.. tip::
+   
+   For an example of a deadlock in a child process, see
+   `PYTHON-3406 <https://jira.mongodb.org/browse/PYTHON-3406>`__ in Jira.
+   
+   For more information about the problems caused by Python locks in
+   multithreaded contexts with ``fork()``, see `Issue 6721 <http://bugs.python.org/issue6721>`__
+   in the Python Issue Tracker.
+
 API Documentation
 -----------------