pub struct Client { /* private fields */ }
sync
or tokio-sync
only.Expand description
This is the main entry point for the synchronous 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
is a wrapper around the asynchronous mongodb::Client
, and it
starts up an async-std runtime internally to run that wrapped client on.
Client
uses std::sync::Arc
internally,
so it can safely be shared across threads. For example:
let client = Client::with_uri_str("mongodb://example.com")?;
for i in 0..5 {
let client_ref = client.clone();
std::thread::spawn(move || {
let collection = client_ref.database("items").collection::<Document>(&format!("coll{}", i));
// Do something with the collection
});
}
§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.
§Clean shutdown
Because Rust has no async equivalent of Drop
, values that require server-side cleanup when
dropped spawn a new async task to perform that cleanup. This can cause two potential issues:
- Drop tasks pending or in progress when the async runtime shuts down may not complete, causing server-side resources to not be freed.
- Drop tasks may run at an arbitrary time even after no
Client
values exist, making it hard to reason about associated resources (e.g. event handlers).
To address these issues, we highly recommend you use Client::shutdown
in the termination
path of your application. This will ensure that outstanding resources have been cleaned up and
terminate internal worker tasks before returning. Please note that shutdown
will wait for
all outstanding resource handles to be dropped, so they must either have been dropped before
calling shutdown
or in a concurrent task; see the documentation of shutdown
for more
details.
Implementations§
source§impl Client
impl Client
sourcepub fn with_uri_str(uri: impl AsRef<str>) -> Result<Self>
pub 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 fn list_databases(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>
) -> Result<Vec<DatabaseSpecification>>
pub 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 fn list_database_names(
&self,
filter: impl Into<Option<Document>>,
options: impl Into<Option<ListDatabasesOptions>>
) -> Result<Vec<String>>
pub 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 fn start_session(
&self,
options: Option<SessionOptions>
) -> Result<ClientSession>
pub fn start_session( &self, options: Option<SessionOptions> ) -> Result<ClientSession>
Starts a new ClientSession
.
sourcepub fn watch(
&self,
pipeline: impl IntoIterator<Item = Document>,
options: impl Into<Option<ChangeStreamOptions>>
) -> Result<ChangeStream<ChangeStreamEvent<Document>>>
pub 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 fn watch_with_session(
&self,
pipeline: impl IntoIterator<Item = Document>,
options: impl Into<Option<ChangeStreamOptions>>,
session: &mut ClientSession
) -> Result<SessionChangeStream<ChangeStreamEvent<Document>>>
pub 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.
sourcepub fn shutdown(self)
pub fn shutdown(self)
Shut down this Client
, terminating background thread workers and closing connections.
This will wait for any live handles to server-side resources (see below) to be
dropped and any associated server-side operations to finish.
IMPORTANT: Any live resource handles that are not dropped will cause this method to wait
indefinitely. It’s strongly recommended to structure your usage to avoid this, e.g. by
only using those types in shorter-lived scopes than the Client
. If this is not possible,
see shutdown_immediate
. For example:
fn upload_data(bucket: &GridFsBucket) {
let stream = bucket.open_upload_stream("test", None);
// .. write to the stream ..
}
let client = Client::with_uri_str("mongodb://example.com")?;
let bucket = client.database("test").gridfs_bucket(None);
upload_data(&bucket);
client.shutdown();
// Background cleanup work from `upload_data` is guaranteed to have run.
If the handle is used in the same scope as shutdown
, explicit drop
may be needed:
let client = Client::with_uri_str("mongodb://example.com")?;
let bucket = client.database("test").gridfs_bucket(None);
let stream = bucket.open_upload_stream("test", None);
// .. write to the stream ..
drop(stream);
client.shutdown();
// Background cleanup work for `stream` is guaranteed to have run.
Calling any methods on clones of this Client
or derived handles after this will return
errors.
Handles to server-side resources are Cursor
, SessionCursor
, Session
, or
GridFsUploadStream
.
sourcepub fn shutdown_immediate(self)
pub fn shutdown_immediate(self)
Shut down this Client
, terminating background thread workers and closing connections.
This does not wait for other pending resources to be cleaned up, which may cause both
client-side errors and server-side resource leaks. Calling any methods on clones of this
Client
or derived handles after this will return errors.
let client = Client::with_uri_str("mongodb://example.com")?;
let bucket = client.database("test").gridfs_bucket(None);
let stream = bucket.open_upload_stream("test", None);
// .. write to the stream ..
client.shutdown_immediate();
// Background cleanup work for `stream` may or may not have run.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for Client
impl !RefUnwindSafe for Client
impl Send for Client
impl Sync for Client
impl Unpin for Client
impl !UnwindSafe for Client
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> FmtForward for T
impl<T> FmtForward for T
source§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self
to use its Binary
implementation when Debug
-formatted.source§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self
to use its Display
implementation when
Debug
-formatted.source§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self
to use its LowerExp
implementation when
Debug
-formatted.source§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self
to use its LowerHex
implementation when
Debug
-formatted.source§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self
to use its Octal
implementation when Debug
-formatted.source§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self
to use its Pointer
implementation when
Debug
-formatted.source§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self
to use its UpperExp
implementation when
Debug
-formatted.source§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self
to use its UpperHex
implementation when
Debug
-formatted.source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
source§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
source§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read moresource§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read moresource§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
source§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
source§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
self
, then passes self.as_ref()
into the pipe function.source§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
self
, then passes self.as_mut()
into the pipe
function.source§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self
, then passes self.deref()
into the pipe function.source§impl<T> Pointable for T
impl<T> Pointable for T
source§impl<T> Tap for T
impl<T> Tap for T
source§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B>
of a value. Read moresource§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B>
of a value. Read moresource§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R>
view of a value. Read moresource§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R>
view of a value. Read moresource§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target
of a value. Read moresource§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.source§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.source§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow()
only in debug builds, and is erased in release
builds.source§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.source§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref()
only in debug builds, and is erased in release
builds.source§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut()
only in debug builds, and is erased in release
builds.source§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref()
only in debug builds, and is erased in release
builds.