Struct QueryBuilder 

pub struct QueryBuilder { /* private fields */ }

A statement being assembled.

Implementations

impl QueryBuilder

pub fn new(table: impl Into<String>) -> Self

pub fn select(self, columns: &[&str]) -> Self

Choose columns. Without this the query selects everything.

pub fn distinct(self) -> Self

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

where column = value.

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

where column <operator> value, with the operator checked against a list — an operator cannot be smuggled in from user input.

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

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

or column <operator> value.

The or_ half of filter_op, which was missing: or_filter could only ever mean equality, so a search across three columns with like had no way to say so.

pub fn or_filter_like(self, column: &str, pattern: impl Into<Value>) -> Self

or column like pattern.

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

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

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

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

pub fn filter_between( self, column: &str, low: impl Into<Value>, high: impl Into<Value>, ) -> Self

pub fn filter_like(self, column: &str, pattern: impl Into<Value>) -> Self

where column like pattern.

pub fn group_filter( self, build: impl FnOnce(QueryBuilder) -> QueryBuilder, ) -> Self

A parenthesised group of conditions.

pub fn or_group_filter( self, build: impl FnOnce(QueryBuilder) -> QueryBuilder, ) -> Self

pub fn join(self, table: &str, left: &str, operator: &str, right: &str) -> Self

pub fn left_join( self, table: &str, left: &str, operator: &str, right: &str, ) -> Self

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

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

pub fn group_by(self, columns: &[&str]) -> Self

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

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

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

Limit and offset for a 1-based page.

pub fn to_sql(&self, dialect: &dyn Dialect) -> Result<(String, Vec<Value>)>

Build the select statement and its parameters for one database.

The dialect supplies the quoting, the placeholders and the paging syntax, so the same builder chain is correct on PostgreSQL, MySQL and SQL Server without the caller knowing which is underneath.

pub fn to_count_sql( &self, dialect: &dyn Dialect, ) -> Result<(String, Vec<Value>)>

The select count(*) form of this query, ignoring order and paging.

pub async fn get(&self, db: &Database) -> Result<Vec<Row>>

Run the query and return every matching row.

pub async fn first(&self, db: &Database) -> Result<Option<Row>>

The first matching row, if any.

pub async fn get_json(&self, db: &Database) -> Result<Json>

Rows as a JSON array, ready to return from an API handler.

pub async fn count(&self, db: &Database) -> Result<i64>

pub async fn exists(&self, db: &Database) -> Result<bool>

pub async fn insert( &self, db: &Database, values: &[(&str, Value)], ) -> Result<i64>

Insert one row, returning its id.

pub async fn insert_returning( &self, db: &Database, values: &[(&str, Value)], column: &str, ) -> Result<Value>

Insert one row and return one column of it — how a model picks up the key the database generated.

pub async fn insert_without_id( &self, db: &Database, values: &[(&str, Value)], ) -> Result<u64>

Insert one row without asking for a generated key.

pub async fn insert_many( &self, db: &Database, rows: &[Vec<(String, Value)>], ) -> Result<u64>

Insert many rows in one statement.

pub async fn update( &self, db: &Database, values: &[(&str, Value)], ) -> Result<u64>

Update the rows this query matches. Requires a filter.

pub async fn delete(&self, db: &Database) -> Result<u64>

Delete the rows this query matches. Requires a filter.

pub async fn delete_all(&self, db: &Database) -> Result<u64>

Delete every row in the table. Deliberately separate from delete.

pub async fn get_in(&self, tx: &mut Transaction) -> Result<Vec<Row>>

get, inside a transaction.

pub async fn first_in(&self, tx: &mut Transaction) -> Result<Option<Row>>

first, inside a transaction.

pub async fn count_in(&self, tx: &mut Transaction) -> Result<i64>

count, inside a transaction.

pub async fn insert_in( &self, tx: &mut Transaction, values: &[(&str, Value)], ) -> Result<u64>

insert_without_id, inside a transaction.

pub async fn update_in( &self, tx: &mut Transaction, values: &[(&str, Value)], ) -> Result<u64>

update, inside a transaction. The row count it returns is what a compare-and-set reads: filter("balance", …) and zero rows means somebody else moved first.

pub async fn delete_in(&self, tx: &mut Transaction) -> Result<u64>

delete, inside a transaction.

impl QueryBuilder

pub async fn paginate( &self, db: &Database, page: i64, per_page: i64, ) -> Result<Page>

Fetch one page, with a count query for the total.

Convenient and familiar, but the count scans the whole matching set: past a few hundred thousand rows, reach for QueryBuilder::cursor_paginate.

pub async fn cursor_paginate( &self, db: &Database, column: &str, after: Option<&str>, per_page: i64, ) -> Result<CursorPage>

Fetch one page by cursor, ordered by a unique column.

No count and no offset, so the cost does not grow with the page number, and a row inserted while the reader pages through cannot cause another row to be skipped or repeated.

Trait Implementations

impl Clone for QueryBuilder

fn clone(&self) -> QueryBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for QueryBuilder

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

Formats the value using the given formatter.