Struct QueryStream 

pub struct QueryStream { /* private fields */ }

Streaming view of a query result.

Constructed by crate::Connection::query. Owns the underlying DynRowStream and lets callers observe schema metadata, drain the rows, or close the cursor explicitly.

The type is not marked #[non_exhaustive] because every field is private; the struct is only ever built through QueryStream::new (driver authors / test helpers) or returned from crate::Connection::query (consumers). Adding a field is non-breaking.

Implementations

impl QueryStream

pub fn new(inner: Box<dyn DynRowStream>) -> Self

Wrap an existing row stream. Used by the default Connection::query implementation and by driver authors that build a richer stream out-of-band.

Column metadata is read on-demand from DynRowStream::columns — the caller does not pass it in (review fixup M8: prevents the redundant column-vector clone the previous shape required).

pub fn columns(&self) -> &[ColumnHeader]

Column headers describing the shape of every row this stream will yield. Safe to call before the first Self::next_row — the headers are materialised eagerly by the driver as part of opening the cursor. Delegates to the wrapped DynRowStream::columns so the two views never disagree.

pub const fn rows_yielded(&self) -> usize

Number of rows successfully yielded so far. Drives the TUI’s “streaming · N rows” header.

pub fn elapsed(&self) -> Duration

Elapsed wall-clock time since the stream was opened. Drives the TUI’s live-elapsed indicator.

pub async fn next_row(&mut self) -> Option<Result<Row>>

Advance the stream by one row.

Returns None once the underlying stream reports end-of-data or a previous call returned an error. The fused shape lets callers loop with while let Some(row) = s.next_row().await without worrying about double-polling.

pub async fn collect_all(self) -> Result<QueryResult>

Drain the stream into a materialised QueryResult. Used by tests, the MCP query tool, and the export path when the caller genuinely needs the whole shape in memory before continuing.

elapsed_ms is filled from the wall-clock between Connection::query returning and the last row arriving — useful for “how long did the streamed query take” reporting without the caller wiring its own timer.

On error any rows already yielded are discarded; the caller gets the engine error verbatim. If partial materialisation matters, use Self::next_row in a loop and accumulate manually.

pub async fn collect_with_limit( self, limit: usize, ) -> Result<(QueryResult, bool)>

Drain the stream into a materialised QueryResult but stop once limit rows have been accumulated. Subsequent rows produced by the engine are discarded and the cursor is closed — useful for the MCP tool’s hard row cap without reaching for take-style adapters.

truncated in the returned tuple is true when the engine had more rows to give. Callers should surface this to the agent so it knows the response is incomplete.

pub async fn close(self) -> Result<()>

Explicitly close the stream. Equivalent to dropping it for any driver that wires its Drop impl to release the cursor, but close() is awaitable so callers can surface server-side release errors. Required by drivers that hold ephemeral server-side state (PG portals, ClickHouse HTTP body) where the async close round-trip must complete before the connection is returned to the pool.