MongoDB C++ Driver
mongocxx-3.10.2
|
Class representing a client connection to MongoDB. More...
#include <client.hpp>
Public Member Functions | |
client () noexcept | |
Default constructs a new client. More... | |
client (const mongocxx::v_noabi::uri &mongodb_uri, const options::client &options=options::client()) | |
Creates a new client connection to MongoDB. More... | |
client (client &&) noexcept | |
Move constructs a client. | |
client & | operator= (client &&) noexcept |
Move assigns a client. | |
~client () | |
Destroys a client. | |
operator bool () const noexcept | |
Returns true if the client is valid, meaning it was not default constructed or moved from. | |
void | read_concern (mongocxx::v_noabi::read_concern rc) |
Sets the read concern for this client. More... | |
mongocxx::v_noabi::read_concern | read_concern () const |
Returns the current read concern for this client. More... | |
void | read_preference (mongocxx::v_noabi::read_preference rp) |
Sets the read preference for this client. More... | |
mongocxx::v_noabi::read_preference | read_preference () const |
Returns the current read preference for this client. More... | |
mongocxx::v_noabi::uri | uri () const |
Returns the current uri for this client. More... | |
void | write_concern (mongocxx::v_noabi::write_concern wc) |
Sets the write concern for this client. More... | |
mongocxx::v_noabi::write_concern | write_concern () const |
Returns the current write concern for this client. More... | |
mongocxx::v_noabi::database | database (bsoncxx::v_noabi::string::view_or_value name) const & |
Obtains a database that represents a logical grouping of collections on a MongoDB server. More... | |
mongocxx::v_noabi::database | operator[] (bsoncxx::v_noabi::string::view_or_value name) const & |
Allows the syntax client ["db_name"] as a convenient shorthand for the client::database() method by implementing the array subscript operator. More... | |
client_session | start_session (const options::client_session &options={}) |
Create a client session for a sequence of operations. More... | |
void | reset () |
Prevents resource cleanup in the child process from interfering with the parent process after forking. More... | |
cursor | list_databases () const |
Enumerates the databases in the client. More... | |
cursor | list_databases (const client_session &session) const |
Enumerates the databases in the client. More... | |
cursor | list_databases (const bsoncxx::v_noabi::document::view_or_value opts) const |
Enumerates the databases in the client. More... | |
cursor | list_databases (const client_session &session, const bsoncxx::v_noabi::document::view_or_value opts) const |
Enumerates the databases in the client. More... | |
std::vector< std::string > | list_database_names (const bsoncxx::v_noabi::document::view_or_value filter={}) const |
Queries the MongoDB server for a list of known databases. More... | |
std::vector< std::string > | list_database_names (const client_session &session, const bsoncxx::v_noabi::document::view_or_value filter={}) const |
Queries the MongoDB server for a list of known databases. More... | |
change_stream | watch (const options::change_stream &options={}) |
Gets a change stream on this client with an empty pipeline. More... | |
change_stream | watch (const client_session &session, const options::change_stream &options={}) |
change_stream | watch (const pipeline &pipe, const options::change_stream &options={}) |
Gets a change stream on this client. More... | |
change_stream | watch (const client_session &session, const pipeline &pipe, const options::change_stream &options={}) |
Gets a change stream on this client. More... | |
Class representing a client connection to MongoDB.
Acts as a logical gateway for working with databases contained within a MongoDB server.
Databases that are created via this client inherit the read_concern
, read_preference
, and write_concern
settings of this client when they are created. The lifetimes of objects created via a client object (databases, collections, cursors, etc...) must be a subset of the lifetime of the client that created them.
Example:
Note that client is not thread-safe. See https://mongocxx.org/mongocxx-v3/thread-safety/ for more details.
|
noexcept |
Default constructs a new client.
The client is not connected and is equivalent to the state of a moved-from client. The only valid actions to take with a default constructed 'client' are to assign to it, or destroy it.
mongocxx::v_noabi::client::client | ( | const mongocxx::v_noabi::uri & | mongodb_uri, |
const options::client & | options = options::client() |
||
) |
Creates a new client connection to MongoDB.
mongodb_uri | A MongoDB URI representing the connection parameters |
options | Additional options that cannot be specified via the mongodb_uri |
mongocxx::v_noabi::exception | if invalid options are provided (whether from the URI or provided client options). |
mongocxx::v_noabi::database mongocxx::v_noabi::client::database | ( | bsoncxx::v_noabi::string::view_or_value | name | ) | const & |
Obtains a database that represents a logical grouping of collections on a MongoDB server.
name | The name of the database to get |
std::vector<std::string> mongocxx::v_noabi::client::list_database_names | ( | const bsoncxx::v_noabi::document::view_or_value | filter = {} | ) | const |
Queries the MongoDB server for a list of known databases.
filter | An optional query expression to filter the returned database names. |
mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails. |
std::vector<std::string> mongocxx::v_noabi::client::list_database_names | ( | const client_session & | session, |
const bsoncxx::v_noabi::document::view_or_value | filter = {} |
||
) | const |
Queries the MongoDB server for a list of known databases.
session | The mongocxx::v_noabi::client_session with which to perform the aggregation. |
filter | An optional query expression to filter the returned database names. |
mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails. |
cursor mongocxx::v_noabi::client::list_databases | ( | ) | const |
Enumerates the databases in the client.
mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails. |
cursor mongocxx::v_noabi::client::list_databases | ( | const bsoncxx::v_noabi::document::view_or_value | opts | ) | const |
Enumerates the databases in the client.
opts | Options passed directly to the 'listDatabases' command. |
mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails. |
cursor mongocxx::v_noabi::client::list_databases | ( | const client_session & | session | ) | const |
Enumerates the databases in the client.
session | The mongocxx::v_noabi::client_session with which to perform the aggregation. |
mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails. |
cursor mongocxx::v_noabi::client::list_databases | ( | const client_session & | session, |
const bsoncxx::v_noabi::document::view_or_value | opts | ||
) | const |
Enumerates the databases in the client.
session | The mongocxx::v_noabi::client_session with which to perform the aggregation. |
opts | Options passed directly to the 'listDatabases' command. |
mongocxx::v_noabi::operation_exception | if the underlying 'listDatabases' command fails. |
mongocxx::v_noabi::database mongocxx::v_noabi::client::operator[] | ( | bsoncxx::v_noabi::string::view_or_value | name | ) | const & |
Allows the syntax client
["db_name"] as a convenient shorthand for the client::database() method by implementing the array subscript operator.
name | The name of the database. |
mongocxx::v_noabi::read_concern mongocxx::v_noabi::client::read_concern | ( | ) | const |
Returns the current read concern for this client.
read_concern
void mongocxx::v_noabi::client::read_concern | ( | mongocxx::v_noabi::read_concern | rc | ) |
Sets the read concern for this client.
Modifications at this level do not affect existing database instances that have been created by this client but do affect new ones as databases inherit the read_concern
settings of their parent upon instantiation.
rc | The new read_concern |
mongocxx::v_noabi::read_preference mongocxx::v_noabi::client::read_preference | ( | ) | const |
Returns the current read preference for this client.
read_preference
void mongocxx::v_noabi::client::read_preference | ( | mongocxx::v_noabi::read_preference | rp | ) |
Sets the read preference for this client.
Modifications at this level do not affect existing database instances that have been created by this client but do affect new ones as databases inherit the read_preference
settings of their parent upon instantiation.
rp | The new read_preference |
void mongocxx::v_noabi::client::reset | ( | ) |
Prevents resource cleanup in the child process from interfering with the parent process after forking.
Clients should not be reused after forking. Call this method in the child after forking to safely destroy the client. This method should not be used with multi-threaded clients.
This method causes the client to clear its session pool without sending endSessions. It also increments an internal generation counter on the given client. After this method is called, cursors from previous generations will not issue a killCursors command when they are destroyed. Client sessions from previous generations cannot be used and should be destroyed.
client_session mongocxx::v_noabi::client::start_session | ( | const options::client_session & | options = {} | ) |
Create a client session for a sequence of operations.
mongocxx::v_noabi::client_session
for more information.mongocxx::v_noabi::operation_exception | if the driver is not built with crypto support, if options is misconfigured, or if the session is configured with options that the server does not support. |
mongocxx::v_noabi::uri mongocxx::v_noabi::client::uri | ( | ) | const |
Returns the current uri for this client.
uri
that this client was created with. change_stream mongocxx::v_noabi::client::watch | ( | const client_session & | session, |
const options::change_stream & | options = {} |
||
) |
session | The mongocxx::v_noabi::client_session with which to perform the watch operation. |
options | The options to use when creating the change stream. |
change_stream mongocxx::v_noabi::client::watch | ( | const client_session & | session, |
const pipeline & | pipe, | ||
const options::change_stream & | options = {} |
||
) |
Gets a change stream on this client.
session | The mongocxx::v_noabi::client_session with which to perform the watch operation. |
pipe | The aggregation pipeline to be used on the change notifications. |
options | The options to use when creating the change stream. |
change_stream mongocxx::v_noabi::client::watch | ( | const options::change_stream & | options = {} | ) |
Gets a change stream on this client with an empty pipeline.
Change streams are only supported with a "majority" read concern or no read concern.
options | The options to use when creating the change stream. |
change_stream mongocxx::v_noabi::client::watch | ( | const pipeline & | pipe, |
const options::change_stream & | options = {} |
||
) |
Gets a change stream on this client.
Change streams are only supported with a "majority" read concern or no read concern.
pipe | The aggregation pipeline to be used on the change notifications. Only a subset of pipeline operations are supported for change streams. For more information see the change streams documentation. |
options | The options to use when creating the change stream. |
mongocxx::v_noabi::write_concern mongocxx::v_noabi::client::write_concern | ( | ) | const |
Returns the current write concern for this client.
write_concern
void mongocxx::v_noabi::client::write_concern | ( | mongocxx::v_noabi::write_concern | wc | ) |
Sets the write concern for this client.
write_concern
upon instantiation.wc | The new write concern |