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::ResultSetClient;
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
51//! .execute("SELECT 1 AS value".into(), None, None)
52//! .await?;
53//!
54//! if let Some(rs) = client.get_current_resultset() {
55//! while let Some(row) = rs.next_row().await? {
56//! println!("{row:?}");
57//! }
58//! }
59//!
60//! client.close_query().await?;
61//! Ok(())
62//! }
63//! ```
64//!
65//! # Modules
66//!
67//! - [`connection`] — Client type ([`connection::tds_client::TdsClient`]),
68//! connection context, and authentication configuration.
69//! - [`connection_provider`] — Connection factory
70//! ([`connection_provider::tds_connection_provider::TdsConnectionProvider`]).
71//! - [`core`] — Shared types: [`core::TdsResult`], [`core::EncryptionOptions`],
72//! [`core::CancelHandle`].
73//! - [`cursor`] — Cursor types, bitflags, and response structs for `sp_cursor*` RPCs.
74//! - [`datatypes`] — SQL Server data types and column value representations.
75//! - [`error`] — Error definitions.
76//! - [`message`] — TDS message types (prelogin, login7, etc.).
77//! - [`query`] — Query metadata and column descriptors.
78//! - [`token`] — TDS token stream parsing (COLMETADATA, ROW, DONE, etc.).
79
80pub mod connection;
81pub mod connection_provider;
82/// Shared types: result aliases, encryption settings, and cancellation.
83pub mod core;
84/// Cursor types and response structures for TDS cursor RPCs.
85pub mod cursor;
86pub mod datatypes;
87/// Error definitions for TDS operations.
88pub mod error;
89pub(crate) mod handler;
90pub(crate) mod io;
91pub mod message;
92pub mod query;
93pub mod security;
94pub(crate) mod sql_identifier;
95pub(crate) mod ssrp;
96pub mod token;
97
98// Expose internal APIs for fuzzing
99#[cfg(fuzzing)]
100pub mod fuzz_support;