DOCSEARCHbyAlgolia
Submit Docs

MongoDB C++ Driver

repository·master·Indexed 22 days ago

https://github.com/mongodb/mongo-cxx-driver

A native interface for C++ applications to interact with MongoDB databases, supporting high-performance data operations. The driver includes the mongocxx and bsoncxx libraries, providing tools for BSON document and array manipulation, as well as a suite of microbenchmarks and project-based examples for integration via CMake or Docker.

Tokens
32.5K
Snippets
119
Records
168
Agent score
78%

What's inside mongo-cxx-driver

  2. Check MongoDB C++ Driver development status and stability

    master

    Before using the driver in production, check its development status and stability.

    • master: Active development. Do not use in production!
    • Ready for Use: Versions marked as 'Ready for Use' are suitable for production.
    • Bug Fixes Only: The current major version (e.g., 4.4.1) typically receives bug fixes for a period of one year after a new major version is released.
    • Not Supported: Older versions that are no longer receiving active updates.

    Always verify the Soversion if your deployment environment requires specific shared object versioning.

    | Version     | Soversion       | Development Stability       | Development Status |
| :---------: | :-------------: | :-------------------------: | :----------------: |
| master      | N/A             | _Do not use in production!_ | Active |
| 4.4.1       | 1               | Ready for Use               | Bug Fixes Only |
| 4.4.0       | 1               | Ready for Use               | Not Supported |
| 4.3.1       | None            | Ready for Use               | Not Supported |
| 4.0.0       | None            | Ready for Use               | Not Supported |

  3. Understand MongoDB C++ Driver development status and versioning

    master

    The driver follows Semantic Versioning. When choosing a version, consider the development status:

    • master: Active development. Do not use in production!
    • Stable versions (e.g., 4.4.x): Ready for use. Versions marked as 'Bug Fixes Only' are the most reliable for production.
    • Legacy versions: Versions marked as 'Not Supported' are still 'Ready for Use' but do not receive new updates.

    Note on Bug Fixes: Relevant bug fixes are backported from the current major version to the previous major version for one year after a new major version is released.

  4. Benchmarking best practices and limitations

    master

    When using the microbenchmarks suite, keep the following in mind:

    • Comparison Accuracy: To compare performance against other drivers, use an inMemory mongod instance.
    • BSON Decoding: bson_decoding is currently not included in the suite because extended_bson has not yet been added to the C++ driver.
    • BSONBench Implementation: BSONBench tests are implemented to mirror the C driver's interpretation of the specification.

  5. How ABI namespaces and root namespace redeclarations work

    master

    The driver uses namespaces to manage Application Binary Interface (ABI) compatibility:

    1. ABI Namespaces: Symbols are declared within specific namespaces like mongocxx::v_noabi (unstable) or mongocxx::v1 (stable).
    2. Root Namespace Redeclarations: The library redeclares these entities in the root namespace (e.g., mongocxx::document::view) so users can opt-into the latest supported ABI version automatically without changing code.

    Best Practices for Developers:

    • To use the default (latest) version: Use the root namespace (e.g., mongocxx::example::type).
    • To pin to a specific version: Use the explicit ABI namespace (e.g., mongocxx::v1::example::type).
    • When writing library code: Inside an ABI namespace, always use (un)qualified references to avoid being affected by root namespace changes.

    Incorrect Pattern (Avoid):

    namespace mongocxx::v_noabi::example {
  // If mongocxx::example::type changes from v_noabi to v1, 
  // this parameter incorrectly changes type too.
  void fn(mongocxx::example::type param);
}

    Correct Pattern:

    namespace mongocxx::v_noabi::example {
  // Always resolves to the specific version intended.
  void fn(v_noabi::example::type param);
}

  6. Understand the relationship between bsoncxx and mongocxx

    master
    The MongoDB C++ Driver is composed of two primary libraries: bsoncxx (for BSON manipulation) and mongocxx (for MongoDB server interaction). These libraries share a similar architectural structure and coding patterns. When reviewing documentation or guidelines, descriptions intended for bsoncxx generally apply to mongocxx as well, unless explicitly stated otherwise.

  8. Use forward headers for optimized includes

    master

    The driver provides forward headers with the -fwd suffix (e.g., value-fwd.hpp) and a special fwd.hpp in each ABI subdirectory. These headers declare class types and enumerations without defining them, which helps reduce compilation dependencies.

    • fwd.hpp: Provides all forward declarations for a specific ABI namespace.
    • <name>-fwd.hpp: Provides forward declarations for a specific component.

    When using the driver, prefer including the forward header when you only need to declare a pointer or reference to a type.

  9. Avoid recreating or using a destroyed mongocxx::instance

    master
    The mongocxx::instance is designed to be a singleton-like lifecycle manager. You should not attempt to recreate an instance once one has been destroyed, nor should you attempt to use any driver objects (like mongocxx::client) after the mongocxx::instance has gone out of scope or been destroyed. Doing so will result in undefined behavior or errors.

  10. Configure Constructor Implicit/Explicit Behavior

    master

    The driver follows a strict policy regarding implicit conversions to prevent ambiguous overloads:

    • Default to explicit: Any single-argument constructor or User-Defined Conversion Function (UDCF) should be marked explicit by default.
    • When to use implicit: You may only use implicit conversions sparingly if:
      • The target type is a non-owning, read-only "view" of an owning type (e.g., std::string to std::string_view).
      • The target is an owning type representing a conceptual value of the source (e.g., T to std::optional<T>).
      • The target is unambiguously preferable in an overload set.
      • The conversion has a wide contract (no preconditions) and cannot fail (no exceptions/undefined behavior).

  11. Implement Error Codes using errc and error_category

    master

    To maintain consistency with the driver's error handling pattern, follow these rules for declaring error codes:

    • Class-specific errors: If error codes are specific to a class, declare an errc enumeration as a nested enum inside that class. Implement a static error_category() member function within that same class.
    • Namespace-level errors: If error codes belong to a namespace (e.g., in exception.hpp), declare the errc enumeration at the namespace scope and implement error_category() as a free function.

  12. Understand the MongoDB C++ Driver directory structure

    master

    The bsoncxx and mongocxx libraries are organized into three main functional directories: include/, lib/, and test/.

    • include/<library>/: Contains public headers installed to the prefix.
      • Headers under v<N> (stable ABI) must not include headers from v_noabi (unstable ABI) or older v<N> versions.
      • Headers under v_noabi are placed under an extra <library>/ subdirectory (e.g., include/bsoncxx/v_noabi/bsoncxx/...) to support direct include styles like #include <bsoncxx/document/element.hpp>.
    • lib/<library>/: Contains internal headers and implementation files.
      • private/ contains internal interfaces reusable across ABI components without affecting the ABI.
      • lib/v<abi>/... mirrors the layout of the include directory.
    • test/<library>/: Contains test files that mirror the lib/ layout and can use any ABI component.