Discover sql server named instance ports

[lovasoa]

Add support for SQL Server named instances to automatically resolve ports via SSRP.

This PR implements the SQL Server Resolution Protocol (SSRP) to discover the correct TCP port for named instances, allowing users to specify instance=NAME in connection strings. It correctly handles MBCS encoding for SSRP responses as per the specification.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[lovasoa]

@cursoragent If an user enters a port explicitly, then the port discovery logic should not kick in :

pub struct MssqlConnectOptions {
    pub(crate) host: String,
    pub(crate) port: Option<u16>,

So: if the user enters a port, then use it. If not, then either do port discovery, or use the default port.

[cursor]

Perfect! I've updated the implementation to handle explicit ports correctly. Here's what changed:

Changes Made

1. Changed port to Option<u16> in MssqlConnectOptions

pub struct MssqlConnectOptions {
    pub(crate) host: String,
    pub(crate) port: Option<u16>,  // Was: u16
    // ...
}

2. Updated Connection Logic with proper priority:

let port = match (options.port, &options.instance) {
    (Some(port), _) => {
        // Priority 1: Explicit port always takes precedence
        log::debug!("using explicitly specified port {} for host '{}'", port, options.host);
        port
    }
    (None, Some(instance)) => {
        // Priority 2: No explicit port + instance name = use SSRP
        super::ssrp::resolve_instance_port(&options.host, instance).await?
    }
    (None, None) => {
        // Priority 3: No port, no instance = default 1433
        const DEFAULT_PORT: u16 = 1433;
        log::debug!("using default port {} for host '{}'", DEFAULT_PORT, options.host);
        DEFAULT_PORT
    }
};

3. Updated Documentation to clarify the behavior:

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

Examples:

// SSRP discovery (no port specified)
mssql://user:pass@localhost/mydb?instance=SQLEXPRESS

// Explicit port takes precedence (SSRP NOT used)
mssql://user:pass@localhost:1434/mydb?instance=SQLEXPRESS

// Default port 1433 (no port, no instance)
mssql://user:pass@localhost/mydb

✅ All checks pass
✅ No linter errors
✅ Works with both tokio and async-std runtimes

---

 

_{Learn more about Cursor Agents}