mssql_tds/lib.rs
1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4#![warn(missing_docs)]
5
6//! Async Rust implementation of the TDS (Tabular Data Stream) protocol for SQL Server
7//! and Azure SQL Database.
8//!
9//! # Overview
10//!
11//! `mssql-tds` provides a low-level, async client for communicating with SQL Server
12//! using the TDS protocol. It handles connection negotiation (prelogin, TLS, login7),
13//! query execution, result set streaming, bulk copy, RPC calls, and transaction
14//! management.
15//!
16//! # Feature flags
17//!
18//! | Flag | Default | Description |
19//! |------|---------|-------------|
20//! | `integrated-auth` | **yes** | Enables both `sspi` and `gssapi` |
21//! | `sspi` | via `integrated-auth` | Windows SSPI (Kerberos/NTLM) |
22//! | `gssapi` | via `integrated-auth` | Unix GSSAPI (Kerberos) via runtime `dlopen` |
23//!
24//! Disable the default to drop platform-specific auth dependencies:
25//!
26//! ```toml
27//! mssql-tds = { version = "0.1", default-features = false }
28//! ```
29//!
30//! # Quick start
31//!
32//! ```rust,no_run
33//! use mssql_tds::connection::client_context::ClientContext;
34//! use mssql_tds::connection::tds_client::ResultSet;
35//! use mssql_tds::connection_provider::tds_connection_provider::TdsConnectionProvider;
36//! use mssql_tds::core::TdsResult;
37//!
38//! #[tokio::main]
39//! async fn main() -> TdsResult<()> {
40//! let mut context = ClientContext::default();
41//! context.user_name = std::env::var("DB_USER").unwrap_or("<user>".into());
42//! context.password = std::env::var("DB_PASSWORD").unwrap_or("<password>".into());
43//! context.database = "master".into();
44//!
45//! let provider = TdsConnectionProvider {};
46//! let mut client = provider
47//! .create_client(context, "tcp:localhost,1433", None)
48//! .await?;
49//!
50//! client.execute("SELECT 1 AS value".into(), ()).await?;
51//!
52//! if client.on_rows() {
53//! while let Some(row) = client.next_row().await? {
54//! println!("{row:?}");
55//! }
56//! }
57//!
58//! client.close_query().await?;
59//! Ok(())
60//! }
61//! ```
62//!
63//! # Modules
64//!
65//! - [`connection`] — Client type ([`connection::tds_client::TdsClient`]),
66//! connection context, and authentication configuration.
67//! - [`connection_provider`] — Connection factory
68//! ([`connection_provider::tds_connection_provider::TdsConnectionProvider`]).
69//! - [`core`] — Shared types: [`core::TdsResult`], [`core::EncryptionOptions`],
70//! [`core::CancelHandle`].
71//! - [`cursor`] — Cursor types, bitflags, and response structs for `sp_cursor*` RPCs.
72//! - [`datatypes`] — SQL Server data types and column value representations.
73//! - [`error`] — Error definitions.
74//! - [`message`] — TDS message types (prelogin, login7, etc.).
75//! - [`query`] — Query metadata and column descriptors.
76//! - [`token`] — TDS token stream parsing (COLMETADATA, ROW, DONE, etc.).
77
78pub mod connection;
79pub mod connection_provider;
80/// Shared types: result aliases, encryption settings, and cancellation.
81pub mod core;
82
83// `EncodingType::encoding` and `lcid_to_encoding` hand out `&'static
84// encoding_rs::Encoding`, so a consumer needs the exact same `encoding_rs` build
85// to name the type. Re-exported so they inherit ours instead of guessing a
86// matching version.
87pub use encoding_rs;
88/// Cursor types and response structures for TDS cursor RPCs.
89pub mod cursor;
90pub mod datatypes;
91/// Error definitions for TDS operations.
92pub mod error;
93pub(crate) mod handler;
94pub(crate) mod io;
95pub mod message;
96pub mod query;
97pub mod security;
98pub(crate) mod sql_identifier;
99pub(crate) mod ssrp;
100pub mod token;
101
102// Expose internal APIs for fuzzing
103#[cfg(fuzzing)]
104pub mod fuzz_support;
105
106// Test-only helpers for driving a `TdsClient` from scripted TDS tokens. Gated
107// behind `test-util` so downstream crates can unit-test client-driven paths.
108#[cfg(any(test, feature = "test-util"))]
109pub mod test_client_support;
110
111// Test-only plumbing for feeding hand-built TDS packets to a real
112// `NetworkTransport`. Spans `io` and `connection::transport`, so it belongs to
113// neither.
114#[cfg(test)]
115pub(crate) mod test_packet_support;