#diesel #pagination #filter #json #rocket

diesel_filter

Diesel filter is a quick way to add filters and pagination to your diesel models

3 releases

0.1.2 Jan 12, 2022
0.1.1 Nov 10, 2021
0.1.0 Aug 13, 2021

#149 in Database interfaces

Download history 1/week @ 2021-10-01 3/week @ 2021-10-08 9/week @ 2021-10-15 4/week @ 2021-10-22 1/week @ 2021-10-29 24/week @ 2021-11-05 13/week @ 2021-11-12 16/week @ 2021-11-19 5/week @ 2021-11-26 22/week @ 2021-12-03 35/week @ 2021-12-10 16/week @ 2021-12-17 29/week @ 2021-12-31 56/week @ 2022-01-07 18/week @ 2022-01-14

106 downloads per month

MIT/Apache

6KB
123 lines

Diesel Filter

Diesel filter is a quick way to add filters and pagination to your diesel models. Works with Diesel and Postgres.

Crate features

  • rocket Derives FromForm on the generated filter struct (See this example)
  • actix Derives Deserialize on the generated filter struct (See this example)
  • pagination Adds the Paginate trait (See this example)
  • serialize with pagination Adds the PaginatedPayload trait that can directly be sent to your client

Usage & Examples

Cargo.toml

diesel_filter = { path = "../../diesel_filter/core", features = ["pagination", "serialize", "rocket"] }

Derive your struct with DieselFilter and annotate the fields that will be used as filters. The top level annotation #[table_name = "db_table"] is mandatory.

#[derive(Queryable, DieselFilter)]
#[table_name = "projects"]
pub struct Project {
    pub id: Uuid,
    #[filter(substring, insensitive)]
    pub name: String,
    #[filter(substring)]
    pub owner_email: String,
    #[filter]
    pub owner_id: Uuid,
    pub created_at: NaiveDateTime,
}

The #[filter] annotation can receive the kinds of filter you want to apply on it, for the moment, there is only substring and insensitive.

A struct for the filtering data will be generated with the name [YourStructName]Filters, e.g: ProjectFilters. Two methods will be generated (let's keep Project as an example):

pub fn filter<'a>(filters: &'a ProjectFilters) -> BoxedQuery<'a, Pg>

and

pub fn filtered(filters: &ProjectFilters, conn: &PgConnection) -> Result<Vec<Project>, Error>

The filter method can be used in conjunction with other diesel methods like inner_join and such.

Project::filter(&filters)
    .inner_join(clients::table)
    .select((projects::id, clients::name))
    .load::<ProjectResponse>(conn)

With Rocket

With the rocket feature, the generated struct can be obtained from the request query parameters (dot notation ?filters.name=xxx)

use diesel_filter::PaginatedPayload;

#[get("/?<filters>")]
async fn index(filters: ClientFilters, conn: DbConn) -> Result<Json<PaginatedPayload<Client>>, Error> {
    Ok(Json(
        conn.run(move |conn| Client::filtered(&filters, conn))
            .await?
            .into(),
    ))
}

With Actix

With the actix feature, the generated struct can be obtained from the request query parameters

N.B: unlike the rocket integration, the query parameters must be sent unscopped. e.g ?field=xxx&other=1

use diesel_filter::PaginatedPayload;

#[get("/?<filters>")]
async fn index(filters: web::Query(ClientFilters), conn: DbConn) -> Result<Json<PaginatedPayload<Client>>, Error> {
    Ok(Json(
        conn.run(move |conn| Client::filtered(&filters, conn))
            .await?
            .into(),
    ))
}

With Pagination

With the pagination feature, you have access to the methods paginate, per_page and load_and_count

use diesel_filter::Paginate;

Project::filter(&filters)
    .inner_join(clients::table)
    .select((projects::id, clients::name))
    .paginate(filters.page)
    .per_page(filters.per_page)
    .load_and_count::<ProjectResponse>(conn)

These are independent of the #[pagination] annotation that you can add on your struct to add page and per_page to your generated filter struct and change the signature of the filtered method.

#[derive(Queryable, DieselFilter)]
#[table_name = "projects"]
#[pagination]
pub struct Project

To convert this into Json, with the feature flag serialize you can use PaginatedPayload.

pub struct PaginatedPayload<T> {
    data: Vec<T>,
    total: i64,
}
#[get("/?<filters>")]
async fn index(filters: ProjectFilters, conn: DbConn) -> Result<Json<PaginatedPayload<Project>>, Error> {
    Ok(Json(
        conn.run(move |conn| Project::filtered(&filters))
        .await
        .into(),
    ))
}

License

Diesel filter is licensed under either of the following, at your option:

Dependencies

~0.3–1MB
~25K SLoC

^a