Understanding Amazon DocumentDB Connection Counts: Replica Set vs. Direct Connection
Why are there so many connections to my Amazon DocumentDB instances?
I often find myself helping customers understand why they have so many connections to each instance in their DocumentDB clusters. This content is specifically intended to help with the math and concepts. I'll create a follow up on how connection string parameters can be tuned to optimize resource usage and improve performance.
When building applications on DocumentDB, the way you configure your connection string has a significant impact on how many database connections your application creates. This article explains the difference between connecting in replica set mode (using
replicaSet=rs0) and connecting with a direct connection (using directConnection=true), and how each approach affects the total number of connections consumed in your cluster.How MongoDB-Compatible Drivers Manage Connections
MongoDB-compatible drivers maintain a connection pool per server in the discovered topology. This is a critical detail: the pool is not per cluster, it is per individual instance. On MongoDB each
MongoClient instance also opens up to 2 additional connections per server to track the health and state of each member and the round trip time (RTT) whereas in DocumentDB there is only 1 additional connection per server for health, state, and RTT.Replica Set Mode (replicaSet=rs0)
When you connect to DocumentDB using replica set mode:
1
mongodb://<user>:<password>@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?replicaSet=rs0&readPreference=secondaryPreferredThe driver performs topology discovery. It contacts the seed endpoint as provided, learns about all members of the replica set (the primary and all replicas), and creates a separate connection pool for each discovered instance. Worth noting is the the seed endpoint is only used for initial discovery, the same number of connection pools and connections will result from any usable endpoint.
Connection math
For a 3-instance cluster (1 primary + 2 replicas) with default settings:
| Component | Calculation | Connections |
|---|---|---|
| Application connection pools | maxPoolSize (100) × 3 instances | Up to 300 |
| Monitoring connections | 1 × 3 instances | 3 |
| Total per MongoClient | Up to 303 |
If you have 4 application servers, each running a singleton MongoClient:
- Outgoing from each app server: up to 303 connections
- Incoming to each DocumentDB instance: up to 100 (pool) × 4 (app servers) + 1 × 4 (monitoring) = 404 connections per instance
Key behaviors
- The driver discovers all cluster members automatically, including instances added later.
- Read requests can be distributed to replicas (with
secondaryPreferredorsecondaryread preference). - Write requests are routed to the primary.
- The application can leverage the full connection capacity of the entire cluster.
Direct Connection Mode (directConnection=true)
When you connect to DocumentDB in direct connection mode:
1
mongodb://<user>:<password>@mycluster.node.us-east-1.docdb.amazonaws.com:27017/?directConnection=trueThe driver bypasses topology discovery entirely. It connects only to the single host specified in the connection string and does not attempt to learn about other members.
Connection math
For the same 3-instance cluster with default settings:
| Component | Calculation | Connections |
|---|---|---|
| Application connection pool | maxPoolSize (100) × 1 instance | Up to 100 |
| Monitoring connections | 1 × 1 instance | 1 |
| Total per MongoClient | Up to 101 |
With 4 application servers:
- Outgoing from each app server: up to 101 connections
- Incoming to the single targeted instance: up to 100 × 4 + 1 × 4 = 404 connections
- Incoming to other instances: 0 connections
Key behaviors
- All traffic (reads and writes) goes to a single instance.
- Other instances sit idle—their connection capacity and compute resources are unused.
- No automatic failover awareness; if the targeted instance becomes unavailable, the application fails until the DNS record updates or the application reconnects.
Side-by-Side Comparison
| Characteristic | Replica Set Mode | Direct Connection |
|---|---|---|
| Topology discovery | Yes | No |
| Connection pools created | One per instance (N pools) | One pool (single instance) |
| Max connections per MongoClient (3-instance cluster, default maxPoolSize) | 303 | 101 |
| Connections distributed across cluster | Yes | No |
| Read scaling to replicas | Yes (with appropriate read preference) | No |
| Automatic failover awareness | Yes | No |
| Total cluster connection capacity utilized | 100% | ~33% (1 of 3 instances) |
Why This Matters for DocumentDB
DocumentDB instance types have per-instance connection limits (e.g., 3,400 for r8g.large). When you connect in direct mode, all your application connections concentrate on a single instance. This means:
- You hit connection limits sooner. With 10 application servers using maxPoolSize=100 in direct mode, you consume 1,000 connections on one instance. In replica set mode, those same connections could be spread across 3 instances (~333 each).
- You waste provisioned capacity. Replica instances that you're paying for receive zero application traffic.
- You lose resilience. Without topology awareness, your application cannot automatically route around a failed instance.
Recommendations
- Always connect in replica set mode using the cluster endpoint unless you have a specific reason not to (e.g., SSH tunnel constraints).
- Right-size
maxPoolSizebased on your application's concurrency needs. Remember that this value is multiplied by the number of instances in your cluster. - Monitor
DatabaseConnectionsper instance in Amazon CloudWatch to ensure connections are distributed evenly and you're not approaching instance limits. - Use singleton
MongoClientinstances. Creating a new client per request multiplies your connection count by the number of concurrent requests. - Factor in monitoring connections. Each
MongoClientopens 1 monitoring connection per instance regardless of pool size. With many microservices or Lambda functions, these add up. - Be intentional Don't rely on default behavior for connection type in your connection string. The default is currently direct connection mode but that can change in the future.
Conclusion
The choice between replica set emulation and direct connection isn't just about routing, it fundamentally changes how many connections your application creates and where they land. Replica set mode creates a connection pool per discovered instance (multiplying your connection footprint across the cluster), while direct connection limits the pool to a single target. For DocumentDB workloads, replica set mode is almost always the right choice as it distributes load, improves resilience, and makes full use of the cluster resources you're paying for.
Be sure to join the NoSQL Launchpad in Builder Center - that's where all of the AWS NoSQL specialists hang out, knowledge share, and post cool stuff.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article