Trait tokio_postgres_extractor::Extract

pub trait Extract<'row>: Columns + Sized {
    // Required method
    fn extract_with_columns(
        columns: &<Self as Columns>::Columns,
        row: &'row Row
    ) -> Self;

    // Provided methods
    fn extract_once(row: &'row Row) -> Self { ... }
    fn extract(
        columns: &mut Option<<Self as Columns>::Columns>,
        row: &'row Row
    ) -> Self { ... }
}

A type that can be extracted from a Row.

This trait is usually derived:

#[derive(Columns, Extract)]
struct User<'a> {
    id: i32,
    name: &'a str,
}

Most of the time you will not use this trait directly but one of the utility functions:

• IterExtractExt::extract
• IterExtractRefExt::extract_ref
• RowStreamExtractExt::extract
• RowStreamExtractExt::extract_mut

Examples

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

async fn get_user(client: &Client, id: u32) -> Result<User, Error> {
    client
        .query_one("select * from user where id = $1", &[&id])
        .await
        .map(|r| User::extract_once(&r))
}

Required Methods

fn extract_with_columns( columns: &<Self as Columns>::Columns, row: &'row Row ) -> Self

Extracts an instance of the type from a Row and a mapping between the fields and columns.

This function is usually derived with the Extract proc macro. In this case the implementation looks as follows:

#[derive(Columns)]
struct User<'a> {
    id: i32,
    name: &'a str,
}

impl<'a, 'row> Extract<'row> for User<'a>
where
    i32: FromSql<'row>,
    &'a str: FromSql<'row>,
{
    fn extract_with_columns(columns: &Self::Columns, row: &'row Row) -> Self {
        Self {
            id: row.get(columns[0]),
            name: row.get(columns[1]),
        }
    }
}

Panics

Panics if Row::get panics.

Provided Methods

fn extract_once(row: &'row Row) -> Self

Extracts an instance of the type from a Row.

If the implementation of Columns was derived, then this function is almost always faster than manually calling Row::get with the column names. Usually it is much faster.

However, if you are extracting more than one row at at time, then you will want to instead call

• Extract::extract,
• IterExtractExt::extract,
• IterExtractRefExt::extract_ref,
• RowStreamExtractExt::extract, or
• RowStreamExtractExt::extract_mut.

These function memorize the output of Columns::columns and are often 2x as fast per row as this function.

Panics

Panics if Columns::columns or Row::get panics.

Examples

#[derive(Columns, Extract)]
struct User<'a> {
    id: i32,
    name: &'a str,
}

fn map_user(row: &Row) -> User<'_> {
    User::extract_once(row)
}

fn extract( columns: &mut Option<<Self as Columns>::Columns>, row: &'row Row ) -> Self

Extracts an instance of the type from a Row, memorizing the mapping between fields and columns.

If you call this function multiple times with a memorized mapping, then you should make sure that the columns in the rows are in the same order. This is always the case if the rows were produced by a single SQL statement. Otherwise this function might panic or the mapping might be incorrect.

Often you will want to call

• IterExtractExt::extract,
• IterExtractRefExt::extract_ref,
• RowStreamExtractExt::extract, or
• RowStreamExtractExt::extract_mut.

instead, which hide the memorization behind and abstraction.

Panics

Panics if Columns::columns or Row::get panics.

Examples

#[derive(Columns, Extract)]
struct User<'a> {
    id: i32,
    name: &'a str,
}

fn map_users(rows: &[Row]) -> Vec<User<'_>> {
    let mut columns = None;
    rows.iter().map(|row| User::extract(&mut columns, row)).collect()
}

Implementors