From 8c7e3afa933e924fff3943e35a5c8729d413a5e8 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Mon, 11 Nov 2024 09:56:56 -0500 Subject: [PATCH 1/3] PHPLIB-1278: FAQ entry on connection persistence --- source/faq.txt | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/source/faq.txt b/source/faq.txt index 5e333636..13455a6e 100644 --- a/source/faq.txt +++ b/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 `. When a :phpclass:`MongoDB\Client` is +constructed, the |php-library| creates a +:php:`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 `. + +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 + + 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 ------------------------- From edc759aef83d8a5d71a20bc92a69cb030a582c06 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Mon, 11 Nov 2024 10:09:53 -0500 Subject: [PATCH 2/3] Address vale lint checks on word usage --- source/faq.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 13455a6e..b9f7b3be 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -118,30 +118,30 @@ worker process. This process is described in more detail in the 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 +PHP driver can 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 +Persistent libmongoc clients are not freed 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. +- PHP-FPM is configured with ``pm.max_requests=0`` (workers never respawn) and a + PHP application is deployed many times with small changes to its MongoDB + connection string 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. +allows the application to relinquish any unused libmongoc clients and still use +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 +create a new libmongoc client and ensure it is freed when the corresponding ``MongoDB\Driver\Manager`` goes out of scope. .. code-block:: php @@ -154,9 +154,9 @@ create a new libmongoc client and ensure it is destroyed when the corresponding 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. +Use the ``disableClientPersistence`` driver option sparingly, as opting out of +client persistence will require more time to establish connections to the +MongoDB deployment and discover its topology. Server Selection Failures From da7b1e4bf9a95b118fbff9bc0b340f7a7f46959d Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 11 Nov 2024 11:50:20 -0500 Subject: [PATCH 3/3] Docs edits --- source/faq.txt | 70 +++++++++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 32 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index b9f7b3be..a1e6a655 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -101,50 +101,56 @@ 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 `. When a :phpclass:`MongoDB\Client` is -constructed, the |php-library| creates a -:php:`MongoDB\Driver\Manager ` using the +Connections to the MongoDB deployment are handled by the ``libmongoc`` +library and the :php:`{+extension-short+} `. When you construct +a :phpclass:`MongoDB\Client` instance, the {+library-short+} creates a +:php:`MongoDB\Driver\Manager ` instance by 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 `. - -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 can avoid the overhead of establishing new connections and +arguments to derive a hash key for persistent ``libmongoc`` clients. If +you previously persisted a ``libmongoc`` client by using a key, it is +reused. Otherwise, a new ``libmongoc`` client is created and persisted +for the lifetime of the PHP worker process. You can learn more about +this process in the :php:`{+extension-short+} documentation +`. + +Each ``libmongoc`` client maintains its own connections to the MongoDB deployment +and a view of its topology. When you reuse a persistent ``libmongoc`` client, the +{+library-short+} can avoid the overhead of establishing new connections and rediscovering the topology. This approach generally improves performance and is -therefore the driver's default behavior. +the driver's default behavior. -Persistent libmongoc clients are not freed 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 +Persistent ``libmongoc`` clients are not freed until the PHP worker process +ends. This means that connections to a MongoDB deployment might remain open +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: +it might be problematic in some situations, which are described in the +following list: -- PHP-FPM is configured with ``pm.max_requests=0`` (workers never respawn) and a +- PHP-FPM is configured with ``pm.max_requests=0``, so that workers never respawn, and a PHP application is deployed many times with small changes to its MongoDB - connection string 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. + connection string or options. This could lead to an accumulation of ``libmongoc`` + client objects in each worker process. + +- An application occasionally connects to a separate MongoDB deployment in a + backend component where request latency is not the most important aspect. In the first case, restarting PHP-FPM as part of the application deployment -allows the application to relinquish any unused libmongoc clients and still use +allows the application to release any unused ``libmongoc`` clients and still use 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 freed when the corresponding +The second case requires a different solution. Specifying ``true`` for the +``disableClientPersistence`` driver option instructs the {+library-short+} to +create a new ``libmongoc`` client and ensure it is freed when the corresponding ``MongoDB\Driver\Manager`` goes out of scope. +The following code demonstrates how to set the +``disableClientPersistence`` option to ``true`` when creating a client: + .. code-block:: php + :emphasize-lines: 6 true], ); -Use the ``disableClientPersistence`` driver option sparingly, as opting out of -client persistence will require more time to establish connections to the -MongoDB deployment and discover its topology. - +Use the ``disableClientPersistence`` driver option after careful +consideration, because opting out of client persistence requires more +time to establish connections to the MongoDB deployment and discover its +topology. Server Selection Failures -------------------------