Trait Queryable

Source

pub trait Queryable<ST, DB>: Sizedwhere
    DB: Backend,{
    type Row: FromStaticSqlRow<ST, DB>;

    // Required method
    fn build(row: Self::Row) -> Result<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.

This trait can be derived

§How to resolve compiler errors while loading data from the database

In case you getting uncomprehensable compiler errors while loading data from the database 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 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.

§Interaction with `NULL`/`Option`

Nullable types can be queried into Option. This is valid for single fields, tuples, and structures with Queryable.

With tuples and structs, the process for deserializing an Option<(A,B,C)> is to attempt to deserialize A, B and C, and if either of these return an UnexpectedNullError, the Option will be deserialized as None. If all succeed, the Option will be deserialized as Some((a,b,c)).

§Examples

§Simple mapping from query to struct

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.order_by(id).first(connection)?;
let expected = User {
    id: 1,
    name: "Sean".into(),
};
assert_eq!(expected, first_user);

§Interaction with `NULL`/`Option`

§Single field

table! {
    animals {
        id -> Integer,
        species -> VarChar,
        legs -> Integer,
        name -> Nullable<VarChar>,
    }
}
#[derive(Queryable, PartialEq, Debug)]
struct Animal {
    id: i32,
    name: Option<String>,
}

let all_animals = animals.select((id, name)).order_by(id).load(connection)?;
let expected = vec![
    Animal {
        id: 1,
        name: Some("Jack".to_owned()),
    },
    Animal { id: 2, name: None },
];
assert_eq!(expected, all_animals);

§Multiple fields

#[derive(Queryable, PartialEq, Debug)]
struct UserWithPost {
    id: i32,
    post: Option<Post>,
}
#[derive(Queryable, PartialEq, Debug)]
struct Post {
    id: i32,
    title: String,
}

let all_posts = users::table
    .left_join(posts::table)
    .select((users::id, (posts::id, posts::title).nullable()))
    .order_by((users::id, posts::id))
    .load(connection)?;
let expected = vec![
    UserWithPost {
        id: 1,
        post: Some(Post {
            id: 1,
            title: "My first post".to_owned(),
        }),
    },
    UserWithPost {
        id: 1,
        post: Some(Post {
            id: 2,
            title: "About Rust".to_owned(),
        }),
    },
    UserWithPost {
        id: 2,
        post: Some(Post {
            id: 3,
            title: "My first post too".to_owned(),
        }),
    },
    UserWithPost { id: 3, post: None },
];
assert_eq!(expected, all_posts);

§`deserialize_as` attribute

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> Queryable<Text, DB> for LowercaseString
where
    DB: Backend,
    String: FromSql<Text, DB>,
{
    type Row = String;

    fn build(s: String) -> deserialize::Result<Self> {
        Ok(LowercaseString(s.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);

§Manual implementation

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

use diesel::deserialize::{self, Queryable};
use schema::users;

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) -> deserialize::Result<Self> {
        Ok(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);

Required Associated Types§

Source

type Row: FromStaticSqlRow<ST, DB>

The Rust type you’d like to map from.

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

Required Methods§

Source

fn build(row: Self::Row) -> Result<Self>

Construct an instance of this type

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.

Trait Queryable Copy item path

§How to resolve compiler errors while loading data from the database

§Interaction with NULL/Option

§Examples

§Simple mapping from query to struct

§Interaction with NULL/Option

§Single field

§Multiple fields

§deserialize_as attribute

§Manual implementation

Required Associated Types§

type Row: FromStaticSqlRow<ST, DB>

Required Methods§

fn build(row: Self::Row) -> Result<Self>

Dyn Compatibility§

Implementations on Foreign Types§

impl Queryable<Binary, Mysql> for *const [u8]

type Row = *const [u8]

fn build(row: Self::Row) -> Result<Self>

impl Queryable<Binary, Pg> for *const [u8]

type Row = *const [u8]

fn build(row: Self::Row) -> Result<Self>

impl Queryable<Binary, Sqlite> for *const [u8]

type Row = *const [u8]

fn build(row: Self::Row) -> Result<Self>

impl Queryable<Text, Mysql> for *const str

type Row = *const str

fn build(row: Self::Row) -> Result<Self>

impl Queryable<Text, Pg> for *const str

type Row = *const str

fn build(row: Self::Row) -> Result<Self>

impl Queryable<Text, Sqlite> for *const str

type Row = *const str

fn build(row: Self::Row) -> Result<Self>

impl<'a, T, ST, DB> Queryable<ST, DB> for Cow<'a, T>where T: 'a + ToOwned + ?Sized, ST: SingleValue, DB: Backend, Self: FromSql<ST, DB>,

type Row = Cow<'a, T>

fn build(row: Self::Row) -> Result<Self>

impl<ST, T, DB> Queryable<ST, DB> for Option<T>where ST: SingleValue<IsNull = IsNullable>, DB: Backend, Self: FromSql<ST, DB>,

type Row = Option<T>

fn build(row: Self::Row) -> Result<Self>

impl<T, ST> Queryable<Range<ST>, Pg> for (Bound<T>, Bound<T>)where T: FromSql<ST, Pg> + Defaultable,

type Row = (Bound<T>, Bound<T>)

fn build(row: Self) -> Result<Self>

impl<T, ST> Queryable<Record<(ST,)>, Pg> for (T,)where Self: FromSql<Record<(ST,)>, Pg>,

type Row = (T,)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, ST, ST1> Queryable<Record<(ST, ST1)>, Pg> for (T, T1)where Self: FromSql<Record<(ST, ST1)>, Pg>,

type Row = (T, T1)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, ST, ST1, ST2> Queryable<Record<(ST, ST1, ST2)>, Pg> for (T, T1, T2)where Self: FromSql<Record<(ST, ST1, ST2)>, Pg>,

type Row = (T, T1, T2)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, T3, ST, ST1, ST2, ST3> Queryable<Record<(ST, ST1, ST2, ST3)>, Pg> for (T, T1, T2, T3)where Self: FromSql<Record<(ST, ST1, ST2, ST3)>, Pg>,

type Row = (T, T1, T2, T3)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, T3, T4, ST, ST1, ST2, ST3, ST4> Queryable<Record<(ST, ST1, ST2, ST3, ST4)>, Pg> for (T, T1, T2, T3, T4)where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4)>, Pg>,

type Row = (T, T1, T2, T3, T4)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, T3, T4, T5, ST, ST1, ST2, ST3, ST4, ST5> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5)>, Pg> for (T, T1, T2, T3, T4, T5)where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5)>, Pg>,

type Row = (T, T1, T2, T3, T4, T5)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, T3, T4, T5, T6, ST, ST1, ST2, ST3, ST4, ST5, ST6> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6)>, Pg> for (T, T1, T2, T3, T4, T5, T6)where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6)>, Pg>,

