Trait diesel_async::RunQueryDsl

pub trait RunQueryDsl<Conn>: Sized {
    // Provided methods
    fn execute<'conn, 'query>(
        self,
        conn: &'conn mut Conn,
    ) -> Conn::ExecuteFuture<'conn, 'query>
       where Conn: AsyncConnection + Send,
             Self: ExecuteDsl<Conn> + 'query { ... }
    fn load<'query, 'conn, U>(
        self,
        conn: &'conn mut Conn,
    ) -> LoadFuture<'conn, 'query, Self, Conn, U>
       where U: Send,
             Conn: AsyncConnection,
             Self: LoadQuery<'query, Conn, U> + 'query { ... }
    fn load_stream<'conn, 'query, U>(
        self,
        conn: &'conn mut Conn,
    ) -> Self::LoadFuture<'conn>
       where Conn: AsyncConnection,
             U: 'conn,
             Self: LoadQuery<'query, Conn, U> + 'query { ... }
    fn get_result<'query, 'conn, U>(
        self,
        conn: &'conn mut Conn,
    ) -> GetResult<'conn, 'query, Self, Conn, U>
       where U: Send + 'conn,
             Conn: AsyncConnection,
             Self: LoadQuery<'query, Conn, U> + 'query { ... }
    fn get_results<'query, 'conn, U>(
        self,
        conn: &'conn mut Conn,
    ) -> LoadFuture<'conn, 'query, Self, Conn, U>
       where U: Send,
             Conn: AsyncConnection,
             Self: LoadQuery<'query, Conn, U> + 'query { ... }
    fn first<'query, 'conn, U>(
        self,
        conn: &'conn mut Conn,
    ) -> GetResult<'conn, 'query, Limit<Self>, Conn, U>
       where U: Send + 'conn,
             Conn: AsyncConnection,
             Self: LimitDsl,
             Limit<Self>: LoadQuery<'query, Conn, U> + Send + 'query { ... }
}

Methods used to execute queries.

Provided Methods

