PHPLIB-1278: FAQ entry on connection persistence

Author: jmikola

source/faq.txt

@@ -101,6 +101,64 @@ for the correct environment.
 The aforementioned ``detect-extension`` script can also be used to determine the
 appropriate DLL for your PHP environment.
 
+
+Connection Handling and Persistence
+-----------------------------------
+
+Connections to the MongoDB deployment are handled entirely by libmongoc and the
+:php:`mongodb extension <mongodb>`. When a :phpclass:`MongoDB\Client` is
+constructed, the |php-library| creates a
+:php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>` using the
+same connection string and options. The extension also uses those constructor
+arguments to derive a hash key for persistent libmongoc clients. If a libmongoc
+client was previously persisted with a key, it will be reused; otherwise, a new
+libmongoc client will be created and persisted for the lifetime of the PHP
+worker process. This process is described in more detail in the
+:php:`extension documentation <manual/en/mongodb.connection-handling.php>`.
+
+Each libmongoc client maintains its own connections to the MongoDB deployment
+and a view of its topology. When a persistent libmongoc client is reused, the
+PHP driver is able to avoid the overhead of establishing new connections and
+rediscovering the topology. This approach generally improves performance and is
+therefore the driver's default behavior.
+
+Persistent libmongoc clients are not destroyed until the PHP worker process
+terminates. This means that connections to a MongoDB deployment may remain open
+long after a ``MongoDB\Driver\Manager`` object goes out of scope. While this is
+typically not an issue for applications that connect to one MongoDB deployment,
+it could be problematic in some situations. Consider the following cases:
+
+- PHP-FPM is configured with ``pm.max_requests=0`` (i.e. workers never respawn)
+  and a PHP application is deployed many times with small changes to its MongoDB
+  connection string and/or options. This could lead to an accumulation of
+  libmongoc client objects within each worker process.
+- An application occasionally connects to a separate MongoDB deployment in some
+  backend component where request latency is not paramount.
+
+In the first case, restarting PHP-FPM as part of the application deployment
+would allow the application to relinquish any unused libmongoc clients and still
+utilize a persistent client for the latest connection string.
+
+The second case warrants a different solution. Specifying ``true`` for the
+``disableClientPersistence`` driver option will instruct the PHP driver to
+create a new libmongoc client and ensure it is destroyed when the corresponding
+``MongoDB\Driver\Manager`` goes out of scope.
+
+.. code-block:: php
+
+   <?php
+
+   $client = new MongoDB\Client(
+       uri: getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/',
+       uriOptions: [],
+       driverOptions: ['disableClientPersistence' => true],
+   );
+
+The ``disableClientPersistence`` driver option should be used sparingly, as
+opting out of client persistence means that additional time will be required to
+establish connections to the MongoDB deployment and discover its topology.
+
+
 Server Selection Failures
 -------------------------