Struct QueryBuilder 

pub struct QueryBuilder<M = ()> { /* private fields */ }

Query builder for constructing database queries

Implementations

impl<M> QueryBuilder<M>

pub fn new() -> Self

Create a new query builder

impl<M> QueryBuilder<M>

pub fn insert_into(self, table: &str) -> Self

Start an INSERT query

pub fn update(self, table: &str) -> Self

Start an UPDATE query

pub fn delete_from(self, table: &str) -> Self

Start a DELETE query

pub fn set<T: Into<Value>>(self, column: &str, value: T) -> Self

Set a column value (for INSERT/UPDATE)

pub fn set_null(self, column: &str) -> Self

Set a column to NULL (for INSERT/UPDATE)

pub fn set_values(self, values: Vec<(String, Value)>) -> Self

Set multiple values at once

pub fn upsert( self, table: &str, conflict_columns: Vec<&str>, ) -> UpsertBuilder<M>

Upsert operation (INSERT … ON CONFLICT UPDATE)

impl<M: Model> QueryBuilder<M>

pub async fn get(self, pool: &Pool<Postgres>) -> ModelResult<Vec<M>>

Execute query and return models

pub async fn chunk<F>( self, pool: &Pool<Postgres>, chunk_size: i64, callback: F, ) -> ModelResult<()>

where F: FnMut(Vec<M>) -> Result<(), ModelError>,

Execute query with chunking for large datasets

pub async fn get_raw(self, pool: &Pool<Postgres>) -> ModelResult<Vec<Value>>

Execute query and return raw SQL results (for complex aggregations)

pub async fn first(self, pool: &Pool<Postgres>) -> ModelResult<Option<M>>

Execute query and return first model

pub async fn first_or_fail(self, pool: &Pool<Postgres>) -> ModelResult<M>

Execute query and return first model or error

pub async fn count(self, pool: &Pool<Postgres>) -> ModelResult<i64>

Count query results

pub async fn aggregate( self, pool: &Pool<Postgres>, ) -> ModelResult<Option<Value>>

Execute aggregation query and return single result

impl<M> QueryBuilder<M>

pub fn join(self, table: &str, left_col: &str, right_col: &str) -> Self

Add INNER JOIN to the query

pub fn left_join(self, table: &str, left_col: &str, right_col: &str) -> Self

Add LEFT JOIN to the query

pub fn right_join(self, table: &str, left_col: &str, right_col: &str) -> Self

Add RIGHT JOIN to the query

impl<M> QueryBuilder<M>

pub fn order_by(self, column: &str) -> Self

Add ORDER BY clause (ascending)

pub fn order_by_desc(self, column: &str) -> Self

Add ORDER BY clause (descending)

pub fn group_by(self, column: &str) -> Self

Add GROUP BY clause

pub fn having_eq<T: Into<Value>>(self, column: &str, value: T) -> Self

Add HAVING clause with equals

pub fn having<T: Into<Value>>( self, column: &str, operator: QueryOperator, value: T, ) -> Self

Add HAVING clause with custom operator and value

pub fn having_raw(self, raw_condition: &str) -> Self

Add raw HAVING clause

impl<M> QueryBuilder<M>

pub fn limit(self, count: i64) -> Self

Add LIMIT clause

pub fn offset(self, count: i64) -> Self

Add OFFSET clause

pub fn paginate(self, per_page: i64, page: i64) -> Self

Add pagination (LIMIT + OFFSET)

pub fn paginate_cursor<T: Into<Value>>( self, cursor_column: &str, cursor_value: Option<T>, per_page: i64, direction: OrderDirection, ) -> Self

Cursor-based pagination (for better performance on large datasets)

impl<M> QueryBuilder<M>

pub fn bindings(&self) -> Vec<Value>

Get parameter bindings (for prepared statements) Enhanced to support subqueries and complex conditions

pub fn clone_for_subquery(&self) -> Self

Clone this query builder for use in subqueries

pub fn optimize(self) -> Self

Optimize query by analyzing conditions

pub fn complexity_score(&self) -> u32

Get query complexity score for performance monitoring

impl<M> QueryBuilder<M>

Performance-optimized SQL generation with caching

pub fn generate_placeholders_cached(count: usize) -> String

Generate parameter placeholders with caching for better performance

pub fn generate_sequential_placeholders( start_index: usize, count: usize, ) -> String

Generate sequential parameter placeholders starting from a specific index Used for proper parameter ordering in complex queries

pub fn to_sql_optimized(&self) -> String

Optimized SQL generation with pre-allocated capacity

impl<M> QueryBuilder<M>

pub fn reset(&mut self)

Reset query builder to default state for reuse

impl<M> QueryBuilder<M>

pub fn select(self, fields: &str) -> Self

Add SELECT fields to the query

