Struct QueryBuilder

pub struct QueryBuilder<'q, T, DB: Database> {
    pub conditions: Vec<String>,
    pub arguments: DB::Arguments<'q>,
    /* private fields */
}

Fields

conditions: Vec<String>

arguments: DB::Arguments<'q>

Implementations

impl<T> QueryBuilder<'_, T, Postgres>

where T: Default + Serialize,

pub fn new() -> Self

impl<'q, T, DB> QueryBuilder<'q, T, DB>

where T: Default + Serialize, DB: Database, String: for<'a> Encode<'a, DB> + Type<DB>,

pub fn with_search(self, params: &QueryParams<'_, T>) -> Self

Adds search functionality to the query by creating LIKE conditions for specified columns.

Arguments

• params - Query parameters containing search text and columns to search in

Details

• Only searches in columns that are both specified and considered safe
• Creates case-insensitive LIKE conditions with wildcards
• Multiple search columns are combined with OR operators
• Empty search text or no valid columns results in no conditions being added

Returns

Returns self for method chaining

Example

use sqlx::Postgres;
use serde::{Serialize};
use sqlx_paginated::{QueryBuilder, QueryParamsBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let initial_params = QueryParamsBuilder::<UserExample>::new()
        .with_search("john", vec!["name", "email"])
        .build();
let query_builder = QueryBuilder::<UserExample, Postgres>::new()
    .with_search(&initial_params)
    .build();

pub fn with_filters(self, params: &'q QueryParams<'_, T>) -> Self

Adds equality filters to the query based on provided key-value pairs.

Arguments

• params - Query parameters containing filters as key-value pairs

Details

• Only applies filters for columns that exist and are considered safe
• Automatically handles type casting based on the database dialect
• Skips invalid columns with a warning when tracing is enabled
• Null or empty values are ignored

Returns

Returns self for method chaining

Example

use sqlx::Postgres;
use serde::{Serialize};
use sqlx_paginated::{QueryBuilder, QueryParamsBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let initial_params = QueryParamsBuilder::<UserExample>::new()
        .with_search("john", vec!["name", "email"])
        .build();

let query_builder = QueryBuilder::<UserExample, Postgres>::new()
    .with_filters(&initial_params)
    .build();

pub fn with_date_range(self, params: &'q QueryParams<'_, T>) -> Self

where DateTime<Utc>: for<'a> Encode<'a, DB> + Type<DB>,

Adds date range conditions to the query for a specified date column.

Arguments

• params - Query parameters containing date range information

Type Parameters

Requires DateTime<Utc> to be encodable for the target database

Details

• Adds >= condition for date_after if specified
• Adds <= condition for date_before if specified
• Only applies to columns that exist and are considered safe
• Skips invalid date columns with a warning when tracing is enabled

Returns

Returns self for method chaining

Example

use sqlx::Postgres;
use serde::{Serialize};
use chrono::{DateTime};
use sqlx_paginated::{QueryBuilder, QueryParamsBuilder, QueryParams};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let initial_params = QueryParamsBuilder::<UserExample>::new()
        .with_date_range(None, Some(DateTime::parse_from_rfc3339("2024-12-31T23:59:59Z").unwrap().into()), Some("deleted_at"))
        .build();
let query_builder = QueryBuilder::<UserExample, Postgres>::new()
    .with_date_range(&initial_params)
    .build();

pub fn with_condition( self, column: &str, condition: impl Into<String>, value: String, ) -> Self

Adds a custom condition for a specific column with a provided operator and value.

Arguments

• column - The column name to apply the condition to
• condition - The operator or condition to use (e.g., “>”, “LIKE”, etc.)
• value - The value to compare against

Details

• Only applies to columns that exist and are considered safe
• Automatically handles parameter binding
• Skips invalid columns with a warning when tracing is enabled

Returns

Returns self for method chaining

Example

use sqlx::Postgres;
use serde::{Serialize};
use sqlx_paginated::{QueryBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let query_builder = QueryBuilder::<UserExample, Postgres>::new()
    .with_condition("age", ">", "18".to_string())
    .build();

pub fn with_raw_condition(self, condition: impl Into<String>) -> Self

Adds a raw SQL condition to the query without any safety checks.

Arguments

• condition - Raw SQL condition to add to the query

Safety

This method bypasses column safety checks. Use with caution to prevent SQL injection.

Returns

Returns self for method chaining

Example

use sqlx::Postgres;
use serde::{Serialize};
use sqlx_paginated::{QueryBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let query_builder = QueryBuilder::<UserExample, Postgres>::new()
    .with_raw_condition("status != 'deleted'")
    .build();

pub fn with_combined_conditions<F>(self, f: F) -> Self

where F: FnOnce(&mut QueryBuilder<'_, T, DB>),

Allows adding multiple conditions using a closure.

Arguments

• f - Closure that takes a mutable reference to the QueryBuilder

Details

Useful for grouping multiple conditions that are logically related

Returns

Returns self for method chaining

Example

use sqlx::Postgres;
use serde::{Serialize};
use sqlx_paginated::{QueryBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}
let query_builder = QueryBuilder::<UserExample, Postgres>::new()
    .with_combined_conditions(|builder| {
        builder.conditions.push("status = 'active'".to_string());
        builder.conditions.push("age >= 18".to_string());
    })
    .build();

pub fn disable_protection(self) -> Self

Disables column protection for this query builder instance.

Safety

This removes all column safety checks. Use with caution as it may expose the application to SQL injection if used with untrusted input.

Returns

Returns self for method chaining

Example

use sqlx::Postgres;
use serde::{Serialize};
use sqlx_paginated::{QueryBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let query_builder = QueryBuilder::<UserExample, Postgres>::new()
    .disable_protection()
    .with_raw_condition("custom_column = 'value'")
    .build();

pub fn build(self) -> (Vec<String>, DB::Arguments<'q>)

Builds the final query conditions and arguments.

Returns

Returns a tuple containing:

• Vec: List of SQL conditions
• DB::Arguments: Database-specific arguments for parameter binding

Example

use sqlx::Postgres;
use serde::{Serialize};
use sqlx_paginated::{QueryBuilder, QueryParamsBuilder};

#[derive(Serialize, Default)]
struct UserExample {
    name: String
}

let initial_params = QueryParamsBuilder::<UserExample>::new()
        .with_search("john", vec!["name", "email"])
        .build();
let (conditions, arguments) = QueryBuilder::<UserExample, Postgres>::new()
    .with_search(&initial_params)
    .build();

Trait Implementations

impl<T> Default for QueryBuilder<'_, T, Postgres>

where T: Default + Serialize,

fn default() -> Self

Returns the “default value” for a type.