mongocxx::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 class 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.
MONGOCXX_DEPRECATED void	read_concern (class read_concern rc)
	Sets the read concern for this client. More...
class read_concern	read_concern () const
	Returns the current read concern for this client. More...
MONGOCXX_DEPRECATED void	read_preference (class read_preference rp)
	Sets the read preference for this client. More...
class read_preference	read_preference () const
	Returns the current read preference for this client. More...
class uri	uri () const
	Returns the current uri for this client. More...
MONGOCXX_DEPRECATED void	write_concern (class write_concern wc)
	Sets the write concern for this client. More...
class write_concern	write_concern () const
	Returns the current write concern for this client. More...
class database	database (bsoncxx::string::view_or_value name) const &
	Obtains a database that represents a logical grouping of collections on a MongoDB server. More...
class database	operator[] (bsoncxx::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...
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...

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::client mongo_client{mongocxx::uri{}};
mongocxx::client mongo_client{mongocxx::uri{"mongodb://localhost:27017"}};

Note that client is not thread-safe. See https://mongodb.github.io/mongo-cxx-driver/mongocxx-v3/thread-safety/ for more details.

Examples:

examples/mongocxx/client_session.cpp.

Constructor & Destructor Documentation

client() [1/2]

mongocxx::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::client::client	(	const class uri &	mongodb_uri,
		const options::client &	options = options::client()
	)

Creates a new client connection to MongoDB.

Parameters

mongodb_uri	A MongoDB URI representing the connection parameters
options	Additional options that cannot be specified via the mongodb_uri

Exceptions

mongocxx::exception

if invalid options are provided (whether from the URI or provided client options).

Member Function Documentation

database()

class database mongocxx::client::database

(

bsoncxx::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

name	The name of the database to get

Returns

The database

list_databases() [1/2]

cursor mongocxx::client::list_databases

(

)

const

Enumerates the databases in the client.

Returns

A mongocxx::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::operation_exception

if the underlying 'listDatabases' command fails.

See also

https://docs.mongodb.com/master/reference/command/listDatabases

list_databases() [2/2]

cursor mongocxx::client::list_databases

(

const client_session &

session

)

const

Enumerates the databases in the client.

Parameters

session

The mongocxx::client_session with which to perform the aggregation.

Returns

A mongocxx::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::operation_exception

if the underlying 'listDatabases' command fails.

See also

https://docs.mongodb.com/master/reference/command/listDatabases

operator[]()

database mongocxx::client::operator[]

(

bsoncxx::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

name	The name of the database.

Returns

Client side representation of a server side database

read_concern() [1/2]

MONGOCXX_DEPRECATED void mongocxx::client::read_concern

(

class 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

rc	The new read_concern

See also

https://docs.mongodb.com/master/reference/read-concern/

read_concern() [2/2]

class read_concern mongocxx::client::read_concern

(

)

const

Returns the current read concern for this client.

Returns

The current read_concern

read_preference() [1/2]

MONGOCXX_DEPRECATED void mongocxx::client::read_preference

(

class 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

rp	The new read_preference

See also

https://docs.mongodb.com/master/core/read-preference/

read_preference() [2/2]

class read_preference mongocxx::client::read_preference

(

)

const

Returns the current read preference for this client.

Returns

The current read_preference

See also

https://docs.mongodb.com/master/core/read-preference/

start_session()

client_session mongocxx::client::start_session

(

const options::client_session &

options = {}

)

Create a client session for a sequence of operations.

Returns

A client_session object. See mongocxx::client_session for more information.

Exceptions

mongocxx::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.

uri()

class uri mongocxx::client::uri

(

)

const

Returns the current uri for this client.

Returns

The uri that this client was created with.

write_concern() [1/2]

MONGOCXX_DEPRECATED void mongocxx::client::write_concern

(

class 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

wc	The new write concern

write_concern() [2/2]

class write_concern mongocxx::client::write_concern

(

)

const

Returns the current write concern for this client.

Returns

the current write_concern

---

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

• src/mongocxx/client.hpp