feat: Improve mssql port resolution logic

Co-authored-by: contact <[email protected]>

Author: cursoragent

sqlx-core/src/mssql/connection/stream.rs

@@ -51,10 +51,27 @@ pub(crate) struct MssqlStream {
 
 impl MssqlStream {
     pub(super) async fn connect(options: &MssqlConnectOptions) -> Result<Self, Error> {
-        let port = if let Some(ref instance) = options.instance {
-            super::ssrp::resolve_instance_port(&options.host, instance).await?
-        } else {
-            options.port
+        let port = match (options.port, &options.instance) {
+            (Some(port), _) => {
+                log::debug!(
+                    "using explicitly specified port {} for host '{}'",
+                    port,
+                    options.host
+                );
+                port
+            }
+            (None, Some(instance)) => {
+                super::ssrp::resolve_instance_port(&options.host, instance).await?
+            }
+            (None, None) => {
+                const DEFAULT_PORT: u16 = 1433;
+                log::debug!(
+                    "using default port {} for host '{}'",
+                    DEFAULT_PORT,
+                    options.host
+                );
+                DEFAULT_PORT
+            }
         };
 
         log::debug!("establishing TCP connection to {}:{}", options.host, port);

sqlx-core/src/mssql/options/mod.rs

@@ -13,15 +13,24 @@ mod parse;
 /// mssql://[username[:password]@]host[:port]/database[?param1=value1&param2=value2...]
 /// ```
 ///
-/// When connecting to a named instance, use the `instance` parameter:
+/// Port resolution priority:
+/// 1. If an explicit port is specified, it is always used
+/// 2. If a named instance is specified via `?instance=NAME`, the port is discovered via SSRP
+/// 3. Otherwise, the default port 1433 is used
+///
+/// Example with named instance (port auto-discovered):
 /// ```text
 /// mssql://user:pass@localhost/mydb?instance=SQLEXPRESS
 /// ```
-/// The port will be automatically discovered using the SQL Server Resolution Protocol (SSRP).
+///
+/// Example with explicit port (SSRP not used):
+/// ```text
+/// mssql://user:pass@localhost:1434/mydb?instance=SQLEXPRESS
+/// ```
 #[derive(Debug, Clone)]
 pub struct MssqlConnectOptions {
     pub(crate) host: String,
-    pub(crate) port: u16,
+    pub(crate) port: Option<u16>,
     pub(crate) username: String,
     pub(crate) database: String,
     pub(crate) password: Option<String>,
@@ -51,7 +60,7 @@ impl Default for MssqlConnectOptions {
 impl MssqlConnectOptions {
     pub fn new() -> Self {
         Self {
-            port: 1433,
+            port: None,
             host: String::from("localhost"),
             database: String::from("master"),
             username: String::from("sa"),
@@ -79,7 +88,7 @@ impl MssqlConnectOptions {
     }
 
     pub fn port(mut self, port: u16) -> Self {
-        self.port = port;
+        self.port = Some(port);
         self
     }
 

sqlx-core/src/mssql/options/parse.rs

@@ -19,11 +19,11 @@ impl FromStr for MssqlConnectOptions {
     /// - `username`: The username for SQL Server authentication.
     /// - `password`: The password for SQL Server authentication.
     /// - `host`: The hostname or IP address of the SQL Server.
-    /// - `port`: The port number (default is 1433).
+    /// - `port`: The port number. If not specified, defaults to 1433 or is discovered via SSRP when using named instances.
     /// - `database`: The name of the database to connect to.
     ///
     /// Supported query parameters:
-    /// - `instance`: SQL Server named instance. When specified, the port is automatically discovered using the SQL Server Resolution Protocol (SSRP).
+    /// - `instance`: SQL Server named instance. When specified without an explicit port, the port is automatically discovered using the SQL Server Resolution Protocol (SSRP). If a port is explicitly specified, SSRP is not used.
     /// - `encrypt`: Controls connection encryption:
     ///   - `strict`: Requires encryption and validates the server certificate.
     ///   - `mandatory` or `true` or `yes`: Requires encryption but doesn't validate the server certificate.