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}