Overview
In this guide, you can learn how to use the C++ driver to create and configure a connection pool. A connection pool is a cache of client objects that your application can use to manage multiple concurrent MongoDB operations.
After you instantiate a mongocxx::pool, the pool creates client
objects as needed until it reaches the maximum pool size. Each thread that runs
MongoDB operations checks out a client from the pool, uses it to perform
operations, and returns the client to the pool. The pool
automatically manages the lifecycle of these clients.
Important
Unlike most MongoDB drivers, the C++ driver does not implement the MongoDB Connection Monitoring and Pooling (CMAP) specification. In this context, connection pooling refers to the driver's cache of client objects instead of database connections.
Connection Pool and Client Comparison
Connection pools offer significant performance advantages over
standalone clients. A mongocxx::pool uses separate background
monitoring threads to continuously monitor the cluster. As a result,
application threads can perform operations without waiting for topology
monitoring to complete. In contrast, a standalone mongocxx::client
periodically stops to check the cluster status, blocking all operations
during the check.
You can use a connection pool even if your application uses only one thread. The pool's background monitoring provides better performance than a standalone client's periodic checks.
The following table summarizes the main differences between mongocxx::pool and
mongocxx::client:
Feature | mongocxx::pool | mongocxx::client |
|---|---|---|
Recommended for multi-threaded applications | Yes. | No. |
Background monitoring | Yes. Pools use a separate thread for each server. | No. Clients perform periodic blocking checks. |
Monitoring interval | Every 10 seconds per server. | Every 60 seconds. |
Thread safety | Thread-safe, but acquired clients are not thread-safe. | Not thread-safe. |
Fork safety | You must create the pool after forking. | You must create the client after forking. |
Tip
Threading and Forking
To learn more about how to use clients and client objects across multiple threads and when forking processes, see the Thread and Fork Safety guide.
Create a Connection Pool
To create a connection pool, instantiate a mongocxx::pool object by passing
your connection URI to its constructor. Each thread that runs MongoDB
operations must acquire a client from the pool by calling the acquire()
member function. When the client goes out of scope, it automatically returns to the pool.
This sample file performs the following actions:
Creates a connection pool
Creates three threads that each acquire their own client from the pool
Performs an insert operation in each thread
1 2 3 4 5 6 7 8 9 10 11 using bsoncxx::builder::basic::kvp; 12 using bsoncxx::builder::basic::make_document; 13 14 int main() { 15 mongocxx::instance instance{}; 16 17 mongocxx::uri uri{"mongodb://localhost:27017"}; 18 mongocxx::pool pool{uri}; 19 20 std::vector<std::thread> threads; 21 22 // Creates multiple threads that each acquire a client from the pool 23 for (int i = 0; i < 3; ++i) { 24 threads.emplace_back([&pool, i]() { 25 auto client = pool.acquire(); 26 auto collection = (*client)["db"]["coll"]; 27 28 // Inserts a sample document 29 collection.insert_one(make_document(kvp("thread_id", i))); 30 31 std::cout << "Thread " << i << " inserted a document" << std::endl; 32 }); 33 } 34 35 // Waits for all threads to complete 36 for (auto& thread : threads) { 37 thread.join(); 38 } 39 40 std::cout << "All threads completed" << std::endl; 41 42 return 0; 43 }
Configure Connection Pool Options
You can configure connection pool behavior by including options in your connection URI. The following table describes the connection pool options you can set:
URI Option | Description |
|---|---|
| Specifies the maximum number of clients the pool can create. When this
limit is reached, the acquire() member function blocks until another thread returns a
client to the pool.Defaults to 100.Type: int |
| Specifies the minimum number of clients the pool maintains. The pool
creates this number of clients when initialized and maintains at least this
number of clients continuously. Defaults to 0.Type: int |
| Specifies the maximum time in milliseconds that the acquire() function waits for
a client to become available when the pool has reached the maxPoolSize value.
If this timeout expires, the acquire() function generates an error.Defaults to no timeout. Type: int |
Example
The following example specifies the maxPoolSize option to
create a connection pool with a maximum size of 5
clients:
mongocxx::uri uri{"mongodb://localhost:27017/?maxPoolSize=5"}; mongocxx::pool pool{uri};
API Documentation
To learn more about the types and functions discussed in this guide, see the following API documentation: