Trait RunQueryDsl

pub trait RunQueryDsl<Conn>: Sized {
    // Provided methods
    fn execute(self, conn: &mut Conn) -> QueryResult<usize>
       where Conn: Connection,
             Self: ExecuteDsl<Conn> { ... }
    fn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>
       where Self: LoadQuery<'query, Conn, U> { ... }
    fn load_iter<'conn, 'query: 'conn, U, B>(
        self,
        conn: &'conn mut Conn,
    ) -> QueryResult<Self::RowIter<'conn>>
       where U: 'conn,
             Self: LoadQuery<'query, Conn, U, B> + 'conn { ... }
    fn get_result<'query, U>(self, conn: &mut Conn) -> QueryResult<U>
       where Self: LoadQuery<'query, Conn, U> { ... }
    fn get_results<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>
       where Self: LoadQuery<'query, Conn, U> { ... }
    fn first<'query, U>(self, conn: &mut Conn) -> QueryResult<U>
       where Self: LimitDsl,
             Limit<Self>: LoadQuery<'query, Conn, U> { ... }
}

Methods used to execute queries.

Provided Methods

fn execute(self, conn: &mut Conn) -> QueryResult<usize>

where Conn: Connection, Self: ExecuteDsl<Conn>,

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

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

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

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

where Self: LoadQuery<'query, Conn, U>,

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.

How to resolve compiler errors while loading data from the database

In case you getting uncomprehensable compiler errors while loading data from the database into a type using #[derive(Queryable)] you might want to consider using #[derive(Selectable)] + #[diesel(check_for_backend(YourBackendType))] to check for mismatching fields at compile time. This drastically improves the quality of the generated error messages by pointing to concrete type mismatches at field level.You need to specify the concrete database backend this specific struct is indented to be used with, as otherwise rustc cannot correctly identify the required deserialization implementation.

Examples

Returning a single field

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

Returning a tuple

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

Returning a struct

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

let data = users
    .load::<User>(connection)?;
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_iter<'conn, 'query: 'conn, U, B>( self, conn: &'conn mut Conn, ) -> QueryResult<Self::RowIter<'conn>>

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

Executes the given query, returning an Iterator with the returned rows.

The iterator’s item is QueryResult<U>.

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. This type is specified by the first generic type of this function.

The second generic type parameter specifies the so called loading mode, which describes how the connection implementation loads data from the database. All connections should provide a implementation for DefaultLoadingMode.

They may provide additional modes. Checkout the documentation of the concrete connection types for details. For connection implementations that provide more than one loading mode it is required to specify this generic parameter. This is currently true for PgConnection.

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::connection::DefaultLoadingMode;

let data = users.select(name)
    .load_iter::<String, DefaultLoadingMode>(connection)?
    .collect::<QueryResult<Vec<_>>>()?;
assert_eq!(vec!["Sean", "Tess"], data);

Returning a tuple

use diesel::connection::DefaultLoadingMode;

let data = users
    .load_iter::<(i32, String), DefaultLoadingMode>(connection)?
    .collect::<QueryResult<Vec<_>>>()?;
let expected_data = vec![
    (1, String::from("Sean")),
    (2, String::from("Tess")),
];
assert_eq!(expected_data, data);

Returning a struct

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

use diesel::connection::DefaultLoadingMode;

let data = users
    .load_iter::<User, DefaultLoadingMode>(connection)?
    .collect::<QueryResult<Vec<_>>>()?;
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, U>(self, conn: &mut Conn) -> QueryResult<U>

where Self: LoadQuery<'query, Conn, U>,

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

let inserted_row = insert_into(users)
    .values(name.eq("Ruby"))
    .get_result(connection)?;
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);
assert_eq!(Err(diesel::NotFound), update_result);

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

where Self: LoadQuery<'query, Conn, U>,

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, U>(self, conn: &mut Conn) -> QueryResult<U>

where Self: LimitDsl, Limit<Self>: LoadQuery<'query, Conn, U>,

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:

diesel::insert_into(users)
    .values(&vec![name.eq("Sean"), name.eq("Pascal")])
    .execute(connection)?;

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

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<Conn: Connection, Query> RunQueryDsl<Conn> for BoxedSqlQuery<'_, Conn::Backend, Query>

impl<F, S, D, W, O, LOf, G, H, LC, Conn> RunQueryDsl<Conn> for SelectStatement<F, S, D, W, O, LOf, G, H, LC>

impl<Inner, Conn> RunQueryDsl<Conn> for SqlQuery<Inner>

impl<Query, Value, Conn> RunQueryDsl<Conn> for UncheckedBind<Query, Value>

impl<S: AliasSource, Conn> RunQueryDsl<Conn> for Alias<S>

impl<ST, QS, DB, Conn, GB> RunQueryDsl<Conn> for BoxedSelectStatement<'_, ST, QS, DB, GB>

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

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

where T: Table,

impl<T, U, Ret, Conn> RunQueryDsl<Conn> for DeleteStatement<T, U, Ret>

where T: QuerySource,

impl<T: QuerySource, U, Op, Ret, Conn> RunQueryDsl<Conn> for InsertStatement<T, U, Op, Ret>

impl<T: QuerySource, U, V, Ret, Conn> RunQueryDsl<Conn> for UpdateStatement<T, U, V, Ret>