Connection Configuration Specifications
Baixar
Modo Foco
Tamanho da Fonte
Scenario Description
Once the database connection topology (network routing) is established, connection pool configuration and security safeguards at the application code level directly determine system stability and the security of your data assets. In daily development and troubleshooting, teams frequently encounter the following high-risk scenarios caused by misconfiguration:
Connection Limit Exceeded Risk: In a microservices architecture, frequent use of short-lived connections or a maxPoolSize set too high across multiple application instances can cause the total number of concurrent connections to exceed the database's connection limit. This causes new requests to queue or time out, affecting overall system availability.
Inappropriate Read/Write Policy Matching: Read/write separation must align with your business scenario. Reading from a secondary node during core transactions can lead to data inconsistency due to replication lag between the primary and secondary nodes. Conversely, if read/write separation is not configured for high-frequency analytical and reporting queries, the performance load on the primary node will increase significantly.
Data Security and Compliance Risks: During development or testing, some services may enable public network access for the database without configuring strong authentication passwords. Such configurations — lacking network boundary controls and least-privilege isolation — fail to meet security and compliance requirements and significantly increase the risk of data leakage, malicious tampering, and ransomware attacks.
Connection Specification Overview
Specification No. | Specification Name | Core Requirement | Applicable Scope | Constraint Level |
Specification 1 | Correctly configure core connection string parameters | You must use a high-availability connection address. You must include `authSource=admin`. You must specify `replicaSet` for the replica set. Enable `retryWrites` and `retryReads`. | Replica set / Sharded cluster |  |
Specification 2 | Use connection pools (long connections) | Avoid using short connections in production environments. Use connection pools to reuse connections. | Replica set / Sharded cluster |  |
Specification 3 | Properly configuring connection pool parameters | Calculate `maxPoolSize` based on business concurrency. Keep the total number of connections below 80% of the instance limit. | Replica set / Sharded cluster |  |
Specification 4 | Selecting read preference based on business scenarios | For core strong-consistency services, read from the Primary. For non-sensitive services, read from a Secondary. For read/write splitting, `secondaryPreferred` is recommended. | Replica set / Sharded cluster |  |
Specification 5 | Do not disable authentication or arbitrarily expose to the public network in the production environment. | Enable authentication and restrict access to the private network only. Access from the public network must go through a CLB with security group and IP address restrictions configured. | Replica set / Sharded cluster |  |
Specification 1: Configuring Core Connection String Parameters
The configuration of the connection string (URI) parameters directly determines the availability of the database. You must adhere to the following four core principles:
1. Access address: Single-point connections are strictly prohibited.
Instruction: The connection string must contain all available nodes within the cluster (Seed List).
Reason: To avoid a single point of failure. Pointing to a single node only prevents the driver from automatically discovering the new Primary during a node switchover, resulting in a loss of high availability.
2. Authentication parameters: Specify `authSource`.
Instruction: Explicitly specify the authentication database parameter.
Users created through the console: `authSource=admin` is configured by default.
Users created through the command line: Configure them to the logical database to which they belong.
Reason: To ensure accurate authentication logic and avoid connection authentication failures caused by inconsistent default databases.
3. Architecture awareness: You must include `replicaSet`.
Instruction: The replica set connection string must include `replicaSet=<replica-set-name>`.
Reason: Only by explicitly specifying this parameter can the driver automatically redirect traffic to the new primary node during a failure, achieving seamless switchover.
4. Disaster recovery enhancement: Enable automatic retries (recommended).
Instruction: Append the parameters `retryWrites=true` and `retryReads=true`.
Reason: To improve network fault tolerance. During transient network jitter or master-slave elections, the driver layer automatically initiates retries to minimize the impact of failures.
Key Connection String Parameters
Parameter | Required or Not | Description | Example Value |
`authSource` | Yes | The authentication database. Tencent Cloud uniformly sets it to admin. | `admin` |
`replicaSet` | Required for replica set | Obtain the replica set name from the console. | `cmgo-xxxxxxxx` |
`readPreference` | Recommendation | Read preference setting | `secondaryPreferred` |
`maxPoolSize` | Recommendation | Maximum number of connections in the connection pool. | `150` |
`retryWrites` | Recommendation | Automatic write retry | `true` |
`retryReads` | Recommendation | Automatic read retry | `true` |
`w` | Required for core business | Write acknowledgment level | `majority` |
Business Applications
A financial system runs on a replica set architecture (1 primary + 2 secondaries), but the connection string does not specify the replicaSet parameter. Without this parameter, the MongoDB driver treats the connection as standalone mode and connects directly to the single node specified in the connection string, with no awareness of the overall replica set topology.
No exceptions occurred during normal operation. However, during a scheduled maintenance operation, a primary failover took place on the primary node. The original primary was demoted to a secondary, and another secondary was elected as the new primary. At this point, the driver continued sending write requests to the original node (now demoted to a secondary). Since secondary nodes reject write operations by default, a large number of not master errors appeared on the application side, and write failures persisted for approximately 15 minutes.
The operations team manually restarted the application and updated the connection address to restore service. After adding the replicaSet=cmgo-xxxxxxxx parameter to the connection string, the driver runs in replica set mode, automatically detects topology changes, and routes write requests to the new primary within seconds of a failover. This eliminates the need to restart applications or modify connection addresses, enabling automatic failure recovery.
Specification 2: Using Connection Pools (Long Connections)
For production environments, use connection pools (persistent connections) and avoid short-lived connection mode.
In short-lived connection mode, each database request must go through the full sequence of TCP three-way handshake, TLS negotiation (if encryption is enabled), and SCRAM authentication. Establishing a single connection typically takes 10–50 ms.
In high-concurrency scenarios, frequent connection creation and destruction not only significantly increase request latency but also quickly exhaust the instance's connection limit, causing subsequent requests to fail due to timeouts when connections cannot be obtained.
Connection pools pre-establish connections and reuse them across multiple requests, eliminating the overhead of repeated handshakes and authentication. This allows the application to maintain a stable, predictable number of connections under high concurrency, with response latency at the millisecond level.
Short Connections vs. Long Connections
Dimension | Short-lived connection | Long-lived Connection (Connection Pool) |
Connection establishment | Create a new connection for each request | Reusing established connections |
Authentication overhead | Authentication is required for each request (10-50ms). | Authentication only on the first connection |
Number of connections | Increases linearly with QPS | Stable and controllable |
Applicable Scenario | Not suitable for production environments | All production environments |
Business Applications
An e-commerce platform initially used PHP's short-lived connection mode, where every database request established a new connection that was immediately destroyed after the request completed. The system ran normally under daily traffic (around 1,000 QPS). However, during a major promotional event, the QPS surged from 1,000 to 10,000. Because each request required a dedicated connection, the rate of connection establishment could not keep up with the rate of incoming requests. The number of connections to the MongoDB instance soared from 200 to 3,000 (the instance's default limit) within minutes. As a result, all new requests timed out while queuing for connections. The average API response time deteriorated from 50 ms to over 5 seconds, causing a large number of order submission failures.
After switching to a connection pool (maxPoolSize=200), the application pre-established a batch of connections at startup and reused them across requests, eliminating the overhead of repeated handshakes and authentication. Even when the QPS reached 50,000 during the following year's promotional event, the actual number of connections remained stable below 500, and the API response time consistently stayed at the millisecond level.
Note:
For architectures such as Serverless and PHP-FPM that cannot maintain persistent connection pools in application memory, it is recommended to introduce a middleware proxy (Proxy) between the business layer and the database to implement connection pooling.
Specification 3: Configuring Connection Pool Parameters
The connection pool size (maxPoolSize) is not always better when larger. If the connection pool size is configured too high, the number of global connections can be instantly saturated, causing new requests to be rejected by the database. If the connection pool size is configured too low, local queuing occurs during peak business hours, unnecessarily increasing request latency. To correctly configure the connection pool, you must comprehensively consider the time consumption of a single request, the scaling boundaries of application instances, and the network access topology.
Calculating Connections for Different Connection Methods
The theoretical total number of connections across all applications must not exceed 80% of the MongoDB instance's connection limit, leaving headroom for sudden business growth or reconnections after a primary failover. For sharded clusters, the driver's connection pool establishment logic exhibits a "multiplier amplification effect" due to how the cluster is accessed. Before performing calculations, clarify the following three key variables:
A (Application): The total number of business applications currently deployed.
P (Pool Size): The maxPoolSize value configured for a single application.
M (Mongos): The total number of Mongos nodes, which is resolved through SRV or specified in the connection string.
Connection Access Method | Driver Connection Behavior | Theoretical Total Connection Count Formula |
LB CLB (private network VIP, and so on) | The driver treats the LB as a single node, establishes only one connection pool with the LB, and the LB distributes requests at the underlying layer. | A x P |
SRV record connection | The driver automatically parses the SRV record and establishes an independent connection pool for each Mongos node behind the cluster. | A x P x M |
Direct connection to all Mongos | The driver establishes an independent connection pool for each Mongos node explicitly configured in the connection string (URI). | A x P x M |
maxPoolSize Parameter Estimation Recommendations
Most connection limit exceeded failures are caused by developers blindly using default values or incorrectly equating QPS with number of connections. Follow the steps below to deduce the appropriate maxPoolSize for a single application:
Step 1: Calculating the Base Concurrency Requirement for a Single Application
The number of concurrent connections depends on the request volume and processing speed. The formula is: Basic Requirement per Application = (Expected Peak QPS per Application × Average Database Response Time in Seconds) × 1.5 (Anti-Jitter Factor). For example, with a single-instance peak QPS of 1000 and an average query time of 0.02 seconds (20 ms), the basic concurrent requirement is 1000 × 0.02 × 1.5 = 30.
Step 2: Calculating the Final Value Based on the Topology Architecture
If the deployment is in CLB mode: you can directly use the basic requirement, meaning maxPoolSize ≈ 30.
For SRV or direct multi-Mongos mode: Because requests are automatically distributed by the driver to the connection pools of M nodes, you must proportionally reduce the pool size to prevent the global total number of connections from exceeding the limit by a multiple. That is, maxPoolSize ≈ Basic Requirement ÷ M.
Connection Pool Parameter Settings Reference
Parameter | Description | Recommended Value | Consequences of Improper Configuration |
`maxPoolSize` | Maximum Number of Connections | 50-200 | Too large: Exceeds limit; Too small: Queuing |
`minPoolSize` | Minimum Number of Connections | 5-20 | Too small: Slow cold start |
`maxIdleTimeMS` | Maximum Idle Time | 60000-300000 | Too small: Frequent re-creation |
`waitQueueTimeoutMS` | Wait Timeout | 5000-10000 | Too short: Normal requests are rejected |
`connectTimeoutMS` | Connection Timeout | 10000-30000 | Too short: Fails during network jitter |
Business Applications
A content platform deployed 20 applications, all connecting to a sharded cluster through a CLB. The maxPoolSize for each application was set to 200 (the driver's default value). The theoretical total number of connections was 20 × 200 = 4,000, which had already created a hidden risk of exceeding the MongoDB instance's connection limit (3,000).
During daily off-peak hours, the connection pool was not fully utilized and operated normally due to low actual concurrency. However, during a business scale-out, five new applications were added. When all 25 applications started simultaneously and initialized their connection pools, the number of connections instantly approached 5,000, triggering the instance's connection limit protection. As a result, the five newly started applications all reported
connection pool exhausted errors and failed to connect to the database, leaving the newly launched feature modules completely unavailable.After troubleshooting, the team adjusted
maxPoolSize from 200 to 100. This reduced the theoretical total to 25 × 100 = 2,500 connections — 83% of the instance's connection limit — while reserving capacity for future scaling to 30 applications. At the same time, minPoolSize=10 was set to ensure sufficient warm connections during cold starts, resolving the connection avalanche issue during scaling.Specification 4: Selecting Read Preference Based on Business Scenarios
The readPreference setting determines which node the MongoDB driver routes read requests to. Different business scenarios have different consistency requirements: core transactions such as transfers and order placement require the most up-to-date data and must read from the primary node. In contrast, latency-tolerant scenarios such as analytical reporting and historical queries can read from secondary nodes to offload traffic from the primary. An inappropriate choice leads to two common issues:Routing strongly consistent reads to a secondary node can cause the application to read stale data, triggering logical errors. Concentrating all reads on the primary node leaves secondary node resources idle and turns the primary into a bottleneck under high concurrency.
Read Preference Selection Decision Table
Note:
When read/write separation is required for your business, using
secondaryPreferred is recommended for higher availability. If a business only accesses read-only nodes, configure two or more read-only nodes to achieve load balancing for read requests. The connection string for read-only nodes can be directly obtained from the network configuration on the instance details page.Read Preference | Consistency | Use Cases |
`primary` | Strong consistency | Check balance after transfer, check order status after placing an order |
`primaryPreferred` | Strong consistency preferred | For general services, read operations fall back to a Secondary when the Primary is unavailable. |
`secondary` | Eventual consistency | Read-only scenarios, report queries, data analysis |
`secondaryPreferred` | Eventual consistency preferred | Read-intensive scenarios, offloading Primary pressure (Recommended) |
`nearest` | Node-dependent | Geographically distributed deployment, accessing the nearest node |
Business Applications
In a bank's core system, the account balance query API was configured with
readPreference=secondary. After a user completed a transfer (written to the primary node) and immediately queried the balance, the data on the secondary node had not yet been updated due to a 10–100 ms replication lag. As a result, the API returned the pre-transfer balance. Seeing that the transfer succeeded but the balance remained unchanged, users frequently initiated duplicate transfers or contacted customer service to complain. After the API was changed to readPreference=primary, balance queries were served directly from the primary node, ensuring that the accurate balance was returned immediately after a transfer, and customer complaints dropped significantly. For non-real-time operations such as historical bill queries and monthly report exports, readPreference=secondaryPreferred was retained. This routed approximately 60% of the read traffic to secondary nodes, reducing the primary node's CPU utilization from 85% to 50% and improving both read and write latency.Note:
When secondary or secondaryPreferred is enabled, your business logic must be designed to tolerate the risk of Stale Reads due to replication latency.
Specification 5: Disabling Authentication or Exposing to the Public Network Is Prohibited in Production Environments
For MongoDB instances in a production environment, you must enable authentication and allow access only via a private network (VPC). An instance with authentication not enabled is equivalent to granting full read/write permissions to any client that can access its IP address. Once discovered by scanning, it faces the risk of data leakage or being held for ransom through database deletion. If your business genuinely requires public network access, you must configure the public network access service through CLB and simultaneously meet the following conditions: configure security groups for both the CLB and the MongoDB instance, allowing only specified client public IP addresses; enable SSL/TLS encryption to prevent data interception during transmission over the public network; use a strong password (12 characters or more, containing uppercase and lowercase letters, numbers, and special characters) to reduce the risk of brute-force attacks.
Security Configuration Requirements
1. Network boundary isolation (VPC and security groups): Access is restricted to the private network by default. Public network access must undergo strict network boundary control.
Default private network direct connection: In a production environment, you must restrict access to private network access only via application servers within the same VPC.
Compliant public network access architecture: If your business (such as cross-region debugging or external data direct connection) genuinely requires public network access, you must not directly bind a public IP address to the instance. You must establish the public network access path through CLB and enforce two-layer security group control:
CLB security group: Only allow the public IP addresses of specific clients (such as the company's egress IP) and the listener port, implementing the first layer of interception.
MongoDB security group: Only allow the specified client public IP addresses and port 27017. You must also allow the VIP address of the CLB instance to ensure the CLB node's health checks on the backend database function properly.
2. Access authentication and least privilege authorization: Disable password-free login and strictly separate application accounts from administrative accounts.
Mandatory authentication enforcement: Authentication must be enabled for the instance.
Strong password validation: Database passwords must be longer than 12 characters and contain uppercase and lowercase letters, numbers, and special characters. Avoid using weak passwords such as admin123 or root to prevent brute-force attacks.
Adhere to the principle of Least Privilege: Do not allow business applications to directly connect to the database using the root account or super accounts with the dbAdminAnyDatabase privilege. You must create a dedicated database account for each specific business module and grant it only the readWrite permission for the corresponding business database.
3. Transport layer encryption (TLS/SSL): All transmissions involving public network links must be encrypted.
Preventing packet capture and man-in-the-middle attacks: Once the public network access link is enabled, you must enable the SSL/TLS encrypted transmission feature in the console. Additionally, explicitly append tls=true to the application-side connection string to ensure that data is not intercepted in plaintext or tampered with during transmission over the untrusted public network.
Security Configuration Self-Check List
Check Dimension | Check Item | Compliance Standard |
Network Layer | Public Network Exposure Surface | Access is allowed only via a private network; public network access must be proxied through CLB and configured with an allowlist. |
Network Layer | Security group policy | Do not configure the 0.0.0.0/0 allow-all rule. Only allow access from specified source IPs. |
Authentication Layer | Identity authentication | Enable the authentication feature. |
Authentication Layer | Password complexity | The length must be at least 12 characters, containing uppercase letters, lowercase letters, digits, and special symbols. |
Authorization Layer | Principle of Least Privilege | Application accounts have only read and write permissions on the target database, and no administrative permissions. |
Transport Layer | SSL/TLS encryption | Enable SSL/TLS when public network access is enabled. |
Application layer | Secure storage of credentials | Do not hardcode database account passwords in the code. Use environment variables or the KMS service instead. |
Documentation
Ajuda e Suporte
Esta página foi útil?
Você também pode entrar em contato com a Equipe de vendas ou Enviar um tíquete em caso de ajuda.
comentários