Expand description
§mssql-client
High-level async SQL Server client with type-state connection management.
This is the primary public API surface for the rust-mssql-driver project. It provides a type-safe, ergonomic interface for working with SQL Server databases.
§Features
- Type-state pattern: Compile-time enforcement of connection states
- Async/await: Built on Tokio for efficient async I/O
- Prepared statements: Automatic caching with LRU eviction
- Transactions: Full transaction support with savepoints
- Azure support: Automatic routing and failover handling
- Streaming results: Memory-efficient processing of large result sets
§Type-State Connection Management
The client uses a compile-time type-state pattern that ensures invalid operations are caught at compile time rather than runtime:
Disconnected -> Ready (via connect())
Ready -> InTransaction (via begin_transaction())
Ready -> Streaming (via query that returns a stream)
InTransaction -> Ready (via commit() or rollback())§Example
ⓘ
use mssql_client::{Client, Config};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = Config::from_connection_string(
"Server=localhost;Database=test;User Id=sa;Password=Password123;"
)?;
let mut client = Client::connect(config).await?;
// Execute a query with parameters
let rows = client
.query("SELECT * FROM users WHERE id = @p1", &[&1])
.await?;
for row in rows {
let name: String = row.get(0)?;
println!("User: {}", name);
}
// Transactions with savepoint support
let mut tx = client.begin_transaction().await?;
tx.execute("INSERT INTO users (name) VALUES (@p1)", &[&"Alice"]).await?;
// Create a savepoint for partial rollback
let sp = tx.savepoint("before_update").await?;
tx.execute("UPDATE users SET active = 1", &[]).await?;
// Rollback to savepoint if needed
// tx.rollback_to(&sp).await?;
tx.commit().await?;
Ok(())
}Re-exports§
pub use bulk::BulkColumn;pub use bulk::BulkInsert;pub use bulk::BulkInsertBuilder;pub use bulk::BulkInsertResult;pub use bulk::BulkOptions;pub use client::Client;pub use config::Config;pub use config::RedirectConfig;pub use config::RetryPolicy;pub use config::TimeoutConfig;pub use error::Error;pub use from_row::FromRow;pub use from_row::MapRows;pub use from_row::RowIteratorExt;pub use query::Query;pub use row::Column;pub use row::Row;pub use state::Connected;pub use state::ConnectionState;pub use state::Disconnected;pub use state::InTransaction;pub use state::ProtocolState;pub use state::Ready;pub use state::Streaming;pub use statement_cache::PreparedStatement;pub use statement_cache::StatementCache;pub use statement_cache::StatementCacheConfig;pub use stream::ExecuteResult;pub use stream::MultiResultStream;pub use stream::OutputParam;pub use stream::QueryStream;pub use stream::ResultSet;pub use to_params::NamedParam;pub use to_params::ParamList;pub use to_params::ToParams;pub use transaction::IsolationLevel;pub use transaction::SavePoint;pub use transaction::Transaction;pub use tvp::Tvp;pub use tvp::TvpColumn;pub use tvp::TvpRow;pub use tvp::TvpValue;
Modules§
- blob
- Streaming large object (LOB) reader for VARBINARY(MAX) and TEXT types.
- bulk
- Bulk Copy Protocol (BCP) support.
- client
- SQL Server client implementation.
- config
- Client configuration.
- error
- Client error types.
- from_
row - FromRow trait for automatic row-to-struct mapping.
- instrumentation
- OpenTelemetry instrumentation for database operations.
- query
- Query builder and prepared statement support.
- row
- Row representation for query results.
- state
- Connection state types for type-state pattern.
- statement_
cache - Prepared statement caching with LRU eviction.
- stream
- Streaming query result support.
- to_
params - ToParams trait for automatic struct-to-parameters mapping.
- transaction
- Transaction support.
- tvp
- Table-Valued Parameters (TVP) support.
Enums§
- Credentials
- Credentials for SQL Server authentication.
- SqlValue
- A SQL value that can represent any SQL Server data type.