type Row = (T, T1, T2, T3, T4, T5, T6)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, T3, T4, T5, T6, T7, ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7)>, Pg> for (T, T1, T2, T3, T4, T5, T6, T7)where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7)>, Pg>,

type Row = (T, T1, T2, T3, T4, T5, T6, T7)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, T3, T4, T5, T6, T7, T8, ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8)>, Pg> for (T, T1, T2, T3, T4, T5, T6, T7, T8)where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8)>, Pg>,

type Row = (T, T1, T2, T3, T4, T5, T6, T7, T8)

fn build(row: Self::Row) -> Result<Self>

impl<T, T1, T2, T3, T4, T5, T6, T7, T8, T9, ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8, ST9> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8, ST9)>, Pg> for (T, T1, T2, T3, T4, T5, T6, T7, T8, T9)where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8, ST9)>, Pg>,

type Row = (T, T1, T2, T3, T4, T5, T6, T7, T8, T9)

fn build(row: Self::Row) -> Result<Self>

type Row = (T, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)

fn build(row: Self::Row) -> Result<Self>

type Row = (T, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11)

fn build(row: Self::Row) -> Result<Self>

type Row = (T, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12)

fn build(row: Self::Row) -> Result<Self>

type Row = (T, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13)

Trait Queryable

§Interaction with `NULL`/`Option`

§Interaction with `NULL`/`Option`

§`deserialize_as` attribute

impl<'a, T, ST, DB> Queryable<ST, DB> for Cow<'a, T>
where T: 'a + ToOwned + ?Sized, ST: SingleValue, DB: Backend, Self: FromSql<ST, DB>,

impl<ST, T, DB> Queryable<ST, DB> for Option<T>
where ST: SingleValue<IsNull = IsNullable>, DB: Backend, Self: FromSql<ST, DB>,

impl<T, ST> Queryable<Range<ST>, Pg> for (Bound<T>, Bound<T>)
where T: FromSql<ST, Pg> + Defaultable,

impl<T, ST> Queryable<Record<(ST,)>, Pg> for (T,)
where Self: FromSql<Record<(ST,)>, Pg>,

impl<T, T1, ST, ST1> Queryable<Record<(ST, ST1)>, Pg> for (T, T1)
where Self: FromSql<Record<(ST, ST1)>, Pg>,

impl<T, T1, T2, ST, ST1, ST2> Queryable<Record<(ST, ST1, ST2)>, Pg> for (T, T1, T2)
where Self: FromSql<Record<(ST, ST1, ST2)>, Pg>,

impl<T, T1, T2, T3, ST, ST1, ST2, ST3> Queryable<Record<(ST, ST1, ST2, ST3)>, Pg> for (T, T1, T2, T3)
where Self: FromSql<Record<(ST, ST1, ST2, ST3)>, Pg>,

impl<T, T1, T2, T3, T4, ST, ST1, ST2, ST3, ST4> Queryable<Record<(ST, ST1, ST2, ST3, ST4)>, Pg> for (T, T1, T2, T3, T4)
where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4)>, Pg>,

impl<T, T1, T2, T3, T4, T5, ST, ST1, ST2, ST3, ST4, ST5> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5)>, Pg> for (T, T1, T2, T3, T4, T5)
where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5)>, Pg>,

impl<T, T1, T2, T3, T4, T5, T6, ST, ST1, ST2, ST3, ST4, ST5, ST6> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6)>, Pg> for (T, T1, T2, T3, T4, T5, T6)
where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6)>, Pg>,

impl<T, T1, T2, T3, T4, T5, T6, T7, ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7)>, Pg> for (T, T1, T2, T3, T4, T5, T6, T7)
where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7)>, Pg>,

impl<T, T1, T2, T3, T4, T5, T6, T7, T8, ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8)>, Pg> for (T, T1, T2, T3, T4, T5, T6, T7, T8)
where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8)>, Pg>,

impl<T, T1, T2, T3, T4, T5, T6, T7, T8, T9, ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8, ST9> Queryable<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8, ST9)>, Pg> for (T, T1, T2, T3, T4, T5, T6, T7, T8, T9)
where Self: FromSql<Record<(ST, ST1, ST2, ST3, ST4, ST5, ST6, ST7, ST8, ST9)>, Pg>,

impl<T, DB, ST> Queryable<(ST,), DB> for (T₁, T₂, …, Tₙ)
where DB: Backend, Self: FromStaticSqlRow<(ST,), DB>,