caisin/sea-orm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documetation for the executor module

Browse Source
This commit is contained in:
Charles Chege 2021-10-29 10:38:55 +03:00
parent a9b6f8cc83
commit 817e9bdd23
7 changed files with 78 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/executor/delete.rs
View File

@ -4,13 +4,16 @@ use crate::{
use sea_query::DeleteStatement;
use std::future::Future;
/// Handles DELETE operations in a ActiveModel using [DeleteStatement]
#[derive(Clone, Debug)]
pub struct Deleter {
query: DeleteStatement,
}
/// The result of a DELETE operation
#[derive(Clone, Debug)]
pub struct DeleteResult {
/// The number of rows affected by the DELETE operation
pub rows_affected: u64,
}
@ -18,6 +21,7 @@ impl<'a, A: 'a> DeleteOne<A>
where
A: ActiveModelTrait,
{
/// Execute a DELETE operation on one ActiveModel
pub fn exec<C>(self, db: &'a C) -> impl Future<Output = Result<DeleteResult, DbErr>> + '_
where
C: ConnectionTrait<'a>,
@ -31,6 +35,7 @@ impl<'a, E> DeleteMany<E>
where
E: EntityTrait,
{
/// Execute a DELETE operation on many ActiveModels
pub fn exec<C>(self, db: &'a C) -> impl Future<Output = Result<DeleteResult, DbErr>> + '_
where
C: ConnectionTrait<'a>,
@ -41,10 +46,12 @@ where
}
impl Deleter {
/// Instantiate a new [Deleter] by passing it a [DeleteStatement]
pub fn new(query: DeleteStatement) -> Self {
Self { query }
}
/// Execute a DELETE operation
pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<DeleteResult, DbErr>> + '_
where
C: ConnectionTrait<'a>,

10
src/executor/execute.rs
View File

@ -1,16 +1,24 @@
/// Defines the result of executing an operation
#[derive(Debug)]
pub struct ExecResult {
/// The type of result from the execution depending on the feature flag enabled
/// to choose a database backend
pub(crate) result: ExecResultHolder,
}
/// Holds a result depending on the database backend chosen by the feature flag
#[derive(Debug)]
pub(crate) enum ExecResultHolder {
/// Holds the result of executing an operation on a MySQL database
#[cfg(feature = "sqlx-mysql")]
SqlxMySql(sqlx::mysql::MySqlQueryResult),
/// Holds the result of executing an operation on a PostgreSQL database
#[cfg(feature = "sqlx-postgres")]
SqlxPostgres(sqlx::postgres::PgQueryResult),
/// Holds the result of executing an operation on a SQLite database
#[cfg(feature = "sqlx-sqlite")]
SqlxSqlite(sqlx::sqlite::SqliteQueryResult),
/// Holds the result of executing an operation on the Mock database
#[cfg(feature = "mock")]
Mock(crate::MockExecResult),
}
@ -18,6 +26,7 @@ pub(crate) enum ExecResultHolder {
// ExecResult //
impl ExecResult {
/// Get the last id after `AUTOINCREMENT` is done on the primary key
pub fn last_insert_id(&self) -> u64 {
match &self.result {
#[cfg(feature = "sqlx-mysql")]
@ -40,6 +49,7 @@ impl ExecResult {
}
}
/// Get the number of rows affedted by the operation
pub fn rows_affected(&self) -> u64 {
match &self.result {
#[cfg(feature = "sqlx-mysql")]

6
src/executor/insert.rs
View File

@ -5,6 +5,7 @@ use crate::{
use sea_query::{FromValueTuple, InsertStatement, ValueTuple};
use std::{future::Future, marker::PhantomData};
/// Defines a structure to perform INSERT operations in an ActiveModel
#[derive(Debug)]
pub struct Inserter<A>
where
@ -15,11 +16,13 @@ where
model: PhantomData<A>,
}
/// The result of an INSERT operation on an ActiveModel
#[derive(Debug)]
pub struct InsertResult<A>
where
A: ActiveModelTrait,
{
/// The id performed when AUTOINCREMENT was performed on the PrimaryKey
pub last_insert_id: <<<A as ActiveModelTrait>::Entity as EntityTrait>::PrimaryKey as PrimaryKeyTrait>::ValueType,
}
@ -27,6 +30,7 @@ impl<A> Insert<A>
where
A: ActiveModelTrait,
{
/// Execute an insert operation
#[allow(unused_mut)]
pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<InsertResult<A>, DbErr>> + '_
where
@ -53,6 +57,7 @@ impl<A> Inserter<A>
where
A: ActiveModelTrait,
{
/// Instantiate a new insert operation
pub fn new(primary_key: Option<ValueTuple>, query: InsertStatement) -> Self {
Self {
primary_key,
@ -61,6 +66,7 @@ where
}
}
/// Execute an insert operation
pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<InsertResult<A>, DbErr>> + '_
where
C: ConnectionTrait<'a>,

2
src/executor/paginator.rs
View File

@ -4,8 +4,10 @@ use futures::Stream;
use sea_query::{Alias, Expr, SelectStatement};
use std::{marker::PhantomData, pin::Pin};
/// Pin a Model so that stream operations can be performed on the model
pub type PinBoxStream<'db, Item> = Pin<Box<dyn Stream<Item = Item> + 'db>>;
/// Defined a structure to handle pagination of a result from a query operation on a Model
#[derive(Clone, Debug)]
pub struct Paginator<'db, C, S>
where

13
src/executor/query.rs
View File

@ -3,6 +3,7 @@ use crate::debug_print;
use crate::{DbErr, SelectGetableValue, SelectorRaw, Statement};
use std::fmt;
/// Defines the result of a query operation on a Model
#[derive(Debug)]
pub struct QueryResult {
pub(crate) row: QueryResultRow,
@ -19,13 +20,18 @@ pub(crate) enum QueryResultRow {
Mock(crate::MockRow),
}
/// Constrain any type trying to get a Row in a database
pub trait TryGetable: Sized {
/// Ensure the type implements this method
fn try_get(res: &QueryResult, pre: &str, col: &str) -> Result<Self, TryGetError>;
}
/// An error from trying to get a row from a Model
#[derive(Debug)]
pub enum TryGetError {
/// A database error was encountered as defined in [crate::DbErr]
DbErr(DbErr),
/// A null value was encountered
Null,
}
@ -41,6 +47,7 @@ impl From<TryGetError> for DbErr {
// QueryResult //
impl QueryResult {
/// Get a Row from a Column
pub fn try_get<T>(&self, pre: &str, col: &str) -> Result<T, DbErr>
where
T: TryGetable,
@ -48,6 +55,7 @@ impl QueryResult {
Ok(T::try_get(self, pre, col)?)
}
/// Perform query operations on multiple Columns
pub fn try_get_many<T>(&self, pre: &str, cols: &[String]) -> Result<T, DbErr>
where
T: TryGetableMany,
@ -306,7 +314,9 @@ try_getable_all!(uuid::Uuid);
// TryGetableMany //
/// Perform a query on multiple columns
pub trait TryGetableMany: Sized {
/// THe method to perform a query on multiple columns
fn try_get_many(res: &QueryResult, pre: &str, cols: &[String]) -> Result<Self, TryGetError>;
/// ```
@ -453,8 +463,9 @@ fn try_get_many_with_slice_len_of(len: usize, cols: &[String]) -> Result<(), Try
}
// TryFromU64 //
/// Try to convert a type to a u64
pub trait TryFromU64: Sized {
/// The method to convert the type to a u64
fn try_from_u64(n: u64) -> Result<Self, DbErr>;
}

34
src/executor/select.rs
View File

@ -11,6 +11,7 @@ use std::pin::Pin;
#[cfg(feature = "with-json")]
use crate::JsonValue;
/// Defines a type to do `SELECT` operations though a [SelectStatement] on a Model
#[derive(Clone, Debug)]
pub struct Selector<S>
where
@ -20,6 +21,7 @@ where
selector: S,
}
/// Performs a raw `SELECT` operation on a model
#[derive(Clone, Debug)]
pub struct SelectorRaw<S>
where
@ -29,12 +31,16 @@ where
selector: S,
}
/// Used to enforce constraints on any type that wants to perform SELECT queries
pub trait SelectorTrait {
#[allow(missing_docs)]
type Item: Sized;
/// The method to perform a query on a Model
fn from_raw_query_result(res: QueryResult) -> Result<Self::Item, DbErr>;
}
/// Perform an operation on an entity that can yield a Value
#[derive(Debug)]
pub struct SelectGetableValue<T, C>
where
@ -45,6 +51,7 @@ where
model: PhantomData<T>,
}
/// Defines a type to get a Model
#[derive(Debug)]
pub struct SelectModel<M>
where
@ -53,6 +60,7 @@ where
model: PhantomData<M>,
}
/// Defines a type to get two Modelss
#[derive(Clone, Debug)]
pub struct SelectTwoModel<M, N>
where
@ -105,6 +113,7 @@ impl<E> Select<E>
where
E: EntityTrait,
{
/// Perform a Select operation on a Model using a [Statement]
#[allow(clippy::wrong_self_convention)]
pub fn from_raw_sql(self, stmt: Statement) -> SelectorRaw<SelectModel<E::Model>> {
SelectorRaw {
@ -113,6 +122,7 @@ where
}
}
/// Return a [Selector] from `Self` that wraps a [SelectModel]
pub fn into_model<M>(self) -> Selector<SelectModel<M>>
where
M: FromQueryResult,
@ -123,6 +133,7 @@ where
}
}
/// Get a selectable Model as a [JsonValue] for SQL JSON operations
#[cfg(feature = "with-json")]
pub fn into_json(self) -> Selector<SelectModel<JsonValue>> {
Selector {
@ -239,6 +250,7 @@ where
Selector::<SelectGetableValue<T, C>>::with_columns(self.query)
}
/// Get one Model from a SELECT operation
pub async fn one<'a, C>(self, db: &C) -> Result<Option<E::Model>, DbErr>
where
C: ConnectionTrait<'a>,
@ -246,6 +258,7 @@ where
self.into_model().one(db).await
}
/// Get all the Models from a SELECT operation
pub async fn all<'a, C>(self, db: &C) -> Result<Vec<E::Model>, DbErr>
where
C: ConnectionTrait<'a>,
@ -253,6 +266,7 @@ where
self.into_model().all(db).await
}
/// Stream the results of a SELECT operation on a Model
pub async fn stream<'a: 'b, 'b, C>(
self,
db: &'a C,
@ -263,6 +277,7 @@ where
self.into_model().stream(db).await
}
/// Paginate the results of a SELECT operation on a Model
pub fn paginate<'a, C>(
self,
db: &'a C,
@ -274,6 +289,7 @@ where
self.into_model().paginate(db, page_size)
}
/// Perform a `COUNT` operation on a items on a Model using pagination
pub async fn count<'a, C>(self, db: &'a C) -> Result<usize, DbErr>
where
C: ConnectionTrait<'a>,
@ -287,6 +303,7 @@ where
E: EntityTrait,
F: EntityTrait,
{
/// Perform a conversion into a [SelectTwoModel]
pub fn into_model<M, N>(self) -> Selector<SelectTwoModel<M, N>>
where
M: FromQueryResult,
@ -298,6 +315,7 @@ where
}
}
/// Convert the Models into JsonValue
#[cfg(feature = "with-json")]
pub fn into_json(self) -> Selector<SelectTwoModel<JsonValue, JsonValue>> {
Selector {
@ -306,6 +324,7 @@ where
}
}
/// Get one Model from a Select operation
pub async fn one<'a, C>(self, db: &C) -> Result<Option<(E::Model, Option<F::Model>)>, DbErr>
where
C: ConnectionTrait<'a>,
@ -313,6 +332,7 @@ where
self.into_model().one(db).await
}
/// Get all Models from a Select operation
pub async fn all<'a, C>(self, db: &C) -> Result<Vec<(E::Model, Option<F::Model>)>, DbErr>
where
C: ConnectionTrait<'a>,
@ -320,6 +340,7 @@ where
self.into_model().all(db).await
}
/// Stream the results of a Select operation on a Model
pub async fn stream<'a: 'b, 'b, C>(
self,
db: &'a C,
@ -330,6 +351,7 @@ where
self.into_model().stream(db).await
}
/// Paginate the results of a select operation on two models
pub fn paginate<'a, C>(
self,
db: &'a C,
@ -341,6 +363,7 @@ where
self.into_model().paginate(db, page_size)
}
/// Perform a count on the paginated results
pub async fn count<'a, C>(self, db: &'a C) -> Result<usize, DbErr>
where
C: ConnectionTrait<'a>,
@ -354,6 +377,7 @@ where
E: EntityTrait,
F: EntityTrait,
{
/// Performs a conversion to [Selector]
fn into_model<M, N>(self) -> Selector<SelectTwoModel<M, N>>
where
M: FromQueryResult,
@ -365,6 +389,7 @@ where
}
}
/// Convert the results to JSON
#[cfg(feature = "with-json")]
pub fn into_json(self) -> Selector<SelectTwoModel<JsonValue, JsonValue>> {
Selector {
@ -373,6 +398,7 @@ where
}
}
/// Select one Model
pub async fn one<'a, C>(self, db: &C) -> Result<Option<(E::Model, Option<F::Model>)>, DbErr>
where
C: ConnectionTrait<'a>,
@ -380,6 +406,7 @@ where
self.into_model().one(db).await
}
/// Stream the result of the operation
pub async fn stream<'a: 'b, 'b, C>(
self,
db: &'a C,
@ -390,6 +417,7 @@ where
self.into_model().stream(db).await
}
/// Get all the Models from the select operation
pub async fn all<'a, C>(self, db: &C) -> Result<Vec<(E::Model, Vec<F::Model>)>, DbErr>
where
C: ConnectionTrait<'a>,
@ -428,6 +456,7 @@ where
}
}
/// Get a Model from a Select operation
pub async fn one<'a, C>(mut self, db: &C) -> Result<Option<S::Item>, DbErr>
where
C: ConnectionTrait<'a>,
@ -441,6 +470,7 @@ where
}
}
/// Get all results from a Select operation
pub async fn all<'a, C>(self, db: &C) -> Result<Vec<S::Item>, DbErr>
where
C: ConnectionTrait<'a>,
@ -454,6 +484,7 @@ where
Ok(models)
}
/// Stream the results of the operation
pub async fn stream<'a: 'b, 'b, C>(
self,
db: &'a C,
@ -469,6 +500,7 @@ where
})))
}
/// Paginate the result of a select operation on a Model
pub fn paginate<'a, C>(self, db: &'a C, page_size: usize) -> Paginator<'a, C, S>
where
C: ConnectionTrait<'a>,
@ -499,7 +531,7 @@ where
}
}
/// Create `SelectorRaw` from Statment and columns. Executing this `SelectorRaw` will
/// Create `SelectorRaw` from Statement and columns. Executing this `SelectorRaw` will
/// return a type `T` which implement `TryGetableMany`.
pub fn with_columns<T, C>(stmt: Statement) -> SelectorRaw<SelectGetableValue<T, C>>
where

