From 10e63b745c7748e4a74891c8735d14beba1b4482 Mon Sep 17 00:00:00 2001 From: Mike Woofter Date: Fri, 26 Apr 2024 11:59:34 -0500 Subject: [PATCH 1/9] autobuilder From e1b75fa8d9b129fe94e44a55bafc70a313c06ec8 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:16:48 -0600 Subject: [PATCH 2/9] wip --- source/connect/connection-options.txt | 60 +++++++++++++++++++++++++++ source/index.txt | 21 +++++----- 2 files changed, 71 insertions(+), 10 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 7a872ee0..241def7b 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -144,6 +144,66 @@ Server Selection | **MongoClient Example**: ``server_selector = your_function`` | **Connection URI Example**: N/A +Connection Pools +~~~~~~~~~~~~~~~~ + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Setting + - Description + + * - ``connectTimeoutMS`` + - | Sets the time that {+driver-short+} waits when connecting a new + socket before timing out. + | Defaults to ``20000`` + + * - ``maxConnecting`` + - | Sets the maximum number of connections that each pool can establish concurrently. + If this limit is reached, further requests wait until a connection is established + or another in-use connection is checked back into the pool. + | Defaults to ``2`` + + * - ``maxIdleTimeMS`` + - | Sets the maximum time that a connection can remain idle in the pool. + | Defaults to ``None`` (no limit) + + * - ``maxPoolSize`` + - | Sets the maximum number of concurrent connections that the pool maintains. + If the maximum pool size is reached, further requests wait until a connection + becomes available. + | Defaults to ``100`` + + * - ``minPoolSize`` + - | Sets the minimum number of concurrent connections that the pool maintains. If + the number of open connections falls below this value due to network errors, + {+driver-short+} attempts to create new connections to maintain this minimum. + | Defaults to ``0`` + + * - ``socketTimeoutMS`` + - | Sets the length of time that {+driver-short+} waits for a response from the server + before timing out. + | Defaults to ``None`` (no timeout) + + * - ``waitQueueTimeoutMS`` + - | Sets how long a thread waits for a connection to become available in the connection pool + before timing out. + | Defaults to ``None`` (no timeout) + +The following code creates a client with a maximum connection pool size of ``50`` by using the +``maxPoolSize`` parameter: + +.. code-block:: python + + client = MongoClient(host, port, maxPoolSize=50) + +The following code creates a client with the same configuration as the preceding example, +but uses a connection URI: + +.. code-block:: python + + client = MongoClient("mongodb://:/?maxPoolSize=50") Authentication ~~~~~~~~~~~~~~ diff --git a/source/index.txt b/source/index.txt index e9f192d1..8dd497cb 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,30 +12,31 @@ MongoDB {+driver-short+} Documentation .. toctree:: - Get Started + Getting Started Connect + CRUD Operations + Data Formats + Indexes + Run a Database Command + Logging Monitoring + Security + Versioning + API Documentation <{+api-root+}> + Issues & Help + Databases & Collections Write Data Read Data - Run a Database Command - Indexes Aggregation - Security - Data Formats - Logging - Monitoring Serialization Third-Party Tools - FAQ Troubleshooting What's New Upgrade Migrate from Motor Switch to PyMongo Async Previous Versions - Issues & Help Compatibility - API Documentation <{+api-root+}> Overview -------- From b2eabb313906c03b7590123193f096eea99c0a57 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:39:21 -0600 Subject: [PATCH 3/9] first draft --- config/redirects | 1 + 1 file changed, 1 insertion(+) diff --git a/config/redirects b/config/redirects index 24adc3fe..c3e8b7e9 100644 --- a/config/redirects +++ b/config/redirects @@ -12,3 +12,4 @@ raw: ${prefix}/master -> ${base}/upcoming/ raw: ${prefix}/get-started/download-and-install/ -> ${base}/current/get-started/download-and-install/ [*-master]: ${prefix}/${version}/security/enterprise-authentication/ -> ${base}/${version}/security/authentication/ +[*-master]: ${prefix}/${version}/connect/connection-pools/ -> ${base}/${version}/connect/connection-options/#connection-pools \ No newline at end of file From 235e2dea035bc3acc0181d66dd2b21673873a82a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:41:05 -0600 Subject: [PATCH 4/9] options --- source/connect/connection-options.txt | 113 ++++++++++++++++---------- source/connect/connection-pools.txt | 108 ------------------------ 2 files changed, 69 insertions(+), 152 deletions(-) delete mode 100644 source/connect/connection-pools.txt diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 241def7b..d26b918b 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -80,7 +80,7 @@ Network Compression * - Connection Option - Description - * - **compressors** + * - ``compressors`` - | The preferred compression types, in order, for wire-protocol messages sent to | or received from the server. The driver uses the first of these compression types | that the server supports. @@ -90,7 +90,7 @@ Network Compression | **MongoClient Example**: ``compressors = "snappy,zstd,zlib"`` | **Connection URI Example**: ``compressors=snappy,zstd,zlib`` - * - **zlibCompressionLevel** + * - ``zlibCompressionLevel`` - | The compression level for zlib to use. This option accepts | an integer value between ``-1`` and ``9``: | @@ -114,7 +114,7 @@ Timeouts * - Connection Option - Description - * - **timeoutMS** + * - ``timeoutMS`` - | The number of milliseconds each driver operation must complete within. If an | operation doesn't finish in the specified time, {+driver-short+} raises a timeout exception. | For more information, see :ref:``. @@ -134,7 +134,7 @@ Server Selection * - Connection Option - Description - * - **server_selector** + * - ``server_selector`` - | A user-defined Python function called by {+driver-short+} to choose the server | to run an operation against. For more information, see | :ref:``. @@ -147,6 +147,16 @@ Server Selection Connection Pools ~~~~~~~~~~~~~~~~ +A **connection pool** is a cache of open database connections maintained by {+driver-short+}. +When your application requests a connection to MongoDB, {+driver-short+} seamlessly +gets a connection from the pool, performs operations, and returns the connection +to the pool for reuse. Connection pools help reduce application latency and the number +of times new connections are created by {+driver-short+}. + +To learn more about connection pools, see +:manual:`Connection Pool Overview ` +in the {+mdb-server+} manual. + .. list-table:: :widths: 30 70 :header-rows: 1 @@ -155,55 +165,70 @@ Connection Pools - Description * - ``connectTimeoutMS`` - - | Sets the time that {+driver-short+} waits when connecting a new + - | The time that {+driver-short+} waits when connecting a new socket before timing out. - | Defaults to ``20000`` + | + | **Data Type**: ``int`` + | **Default**: ``20000`` + | **MongoClient Example**: ``connectTimeoutMS = 40000`` + | **Connection URI Example**: ``connectTimeoutMS=40000`` * - ``maxConnecting`` - - | Sets the maximum number of connections that each pool can establish concurrently. + - | The maximum number of connections that each pool can establish concurrently. If this limit is reached, further requests wait until a connection is established or another in-use connection is checked back into the pool. - | Defaults to ``2`` + | + | **Data Type**: ``int`` + | **Default**: ``2`` + | **MongoClient Example**: ``maxConnecting = 3`` + | **Connection URI Example**: ``maxConnecting=3`` * - ``maxIdleTimeMS`` - - | Sets the maximum time that a connection can remain idle in the pool. - | Defaults to ``None`` (no limit) + - | The maximum time that a connection can remain idle in the pool. + | + | **Data Type**: ``int`` + | **Default**: ``None`` (no limit) + | **MongoClient Example**: ``maxIdleTimeMS = 60000`` + | **Connection URI Example**: ``maxIdleTimeMS=60000`` * - ``maxPoolSize`` - - | Sets the maximum number of concurrent connections that the pool maintains. + - | The maximum number of concurrent connections that the pool maintains. If the maximum pool size is reached, further requests wait until a connection becomes available. - | Defaults to ``100`` + | + | **Data Type**: ``int`` + | **Default**: ``100`` + | **MongoClient Example**: ``maxPoolSize = 150`` + | **Connection URI Example**: ``maxPoolSize=150`` * - ``minPoolSize`` - - | Sets the minimum number of concurrent connections that the pool maintains. If + - | The minimum number of concurrent connections that the pool maintains. If the number of open connections falls below this value due to network errors, {+driver-short+} attempts to create new connections to maintain this minimum. - | Defaults to ``0`` + | + | **Data Type**: ``int`` + | **Default**: ``0`` + | **MongoClient Example**: ``minPoolSize = 3`` + | **Connection URI Example**: ``minPoolSize=3`` * - ``socketTimeoutMS`` - - | Sets the length of time that {+driver-short+} waits for a response from the server + - | The length of time that {+driver-short+} waits for a response from the server before timing out. - | Defaults to ``None`` (no timeout) + | + | **Data Type**: ``int`` + | **Default**: ``None`` (no timeout) + | **MongoClient Example**: ``socketTimeoutMS = 100000`` + | **Connection URI Example**: ``socketTimeoutMS=100000`` * - ``waitQueueTimeoutMS`` - - | Sets how long a thread waits for a connection to become available in the connection pool + - | How long a thread waits for a connection to become available in the connection pool before timing out. - | Defaults to ``None`` (no timeout) - -The following code creates a client with a maximum connection pool size of ``50`` by using the -``maxPoolSize`` parameter: - -.. code-block:: python - - client = MongoClient(host, port, maxPoolSize=50) - -The following code creates a client with the same configuration as the preceding example, -but uses a connection URI: - -.. code-block:: python + | + | **Data Type**: ``int`` + | **Default**: ``None`` (no timeout) + | **MongoClient Example**: ``waitQueueTimeoutMS = 100000`` + | **Connection URI Example**: ``waitQueueTimeoutMS=100000`` - client = MongoClient("mongodb://:/?maxPoolSize=50") Authentication ~~~~~~~~~~~~~~ @@ -214,7 +239,7 @@ Authentication * - Connection Option - Description - * - **authMechanism** + * - ``authMechanism`` - | The mechanism {+driver-short+} uses to authenticate the application. Valid | options are defined in `MECHANISMS. <{+api-root+}pymongo/database.html#pymongo.auth.MECHANISMS>`__ | @@ -224,7 +249,7 @@ Authentication | **MongoClient Example**: ``authMechanism = "MONGODB-X509"`` | **Connection URI Example**: ``authMechanism=MONGODB-X509`` - * - **authMechanismProperties** + * - ``authMechanismProperties`` - | Options specific to the authentication mechanism. Not needed for all authentication | mechanisms. | @@ -233,7 +258,7 @@ Authentication | **MongoClient Example**: ``authMechanismProperties = "AWS_SESSION_TOKEN:12345"`` | **Connection URI Example**: ``authMechanismProperties=AWS_SESSION_TOKEN:12435`` - * - **authSource** + * - ``authSource`` - | The database to authenticate against. | | **Data Type**: {+string-data-type+} @@ -241,7 +266,7 @@ Authentication | **MongoClient Example**: ``authSource = "admin"`` | **Connection URI Example**: ``authSource=admin`` - * - **username** + * - ``username`` - | The username for authentication. When this option is included in a connection | URI, you must percent-escape it. | @@ -250,7 +275,7 @@ Authentication | **MongoClient Example**: ``username = "my user"`` | **Connection URI Example**: ``username=my+user`` - * - **password** + * - ``password`` - | The password for authentication. When this option is included in a connection | URI, you must percent-escape it. | @@ -271,7 +296,7 @@ Read and Write Operations * - Connection Option - Description - * - **replicaSet** + * - ``replicaSet`` - | Specifies the name of the replica set to connect to. | | **Data Type**: {+string-data-type+} @@ -279,7 +304,7 @@ Read and Write Operations | **MongoClient Example**: ``replicaSet='replicaSetName'`` | **Connection URI Example**: ``replicaSet=replicaSetName`` - * - **directConnection** + * - ``directConnection`` - | Whether to connect only to the primary member of the replica set. | | **Data Type**: {+bool-data-type+} @@ -287,7 +312,7 @@ Read and Write Operations | **MongoClient Example**: ``directConnection=True`` | **Connection URI Example**: ``directConnection=true`` - * - **readPreference** + * - ``readPreference`` - | Specifies the client's read-preference settings. | | **Data Type**: `read_preferences <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences>`__ @@ -295,7 +320,7 @@ Read and Write Operations | **MongoClient Example**: ``readPreference=ReadPreference.SECONDARY_PREFERRED`` | **Connection URI Example**: ``readPreference=secondaryPreferred`` - * - **readConcern** + * - ``readConcern`` - | Specifies the client's read-concern settings. For more information, see :manual:``. | | **Data Type**: {+string-data-type+} @@ -303,7 +328,7 @@ Read and Write Operations | **MongoClient Example**: ``readConcern="majority"`` | **Connection URI Example**: ``readConcern=majority`` - * - **writeConcern** + * - ``writeConcern`` - | Specifies the client's write-concern settings. For more information, see :manual:``. | @@ -312,7 +337,7 @@ Read and Write Operations | **MongoClient Example**: ``writeConcern="majority"`` | **Connection URI Example**: ``writeConcern=majority`` - * - **localThresholdMS** + * - ``localThresholdMS`` - | The latency window for a replica-set members eligibility. If a member's round trip ping takes longer than the fastest server's round-trip ping time plus this value, the server isn't eligible for selection. @@ -322,7 +347,7 @@ Read and Write Operations | **MongoClient Example**: ``localThresholdMS=35`` | **Connection URI Example**: ``localThresholdMS=35`` - * - **retryReads** + * - ``retryReads`` - | Specifies whether the client retries supported read operations. For more information, see :manual:`Retryable Reads ` in the {+mdb-server+} manual. @@ -332,7 +357,7 @@ Read and Write Operations | **MongoClient Example**: ``retryReads=False`` | **Connection URI Example**: ``retryReads=false`` - * - **retryWrites** + * - ``retryWrites`` - | Specifies whether the client retries supported write operations. For more information, see :manual:`Retryable Writes ` in the {+mdb-server+} manual. diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt deleted file mode 100644 index 48ee9ac2..00000000 --- a/source/connect/connection-pools.txt +++ /dev/null @@ -1,108 +0,0 @@ -.. _pymongo-connection-pools: - -================ -Connection Pools -================ - -.. facet:: - :name: genre - :values: reference - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn about how {+driver-short+} uses connection pools to manage -connections to a MongoDB deployment and how you can configure connection pool settings -in your application. - -A connection pool is a cache of open database connections maintained by {+driver-short+}. -When your application requests a connection to MongoDB, {+driver-short+} seamlessly -gets a connection from the pool, performs operations, and returns the connection -to the pool for reuse. - -Connection pools help reduce application latency and the number of times new connections -are created by {+driver-short+}. - -Configuring Connection Pools ----------------------------- - -You can specify the following connection pool settings in your ``MongoClient`` object or in -your connection URI: - -.. list-table:: - :widths: 30 70 - :header-rows: 1 - - * - Setting - - Description - - * - ``connectTimeoutMS`` - - | Sets the time that {+driver-short+} waits when connecting a new - socket before timing out. - | Defaults to ``20000`` - - * - ``maxConnecting`` - - | Sets the maximum number of connections that each pool can establish concurrently. - If this limit is reached, further requests wait until a connection is established - or another in-use connection is checked back into the pool. - | Defaults to ``2`` - - * - ``maxIdleTimeMS`` - - | Sets the maximum time that a connection can remain idle in the pool. - | Defaults to ``None`` (no limit) - - * - ``maxPoolSize`` - - | Sets the maximum number of concurrent connections that the pool maintains. - If the maximum pool size is reached, further requests wait until a connection - becomes available. - | Defaults to ``100`` - - * - ``minPoolSize`` - - | Sets the minimum number of concurrent connections that the pool maintains. If - the number of open connections falls below this value due to network errors, - {+driver-short+} attempts to create new connections to maintain this minimum. - | Defaults to ``0`` - - * - ``socketTimeoutMS`` - - | Sets the length of time that {+driver-short+} waits for a response from the server - before timing out. - | Defaults to ``None`` (no timeout) - - * - ``waitQueueTimeoutMS`` - - | Sets how long a thread waits for a connection to become available in the connection pool - before timing out. - | Defaults to ``None`` (no timeout) - -The following code creates a client with a maximum connection pool size of ``50`` by using the -``maxPoolSize`` parameter: - -.. code-block:: python - - client = MongoClient(host, port, maxPoolSize=50) - -The following code creates a client with the same configuration as the preceding example, -but uses a connection URI: - -.. code-block:: python - - client = MongoClient("mongodb://:/?maxPoolSize=50") - -Additional Information ----------------------- - -To learn more about connection pools, see :manual:`Connection Pool Overview ` -in the {+mdb-server+} manual. - -API Documentation -~~~~~~~~~~~~~~~~~ - -To learn more about any of the methods or types discussed in this -guide, see the following API documentation: - -- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ \ No newline at end of file From e50683a3e22a2f52a5ad3ba70cf08388c34bcb16 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:42:31 -0600 Subject: [PATCH 5/9] reset index --- source/index.txt | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/source/index.txt b/source/index.txt index 8dd497cb..e9f192d1 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,31 +12,30 @@ MongoDB {+driver-short+} Documentation .. toctree:: - Getting Started + Get Started Connect - CRUD Operations - Data Formats - Indexes - Run a Database Command - Logging Monitoring - Security - Versioning - API Documentation <{+api-root+}> - Issues & Help - Databases & Collections Write Data Read Data + Run a Database Command + Indexes Aggregation + Security + Data Formats + Logging + Monitoring Serialization Third-Party Tools + FAQ Troubleshooting What's New Upgrade Migrate from Motor Switch to PyMongo Async Previous Versions + Issues & Help Compatibility + API Documentation <{+api-root+}> Overview -------- From e6ec3b9f1f4e976d716d479b3408f444d9e16a14 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:45:47 -0600 Subject: [PATCH 6/9] remove from index page --- source/connect.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index e140716f..b66bbd25 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,12 +25,10 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target Specify Connection Options - Configure TLS Compress Network Traffic Customize Server Selection Stable API Limit Server Execution Time - Connection Pools Overview -------- From cf5229b53adf6c7ec0da25268b6d458c141cee2d Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 10:51:52 -0600 Subject: [PATCH 7/9] fix --- source/connect.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/connect.txt b/source/connect.txt index b66bbd25..6c983b01 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,6 +25,7 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target Specify Connection Options + Configure TLS Compress Network Traffic Customize Server Selection Stable API From d8b77884c0acf32dc25fdd5448a2eb37547886ef Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 12:37:43 -0600 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> --- source/connect/connection-options.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index d26b918b..9c6e89cc 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -148,10 +148,10 @@ Connection Pools ~~~~~~~~~~~~~~~~ A **connection pool** is a cache of open database connections maintained by {+driver-short+}. -When your application requests a connection to MongoDB, {+driver-short+} seamlessly +When your application requests a connection to MongoDB, {+driver-short+} gets a connection from the pool, performs operations, and returns the connection to the pool for reuse. Connection pools help reduce application latency and the number -of times new connections are created by {+driver-short+}. +of times that {+driver-short+} must create new connections. To learn more about connection pools, see :manual:`Connection Pool Overview ` From 39b78339998a89ec3f22fa4061b536f7df5739c6 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 19 Feb 2025 12:38:03 -0600 Subject: [PATCH 9/9] change toc depth --- source/connect/connection-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 9c6e89cc..7d9fe378 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -7,7 +7,7 @@ Specify Connection Options .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol .. facet::