PCSM-312 connection pool size configurable

docs/install/parameters.md

@@ -47,3 +47,90 @@
 | `PCSM_REPL_WORKER_QUEUE_SIZE` | Defines the maximum number of replication events that each replication worker thread can queue before processing. | `5000` |
 | `PCSM_REPL_BULK_OPS_SIZE` | Defines the maximum number of operations that can be grouped together into a single bulk apply batch during replication. | `5000` |
 
+
+## MongoDB connection string
+
+!!! admonition "Version added: 0.10.0"
+
+PCSM supports the MongoDB `maxPoolSize` connection string option, which controls the maximum number of connections the MongoDB Go driver can maintain in its connection pool.
+
+You can set this option in the source and/or target MongoDB connection strings using `--source` and `--target` command-line options or through the `PCSM_SOURCE_URI` and `PCSM_TARGET_URI` environment variables.
+
+### Syntax
+
+Append `maxPoolSize` as a query parameter to your connection string:
+
+Without existing query parameters:
+
+~~~text
+mongodb://host:port/?maxPoolSize=500
+~~~
+
+With existing query parameters:
+
+~~~text
+mongodb://host:port/?replicaSet=rs0&maxPoolSize=500
+~~~
+
+??? example "Example: maxPoolSize=500"
+
+    ```{.bash data-prompt="$"}
+    $ pcsm --source='mongodb://rs00:30000/?maxPoolSize=500' --target='mongodb://rs10:30100' --log-level='debug'
+    ```
+
+    Output
+    ```{.text .no-copy}
+    2026-06-24 15:16:40.691 INF Percona ClusterSync for MongoDB v0.10.0 3eb82dd 2026-06-24_09:36_UTC
+    2026-06-24 15:16:40.692 INF Config: source client compressors: [snappy zstd zlib] s=connect
+    2026-06-24 15:16:40.692 INF Config: source client maxPoolSize: 500 s=connect
+    2026-06-24 15:16:40.711 INF Connected to source cluster [Percona Server for MongoDB 8.0.16-5]: mongodb://rs00:30000
+    2026-06-24 15:16:40.711 INF Config: target client compressors: [snappy zstd zlib] s=connect
+    2026-06-24 15:16:40.711 INF Config: target client maxPoolSize: 100 (driver default) s=connect
+    2026-06-24 15:16:40.724 INF Connected to target cluster [Percona Server for MongoDB 8.0.16-5]: mongodb://rs10:30100
+    2026-06-24 15:16:40.728 INF Checking Recovery Data for "pcsm" s=recovery
+    2026-06-24 15:16:40.729 INF Recovery Data not found s=recovery
+    2026-06-24 15:16:40.729 INF Starting HTTP server at http://localhost:2242
+    ```
+
+### How maxPoolSize works
+
+| **Configuration** | **Behavior** |
+| --------------- | -------- |
+| Not set | Driver defaults to **100** connections |
+| `maxPoolSize=N` | Driver caps the pool at **N** connections |
+| `maxPoolSize=0` | Removes the limit, allowing the driver to create as many connections as needed. |
+
+
+??? example "Example: maxPoolSize not defined"
+
+    ```{.bash data-prompt="$"}
+    $ pcsm --source='mongodb://rs00:30000' --target='mongodb://rs10:30100' --log-level='debug'
+    ```
+
+    Output
+    ```{.text .no-copy}
+    2026-06-24 15:15:04.503 INF Percona ClusterSync for MongoDB v0.10.0 3eb82dd 2026-06-24_09:36_UTC
+    2026-06-24 15:15:04.504 INF Config: source client compressors: [snappy zstd zlib] s=connect
+    2026-06-24 15:15:04.504 INF Config: source client maxPoolSize: 100 (driver default) s=connect
+    2026-06-24 15:15:04.525 INF Connected to source cluster [Percona Server for MongoDB 8.0.16-5]: mongodb://rs00:30000
+    2026-06-24 15:15:04.525 INF Config: target client compressors: [snappy zstd zlib] s=connect
+    2026-06-24 15:15:04.525 INF Config: target client maxPoolSize: 100 (driver default) s=connect
+    2026-06-24 15:15:04.533 INF Connected to target cluster [Percona Server for MongoDB 8.0.16-5]: mongodb://rs10:30100
+    2026-06-24 15:15:04.546 INF Checking Recovery Data for "pcsm" s=recovery
+    2026-06-24 15:15:04.546 INF Recovery Data not found s=recovery
+    2026-06-24 15:15:04.546 INF Starting HTTP server at http://localhost:2242
+    ```
+
+### Recommendations
+
+For the best clone performance, size the connection pool to match or exceed the number of clone workers.
+
+| Cluster | Recommended `maxPoolSize`           |
+| ------- | ----------------------------------- |
+| Source  | At least `--clone-num-read-workers`   |
+| Target  | At least `--clone-num-insert-workers` |
+
+When PCSM starts, it logs the effective `maxPoolSize` for both the source and target clients.
+
+!!! note
+    `maxPoolSize` applies independently to each MongoDB server or `mongos` instance that the client connects to. It does not define a single global connection limit for the entire client.