fn execute<'conn, 'query>( self, conn: &'conn mut Conn, ) -> Conn::ExecuteFuture<'conn, 'query>

where Conn: AsyncConnection + Send, Self: ExecuteDsl<Conn> + 'query,

Executes the given command, returning the number of rows affected.

execute is usually used in conjunction with insert_into, update and delete where the number of affected rows is often enough information.

When asking the database to return data from a query, load should probably be used instead.

Example

use diesel_async::RunQueryDsl;

let inserted_rows = insert_into(users)
    .values(name.eq("Ruby"))
    .execute(connection)
    .await?;
assert_eq!(1, inserted_rows);

let inserted_rows = insert_into(users)
    .values(&vec![name.eq("Jim"), name.eq("James")])
    .execute(connection)
    .await?;
assert_eq!(2, inserted_rows);

fn load<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> LoadFuture<'conn, 'query, Self, Conn, U>

where U: Send, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Executes the given query, returning a Vec with the returned rows.

When using the query builder, the return type can be a tuple of the values, or a struct which implements Queryable.

When this method is called on sql_query, the return type can only be a struct which implements QueryableByName

For insert, update, and delete operations where only a count of affected is needed, execute should be used instead.

Examples

Returning a single field

use diesel_async::{RunQueryDsl, AsyncConnection};

let data = users.select(name)
    .load::<String>(connection)
    .await?;
assert_eq!(vec!["Sean", "Tess"], data);

Returning a tuple

use diesel_async::RunQueryDsl;

let data = users
    .load::<(i32, String)>(connection)
    .await?;
let expected_data = vec![
    (1, String::from("Sean")),
    (2, String::from("Tess")),
];
assert_eq!(expected_data, data);

Returning a struct

use diesel_async::RunQueryDsl;

#[derive(Queryable, PartialEq, Debug)]
struct User {
    id: i32,
    name: String,
}

let data = users
    .load::<User>(connection)
    .await?;
let expected_data = vec![
    User { id: 1, name: String::from("Sean") },
    User { id: 2, name: String::from("Tess") },
];
assert_eq!(expected_data, data);

fn load_stream<'conn, 'query, U>( self, conn: &'conn mut Conn, ) -> Self::LoadFuture<'conn>

where Conn: AsyncConnection, U: 'conn, Self: LoadQuery<'query, Conn, U> + 'query,

Executes the given query, returning a Stream with the returned rows.

You should normally prefer to use RunQueryDsl::load instead. This method is provided for situations where the result needs to be collected into a different container than a Vec

When using the query builder, the return type can be a tuple of the values, or a struct which implements Queryable.

When this method is called on sql_query, the return type can only be a struct which implements QueryableByName

For insert, update, and delete operations where only a count of affected is needed, execute should be used instead.

Examples

Returning a single field

use diesel_async::RunQueryDsl;

let data = users.select(name)
    .load_stream::<String>(connection)
    .await?
    .try_fold(Vec::new(), |mut acc, item| {
         acc.push(item);
         futures_util::future::ready(Ok(acc))
     })
    .await?;
assert_eq!(vec!["Sean", "Tess"], data);

Returning a tuple

use diesel_async::RunQueryDsl;
let data = users
    .load_stream::<(i32, String)>(connection)
    .await?
    .try_fold(Vec::new(), |mut acc, item| {
         acc.push(item);
         futures_util::future::ready(Ok(acc))
     })
    .await?;
let expected_data = vec![
    (1, String::from("Sean")),
    (2, String::from("Tess")),
];
assert_eq!(expected_data, data);

Returning a struct

use diesel_async::RunQueryDsl;

#[derive(Queryable, PartialEq, Debug)]
struct User {
    id: i32,
    name: String,
}

let data = users
    .load_stream::<User>(connection)
    .await?
    .try_fold(Vec::new(), |mut acc, item| {
         acc.push(item);
         futures_util::future::ready(Ok(acc))
     })
    .await?;
let expected_data = vec![
    User { id: 1, name: String::from("Sean") },
    User { id: 2, name: String::from("Tess") },
];
assert_eq!(expected_data, data);

fn get_result<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> GetResult<'conn, 'query, Self, Conn, U>

where U: Send + 'conn, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Runs the command, and returns the affected row.

Err(NotFound) will be returned if the query affected 0 rows. You can call .optional() on the result of this if the command was optional to get back a Result<Option<U>>

When this method is called on an insert, update, or delete statement, it will implicitly add a RETURNING * to the query, unless a returning clause was already specified.

This method only returns the first row that was affected, even if more rows are affected.

Example

use diesel_async::RunQueryDsl;

let inserted_row = insert_into(users)
    .values(name.eq("Ruby"))
    .get_result(connection)
    .await?;
assert_eq!((3, String::from("Ruby")), inserted_row);

// This will return `NotFound`, as there is no user with ID 4
let update_result = update(users.find(4))
    .set(name.eq("Jim"))
    .get_result::<(i32, String)>(connection)
    .await;
assert_eq!(Err(diesel::NotFound), update_result);

fn get_results<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> LoadFuture<'conn, 'query, Self, Conn, U>

where U: Send, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Runs the command, returning an Vec with the affected rows.

This method is an alias for load, but with a name that makes more sense for insert, update, and delete statements.

fn first<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> GetResult<'conn, 'query, Limit<Self>, Conn, U>

where U: Send + 'conn, Conn: AsyncConnection, Self: LimitDsl, Limit<Self>: LoadQuery<'query, Conn, U> + Send + 'query,

Attempts to load a single record.

This method is equivalent to .limit(1).get_result()

Returns Ok(record) if found, and Err(NotFound) if no results are returned. If the query truly is optional, you can call .optional() on the result of this to get a Result<Option<U>>.

Example:

use diesel_async::RunQueryDsl;

for n in &["Sean", "Pascal"] {
    diesel::insert_into(users)
        .values(name.eq(n))
        .execute(connection)
        .await?;
}

let first_name = users.order(id)
    .select(name)
    .first(connection)
    .await;
assert_eq!(Ok(String::from("Sean")), first_name);

let not_found = users
    .filter(name.eq("Foo"))
    .first::<(i32, String)>(connection)
    .await;
assert_eq!(Err(diesel::NotFound), not_found);

Object Safety

This trait is not object safe.

Implementors

impl<T, Conn> RunQueryDsl<Conn> for T