Skip to main content

sqlx_sqlserver/
options.rs

1use percent_encoding::percent_decode_str;
2use sqlx_core::connection::ConnectOptions;
3use sqlx_core::error::Error;
4use std::fmt;
5use std::path::{Path, PathBuf};
6use std::str::FromStr;
7use std::time::Duration;
8use thiserror::Error;
9use url::Url;
10
11use crate::MssqlConnection;
12
13/// SQL Server connection encryption preference.
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub enum Encrypt {
16    /// Encryption is not supported by the client.
17    NotSupported,
18    /// Use encryption when the server supports it.
19    Off,
20    /// Require encryption.
21    On,
22    /// Require encryption and certificate validation.
23    Required,
24}
25
26/// SQL Server connection options.
27#[derive(Clone, PartialEq, Eq)]
28pub struct MssqlConnectOptions {
29    host: String,
30    port: Option<u16>,
31    username: String,
32    password: Option<String>,
33    database: String,
34    instance: Option<String>,
35    encrypt: Encrypt,
36    trust_server_certificate: bool,
37    hostname_in_certificate: Option<String>,
38    ssl_root_cert: Option<PathBuf>,
39    requested_packet_size: u32,
40    client_program_version: u32,
41    client_pid: u32,
42    hostname: String,
43    app_name: String,
44    server_name: String,
45    client_interface_name: String,
46    language: String,
47}
48
49impl fmt::Debug for MssqlConnectOptions {
50    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51        f.debug_struct("MssqlConnectOptions")
52            .field("host", &self.host)
53            .field("port", &self.port)
54            .field("username", &self.username)
55            .field("password", &self.password.as_ref().map(|_| "[REDACTED]"))
56            .field("database", &self.database)
57            .field("instance", &self.instance)
58            .field("encrypt", &self.encrypt)
59            .field("trust_server_certificate", &self.trust_server_certificate)
60            .field("hostname_in_certificate", &self.hostname_in_certificate)
61            .field("ssl_root_cert", &self.ssl_root_cert)
62            .field("requested_packet_size", &self.requested_packet_size)
63            .field("client_program_version", &self.client_program_version)
64            .field("client_pid", &self.client_pid)
65            .field("hostname", &self.hostname)
66            .field("app_name", &self.app_name)
67            .field("server_name", &self.server_name)
68            .field("client_interface_name", &self.client_interface_name)
69            .field("language", &self.language)
70            .finish()
71    }
72}
73
74impl Default for MssqlConnectOptions {
75    fn default() -> Self {
76        Self::new()
77    }
78}
79
80impl MssqlConnectOptions {
81    /// Creates options with SQL Server defaults.
82    pub fn new() -> Self {
83        Self {
84            host: "localhost".to_owned(),
85            port: None,
86            username: "sa".to_owned(),
87            password: None,
88            database: "master".to_owned(),
89            instance: None,
90            encrypt: Encrypt::On,
91            trust_server_certificate: true,
92            hostname_in_certificate: None,
93            ssl_root_cert: None,
94            requested_packet_size: 4096,
95            client_program_version: 0,
96            client_pid: 0,
97            hostname: String::new(),
98            app_name: String::new(),
99            server_name: String::new(),
100            client_interface_name: String::new(),
101            language: String::new(),
102        }
103    }
104
105    /// Parses SQL Server connection options while preserving detailed parser errors.
106    pub fn parse_url(input: &str) -> Result<Self, MssqlInvalidOption> {
107        parse_url(input)
108    }
109
110    /// Returns the configured host.
111    pub fn host(&self) -> &str {
112        &self.host
113    }
114
115    /// Returns the configured port, if one was explicitly set.
116    pub fn port(&self) -> Option<u16> {
117        self.port
118    }
119
120    /// Returns the configured username.
121    pub fn username(&self) -> &str {
122        &self.username
123    }
124
125    /// Returns the configured password.
126    pub fn password(&self) -> Option<&str> {
127        self.password.as_deref()
128    }
129
130    /// Returns the configured database.
131    pub fn database(&self) -> &str {
132        &self.database
133    }
134
135    /// Returns the configured named instance, if any.
136    pub fn instance(&self) -> Option<&str> {
137        self.instance.as_deref()
138    }
139
140    /// Returns the encryption preference.
141    pub fn encrypt(&self) -> Encrypt {
142        self.encrypt
143    }
144
145    /// Returns whether server certificate validation is bypassed.
146    pub fn trust_server_certificate(&self) -> bool {
147        self.trust_server_certificate
148    }
149
150    /// Returns the hostname expected in the server certificate.
151    pub fn hostname_in_certificate(&self) -> Option<&str> {
152        self.hostname_in_certificate.as_deref()
153    }
154
155    /// Returns the configured root certificate path.
156    pub fn ssl_root_cert(&self) -> Option<&Path> {
157        self.ssl_root_cert.as_deref()
158    }
159
160    /// Returns the requested TDS packet size.
161    pub fn requested_packet_size(&self) -> u32 {
162        self.requested_packet_size
163    }
164
165    /// Returns the client program version sent during login.
166    pub fn client_program_version(&self) -> u32 {
167        self.client_program_version
168    }
169
170    /// Returns the client process ID sent during login.
171    pub fn client_pid(&self) -> u32 {
172        self.client_pid
173    }
174
175    /// Returns the client host name sent during login.
176    pub fn hostname(&self) -> &str {
177        &self.hostname
178    }
179
180    /// Returns the application name sent during login.
181    pub fn app_name(&self) -> &str {
182        &self.app_name
183    }
184
185    /// Returns the server name sent during login.
186    pub fn server_name(&self) -> &str {
187        &self.server_name
188    }
189
190    /// Returns the client interface name sent during login.
191    pub fn client_interface_name(&self) -> &str {
192        &self.client_interface_name
193    }
194
195    /// Returns the language sent during login.
196    pub fn language(&self) -> &str {
197        &self.language
198    }
199
200    fn set_requested_packet_size(&mut self, size: u32) -> Result<(), MssqlInvalidOption> {
201        if size < 512 {
202            return Err(MssqlInvalidOption::InvalidValue {
203                key: "packet_size".to_owned(),
204                value: size.to_string(),
205                message: "packet_size must be at least 512 bytes".to_owned(),
206            });
207        }
208
209        self.requested_packet_size = size;
210        Ok(())
211    }
212
213    #[cfg(test)]
214    pub(crate) fn set_hostname_for_test(&mut self, hostname: String) {
215        self.hostname = hostname;
216    }
217
218    #[cfg(feature = "migrate")]
219    pub(crate) fn set_database_for_maintenance(&mut self) {
220        self.database = "master".to_owned();
221    }
222}
223
224impl FromStr for MssqlConnectOptions {
225    type Err = Error;
226
227    fn from_str(input: &str) -> Result<Self, Self::Err> {
228        Self::parse_url(input).map_err(Error::config)
229    }
230}
231
232impl ConnectOptions for MssqlConnectOptions {
233    type Connection = MssqlConnection;
234
235    fn from_url(url: &Url) -> Result<Self, Error> {
236        Self::parse_url(url.as_str()).map_err(Error::config)
237    }
238
239    async fn connect(&self) -> Result<Self::Connection, Error>
240    where
241        Self::Connection: Sized,
242    {
243        MssqlConnection::establish(self).await
244    }
245
246    fn log_statements(self, _level: log::LevelFilter) -> Self {
247        self
248    }
249
250    fn log_slow_statements(self, _level: log::LevelFilter, _duration: Duration) -> Self {
251        self
252    }
253}
254
255fn parse_url(input: &str) -> Result<MssqlConnectOptions, MssqlInvalidOption> {
256    let url = Url::parse(input).map_err(MssqlInvalidOption::Url)?;
257    match url.scheme() {
258        "mssql" | "sqlserver" => {}
259        scheme => return Err(MssqlInvalidOption::UnsupportedScheme(scheme.to_owned())),
260    }
261
262    let mut options = MssqlConnectOptions::new();
263
264    if let Some(host) = url.host_str() {
265        options.host = host.to_owned();
266    }
267
268    options.port = url.port();
269
270    let username = url.username();
271    if !username.is_empty() {
272        options.username = percent_decode_str(username)
273            .decode_utf8()
274            .map_err(MssqlInvalidOption::Utf8)?
275            .into_owned();
276    }
277
278    if let Some(password) = url.password() {
279        options.password = Some(
280            percent_decode_str(password)
281                .decode_utf8()
282                .map_err(MssqlInvalidOption::Utf8)?
283                .into_owned(),
284        );
285    }
286
287    let path = url.path().trim_start_matches('/');
288    if !path.is_empty() {
289        options.database = percent_decode_str(path)
290            .decode_utf8()
291            .map_err(MssqlInvalidOption::Utf8)?
292            .into_owned();
293    }
294
295    for (key, value) in url.query_pairs() {
296        match key.as_ref() {
297            "instance" => options.instance = Some(value.into_owned()),
298            "encrypt" => {
299                options.encrypt =
300                    parse_encrypt(&value).ok_or_else(|| MssqlInvalidOption::InvalidValue {
301                        key: "encrypt".to_owned(),
302                        value: value.into_owned(),
303                        message: "expected strict, mandatory, optional, not_supported, true, false, yes, or no"
304                            .to_owned(),
305                    })?;
306            }
307            "sslrootcert" | "ssl-root-cert" | "ssl-ca" => {
308                options.ssl_root_cert = Some(PathBuf::from(value.as_ref()));
309            }
310            "trust_server_certificate" => {
311                options.trust_server_certificate =
312                    parse_bool(&value).ok_or_else(|| MssqlInvalidOption::InvalidValue {
313                        key: key.into_owned(),
314                        value: value.into_owned(),
315                        message: "expected true, false, yes, or no".to_owned(),
316                    })?;
317            }
318            "hostname_in_certificate" => {
319                options.hostname_in_certificate = Some(value.into_owned());
320            }
321            "packet_size" => {
322                let size = value
323                    .parse()
324                    .map_err(|_| MssqlInvalidOption::InvalidValue {
325                        key: "packet_size".to_owned(),
326                        value: value.to_string(),
327                        message: "expected an integer".to_owned(),
328                    })?;
329                options.set_requested_packet_size(size)?;
330            }
331            "client_program_version" => options.client_program_version = parse_u32(&key, &value)?,
332            "client_pid" => options.client_pid = parse_u32(&key, &value)?,
333            "hostname" => options.hostname = value.into_owned(),
334            "app_name" => options.app_name = value.into_owned(),
335            "server_name" => options.server_name = value.into_owned(),
336            "client_interface_name" => options.client_interface_name = value.into_owned(),
337            "language" => options.language = value.into_owned(),
338            _ => return Err(MssqlInvalidOption::UnknownOption(key.into_owned())),
339        }
340    }
341
342    Ok(options)
343}
344
345fn parse_encrypt(value: &str) -> Option<Encrypt> {
346    match value.to_ascii_lowercase().as_str() {
347        "strict" => Some(Encrypt::Required),
348        "mandatory" | "true" | "yes" => Some(Encrypt::On),
349        "optional" | "false" | "no" => Some(Encrypt::Off),
350        "not_supported" => Some(Encrypt::NotSupported),
351        _ => None,
352    }
353}
354
355fn parse_bool(value: &str) -> Option<bool> {
356    match value.to_ascii_lowercase().as_str() {
357        "true" | "yes" => Some(true),
358        "false" | "no" => Some(false),
359        _ => None,
360    }
361}
362
363fn parse_u32(key: &str, value: &str) -> Result<u32, MssqlInvalidOption> {
364    value.parse().map_err(|_| MssqlInvalidOption::InvalidValue {
365        key: key.to_owned(),
366        value: value.to_owned(),
367        message: "expected an integer".to_owned(),
368    })
369}
370
371/// Error returned while parsing SQL Server connection options.
372#[derive(Debug, Error)]
373pub enum MssqlInvalidOption {
374    /// URL syntax was invalid.
375    #[error("invalid SQL Server URL: {0}")]
376    Url(#[from] url::ParseError),
377    /// Percent-decoded URL component was not valid UTF-8.
378    #[error("invalid UTF-8 in SQL Server URL component: {0}")]
379    Utf8(#[from] std::str::Utf8Error),
380    /// The URL scheme is not supported by this driver.
381    #[error("unsupported SQL Server URL scheme `{0}`")]
382    UnsupportedScheme(String),
383    /// A query parameter is not recognized.
384    #[error("unknown SQL Server connection option `{0}`")]
385    UnknownOption(String),
386    /// A query parameter value is invalid.
387    #[error("invalid value `{value}` for SQL Server connection option `{key}`: {message}")]
388    InvalidValue {
389        /// Option name.
390        key: String,
391        /// Option value.
392        value: String,
393        /// Validation message.
394        message: String,
395    },
396}
397
398#[cfg(test)]
399mod tests {
400    use super::*;
401
402    #[test]
403    fn redacts_password_from_debug_output() {
404        let options =
405            MssqlConnectOptions::parse_url("mssql://sa:private-password@example.com/database")
406                .unwrap();
407        let debug = format!("{options:?}");
408
409        assert!(debug.contains("[REDACTED]"));
410        assert!(!debug.contains("private-password"));
411    }
412
413    #[test]
414    fn parses_username_with_at_sign() {
415        let opts =
416            MssqlConnectOptions::parse_url("mssql://user%40domain:secret@example.com/database")
417                .unwrap();
418
419        assert_eq!("user@domain", opts.username());
420        assert_eq!(Some("secret"), opts.password());
421    }
422
423    #[test]
424    fn parses_password_with_at_sign() {
425        let opts =
426            MssqlConnectOptions::parse_url("mssql://username:p%40ssw0rd@example.com/database")
427                .unwrap();
428
429        assert_eq!(Some("p@ssw0rd"), opts.password());
430    }
431
432    #[test]
433    fn parses_unescaped_username_with_at_sign() {
434        let opts =
435            MssqlConnectOptions::parse_url("mssql://user@hostname:password@example.com/database")
436                .unwrap();
437
438        assert_eq!("user@hostname", opts.username());
439        assert_eq!(Some("password"), opts.password());
440    }
441
442    #[test]
443    fn parses_unescaped_password_with_at_sign() {
444        let opts = MssqlConnectOptions::parse_url("mssql://username:p@ssw0rd@example.com/database")
445            .unwrap();
446
447        assert_eq!("username", opts.username());
448        assert_eq!(Some("p@ssw0rd"), opts.password());
449    }
450
451    #[test]
452    fn parses_named_instance_without_resolving_port() {
453        let opts = MssqlConnectOptions::parse_url(
454            "mssql://sa:secret@example.com/master?instance=SQLEXPRESS",
455        )
456        .unwrap();
457
458        assert_eq!("example.com", opts.host());
459        assert_eq!(None, opts.port());
460        assert_eq!(Some("SQLEXPRESS"), opts.instance());
461    }
462
463    #[test]
464    fn keeps_explicit_port_with_named_instance() {
465        let opts = MssqlConnectOptions::parse_url(
466            "mssql://sa:secret@example.com:1434/master?instance=SQLEXPRESS",
467        )
468        .unwrap();
469
470        assert_eq!(Some(1434), opts.port());
471        assert_eq!(Some("SQLEXPRESS"), opts.instance());
472    }
473
474    #[test]
475    fn parses_encryption_options() {
476        let strict =
477            MssqlConnectOptions::parse_url("mssql://localhost/master?encrypt=strict").unwrap();
478        let optional =
479            MssqlConnectOptions::parse_url("mssql://localhost/master?encrypt=optional").unwrap();
480        let disabled =
481            MssqlConnectOptions::parse_url("mssql://localhost/master?encrypt=not_supported")
482                .unwrap();
483
484        assert_eq!(Encrypt::Required, strict.encrypt());
485        assert_eq!(Encrypt::Off, optional.encrypt());
486        assert_eq!(Encrypt::NotSupported, disabled.encrypt());
487    }
488
489    #[test]
490    fn rejects_invalid_packet_size() {
491        let err = MssqlConnectOptions::parse_url("mssql://localhost/master?packet_size=128")
492            .expect_err("packet_size below 512 should be rejected");
493
494        assert!(err.to_string().contains("packet_size"));
495    }
496
497    #[test]
498    fn rejects_unknown_options() {
499        let err = MssqlConnectOptions::parse_url("mssql://localhost/master?mars=true")
500            .expect_err("unsupported options should fail loudly");
501
502        assert!(matches!(err, MssqlInvalidOption::UnknownOption(_)));
503    }
504}