8
src/executor/update.rs
View File

@ -4,14 +4,17 @@ use crate::{
use sea_query::UpdateStatement;
use std::future::Future;
/// Defines an update operation
#[derive(Clone, Debug)]
pub struct Updater {
query: UpdateStatement,
check_record_exists: bool,
}
/// The result of an update operation on an ActiveModel
#[derive(Clone, Debug, PartialEq)]
pub struct UpdateResult {
/// The rows affected by the update operation
pub rows_affected: u64,
}
@ -19,6 +22,7 @@ impl<'a, A: 'a> UpdateOne<A>
where
A: ActiveModelTrait,
{
/// Execute an update operation on an ActiveModel
pub async fn exec<'b, C>(self, db: &'b C) -> Result<A, DbErr>
where
C: ConnectionTrait<'b>,
@ -32,6 +36,7 @@ impl<'a, E> UpdateMany<E>
where
E: EntityTrait,
{
/// Execute an update operation on multiple ActiveModels
pub fn exec<C>(self, db: &'a C) -> impl Future<Output = Result<UpdateResult, DbErr>> + '_
where
C: ConnectionTrait<'a>,
@ -42,6 +47,7 @@ where
}
impl Updater {
/// Instantiate an update using an [UpdateStatement]
pub fn new(query: UpdateStatement) -> Self {
Self {
query,
@ -49,11 +55,13 @@ impl Updater {
}
}
/// Check if a record exists on the ActiveModel to perform the update operation on
pub fn check_record_exists(mut self) -> Self {
self.check_record_exists = true;
self
}
/// Execute an update operation
pub fn exec<'a, C>(self, db: &'a C) -> impl Future<Output = Result<UpdateResult, DbErr>> + '_
where
C: ConnectionTrait<'a>,