tiberius

When connecting to certain Azure SQL instances, the server may return an Error::Routing { host, port }. This indicates that you must establish a new connection to the redirected address provided in the error.

To handle this, catch the Error::Routing variant, update your Config with the new host and port, and attempt the connection again. You should typically only expect one redirect.

use tiberius::{Client, Config, AuthMethod, error::Error};
use tokio_util::compat::TokioAsyncWriteCompatExt;
use tokio::net::TcpStream;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut config = Config::new();

    config.host("0.0.0.0");
    config.port(1433);
    config.authentication(AuthMethod::sql_server("SA", "<Mys3cureP4ssW0rD>"));

    let tcp = TcpStream::connect(config.get_addr()).await?;
    tcp.set_nodelay(true)?;

    let client = match Client::connect(config, tcp.compat_write()).await {
        // Connection successful.
        Ok(client) => client,
        // The server wants us to redirect to a different address
        Err(Error::Routing { host, port }) => {
            let mut config = Config::new();

            config.host(&host);
            config.port(port);
            config.authentication(AuthMethod::sql_server("SA", "<Mys3cureP4ssW0rD>"));

            let tcp = TcpStream::connect(config.get_addr()).await?;
            tcp.set_nodelay(true)?;

            // we should not have more than one redirect, so we'll short-circuit here.
            Client::connect(config, tcp.compat_write()).await?
        }
        Err(e) => Err(e)?,
    };

    Ok(())
}

To use Rust values as parameters in Client#query or Client#execute methods, the types must implement the ToSql or IntoSql traits. These traits convert Rust types into ColumnData, which is the format understood by the SQL Server TDS protocol.

Supported Type Mappings

Type Flexibility

• Strings: Can be used with ntext, text, varchar, nchar, and char columns.
• Binary: Can be used with binary and image columns.
• Dates: On TDS 7.3+ (SQL Server 2008+), NaiveDateTime can also be used for datetime and smalldatetime columns.

Tiberius uses feature flags to enable specific functionalities like TLS implementations, date/time types, and decimal support.

A Row represents a single record from a query result set. You can access its data in two primary ways:

1. By-reference (Copying): Use .get(idx) or .try_get(idx) to retrieve a value. The index idx can be a zero-indexed usize or a &str representing the column name.

   • .get(idx): Panics if the type conversion fails or the index is out of bounds. Use this when you are certain of the schema.
   • .try_get(idx): Returns a Result<Option<R>>. Use this for safer error handling.

2. By-value (Moving): Implement IntoIterator for Row to consume the row and iterate over its values as ColumnData items.

Metadata such as column names and types can be accessed via .columns().

// By-reference using name
let val: Option<i32> = row.get("col1");

// By-reference using index
let val: Option<i32> = row.get(0);

// By-value iteration
for val in row.into_iter() {
    // val is ColumnData
}

A QueryStream is an asynchronous stream of QueryItem values returned by a query. It can contain both Metadata (describing the columns of the upcoming rows) and Row data.

Key behaviors:

• Metadata First: Every result set in the stream begins with a Metadata item describing the column structure.
• Multiple Results: If a single query (or batch) produces multiple result sets (e.g., SELECT 1; SELECT 2), the stream will yield multiple Metadata items interleaved with their respective rows.
• Performance Warning: You must poll the QueryStream until it is empty before sending another query via the same Client. Failing to do so causes an undeterministic flush that slows down subsequent queries.
• Result Indexing: You can use result_index() on Metadata or Row to determine which result set the item belongs to (starting from 0).

// Example of iterating over a stream with multiple result sets
while let Some(item) = stream.try_next().await? {
    match item {
        // Metadata for the first result set
        QueryItem::Metadata(meta) if meta.result_index() == 0 => {
            // handle metadata
        }
        // A row from the first result set
        QueryItem::Row(row) if row.result_index() == 0 => {
            assert_eq!(Some(1), row.get(0));
        }
        // Metadata for the second result set
        QueryItem::Metadata(meta) => {
            // handle metadata
        }
        // A row from the second result set
        QueryItem::Row(row) => {
            assert_eq!(Some(2), row.get(0));
        }
    }
}

On Windows, connecting to a named instance may require the SQL Browser service to resolve the correct port. To use this, enable the sql-browser-async-std or sql-browser-tokio feature flag. You must provide the instance_name and set the port to the SQL Browser port (default 1434). Use the TcpStream::connect_named(&config) method provided by the SqlBrowser trait.

#[cfg(any(feature = "sql-browser-async-std", feature = "sql-browser-tokio"))]
use tiberius::{Client, Config, AuthMethod, SqlBrowser};
use async_std::net::TcpStream;

#[async_std::main]
async fn main() -> anyhow::Result<()> {
    let mut config = Config::new();
    config.authentication(AuthMethod::sql_server("SA", "<password>"));
    config.host("localhost");
    config.port(1434); // SQL Browser port
    config.instance_name("INSTANCE");
    config.trust_cert();

    // connect_named is provided by the SqlBrowser trait
    let tcp = TcpStream::connect_named(&config).await?;

    let mut client = Client::connect(config, tcp).await?;
    Ok(())
}