Struct SelectBuilder 

pub struct SelectBuilder<'a, C: ConnExt> { /* private fields */ }

Composable query builder combining filters, sorting, and pagination.

Created via ConnExt::select with a base SQL query. Chain filter, order_by, and cursor_column before executing with page, cursor, fetch_all, fetch_one, or fetch_optional.

Implementations

impl<'a, C: ConnExt> SelectBuilder<'a, C>

pub fn filter(self, filter: ValidatedFilter) -> Self

Apply a validated filter (WHERE clauses).

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

Set ORDER BY clause. This is raw SQL — not user input. If a filter has a sort_clause, it takes precedence over this.

pub fn cursor_column(self, col: &str) -> Self

Set the column used for cursor pagination (default: "id").

The column must appear in the SELECT list and be sortable (e.g., ULID, timestamp, auto-increment). Cursor pagination will ORDER BY this column ascending and use it for the WHERE col > ? condition.

pub fn oldest_first(self) -> Self

Use ascending (oldest-first) cursor ordering instead of the default DESC.

By default cursor pagination orders descending (newest-first), which is the common pattern for feeds and timelines. Call this to switch to ascending order when you need chronological (oldest-first) traversal.

pub async fn page<T: FromRow + Serialize>( self, req: PageRequest, ) -> Result<Page<T>>

Execute with offset pagination, returning a Page<T>.

Runs a COUNT(*) subquery for the total, then fetches the requested page with LIMIT/OFFSET.

Errors

Returns an error if the query or row conversion fails.

pub async fn cursor<T: FromRow + Serialize>( self, req: CursorRequest, ) -> Result<CursorPage<T>>

Execute with cursor pagination. Returns CursorPage<T>.

By default orders descending (newest-first). Use oldest_first to switch to ascending order. The cursor column can be changed with cursor_column.

Errors

Returns an error if the query or row conversion fails.

pub async fn fetch_all<T: FromRow>(self) -> Result<Vec<T>>

Execute without pagination, returning all matching rows.

Errors

Returns an error if the query or row conversion fails.

pub async fn fetch_one<T: FromRow>(self) -> Result<T>

Execute without pagination, returning the first row.

Errors

Returns Error::not_found if no rows match.

pub async fn fetch_optional<T: FromRow>(self) -> Result<Option<T>>

Execute without pagination, returning the first row or None.

Errors

Returns an error if the query or row conversion fails.