Use first-wins for synonym keys to match ODBC behaviour

_normalize_params and connstr_to_pycore_params now skip a
canonical key that was already set by an earlier synonym.
Matches ODBC Driver 18 fFromAttrOrProp first-wins semantics
confirmed via live test against sqlcconn.cpp.

Add TestSynonymFirstWins (12 tests) covering server/addr/
address, trustservercertificate snake_case, and packetsize
with-space synonym groups.

Author: bewithgaurav

mssql_python/connection_string_parser.py

@@ -108,8 +108,10 @@ def _normalize_params(params: Dict[str, str], warn_rejected: bool = True) -> Dic
                 if normalized_key in _RESERVED_PARAMETERS:
                     continue
 
-                # Parameter is allowed
-                filtered[normalized_key] = value
+                # First-wins: match ODBC behaviour where the first
+                # occurrence of a synonym group takes precedence.
+                if normalized_key not in filtered:
+                    filtered[normalized_key] = value
             else:
                 # Parameter is not in allow-list
                 # Note: In normal flow, this should be empty since parser validates first

mssql_python/helpers.py

@@ -266,9 +266,12 @@ def connstr_to_pycore_params(params: dict) -> dict:
     strings — ``connection.rs`` validates Yes/No and rejects invalid values.
     Unrecognised keys are silently dropped.
     """
-    # Only keys present in _ALLOWED_CONNECTION_STRING_PARAMS are mapped.
-    # Reserved/unsupported keys (app, workstationid, language, connect_timeout,
-    # mars_connection) are intentionally excluded — the parser rejects them.
+    # Only keys listed below are forwarded to py-core.
+    # Unknown/reserved keys (app, workstationid, language, connect_timeout,
+    # mars_connection) are silently dropped here.  In the normal connect()
+    # path the parser validates keywords first (validate_keywords=True),
+    # but bulkcopy parses with validation off, so this mapping is the
+    # authoritative filter in that path.
     key_map = {
         # auth / credentials
         "uid": "user_name",
@@ -316,6 +319,11 @@ def connstr_to_pycore_params(params: dict) -> dict:
         if raw_value is None:
             continue
 
+        # First-wins: match ODBC behaviour — first synonym in the
+        # connection string takes precedence (e.g. Addr before Server).
+        if pycore_key in pycore_params:
+            continue
+
         # ODBC values are always strings; py-core expects native types for int keys.
         # Boolean params (trust_server_certificate, multi_subnet_failover) are passed
         # as strings — all Yes/No validation is in connection.rs for single-location

tests/test_010_connection_string_parser.py

@@ -440,3 +440,99 @@ def test_incomplete_entry_recovery(self):
         # Should have error about incomplete 'Server'
         errors = exc_info.value.errors
         assert any("Server" in err and "Incomplete specification" in err for err in errors)
+
+
+class TestSynonymFirstWins:
+    """
+    Verify that _normalize_params uses first-wins for synonym keys.
+
+    ODBC Driver 18 behaviour (confirmed via live test against sqlcconn.cpp):
+      - Same key repeated   → first-wins  (fFromAttrOrProp guard)
+      - Addr vs Address     → same KEY_ADDR slot, first-wins
+      - Addr/Address vs Server → separate slots, Addr/Address takes priority
+
+    _ConnectionStringParser._parse() rejects exact duplicate keys outright.
+    These tests cover synonyms that map to the same canonical key during
+    normalization (e.g. addr/address/server → "Server").
+    """
+
+    @staticmethod
+    def _normalize(raw: dict) -> dict:
+        """Shorthand for calling _normalize_params with warnings suppressed."""
+        return _ConnectionStringParser._normalize_params(raw, warn_rejected=False)
+
+    # ---- server / addr / address synonyms --------------------------------
+
+    def test_server_then_addr_first_wins(self):
+        """Server=A;Addr=B → first-wins keeps A."""
+        result = self._normalize({"server": "hostA", "addr": "hostB"})
+        assert result["Server"] == "hostA"
+
+    def test_addr_then_server_first_wins(self):
+        """Addr=A;Server=B → first-wins keeps A."""
+        result = self._normalize({"addr": "hostA", "server": "hostB"})
+        assert result["Server"] == "hostA"
+
+    def test_address_then_server_first_wins(self):
+        """Address=A;Server=B → first-wins keeps A."""
+        result = self._normalize({"address": "hostA", "server": "hostB"})
+        assert result["Server"] == "hostA"
+
+    def test_addr_then_address_first_wins(self):
+        """Addr=A;Address=B → first-wins keeps A."""
+        result = self._normalize({"addr": "hostA", "address": "hostB"})
+        assert result["Server"] == "hostA"
+
+    def test_all_three_server_synonyms_first_wins(self):
+        """Addr=A;Address=B;Server=C → first-wins keeps A."""
+        result = self._normalize({"addr": "hostA", "address": "hostB", "server": "hostC"})
+        assert result["Server"] == "hostA"
+
+    def test_server_only_no_synonyms(self):
+        """Single key has no conflict."""
+        result = self._normalize({"server": "hostA"})
+        assert result["Server"] == "hostA"
+
+    # ---- trustservercertificate / trust_server_certificate synonyms ------
+
+    def test_trustservercertificate_then_snake_case_first_wins(self):
+        """trustservercertificate=Yes;trust_server_certificate=No → first-wins keeps Yes."""
+        result = self._normalize(
+            {"trustservercertificate": "Yes", "trust_server_certificate": "No"}
+        )
+        assert result["TrustServerCertificate"] == "Yes"
+
+    def test_snake_case_then_trustservercertificate_first_wins(self):
+        """trust_server_certificate=No;trustservercertificate=Yes → first-wins keeps No."""
+        result = self._normalize(
+            {"trust_server_certificate": "No", "trustservercertificate": "Yes"}
+        )
+        assert result["TrustServerCertificate"] == "No"
+
+    # ---- packetsize / "packet size" synonyms -----------------------------
+
+    def test_packetsize_then_packet_space_first_wins(self):
+        """packetsize=8192;packet size=4096 → first-wins keeps 8192."""
+        result = self._normalize({"packetsize": "8192", "packet size": "4096"})
+        assert result["PacketSize"] == "8192"
+
+    def test_packet_space_then_packetsize_first_wins(self):
+        """packet size=4096;packetsize=8192 → first-wins keeps 4096."""
+        result = self._normalize({"packet size": "4096", "packetsize": "8192"})
+        assert result["PacketSize"] == "4096"
+
+    # ---- non-synonym keys are unaffected ---------------------------------
+
+    def test_different_keys_both_kept(self):
+        """Non-synonym keys should both be present."""
+        result = self._normalize({"server": "host", "database": "mydb", "uid": "sa"})
+        assert result == {"Server": "host", "Database": "mydb", "UID": "sa"}
+
+    # ---- reserved keys filtered regardless of order ----------------------
+
+    def test_reserved_keys_always_filtered(self):
+        """Driver and APP are always stripped, even when first."""
+        result = self._normalize({"driver": "foo", "server": "host", "app": "bar"})
+        assert "Driver" not in result
+        assert "APP" not in result
+        assert result["Server"] == "host"