pub struct Client { /* private fields */ }
Expand description
This is the main entry point for the API. A Client
is used to connect to a MongoDB cluster.
By default, it will monitor the topology of the cluster, keeping track of any changes, such
as servers being added or removed.
Client
uses std::sync::Arc
internally,
so it can safely be shared across threads or async tasks. For example:
let client = Client::with_uri_str("mongodb://example.com").await?;
for i in 0..5 {
let client_ref = client.clone();
task::spawn(async move {
let collection = client_ref.database("items").collection::<Document>(&format!("coll{}", i));
// Do something with the collection
});
}
Notes on performance
Spawning many asynchronous tasks that use the driver concurrently like this is often the best way to achieve maximum performance, as the driver is designed to work well in such situations.
Additionally, using a custom Rust type that implements Serialize
and Deserialize
as the
generic parameter of Collection
instead of bson::Document
can
reduce the amount of time the driver and your application spends serializing and deserializing
BSON, which can also lead to increased performance.
TCP Keepalive
TCP keepalive is enabled by default with tcp_keepalive_time
set to 120 seconds. The
driver does not set tcp_keepalive_intvl
. See the
MongoDB Diagnostics FAQ keepalive section
for instructions on setting these values at the system level.
Implementations
sourceimpl Client
impl Client
sourcepub async fn with_uri_str(uri: impl AsRef<str>) -> Result<Self>
pub async fn with_uri_str(uri: impl AsRef<str>) -> Result<Self>
Creates a new Client
connected to the cluster specified by uri
. uri
must be a valid
MongoDB connection string.
See the documentation on
ClientOptions::parse
for more details.
sourcepub fn with_options(options: ClientOptions) -> Result<Self>
pub fn with_options(options: ClientOptions) -> Result<Self>
Creates a new Client
connected to the cluster specified by options
.
sourcepub fn selection_criteria(&self) -> Option<&SelectionCriteria>
pub fn selection_criteria(&self) -> Option<&SelectionCriteria>
Gets the default selection criteria the Client
uses for operations..
sourcepub fn read_concern(&self) -> Option<&ReadConcern>
pub fn read_concern(&self) -> Option<&ReadConcern>
Gets the default read concern the Client
uses for operations.
sourcepub fn write_concern(&self) -> Option<&WriteConcern>
pub fn write_concern(&self) -> Option<&WriteConcern>
Gets the default write concern the Client
uses for operations.
sourcepub fn database(&self, name: &str) -> Database
pub fn database(&self, name: &str) -> Database
Gets a handle to a database specified by name
in the cluster the Client
is connected to.
The Database
options (e.g. read preference and write concern) will default to those of the
Client
.
This method does not send or receive anything across the wire to the database, so it can be used repeatedly without incurring any costs from I/O.
sourcepub fn database_with_options(
&self,
name: &str,
options: DatabaseOptions
) -> Database
pub fn database_with_options(
&self,
name: &str,
options: DatabaseOptions
) -> Database
Gets a handle to a database specified by name
in the cluster the Client
is connected to.
Operations done with this Database
will use the options specified by options
by default
and will otherwise default to those of the Client
.
This method does not send or receive anything across the wire to the database, so it can be used repeatedly without incurring any costs from I/O.
sourcepub fn default_database(&self) -> Option<Database>
pub fn default_database(&self) -> Option<Database>
Gets a handle to the default database specified in the ClientOptions
or MongoDB connection
string used to construct this Client
.
If no default database was specified, None
will be returned.
sourcepub async fn list_databases(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>
) -> Result<Vec<DatabaseSpecification>>
pub async fn list_databases(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>
) -> Result<Vec<DatabaseSpecification>>
Gets information about each database present in the cluster the Client is connected to.
sourcepub async fn list_databases_with_session(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>,
session: &mut ClientSession
) -> Result<Vec<DatabaseSpecification>>
pub async fn list_databases_with_session(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>,
session: &mut ClientSession
) -> Result<Vec<DatabaseSpecification>>
Gets information about each database present in the cluster the Client is connected to
using the provided ClientSession
.
sourcepub async fn list_database_names(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>
) -> Result<Vec<String>>
pub async fn list_database_names(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>
) -> Result<Vec<String>>
Gets the names of the databases present in the cluster the Client is connected to.
sourcepub async fn start_session(
&self,
options: impl Into<Option<SessionOptions>>
) -> Result<ClientSession>
pub async fn start_session(
&self,
options: impl Into<Option<SessionOptions>>
) -> Result<ClientSession>
Starts a new ClientSession
.
sourcepub async fn watch(
&self,
pipeline: impl IntoIterator<Item = Document>,
options: impl Into<Option<ChangeStreamOptions>>
) -> Result<ChangeStream<ChangeStreamEvent<Document>>>
pub async fn watch(
&self,
pipeline: impl IntoIterator<Item = Document>,
options: impl Into<Option<ChangeStreamOptions>>
) -> Result<ChangeStream<ChangeStreamEvent<Document>>>
Starts a new ChangeStream
that receives events for all changes in the cluster. The
stream does not observe changes from system collections or the “config”, “local” or
“admin” databases. Note that this method (watch
on a cluster) is only supported in
MongoDB 4.0 or greater.
See the documentation here on change streams.
Change streams require either a “majority” read concern or no read concern. Anything else will cause a server error.
Note that using a $project
stage to remove any of the _id
operationType
or ns
fields
will cause an error. The driver requires these fields to support resumability. For
more information on resumability, see the documentation for
ChangeStream
If the pipeline alters the structure of the returned events, the parsed type will need to be
changed via ChangeStream::with_type
.
sourcepub async fn watch_with_session(
&self,
pipeline: impl IntoIterator<Item = Document>,
options: impl Into<Option<ChangeStreamOptions>>,
session: &mut ClientSession
) -> Result<SessionChangeStream<ChangeStreamEvent<Document>>>
pub async fn watch_with_session(
&self,
pipeline: impl IntoIterator<Item = Document>,
options: impl Into<Option<ChangeStreamOptions>>,
session: &mut ClientSession
) -> Result<SessionChangeStream<ChangeStreamEvent<Document>>>
Starts a new SessionChangeStream
that receives events for all changes in the cluster
using the provided ClientSession
. See Client::watch
for more information.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Client
impl Send for Client
impl Sync for Client
impl Unpin for Client
impl !UnwindSafe for Client
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more