MongoDB C++ Driver  mongocxx-3.10.2
Public Member Functions | List of all members
mongocxx::v_noabi::client Class Reference

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.
 
clientoperator= (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...
 

Detailed Description

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:

mongocxx::v_noabi::client mongo_client{mongocxx::v_noabi::uri{"mongodb://localhost:27017"}};
Class representing a client connection to MongoDB.
Definition: client.hpp:61
Class representing a MongoDB connection string URI.
Definition: uri.hpp:47

Note that client is not thread-safe. See https://mongocxx.org/mongocxx-v3/thread-safety/ for more details.

Constructor & Destructor Documentation

◆ client() [1/2]

mongocxx::v_noabi::client::client ( )
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.

◆ client() [2/2]

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.

Parameters
mongodb_uriA MongoDB URI representing the connection parameters
optionsAdditional options that cannot be specified via the mongodb_uri
Exceptions
mongocxx::v_noabi::exceptionif invalid options are provided (whether from the URI or provided client options).

Member Function Documentation

◆ database()

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.

Note
A database cannot be obtained from a temporary client object.
Parameters
nameThe name of the database to get
Returns
The database

◆ list_database_names() [1/2]

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.

Parameters
filterAn optional query expression to filter the returned database names.
Returns
std::vector<std::string> containing the database names.
Exceptions
mongocxx::v_noabi::operation_exceptionif the underlying 'listDatabases' command fails.
See also
https://www.mongodb.com/docs/manual/reference/command/listDatabases

◆ list_database_names() [2/2]

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.

Parameters
sessionThe mongocxx::v_noabi::client_session with which to perform the aggregation.
filterAn optional query expression to filter the returned database names.
Returns
std::vector<std::string> containing the database names.
Exceptions
mongocxx::v_noabi::operation_exceptionif the underlying 'listDatabases' command fails.
See also
https://www.mongodb.com/docs/manual/reference/command/listDatabases

◆ list_databases() [1/4]

cursor mongocxx::v_noabi::client::list_databases ( ) const

Enumerates the databases in the client.

Returns
A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.
Exceptions
mongocxx::v_noabi::operation_exceptionif the underlying 'listDatabases' command fails.
See also
https://www.mongodb.com/docs/manual/reference/command/listDatabases

◆ list_databases() [2/4]

cursor mongocxx::v_noabi::client::list_databases ( const bsoncxx::v_noabi::document::view_or_value  opts) const

Enumerates the databases in the client.

Parameters
optsOptions passed directly to the 'listDatabases' command.
Returns
A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.
Exceptions
mongocxx::v_noabi::operation_exceptionif the underlying 'listDatabases' command fails.
See also
https://www.mongodb.com/docs/manual/reference/command/listDatabases

◆ list_databases() [3/4]

cursor mongocxx::v_noabi::client::list_databases ( const client_session session) const

Enumerates the databases in the client.

Parameters
sessionThe mongocxx::v_noabi::client_session with which to perform the aggregation.
Returns
A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.
Exceptions
mongocxx::v_noabi::operation_exceptionif the underlying 'listDatabases' command fails.
See also
https://www.mongodb.com/docs/manual/reference/command/listDatabases

◆ list_databases() [4/4]

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.

Parameters
sessionThe mongocxx::v_noabi::client_session with which to perform the aggregation.
optsOptions passed directly to the 'listDatabases' command.
Returns
A mongocxx::v_noabi::cursor containing a BSON document for each database. Each document contains a name field with the database name, a sizeOnDisk field with the total size of the database file on disk in bytes, and an empty field specifying whether the database has any data.
Exceptions
mongocxx::v_noabi::operation_exceptionif the underlying 'listDatabases' command fails.
See also
https://www.mongodb.com/docs/manual/reference/command/listDatabases

◆ operator[]()

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.

Note
A database cannot be obtained from a temporary client object.
Parameters
nameThe name of the database.
Returns
Client side representation of a server side database

◆ read_concern() [1/2]

mongocxx::v_noabi::read_concern mongocxx::v_noabi::client::read_concern ( ) const

Returns the current read concern for this client.

Returns
The current read_concern

◆ read_concern() [2/2]

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.

Deprecated:
This method is deprecated. Read concerns should be set either in the URI or directly on database or collection objects.
Parameters
rcThe new read_concern
See also
https://www.mongodb.com/docs/manual/reference/read-concern/

◆ read_preference() [1/2]

mongocxx::v_noabi::read_preference mongocxx::v_noabi::client::read_preference ( ) const

Returns the current read preference for this client.

Returns
The current read_preference
See also
https://www.mongodb.com/docs/manual/core/read-preference/

◆ read_preference() [2/2]

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.

Deprecated:
This method is deprecated. Read preferences should be set either in the URI or directly on database or collection objects.
Parameters
rpThe new read_preference
See also
https://www.mongodb.com/docs/manual/core/read-preference/

◆ reset()

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.

◆ start_session()

client_session mongocxx::v_noabi::client::start_session ( const options::client_session options = {})

Create a client session for a sequence of operations.

Returns
A client_session object. See mongocxx::v_noabi::client_session for more information.
Exceptions
mongocxx::v_noabi::operation_exceptionif 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.

◆ uri()

mongocxx::v_noabi::uri mongocxx::v_noabi::client::uri ( ) const

Returns the current uri for this client.

Returns
The uri that this client was created with.

◆ watch() [1/4]

change_stream mongocxx::v_noabi::client::watch ( const client_session session,
const options::change_stream options = {} 
)
Parameters
sessionThe mongocxx::v_noabi::client_session with which to perform the watch operation.
optionsThe options to use when creating the change stream.
Returns
A change stream on this client.
See also
https://www.mongodb.com/docs/manual/changeStreams/

◆ watch() [2/4]

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.

Parameters
sessionThe mongocxx::v_noabi::client_session with which to perform the watch operation.
pipeThe aggregation pipeline to be used on the change notifications.
optionsThe options to use when creating the change stream.
Returns
A change stream on this client.
See also
https://www.mongodb.com/docs/manual/changeStreams/

◆ watch() [3/4]

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.

Parameters
optionsThe options to use when creating the change stream.
Returns
A change stream on this client.
See also
https://www.mongodb.com/docs/manual/changeStreams/

◆ watch() [4/4]

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.

Parameters
pipeThe 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.
optionsThe options to use when creating the change stream.
Returns
A change stream on this client.
See also
https://www.mongodb.com/docs/manual/changeStreams/

◆ write_concern() [1/2]

mongocxx::v_noabi::write_concern mongocxx::v_noabi::client::write_concern ( ) const

Returns the current write concern for this client.

Returns
the current write_concern

◆ write_concern() [2/2]

void mongocxx::v_noabi::client::write_concern ( mongocxx::v_noabi::write_concern  wc)

Sets the write concern for this client.

Note
Modifications at this level do not affect existing databases or collection instances that have come from this client but do affect new ones as databases will receive a copy of this client's write_concern upon instantiation.
Deprecated:
This method is deprecated. Write concerns should be set either in the URI or directly on database or collection objects.
Parameters
wcThe new write concern

The documentation for this class was generated from the following file: