Struct Config 

#[non_exhaustive]
pub struct Config {

    pub host: String,
    pub port: u16,
    pub database: Option<String>,
    pub credentials: Credentials,
    pub tls: TlsConfig,
    pub application_name: String,
    pub connect_timeout: Duration,
    pub command_timeout: Duration,
    pub max_response_size: usize,
    pub packet_size: u16,
    pub strict_mode: bool,
    pub trust_server_certificate: bool,
    pub instance: Option<String>,
    pub mars: bool,
    pub encrypt: bool,
    pub no_tls: bool,
    pub redirect: RedirectConfig,
    pub retry: RetryPolicy,
    pub timeouts: TimeoutConfig,
    pub tds_version: TdsVersion,
    pub application_intent: ApplicationIntent,
    pub workstation_id: Option<String>,
    pub language: Option<String>,
    pub multi_subnet_failover: bool,
    pub send_string_parameters_as_unicode: bool,
    pub statement_cache: bool,
    pub column_encryption: Option<Arc<EncryptionConfig>>,
}

Configuration for connecting to SQL Server.

This struct is marked #[non_exhaustive] to allow adding new fields in future releases without breaking semver. Use Config::default() or Config::from_connection_string() to construct instances.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

host: String

Server hostname or IP address.

port: u16

Server port (default: 1433).

database: Option<String>

Database name.

credentials: Credentials

Authentication credentials.

tls: TlsConfig

TLS configuration (only available when tls feature is enabled).

application_name: String

Application name (shown in SQL Server management tools).

connect_timeout: Duration

Connection timeout.

command_timeout: Duration

Command timeout.

max_response_size: usize

Maximum size in bytes of a single buffered response (default: 0 = unlimited).

Query responses are buffered in full before rows are decoded (see the crate-level notes on streaming), so a very large SELECT is otherwise unbounded client memory. When the cap is exceeded the call fails with Error::ResponseTooLarge and the connection is discarded (the response was abandoned mid-stream). Paginate, narrow the SELECT, or raise the cap.

packet_size: u16

TDS packet size.

strict_mode: bool

Whether to use TDS 8.0 strict mode.

trust_server_certificate: bool

Whether to trust the server certificate.

instance: Option<String>

Instance name (for named instances).

mars: bool

Whether to enable MARS (Multiple Active Result Sets).

encrypt: bool

Whether to require encryption (TLS). When true, the connection will use TLS even if the server doesn’t require it. When false, encryption is used only if the server requires it.

no_tls: bool

Disable TLS entirely and connect with plaintext.

⚠️ SECURITY WARNING: This completely disables TLS/SSL encryption. Credentials and data will be transmitted in plaintext. Only use this for development/testing on trusted networks with legacy SQL Server instances that don’t support modern TLS versions.

This option exists for compatibility with legacy SQL Server versions (2008 and earlier) that may only support TLS 1.0/1.1, which modern TLS libraries (like rustls) don’t support for security reasons.

When true:

• Overrides the encrypt setting
• Sends ENCRYPT_NOT_SUP in PreLogin
• No TLS handshake occurs
• All traffic including login credentials is unencrypted

Do not use in production without understanding the security implications.

redirect: RedirectConfig

Redirect handling configuration (for Azure SQL).

retry: RetryPolicy

Retry policy for transient error handling.

timeouts: TimeoutConfig

Timeout configuration for various connection phases.

tds_version: TdsVersion

Requested TDS protocol version.

This specifies which TDS protocol version to request during connection. The server may negotiate a lower version if it doesn’t support the requested version.

Supported versions:

• TdsVersion::V7_3A - SQL Server 2008
• TdsVersion::V7_3B - SQL Server 2008 R2
• TdsVersion::V7_4 - SQL Server 2012+ (default)
• TdsVersion::V8_0 - SQL Server 2022+ strict mode (requires strict_mode = true)

Note: When strict_mode is enabled, this is ignored and TDS 8.0 is used.

application_intent: ApplicationIntent

Application workload intent for AlwaysOn Availability Group routing.

When set to ApplicationIntent::ReadOnly, SQL Server routes the connection to a readable secondary replica. Sent in LOGIN7 TypeFlags as the READONLY_INTENT bit.

workstation_id: Option<String>

Client workstation name sent to SQL Server in the LOGIN7 HostName field.

Used for auditing via sys.dm_exec_sessions.host_name. When None, the driver sends the machine hostname (from the COMPUTERNAME or HOSTNAME environment variable). Set via Workstation ID or WSID in connection strings.

language: Option<String>

Session language for server warning/error messages.

When set, sent in LOGIN7’s Language field. The language name can be up to 128 characters. Set via Language or Current Language in connection strings.

multi_subnet_failover: bool

Enable MultiSubnetFailover for AlwaysOn Availability Group listeners.

When true, the driver resolves the server hostname to all IP addresses and attempts parallel TCP connections simultaneously. The first successful connection wins and all others are cancelled. This reduces connection time when the AG listener spans multiple subnets.

Set via MultiSubnetFailover=True in connection strings.

Default: false

send_string_parameters_as_unicode: bool

Whether to send String/&str parameters as NVARCHAR (Unicode).

When true (default), string parameters are sent as NVARCHAR using UTF-16LE encoding. This is safe for all character sets but prevents SQL Server from using index seeks on VARCHAR columns (due to implicit NVARCHAR→VARCHAR conversion).

When false, string parameters are sent as VARCHAR using Windows-1252 encoding. This allows index seeks on VARCHAR columns but may lose data for characters outside the Windows-1252 range.

Set via SendStringParametersAsUnicode=false in connection strings.

Default: true

statement_cache: bool

Enable the client-side prepared-statement cache for parameterized query calls.

When true, a parameterized query is prepared once per connection (sp_prepare) and subsequent identical queries reuse the handle (sp_execute), trading a one-time cold-path round-trip for cheaper repeated execution. When false (default), every parameterized query uses sp_executesql (the server still reuses plans).

This is an opt-in first increment (the query path only; not query_stream, query_multiple, or Always Encrypted, which fall back to sp_executesql). Set via Statement Cache=true in connection strings.

Default: false

column_encryption: Option<Arc<EncryptionConfig>>

Always Encrypted configuration.

When Some, the client will negotiate Always Encrypted support with the server and transparently decrypt encrypted column values in result sets.

Set via Column Encryption Setting=Enabled in connection strings, or programmatically via Config::with_column_encryption.

Wrapped in Arc because EncryptionConfig contains trait objects (key store providers) which cannot implement Clone. The Arc allows Config to remain Clone while sharing the encryption configuration.

Implementations

impl Config

pub fn new() -> Self

Create a new configuration with default values.

pub fn from_connection_string(conn_str: &str) -> Result<Self, Error>

Parse a connection string into configuration.

Supports ADO.NET-style connection strings with full quoting support:

Server=localhost;Database=mydb;User Id=sa;Password="complex;pass";

Values containing semicolons can be enclosed in double or single quotes per the ADO.NET specification. The tcp: prefix from Azure Portal connection strings is automatically stripped.

pub fn host(self, host: impl Into<String>) -> Self

Set the server host.

pub fn port(self, port: u16) -> Self

Set the server port.

pub fn database(self, database: impl Into<String>) -> Self

Set the database name.

pub fn credentials(self, credentials: Credentials) -> Self

Set the credentials.

pub fn application_name(self, name: impl Into<String>) -> Self

Set the application name.

pub fn connect_timeout(self, timeout: Duration) -> Self

Set the connect timeout.

pub fn trust_server_certificate(self, trust: bool) -> Self

Set trust server certificate option.

pub fn strict_mode(self, enabled: bool) -> Self

Enable TDS 8.0 strict mode.

pub fn tds_version(self, version: TdsVersion) -> Self

Set the TDS protocol version.

This specifies which TDS protocol version to request during connection. The server may negotiate a lower version if it doesn’t support the requested version.

Examples

use mssql_client::Config;
use tds_protocol::version::TdsVersion;

