Struct rorm_db::database::Database

pub struct Database { /* private fields */ }

Main API wrapper.

All operations can be started with methods of this struct.

Implementations

impl Database

pub fn get_sql_dialect(&self) -> DBImpl

Access the used driver at runtime.

This can be used to generate SQL statements for the chosen dialect.

pub async fn connect(
    configuration: DatabaseConfiguration
) -> Result<Self, Error>

Connect to the database using configuration.

pub fn query_stream<'db, 'post_query, 'stream>(
    &'db self,
    model: &str,
    columns: &[ColumnSelector<'_>],
    joins: &[JoinTable<'_, 'post_query>],
    conditions: Option<&Condition<'post_query>>,
    order_by_clause: &[OrderByEntry<'_>],
    limit: Option<LimitClause>,
    transaction: Option<&'stream mut Transaction<'_>>
) -> BoxStream<'stream, Result<Row, Error>>where
    'post_query: 'stream,
    'db: 'stream,

👎Deprecated: Will be removed to reduce number of methods to maintain Use query::<Stream> instead!

This method is used to retrieve a stream of rows that matched the applied conditions.

Parameter:

• model: Name of the table.
• columns: Columns to retrieve values from.
• joins: Join tables expressions.
• conditions: Optional conditions to apply.
• limit: Optional limit / offset to apply to the query.
• transaction: Optional transaction to execute the query on.

pub async fn query_one(
    &self,
    model: &str,
    columns: &[ColumnSelector<'_>],
    joins: &[JoinTable<'_, '_>],
    conditions: Option<&Condition<'_>>,
    order_by_clause: &[OrderByEntry<'_>],
    offset: Option<u64>,
    transaction: Option<&mut Transaction<'_>>
) -> Result<Row, Error>

👎Deprecated: Will be removed to reduce number of methods to maintain Use query::<One> instead!

This method is used to retrieve exactly one row from the table. An error is returned if no value could be retrieved.

Parameter:

• model: Model to query.
• columns: Columns to retrieve values from.
• joins: Join tables expressions.
• conditions: Optional conditions to apply.
• offset: Optional offset to apply to the query.
• transaction: Optional transaction to execute the query on.

pub async fn query_optional(
    &self,
    model: &str,
    columns: &[ColumnSelector<'_>],
    joins: &[JoinTable<'_, '_>],
    conditions: Option<&Condition<'_>>,
    order_by_clause: &[OrderByEntry<'_>],
    offset: Option<u64>,
    transaction: Option<&mut Transaction<'_>>
) -> Result<Option<Row>, Error>

👎Deprecated: Will be removed to reduce number of methods to maintain Use query::<Optional> instead!

This method is used to retrieve an optional row from the table.

Parameter:

• model: Model to query.
• columns: Columns to retrieve values from.
• joins: Join tables expressions.
• conditions: Optional conditions to apply.
• offset: Optional offset to apply to the query.
• transaction: Optional transaction to execute the query on.

pub async fn query_all(
    &self,
    model: &str,
    columns: &[ColumnSelector<'_>],
    joins: &[JoinTable<'_, '_>],
    conditions: Option<&Condition<'_>>,
    order_by_clause: &[OrderByEntry<'_>],
    limit: Option<LimitClause>,
    transaction: Option<&mut Transaction<'_>>
) -> Result<Vec<Row>, Error>

👎Deprecated: Will be removed to reduce number of methods to maintain Use query::<All> instead!

This method is used to retrieve all rows that match the provided query.

Parameter:

• model: Model to query.
• columns: Columns to retrieve values from.
• joins: Join tables expressions.
• conditions: Optional conditions to apply.
• limit: Optional limit / offset to apply to the query.
• transaction: Optional transaction to execute the query on.

pub fn query<'result, 'db: 'result, 'post_query: 'result, Q: QueryStrategy + GetLimitClause>(
    &'db self,
    model: &str,
    columns: &[ColumnSelector<'_>],
    joins: &[JoinTable<'_, 'post_query>],
    conditions: Option<&Condition<'post_query>>,
    order_by_clause: &[OrderByEntry<'_>],
    limit: Option<Q::LimitOrOffset>,
    transaction: Option<&'db mut Transaction<'_>>
) -> Q::Result<'result>

This method is used to retrieve rows that match the provided query.

It is generic over a QueryStrategy which specifies how and how many rows to query.

Parameter:

• model: Model to query.
• columns: Columns to retrieve values from.
• joins: Join tables expressions.
• conditions: Optional conditions to apply.
• limit: Optional limit / offset to apply to the query. Depending on the query strategy, this is either LimitClause (for All and Stream) or a simple u64 (for One and Optional).
• transaction: Optional transaction to execute the query on.

Examples found in repository

src/database.rs (lines 151-160)

    pub fn query_stream<'db, 'post_query, 'stream>(
        &'db self,
        model: &str,
        columns: &[ColumnSelector<'_>],
        joins: &[JoinTable<'_, 'post_query>],
        conditions: Option<&conditional::Condition<'post_query>>,
        order_by_clause: &[OrderByEntry<'_>],
        limit: Option<LimitClause>,
        transaction: Option<&'stream mut Transaction<'_>>,
    ) -> BoxStream<'stream, Result<Row, Error>>
    where
        'post_query: 'stream,
        'db: 'stream,
    {
        Self::query::<Stream>(
            self,
            model,
            columns,
            joins,
            conditions,
            order_by_clause,
            limit,
            transaction,
        )
        .boxed()
    }

    /**
    This method is used to retrieve exactly one row from the table.
    An error is returned if no value could be retrieved.

    **Parameter**:
    - `model`: Model to query.
    - `columns`: Columns to retrieve values from.
    - `joins`: Join tables expressions.
    - `conditions`: Optional conditions to apply.
    - `offset`: Optional offset to apply to the query.
    - `transaction`: Optional transaction to execute the query on.
     */
    #[deprecated(
        note = "Will be removed to reduce number of methods to maintain\nUse `query::<One>` instead!"
    )]
    #[allow(clippy::too_many_arguments)]
    pub async fn query_one(
        &self,
        model: &str,
        columns: &[ColumnSelector<'_>],
        joins: &[JoinTable<'_, '_>],
        conditions: Option<&conditional::Condition<'_>>,
        order_by_clause: &[OrderByEntry<'_>],
        offset: Option<u64>,
        transaction: Option<&mut Transaction<'_>>,
    ) -> Result<Row, Error> {
        Self::query::<One>(
            self,
            model,
            columns,
            joins,
            conditions,
            order_by_clause,
            offset,
            transaction,
        )
        .await
    }

    /**
    This method is used to retrieve an optional row from the table.

    **Parameter**:
    - `model`: Model to query.
    - `columns`: Columns to retrieve values from.
    - `joins`: Join tables expressions.
    - `conditions`: Optional conditions to apply.
    - `offset`: Optional offset to apply to the query.
    - `transaction`: Optional transaction to execute the query on.
     */
    #[deprecated(
        note = "Will be removed to reduce number of methods to maintain\nUse `query::<Optional>` instead!"
    )]
    #[allow(clippy::too_many_arguments)]
    pub async fn query_optional(
        &self,
        model: &str,
        columns: &[ColumnSelector<'_>],
        joins: &[JoinTable<'_, '_>],
        conditions: Option<&conditional::Condition<'_>>,
        order_by_clause: &[OrderByEntry<'_>],
        offset: Option<u64>,
        transaction: Option<&mut Transaction<'_>>,
    ) -> Result<Option<Row>, Error> {
        Self::query::<Optional>(
            self,
            model,
            columns,
            joins,
            conditions,
            order_by_clause,
            offset,
            transaction,
        )
        .await
    }

    /**
    This method is used to retrieve all rows that match the provided query.

    **Parameter**:
    - `model`: Model to query.
    - `columns`: Columns to retrieve values from.
    - `joins`: Join tables expressions.
    - `conditions`: Optional conditions to apply.
    - `limit`: Optional limit / offset to apply to the query.
    - `transaction`: Optional transaction to execute the query on.
     */
    #[deprecated(
        note = "Will be removed to reduce number of methods to maintain\nUse `query::<All>` instead!"
    )]
    #[allow(clippy::too_many_arguments)]
    pub async fn query_all(
        &self,
        model: &str,
        columns: &[ColumnSelector<'_>],
        joins: &[JoinTable<'_, '_>],
        conditions: Option<&conditional::Condition<'_>>,
        order_by_clause: &[OrderByEntry<'_>],
        limit: Option<LimitClause>,
        transaction: Option<&mut Transaction<'_>>,
    ) -> Result<Vec<Row>, Error> {
        Self::query::<All>(
            self,
            model,
            columns,
            joins,
            conditions,
            order_by_clause,
            limit,
            transaction,
        )
        .await
    }

pub async fn insert_returning(
    &self,
    model: &str,
    columns: &[&str],
    values: &[Value<'_>],
    transaction: Option<&mut Transaction<'_>>,
    returning: &[&str]
) -> Result<Row, Error>

This method is used to insert into a table.

Parameter:

• model: Table to insert to
• columns: Columns to set values for.
• values: Values to bind to the corresponding columns.
• transaction: Optional transaction to execute the query on.

pub async fn insert(
    &self,
    model: &str,
    columns: &[&str],
    values: &[Value<'_>],
    transaction: Option<&mut Transaction<'_>>
) -> Result<(), Error>

This method is used to insert into a table.

Parameter:

• model: Table to insert to
• columns: Columns to set values for.
• values: Values to bind to the corresponding columns.
• transaction: Optional transaction to execute the query on.

pub async fn insert_bulk(
    &self,
    model: &str,
    columns: &[&str],
    rows: &[&[Value<'_>]],
    transaction: Option<&mut Transaction<'_>>
) -> Result<(), Error>

This method is used to bulk insert rows.

If one insert statement fails, the complete operation will be rolled back.

Parameter:

• model: Table to insert to
• columns: Columns to set rows for.
• rows: List of values to bind to the corresponding columns.
• transaction: Optional transaction to execute the query on.

pub async fn insert_bulk_returning(
    &self,
    model: &str,
    columns: &[&str],
    rows: &[&[Value<'_>]],
    transaction: Option<&mut Transaction<'_>>,
    returning: &[&str]
) -> Result<Vec<Row>, Error>

This method is used to bulk insert rows.

If one insert statement fails, the complete operation will be rolled back.

Parameter:

• model: Table to insert to
• columns: Columns to set rows for.
• rows: List of values to bind to the corresponding columns.
• transaction: Optional transaction to execute the query on.

pub async fn delete<'post_build>(
    &self,
    model: &str,
    condition: Option<&Condition<'post_build>>,
    transaction: Option<&mut Transaction<'_>>
) -> Result<u64, Error>

This method is used to delete rows from a table.

Parameter:

• model: Name of the model to delete rows from
• condition: Optional condition to apply.
• transaction: Optional transaction to execute the query on.

Returns the rows affected of the delete statement. Note that this also includes relations, etc.

pub async fn update<'post_build>(
    &self,
    model: &str,
    updates: &[(&str, Value<'post_build>)],
    condition: Option<&Condition<'post_build>>,
    transaction: Option<&mut Transaction<'_>>
) -> Result<u64, Error>

This method is used to update rows in a table.

Parameter:

• model: Name of the model to update rows from
• updates: A list of updates. An update is a tuple that consists of a list of columns to update as well as the value to set to the columns.
• condition: Optional condition to apply.
• transaction: Optional transaction to execute the query on.

Returns the rows affected from the update statement. Note that this also includes relations, etc.

pub async fn raw_sql<'a>(
    &self,
    query_string: &'a str,
    bind_params: Option<&[Value<'a>]>,
    transaction: Option<&mut Transaction<'_>>
) -> Result<Vec<Row>, Error>

Execute raw SQL statements on the database.

If possible, the statement is executed as prepared statement.

To bind parameter, use ? as placeholder in SQLite and MySQL and $1, $2, $n in Postgres.

Parameter:

• query_string: Reference to a valid SQL query.
• bind_params: Optional list of values to bind in the query.
• transaction: Optional transaction to execute the query on.

Returns a list of rows. If there are no values to retrieve, an empty list is returned.

pub async fn start_transaction(&self) -> Result<Transaction<'_>, Error>

Entry point for a Transaction.

Examples found in repository

src/database.rs (line 429)

    pub async fn insert_bulk(
        &self,
        model: &str,
        columns: &[&str],
        rows: &[&[Value<'_>]],
        transaction: Option<&mut Transaction<'_>>,
    ) -> Result<(), Error> {
        return match transaction {
            None => {
                let mut transaction = self.start_transaction().await?;
                with_transaction(self, &mut transaction, model, columns, rows).await?;
                transaction.commit().await
            }
            Some(transaction) => {
                with_transaction(self, transaction, model, columns, rows).await?;
                Ok(())
            }
        };
        async fn with_transaction(
            db: &Database,
            tx: &mut Transaction<'_>,
            model: &str,
            columns: &[&str],
            rows: &[&[Value<'_>]],
        ) -> Result<(), Error> {
            for chunk in rows.chunks(25) {
                let mut insert = db.db_impl.insert(model, columns, chunk, None);
                insert = insert.rollback_transaction();
                let (insert_query, insert_params) = insert.build();

                debug!("SQL: {}", insert_query);

                tx.execute::<Nothing>(insert_query, insert_params).await?;
            }
            Ok(())
        }
    }

    /**
    This method is used to bulk insert rows.

    If one insert statement fails, the complete operation will be rolled back.

    **Parameter**:
    - `model`: Table to insert to
    - `columns`: Columns to set `rows` for.
    - `rows`: List of values to bind to the corresponding columns.
    - `transaction`: Optional transaction to execute the query on.
     */
    pub async fn insert_bulk_returning(
        &self,
        model: &str,
        columns: &[&str],
        rows: &[&[Value<'_>]],
        transaction: Option<&mut Transaction<'_>>,
        returning: &[&str],
    ) -> Result<Vec<Row>, Error> {
        return match transaction {
            None => {
                let mut transaction = self.start_transaction().await?;
                let result =
                    with_transaction(self, &mut transaction, model, columns, rows, returning).await;
                transaction.commit().await?;
                result
            }
            Some(transaction) => {
                with_transaction(self, transaction, model, columns, rows, returning).await
            }
        };
        async fn with_transaction(
            db: &Database,
            tx: &mut Transaction<'_>,
            model: &str,
            columns: &[&str],
            rows: &[&[Value<'_>]],
            returning: &[&str],
        ) -> Result<Vec<Row>, Error> {
            let mut inserted = Vec::with_capacity(rows.len());
            for chunk in rows.chunks(25) {
                let mut insert = db.db_impl.insert(model, columns, chunk, Some(returning));
                insert = insert.rollback_transaction();
                let (insert_query, insert_params) = insert.build();

                debug!("SQL: {}", insert_query);

                inserted.extend(tx.execute::<All>(insert_query, insert_params).await?);
            }
            Ok(inserted)
        }
    }

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'executor> Executor<'executor> for &'executor Database

fn execute<'data, 'result, Q>(
    self,
    query: String,
    values: Vec<Value<'data>>
) -> Q::Result<'result>where
    Q: QueryStrategy,
    'executor: 'result,
    'data: 'result,

Execute a query