Struct Row 

pub struct Row { /* private fields */ }

A row from a query result.

Implements the Arc<Bytes> pattern from ADR-004 for reduced memory allocation. The row holds a shared reference to the raw packet buffer and column slice information, deferring parsing and allocation until values are accessed.

Memory Model

Row {
    buffer: Arc<Bytes> ──────────► [raw packet data...]
    slices: Arc<[ColumnSlice]> ──► [{offset, length, is_null}, ...]
    metadata: Arc<ColMetaData> ──► [Column definitions...]
}

Multiple Row instances from the same result set share the metadata. The buffer and slices are unique per row but use Arc for cheap cloning.

Access Patterns

• Zero-copy: get_bytes(), get_str() (when UTF-8 valid)
• Allocating: get_string(), get::<String>()
• Type-converting: get::<T>() uses FromSql trait

Implementations

impl Row

pub fn new( buffer: Arc<Bytes>, slices: Arc<[ColumnSlice]>, metadata: Arc<ColMetaData>, ) -> Self

Create a new row with the Arc<Bytes> pattern.

This is the primary constructor for the reduced-copy pattern.

pub fn get_bytes(&self, index: usize) -> Option<&[u8]>

Returns borrowed slice into buffer (zero additional allocation).

This is the most efficient access method when you need raw bytes.

pub fn get_str(&self, index: usize) -> Option<Cow<'_, str>>

Returns Cow - borrowed if valid UTF-8, owned if conversion needed.

For UTF-8 data, this returns a borrowed reference (zero allocation). For VARCHAR data with collation, uses collation-aware decoding. For UTF-16 data (NVARCHAR), decodes as UTF-16LE.

Collation-Aware Decoding

When the encoding feature is enabled and the column has collation metadata, VARCHAR data is decoded using the appropriate character encoding based on the collation’s LCID. This correctly handles:

• Japanese (Shift_JIS/CP932)
• Simplified Chinese (GB18030/CP936)
• Traditional Chinese (Big5/CP950)
• Korean (EUC-KR/CP949)
• Windows code pages 874, 1250-1258
• SQL Server 2019+ UTF-8 collations

pub fn get_string(&self, index: usize) -> Option<String>

Allocates new String (explicit allocation).

Use this when you need an owned String.

pub fn get_stream(&self, index: usize) -> Option<BlobReader>

Get a streaming reader for a binary/text column.

Returns a BlobReader that implements tokio::io::AsyncRead for streaming access to large binary or text columns. This is useful for:

• Streaming large data to files without fully loading into memory
• Processing data in chunks with progress tracking
• Copying data between I/O destinations efficiently

Supported Column Types

• VARBINARY, VARBINARY(MAX)
• VARCHAR, VARCHAR(MAX)
• NVARCHAR, NVARCHAR(MAX)
• TEXT, NTEXT, IMAGE (legacy types)
• XML

Example

use tokio::io::AsyncWriteExt;

// Stream a large VARBINARY(MAX) column to a file
let mut reader = row.get_stream(0)?;
let mut file = tokio::fs::File::create("output.bin").await?;
tokio::io::copy(&mut reader, &mut file).await?;

Returns

• Some(BlobReader) if the column contains binary/text data
• None if the column is NULL or the index is out of bounds

pub fn get_stream_by_name(&self, name: &str) -> Option<BlobReader>

Get a streaming reader for a binary/text column by name.

See get_stream for details.

Example

let mut reader = row.get_stream_by_name("document_content")?;
// Process the blob stream...

pub fn get<T: FromSql>(&self, index: usize) -> Result<T, TypeError>

Get a value by column index with type conversion.

Uses the FromSql trait to convert the raw value to the requested type.

pub fn get_by_name<T: FromSql>(&self, name: &str) -> Result<T, TypeError>

Get a value by column name with type conversion.

pub fn try_get<T: FromSql>(&self, index: usize) -> Option<T>

Try to get a value by column index, returning None if NULL or not found.

pub fn try_get_by_name<T: FromSql>(&self, name: &str) -> Option<T>

Try to get a value by column name, returning None if NULL or not found.

pub fn get_raw(&self, index: usize) -> Option<SqlValue>

Get the raw SQL value by index.

Note: This may allocate if values haven’t been cached.

pub fn get_raw_by_name(&self, name: &str) -> Option<SqlValue>

Get the raw SQL value by column name.

pub fn len(&self) -> usize

Get the number of columns in the row.

pub fn is_empty(&self) -> bool

Check if the row is empty.

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

Get the column metadata.

pub fn metadata(&self) -> &Arc<ColMetaData>

Get the shared column metadata.

pub fn is_null(&self, index: usize) -> bool

Check if a column value is NULL.

pub fn is_null_by_name(&self, name: &str) -> bool

Check if a column value is NULL by name.

Trait Implementations

impl Clone for Row

fn clone(&self) -> Row

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Row

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

Formats the value using the given formatter.

impl<'a> IntoIterator for &'a Row

type Item = SqlValue

The type of the elements being iterated over.

type IntoIter = RowIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.