mssql_client/
lib.rs

1//! # mssql-client
2//!
3//! High-level async SQL Server client with type-state connection management.
4//!
5//! This is the primary public API surface for the rust-mssql-driver project.
6//! It provides a type-safe, ergonomic interface for working with SQL Server
7//! databases.
8//!
9//! ## Features
10//!
11//! - **Type-state pattern**: Compile-time enforcement of connection states
12//! - **Async/await**: Built on Tokio for efficient async I/O
13//! - **Prepared statements**: Automatic caching with LRU eviction
14//! - **Transactions**: Full transaction support with savepoints
15//! - **Azure support**: Automatic routing and failover handling
16//! - **Streaming results**: Memory-efficient processing of large result sets
17//!
18//! ## Type-State Connection Management
19//!
20//! The client uses a compile-time type-state pattern that ensures invalid
21//! operations are caught at compile time rather than runtime:
22//!
23//! ```text
24//! Disconnected -> Ready (via connect())
25//! Ready -> InTransaction (via begin_transaction())
26//! Ready -> Streaming (via query that returns a stream)
27//! InTransaction -> Ready (via commit() or rollback())
28//! ```
29//!
30//! ## Example
31//!
32//! ```rust,ignore
33//! use mssql_client::{Client, Config};
34//!
35//! #[tokio::main]
36//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
37//!     let config = Config::from_connection_string(
38//!         "Server=localhost;Database=test;User Id=sa;Password=Password123;"
39//!     )?;
40//!
41//!     let mut client = Client::connect(config).await?;
42//!
43//!     // Execute a query with parameters
44//!     let rows = client
45//!         .query("SELECT * FROM users WHERE id = @p1", &[&1])
46//!         .await?;
47//!
48//!     for row in rows {
49//!         let name: String = row.get(0)?;
50//!         println!("User: {}", name);
51//!     }
52//!
53//!     // Transactions with savepoint support
54//!     let mut tx = client.begin_transaction().await?;
55//!     tx.execute("INSERT INTO users (name) VALUES (@p1)", &[&"Alice"]).await?;
56//!
57//!     // Create a savepoint for partial rollback
58//!     let sp = tx.savepoint("before_update").await?;
59//!     tx.execute("UPDATE users SET active = 1", &[]).await?;
60//!
61//!     // Rollback to savepoint if needed
62//!     // tx.rollback_to(&sp).await?;
63//!
64//!     tx.commit().await?;
65//!
66//!     Ok(())
67//! }
68//! ```
69
70#![warn(missing_docs)]
71#![deny(unsafe_code)]
72
73pub mod blob;
74pub mod bulk;
75pub mod cancel;
76pub mod client;
77pub mod config;
78pub mod encryption;
79pub mod error;
80pub mod from_row;
81pub mod instrumentation;
82pub mod query;
83pub mod row;
84pub mod state;
85pub mod statement_cache;
86pub mod stream;
87pub mod to_params;
88pub mod transaction;
89pub mod tvp;
90
91// Re-export commonly used types
92pub use bulk::{BulkColumn, BulkInsert, BulkInsertBuilder, BulkInsertResult, BulkOptions};
93pub use cancel::CancelHandle;
94pub use client::Client;
95pub use config::{Config, RedirectConfig, RetryPolicy, TimeoutConfig};
96pub use error::Error;
97pub use from_row::{FromRow, MapRows, RowIteratorExt};
98pub use mssql_auth::Credentials;
99
100// Secure credential types (with zeroize feature)
101#[cfg(feature = "zeroize")]
102pub use mssql_auth::{SecretString, SecureCredentials};
103pub use mssql_types::{FromSql, SqlValue, ToSql};
104pub use query::Query;
105pub use row::{Column, Row};
106pub use state::{
107    Connected, ConnectionState, Disconnected, InTransaction, ProtocolState, Ready, Streaming,
108};
109pub use statement_cache::{PreparedStatement, StatementCache, StatementCacheConfig};
110pub use stream::{ExecuteResult, MultiResultStream, OutputParam, QueryStream, ResultSet};
111pub use to_params::{NamedParam, ParamList, ToParams};
112pub use transaction::{IsolationLevel, SavePoint, Transaction};
113pub use tvp::{Tvp, TvpColumn, TvpRow, TvpValue};
114
115// Always Encrypted types
116#[cfg(feature = "always-encrypted")]
117pub use encryption::EncryptionContext;
118pub use encryption::{
119    EncryptionConfig, ParameterCryptoInfo, ParameterEncryptionInfo, ResultSetEncryptionInfo,
120};
121
122// OpenTelemetry instrumentation (available whether or not otel feature is enabled)
123pub use instrumentation::{
124    DatabaseMetrics, OperationTimer, SanitizationConfig, attributes, metric_names, span_names,
125};
mssql_client/lib.rs

mssql_client/
lib.rs