// Connect to SQL Server 2008
let config = Config::new()
    .host("legacy-server")
    .tds_version(TdsVersion::V7_3A);

// Connect to SQL Server 2008 R2
let config = Config::new()
    .host("legacy-server")
    .tds_version(TdsVersion::V7_3B);

Note: When strict_mode is enabled, this is ignored and TDS 8.0 is used.

pub fn encrypt(self, enabled: bool) -> Self

Enable or disable TLS encryption.

When true (default), the connection will use TLS encryption. When false, encryption is used only if the server requires it.

Warning: Disabling encryption is insecure and should only be used for development/testing on trusted networks.

pub fn no_tls(self, enabled: bool) -> Self

Disable TLS entirely and connect with plaintext (Tiberius-compatible).

⚠️ SECURITY WARNING: This completely disables TLS/SSL encryption. Credentials and all data will be transmitted in plaintext over the network.

When to use this

This option exists for compatibility with legacy SQL Server versions (2008 and earlier) that may only support TLS 1.0/1.1. Modern TLS libraries like rustls require TLS 1.2 or higher for security reasons, making it impossible to establish encrypted connections to these older servers.

Security implications

When enabled:

• Login credentials are sent in plaintext
• All query data is transmitted without encryption
• Network traffic can be intercepted and read by attackers

Only use this for development/testing on isolated, trusted networks.

Example

use mssql_client::Config;

// Connection string (Tiberius-compatible)
let config = Config::from_connection_string(
    "Server=legacy-server;User Id=sa;Password=secret;Encrypt=no_tls"
)?;

// Builder API
let config = Config::new()
    .host("legacy-server")
    .no_tls(true);

pub fn with_column_encryption(self, config: EncryptionConfig) -> Self

Enable Always Encrypted with the given encryption configuration.

When enabled, the client will negotiate Always Encrypted support during connection and transparently decrypt encrypted column values.

Example

use mssql_client::{Config, EncryptionConfig};
use mssql_auth::InMemoryKeyStore;

let key_store = InMemoryKeyStore::new();
let config = Config::new()
    .with_column_encryption(
        EncryptionConfig::new().with_provider(key_store)
    );

pub fn with_host(self, host: &str) -> Self

Create a new configuration with a different host (for routing).

pub fn with_port(self, port: u16) -> Self

Create a new configuration with a different port (for routing).

pub fn with_statement_cache(self, enabled: bool) -> Self

Enable or disable the client-side prepared-statement cache.

See Config::statement_cache. Off by default.

pub fn redirect(self, redirect: RedirectConfig) -> Self

Set the redirect handling configuration.

pub fn max_redirects(self, max: u8) -> Self

Set the maximum number of redirect attempts.

pub fn retry(self, retry: RetryPolicy) -> Self

Set the retry policy for transient error handling.

pub fn max_retries(self, max: u32) -> Self

Set the maximum number of retry attempts.

pub fn timeouts(self, timeouts: TimeoutConfig) -> Self

Set the timeout configuration.

pub fn application_intent(self, intent: ApplicationIntent) -> Self

Set the application workload intent for AlwaysOn AG routing.

pub fn workstation_id(self, id: impl Into<String>) -> Self

Set the client workstation name sent to SQL Server in LOGIN7.

This appears in sys.dm_exec_sessions.host_name for auditing. When not set, the driver sends the machine hostname automatically.

pub fn language(self, lang: impl Into<String>) -> Self

Set the session language for server messages.

The language name can be up to 128 characters (e.g., "us_english").

pub fn multi_subnet_failover(self, enabled: bool) -> Self

Enable MultiSubnetFailover for AlwaysOn Availability Group listeners.

When enabled, the driver resolves the server hostname to all IP addresses and races parallel TCP connections. The first successful connection wins.

pub fn send_string_parameters_as_unicode(self, enabled: bool) -> Self

Control whether string parameters are sent as NVARCHAR (Unicode) or VARCHAR.

When false, String/&str parameters are sent as VARCHAR using Windows-1252 encoding, which allows SQL Server to use index seeks on VARCHAR columns.

Default: true (NVARCHAR)

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.