pub trait Queryable<ST, DB> where
    DB: Backend
{ type Row: FromSqlRow<ST, DB>; fn build(row: Self::Row) -> Self; }
Expand description

Trait indicating that a record can be queried from the database.

Types which implement Queryable represent the result of a SQL query. This does not necessarily mean they represent a single database table.

Diesel represents the return type of a query as a tuple. The purpose of this trait is to convert from a tuple of Rust values that have been deserialized into your struct.

Deriving

This trait can be derived automatically using #[derive(Queryable)]. This trait can only be derived for structs, not enums.

When this trait is derived, it will assume that the order of fields on your struct match the order of the fields in the query. This means that field order is significant if you are using #[derive(Queryable)]. Field name has no effect.

To provide custom deserialization behavior for a field, you can use #[diesel(deserialize_as = "Type")]. If this attribute is present, Diesel will deserialize into that type, rather than the type on your struct and call .into to convert it. This can be used to add custom behavior for a single field, or use types that are otherwise unsupported by Diesel.

Examples

If we just want to map a query to our struct, we can use derive.

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

let first_user = users.first(&connection)?;
let expected = User { id: 1, name: "Sean".into() };
assert_eq!(expected, first_user);

If we want to do additional work during deserialization, we can use deserialize_as to use a different implementation.

struct LowercaseString(String);

impl Into<String> for LowercaseString {
    fn into(self) -> String {
        self.0
    }
}

impl<DB, ST> Queryable<ST, DB> for LowercaseString
where
    DB: Backend,
    String: Queryable<ST, DB>,
{
    type Row = <String as Queryable<ST, DB>>::Row;

    fn build(row: Self::Row) -> Self {
        LowercaseString(String::build(row).to_lowercase())
    }
}

#[derive(Queryable, PartialEq, Debug)]
struct User {
    id: i32,
    #[diesel(deserialize_as = "LowercaseString")]
    name: String,
}

let first_user = users.first(&connection)?;
let expected = User { id: 1, name: "sean".into() };
assert_eq!(expected, first_user);

Alternatively, we can implement the trait for our struct manually.

use schema::users;
use diesel::deserialize::Queryable;

type DB = diesel::sqlite::Sqlite;

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

impl Queryable<users::SqlType, DB> for User {
    type Row = (i32, String);

    fn build(row: Self::Row) -> Self {
        User {
            id: row.0,
            name: row.1.to_lowercase(),
        }
    }
}

let first_user = users.first(&connection)?;
let expected = User { id: 1, name: "sean".into() };
assert_eq!(expected, first_user);

Associated Types

The Rust type you’d like to map from.

This is typically a tuple of all of your struct’s fields.

Required methods

Construct an instance of this type

Implementations on Foreign Types

Implementors