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 change_tracking;
77pub mod client;
78pub mod config;
79pub mod encryption;
80pub mod error;
81pub mod from_row;
82pub mod instrumentation;
83pub mod query;
84pub mod row;
85pub mod state;
86pub mod statement_cache;
87pub mod stream;
88pub mod to_params;
89pub mod transaction;
90pub mod tvp;
91
92// Re-export commonly used types
93pub use bulk::{BulkColumn, BulkInsert, BulkInsertBuilder, BulkInsertResult, BulkOptions};
94pub use cancel::CancelHandle;
95pub use client::Client;
96pub use config::{Config, RedirectConfig, RetryPolicy, TimeoutConfig};
97pub use error::Error;
98
99// Re-export TDS version for configuration
100pub use from_row::{FromRow, MapRows, RowIteratorExt};
101pub use mssql_auth::Credentials;
102pub use tds_protocol::version::TdsVersion;
103
104// Secure credential types (with zeroize feature)
105#[cfg(feature = "zeroize")]
106pub use mssql_auth::{SecretString, SecureCredentials};
107pub use mssql_types::{FromSql, SqlValue, ToSql};
108pub use query::Query;
109pub use row::{Column, Row};
110pub use state::{
111    Connected, ConnectionState, Disconnected, InTransaction, ProtocolState, Ready, Streaming,
112};
113pub use statement_cache::{PreparedStatement, StatementCache, StatementCacheConfig};
114pub use stream::{ExecuteResult, MultiResultStream, OutputParam, QueryStream, ResultSet};
115pub use to_params::{NamedParam, ParamList, ToParams};
116pub use transaction::{IsolationLevel, SavePoint, Transaction};
117pub use tvp::{Tvp, TvpColumn, TvpRow, TvpValue};
118
119// Always Encrypted types
120#[cfg(feature = "always-encrypted")]
121pub use encryption::EncryptionContext;
122pub use encryption::{
123    EncryptionConfig, ParameterCryptoInfo, ParameterEncryptionInfo, ResultSetEncryptionInfo,
124};
125
126// OpenTelemetry instrumentation (available whether or not otel feature is enabled)
127pub use instrumentation::{
128    DatabaseMetrics, OperationTimer, SanitizationConfig, attributes, metric_names, span_names,
129};
130
131// Change Tracking support
132pub use change_tracking::{
133    ChangeMetadata, ChangeOperation, ChangeTracking, ChangeTrackingQuery, SyncVersionStatus,
134};
mssql_client/lib.rs

mssql_client/
lib.rs