pub fn select_distinct(self, fields: &str) -> Self

Add SELECT DISTINCT to the query

pub fn from(self, table: &str) -> Self

Set the FROM table

pub fn select_count(self, column: &str, alias: Option<&str>) -> Self

Add aggregate functions to SELECT

pub fn select_sum(self, column: &str, alias: Option<&str>) -> Self

Add SUM aggregate

pub fn select_avg(self, column: &str, alias: Option<&str>) -> Self

Add AVG aggregate

pub fn select_min(self, column: &str, alias: Option<&str>) -> Self

Add MIN aggregate

pub fn select_max(self, column: &str, alias: Option<&str>) -> Self

Add MAX aggregate

pub fn select_raw(self, expression: &str) -> Self

Add custom SELECT expression

impl<M> QueryBuilder<M>

pub fn where_eq<T>(self, column: &str, value: T) -> Self

where T: Into<Value>,

Add WHERE condition with equality

pub fn where_ne<T: Into<Value>>(self, column: &str, value: T) -> Self

Add WHERE condition with not equal

pub fn where_gt<T: Into<Value>>(self, column: &str, value: T) -> Self

Add WHERE condition with greater than

pub fn where_gte<T: Into<Value>>(self, column: &str, value: T) -> Self

Add WHERE condition with greater than or equal

pub fn where_lt<T: Into<Value>>(self, column: &str, value: T) -> Self

Add WHERE condition with less than

pub fn where_lte<T: Into<Value>>(self, column: &str, value: T) -> Self

Add WHERE condition with less than or equal

pub fn where_like(self, column: &str, pattern: &str) -> Self

Add WHERE condition with LIKE

pub fn where_not_like(self, column: &str, pattern: &str) -> Self

Add WHERE condition with NOT LIKE

pub fn where_condition<T: Into<Value>>( self, column: &str, operator: &str, value: T, ) -> Self

Add WHERE condition with custom operator

pub fn where_in<T: Into<Value>>(self, column: &str, values: Vec<T>) -> Self

Add WHERE condition with IN

pub fn where_not_in<T: Into<Value>>(self, column: &str, values: Vec<T>) -> Self

Add WHERE condition with NOT IN

pub fn where_null(self, column: &str) -> Self

Add WHERE condition with IS NULL

pub fn where_not_null(self, column: &str) -> Self

Add WHERE condition with IS NOT NULL

pub fn where_between<T: Into<Value>>( self, column: &str, start: T, end: T, ) -> Self

Add WHERE condition with BETWEEN

pub fn where_raw(self, raw_condition: &str) -> Self

Add raw WHERE condition for complex cases

pub fn where_subquery<T>( self, column: &str, operator: QueryOperator, subquery: QueryBuilder<T>, ) -> Self

Add a subquery in the WHERE clause

pub fn where_exists<T>(self, subquery: QueryBuilder<T>) -> Self

Add EXISTS subquery condition

pub fn where_not_exists<T>(self, subquery: QueryBuilder<T>) -> Self

Add NOT EXISTS subquery condition

impl<M> QueryBuilder<M>

pub fn to_sql_with_params(&self) -> (String, Vec<String>)

Generate SQL from query with parameter placeholders and return parameters This method includes basic identifier escaping for security

pub fn to_sql_with_params_secure( &self, ) -> Result<(String, Vec<String>), ModelError>

Generate SQL with security validation - returns Result for proper error handling

pub fn to_sql(&self) -> String

Convert the query to SQL string (for backwards compatibility)

Trait Implementations

impl<M> Clone for QueryBuilder<M>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M: Debug> Debug for QueryBuilder<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M> Default for QueryBuilder<M>

fn default() -> Self

Returns the “default value” for a type.

impl<M> QueryBuilderWithMethods<M> for QueryBuilder<M>

where M: Model + Send + Sync,

Implementation for base QueryBuilder to support eager loading

fn with(self, relation: &str) -> QueryBuilderWithEagerLoading<M>

Add a relationship to eagerly load

fn with_where<F>( self, relation: &str, constraint: F, ) -> QueryBuilderWithEagerLoading<M>

where F: FnOnce(RelationshipConstraintBuilder) -> RelationshipConstraintBuilder + 'static,

Add a relationship with constraints

fn with_when( self, condition: bool, relation: &str, ) -> QueryBuilderWithEagerLoading<M>

Add conditional eager loading

fn with_count(self, relation: &str) -> QueryBuilderWithEagerLoading<M>

Load relationship counts without loading the relationships

fn with_count_where<F>( self, alias: &str, relation: &str, constraint: F, ) -> QueryBuilderWithEagerLoading<M>

where F: FnOnce(RelationshipConstraintBuilder) -> RelationshipConstraintBuilder + 'static,

Load relationship counts with constraints