Struct BuiltQuery 

#[non_exhaustive]
pub struct BuiltQuery {
    pub sql: String,
    pub params: Params,
    pub cacheable: bool,
}

Rendered SQL plus its bind parameters.

Builders expose convenience fetch_* methods that call build() each time. Keep a BuiltQuery when you want to inspect SQL, log the generated shape, or execute the same validated query more than once with the same binds.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

sql: String

Rendered Postgres SQL using $N placeholders.

params: Params

Bind parameters in placeholder order.

cacheable: bool

Whether this query is safe to reuse as a stable prepared statement shape.

rqb passes this to sqlx .persistent(cacheable). SQLx keeps a bounded per-connection prepared-statement cache for Postgres, with a default capacity of 100 entries. Raw SQL fragments make the query non-cacheable because rqb cannot prove that their text is a stable statement shape.

High-cardinality typed query shapes, such as many different IN list lengths or optional-filter combinations, stay memory-bounded by sqlx’s LRU cache but can still churn prepared statements. Tune sqlx with PgConnectOptions::statement_cache_capacity or the statement-cache-capacity URL parameter when an application needs a different cache size.

Implementations

impl BuiltQuery

pub fn arguments(&self) -> Result<PgArguments>

Converts stored parameters into sqlx Postgres arguments for one execution.

sqlx argument buffers are consumed by execution, so each execute/fetch path creates a fresh PgArguments value from the stored params.

pub fn summary(&self) -> String

Returns debug-friendly query output.

The output includes pretty-printed rendered SQL, bind parameter count, Rust type names, and cacheability. It never interpolates bind values into SQL.

pub fn pretty_sql(&self) -> String

Returns only the formatted SQL text for human-readable logs.

This does not change BuiltQuery::sql, which remains the exact SQL text used for execution.

impl BuiltQuery

pub async fn execute<'e>(&self, executor: impl PgExecutor<'e>) -> Result<u64>

Executes the query and returns affected row count.

pub async fn fetch_all<'e>( &self, executor: impl PgExecutor<'e>, ) -> Result<Vec<PgRow>>

Fetches all rows as raw sqlx PgRow values.

pub fn fetch_stream<'q, 'e>( &'q self, executor: impl PgExecutor<'e> + 'q, ) -> Result<BoxStream<'q, Result<PgRow>>>

where 'e: 'q,

Streams raw sqlx PgRow values.

The returned stream borrows this BuiltQuery, so keep the built query value alive until the stream is fully consumed.

pub fn fetch_stream_pool( self, pool: PgPool, ) -> Result<BoxStream<'static, Result<PgRow>>>

Streams raw sqlx PgRow values from an owned pool-backed query.

The returned stream owns this built query and a cloneable PgPool handle, so it can outlive the call frame that created it.

pub async fn fetch_one<'e>( &self, executor: impl PgExecutor<'e>, ) -> Result<PgRow>

Fetches exactly one raw sqlx PgRow.

pub async fn fetch_optional<'e>( &self, executor: impl PgExecutor<'e>, ) -> Result<Option<PgRow>>

Fetches zero or one raw sqlx PgRow.

pub async fn fetch_all_as<'e, T>( &self, executor: impl PgExecutor<'e>, ) -> Result<Vec<T>>

where T: for<'r> FromRow<'r, PgRow> + Send + Unpin,

Fetches all rows into a sqlx::FromRow type.

pub fn fetch_stream_as<'q, 'e, T>( &'q self, executor: impl PgExecutor<'e> + 'q, ) -> Result<BoxStream<'q, Result<T>>>

where T: for<'r> FromRow<'r, PgRow> + Send + Unpin + 'q, 'e: 'q,

Streams rows into a sqlx::FromRow type.

Streaming avoids materializing large exports in memory. Keep the BuiltQuery value alive while consuming the stream.

pub fn fetch_stream_pool_as<T>( self, pool: PgPool, ) -> Result<BoxStream<'static, Result<T>>>

where T: for<'r> FromRow<'r, PgRow> + Send + Unpin + 'static,

Streams rows into a sqlx::FromRow type from an owned pool-backed query.

The returned stream owns this built query and a cloneable PgPool handle, so it can outlive the call frame that created it.

pub async fn fetch_one_as<'e, T>( &self, executor: impl PgExecutor<'e>, ) -> Result<T>

where T: for<'r> FromRow<'r, PgRow> + Send + Unpin,

Fetches exactly one row into a sqlx::FromRow type.

pub async fn fetch_optional_as<'e, T>( &self, executor: impl PgExecutor<'e>, ) -> Result<Option<T>>

where T: for<'r> FromRow<'r, PgRow> + Send + Unpin,

Fetches zero or one row into a sqlx::FromRow type.

pub async fn fetch_scalar<'e, T>( &self, executor: impl PgExecutor<'e>, ) -> Result<Vec<T>>

where T: ScalarValue,

Fetches all rows as a single decoded scalar column.

pub fn fetch_stream_scalar<'q, 'e, T>( &'q self, executor: impl PgExecutor<'e> + 'q, ) -> Result<BoxStream<'q, Result<T>>>

where T: ScalarValue + 'q, 'e: 'q,

Streams rows as a single decoded scalar column.

Keep the BuiltQuery value alive while consuming the stream.

pub fn fetch_stream_pool_scalar<T>( self, pool: PgPool, ) -> Result<BoxStream<'static, Result<T>>>

where T: ScalarValue + 'static,

Streams rows as a single decoded scalar column from an owned pool-backed query.

The returned stream owns this built query and a cloneable PgPool handle, so it can outlive the call frame that created it.

pub async fn fetch_one_scalar<'e, T>( &self, executor: impl PgExecutor<'e>, ) -> Result<T>

where T: ScalarValue,

Fetches exactly one decoded scalar value.

pub async fn fetch_optional_scalar<'e, T>( &self, executor: impl PgExecutor<'e>, ) -> Result<Option<T>>

where T: ScalarValue,

Fetches zero or one decoded scalar value.

Trait Implementations

impl Clone for BuiltQuery

fn clone(&self) -> BuiltQuery

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BuiltQuery

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

Formats the value using the given formatter.