xitca_postgres/
execute.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
mod async_impl;
mod sync_impl;

/// Defining how a query is executed. can be used for customizing encoding, executing and database
/// data decoding.
///
/// For customized encoding please see [`Encode`] trait for detail.
/// For customized decoding please see [`IntoResponse`] trait for detail.
///
/// when to use `execute` or `query` methods:
/// - `execute` method is for use case where sql produce an outcome where it only happen once.
///     usually in the form of preparing a statement or observing how many rows have been modified.
/// - `query` method is for use case where sql produce repeated outcome where it can happen multiple times.
///     usually in the form of visiting an iteration of database rows.
///
/// [`Encode`]: crate::driver::codec::encode::Encode
/// [`IntoResponse`]: crate::driver::codec::response::IntoResponse
pub trait Execute<'c, C>
where
    Self: Sized,
{
    /// outcome of execute.
    /// used for single time database response: number of rows affected by execution for example.
    type ExecuteOutput;

    /// outcome of query.
    /// used for repeated database response: database rows for example
    ///
    /// consider impl [`AsyncLendingIterator`] for async iterator of rows
    /// consider impl [`Iterator`] for iterator of rows
    ///
    /// for type of statement where no repeated response will returning this type can point to
    /// [`Execute::ExecuteOutput`] and it's encouraged to make `query` behave identical to `execute`
    ///
    /// [`AsyncLendingIterator`]: crate::iter::AsyncLendingIterator
    type QueryOutput;

    /// define how a statement is executed with single time response
    fn execute(self, cli: &'c C) -> Self::ExecuteOutput;

    /// define how a statement is queried with repeated response
    fn query(self, cli: &'c C) -> Self::QueryOutput;
}

/// mutable version of [`Execute`] trait where C type is mutably borrowed
pub trait ExecuteMut<'c, C>
where
    Self: Sized,
{
    type ExecuteMutOutput;
    type QueryMutOutput;

    fn execute_mut(self, cli: &'c mut C) -> Self::ExecuteMutOutput;

    fn query_mut(self, cli: &'c mut C) -> Self::QueryMutOutput;
}

/// blocking version of [`Execute`] for synchronous environment
pub trait ExecuteBlocking<'c, C>
where
    Self: Sized,
{
    type ExecuteOutput;
    type QueryOutput;

    fn execute_blocking(self, cli: &'c C) -> Self::ExecuteOutput;

    fn query_blocking(self, cli: &'c C) -> Self::QueryOutput;
}