mongodb_ext/traits.rs
1//! This module conains all traits of this crate.
2
3use crate::{
4 async_trait::async_trait,
5 mongodb::{
6 bson::document::Document, error::Result as MongoResult, Client as DbClient, Database,
7 },
8};
9
10/// Trait that is implemented automatically on each collection struct by [`mongo_db`].
11pub trait MongoCollection {
12 /// The collection's name.
13 const NAME: &'static str;
14 /// The collection's schema version.
15 ///
16 /// Change that in your [`mongo_db!`](crate::mongo_db) invocation every time you change your schema.
17 ///
18 /// You do not actually need to use this in your schema, but it is implemented for your convinience.
19 const SCHEMA_VERSION: i32;
20}
21
22/// Async trait that is implemented automatically on the database handler struct by [`mongo_db`].
23#[async_trait]
24pub trait MongoClient
25where
26 Self: Sized,
27{
28 /// The database's name.
29 const NAME: &'static str;
30 /// Initializer funtion of the database.
31 ///
32 /// Creates a database [`DbClient`] and calls [`new_with_client`](MongoClient::new_with_client) then.
33 async fn new(connection_str: &str) -> MongoResult<Self>;
34 /// Initializer function that uses the given client.
35 ///
36 /// Useful when interacting with multiple databases.
37 async fn new_with_client(client: DbClient) -> MongoResult<Self>;
38 /// Method that sends a ping command to the database.
39 async fn ping(&self) -> MongoResult<Document>;
40
41 /// Returns a reference to the database object.
42 fn database(&self) -> &Database;
43 /// Returns a reference to the mongodb client object.
44 fn client(&self) -> &DbClient;
45}
46
47#[cfg(feature = "mongodb-gridfs")]
48pub use gridfs::GridFSDb;
49
50/// Optional module that is enabled using the _"mongodb-gridfs"_ feature.
51///
52/// Provides automatic implementation of the [`GridFSDb`](gridfs::GridFSDb) trait on all types that implement [`MongoClient`].
53#[cfg(feature = "mongodb-gridfs")]
54pub mod gridfs {
55 use {super::MongoClient, mongodb_gridfs::GridFSBucket};
56
57 /// Trait that is implemented automatically on all Database handlers.
58 ///
59 /// Feature flag _"mongodb-gridfs"_ is needed to use this trait.
60 ///
61 /// ```rust
62 /// use mongodb_ext::{mongo_db, GridFSDb, MongoClient};
63 /// use mongodb_gridfs::GridFSBucket;
64 /// use tokio_test::block_on;
65 ///
66 /// mongo_db! {
67 /// SomeDatabase {
68 /// SomeCollection {
69 /// some_field: String
70 /// }
71 /// }
72 /// }
73 ///
74 /// use mongo::SomeDatabase;
75 ///
76 /// // using `tokio::block_on` to run async code in tests
77 /// let db: SomeDatabase = block_on(SomeDatabase::new("mongodb://example.com")).unwrap();
78 /// let bucket: GridFSBucket = db.create_bucket();
79 /// ```
80 pub trait GridFSDb: MongoClient {
81 /// Creates a mongodb GridFS bucket.
82 fn create_bucket(&self) -> GridFSBucket {
83 GridFSBucket::new(self.database().clone(), None)
84 }
85 }
86
87 impl<T> GridFSDb for T where T: MongoClient {}
88}