FEAT: Add opt-in/opt-out ODBC provider selection (msodbcsql18 / mssql-odbc)

CHANGELOG.md

@@ -43,6 +43,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
   This is a non-breaking step toward decoupling driver-binary updates from
   mssql-python releases; a future major version will make the dependency
   explicit and drop the bundled binaries.
+- **Opt-in/opt-out native provider selection:** a new `mssql_python.native_provider`
+  module property (and `MSSQL_PYTHON_NATIVE_PROVIDER` environment variable, which
+  takes precedence) lets a caller select which native ODBC provider is loaded:
+  the default `"msodbcsql18"` (Microsoft ODBC Driver 18, unchanged behavior) or
+  the opt-in `"mssql-odbc"` (a Rust-based driver, shipped inside the
+  `mssql-python-rs` package alongside the Rust TDS core). The selection must be made before the first
+  connection; it resolves and freezes then, and a later change is ignored with
+  a `RuntimeWarning`; a conflicting property assignment also warns when the
+  environment variable takes precedence. Call `mssql_python.get_native_provider_info()`
+  for diagnostics (selected id, package, version, driver path, source, and
+  whether it's frozen). This PR
+  does not change the default provider or ship any Rust driver binaries.
 
 ### Changed
 - Connection strings and string connection parameters that contain a NUL

README.md

@@ -18,9 +18,12 @@ The driver is compatible with all the Python versions >= 3.10
 > - Import name: `mssql_python_odbc`
 > - Current version: **18.6.2.1**
 >
-> `mssql-python` depends on `mssql-python-odbc==18.6.2.1` and loads the ODBC driver binaries from it at import time. `pip install mssql-python` transparently pulls the companion package alongside it — no separate install step is required.
+> `mssql-python` depends on `mssql-python-odbc==18.6.2.1`. The ODBC driver is loaded lazily when the first connection is created. `pip install mssql-python` transparently pulls the companion package alongside it — no separate install step is required.
 >
-> Starting with v1.13.0, the bundled `libs/` fallback that shipped in v1.12.0 has been removed. `mssql-python` will fail to import if `mssql-python-odbc` is not installed. If you install `mssql-python` from a private index or with `--no-deps`, make sure `mssql-python-odbc==18.6.2.1` is installed alongside it.
+> Starting with v1.13.0, the bundled `libs/` fallback that shipped in v1.12.0 has been removed. Creating a connection will fail if `mssql-python-odbc` is not installed. If you install `mssql-python` from a private index or with `--no-deps`, make sure `mssql-python-odbc==18.6.2.1` is installed alongside it.
+>
+> ### ODBC Provider Selection (opt-in)
+> `mssql-python` also supports selecting an alternate native ODBC provider before the first connection, via the `mssql_python.native_provider` module property or the `MSSQL_PYTHON_NATIVE_PROVIDER` environment variable (which takes precedence). A conflicting property assignment emits a `RuntimeWarning`. The default, `"msodbcsql18"`, is unchanged; opting into `"mssql-odbc"` requires the `mssql-python-rs` package (which bundles the Rust ODBC driver alongside the Rust TDS core). Call `mssql_python.get_native_provider_info()` to check the selected provider, source, package version, and resolved driver path.
 
 ## Installation
 

mssql_python/__init__.py

@@ -9,6 +9,7 @@
 import threading
 import types
 import weakref
+from typing import Optional
 
 # Import settings from helpers module
 from .helpers import Settings, get_settings, _settings, _settings_lock
@@ -75,6 +76,20 @@
 # Pooling
 from .pooling import PoolingManager
 
+# ODBC provider selection
+from .odbc_provider import ProviderManager
+
+
+def get_native_provider_info() -> dict:
+    """Return the selected native provider for diagnostics.
+
+    Reports the provider ``id``, package ``version``, resolved ``driver_path``,
+    the ``package`` that ships its native binaries, selection ``source``, and
+    whether the choice is ``frozen`` (loaded and no longer changeable).
+    """
+    return ProviderManager.get_info()
+
+
 # Global registry for tracking active connections (using weak references)
 _active_connections = weakref.WeakSet()
 _connections_lock = threading.Lock()
@@ -510,6 +525,9 @@ def _cleanup_connections():
     # Module properties
     "lowercase",
     "native_uuid",
+    "native_provider",
+    # Native provider diagnostics
+    "get_native_provider_info",
 ]
 
 
@@ -583,6 +601,21 @@ def native_uuid(self, value: bool) -> None:
         with _settings_lock:
             _settings.native_uuid = value
 
+    @property
+    def native_provider(self) -> str:
+        """Get the native ODBC provider that will be (or was) loaded.
+
+        Honored only when set before the first connection; a later change is
+        ignored with a warning. The ``MSSQL_PYTHON_NATIVE_PROVIDER`` environment
+        variable takes precedence over this property.
+        """
+        return ProviderManager.effective()
+
+    @native_provider.setter
+    def native_provider(self, value: Optional[str]) -> None:
+        """Set the native ODBC provider selection (or None to clear)."""
+        ProviderManager.set_property(value)
+
 
 # Replace the current module with our custom module class
 old_module: types.ModuleType = sys.modules[__name__]

mssql_python/connection.py

@@ -28,6 +28,7 @@
 from mssql_python.logging import logger
 from mssql_python import ddbc_bindings
 from mssql_python.pooling import PoolingManager
+from mssql_python.odbc_provider import ProviderManager
 from mssql_python.exceptions import (
     Warning,  # pylint: disable=redefined-builtin
     Error,
@@ -730,6 +731,16 @@ def _token_factory():
             PoolingManager.enable()
         self._pooling = PoolingManager.is_enabled()
 
+        # Resolve and freeze the ODBC provider, then hand the selection to the
+        # native loader so it imports the matching provider package. Done here —
+        # after every Python-side validation and token acquisition has succeeded
+        # and immediately before the native driver loads — so a call that fails
+        # earlier never freezes the selection as a side effect; a later, corrected
+        # connection can then still choose a different provider without a process
+        # restart.
+        _provider = ProviderManager.ensure_available()
+        ddbc_bindings._set_odbc_provider(_provider)
+
         try:
             self._conn = ddbc_bindings.Connection(
                 self.connection_str,

mssql_python/mssql_python.pyi

@@ -30,6 +30,7 @@ threadsafety: int  # 1
 # Module Settings - Properties that can be get/set at module level
 lowercase: bool  # Controls column name case behavior
 native_uuid: bool  # Controls UUID type handling
+native_provider: Optional[str]  # Selects the native ODBC provider ('msodbcsql18' or 'mssql-odbc')
 
 # Settings Class
 class Settings:
@@ -43,6 +44,7 @@ def get_settings() -> Settings: ...
 def setDecimalSeparator(separator: str) -> None: ...
 def getDecimalSeparator() -> str: ...
 def pooling(max_size: int = 100, idle_timeout: int = 600, enabled: bool = True) -> None: ...
+def get_native_provider_info() -> Dict[str, object]: ...
 def get_info_constants() -> Dict[str, int]: ...
 
 # Logging Functions

mssql_python/odbc_provider.py

@@ -0,0 +1,250 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+Selects which ODBC provider (native driver package) mssql-python loads.
+
+Two providers are supported: ``msodbcsql18`` (the Microsoft ODBC Driver 18,
+shipped by ``mssql_python_odbc``) and ``mssql-odbc`` (the Rust driver, shipped
+inside ``mssql_py_core`` / the ``mssql-python-rs`` wheel). Selection is process-wide and resolved exactly
+once, before the native driver loads, from — in precedence order — the
+``MSSQL_PYTHON_NATIVE_PROVIDER`` environment variable, the ``mssql_python.native_provider``
+module property, then the release default. An unknown value fails closed rather
+than falling back.
+"""
+
+import os
+import threading
+import warnings
+import importlib
+from typing import Dict, Optional, Tuple
+
+from mssql_python.logging import logger
+
+NATIVE_PROVIDER_ENV_VAR = "MSSQL_PYTHON_NATIVE_PROVIDER"
+
+# Customer-facing provider identifiers.
+PROVIDER_MSODBCSQL18 = "msodbcsql18"
+PROVIDER_MSSQL_ODBC = "mssql-odbc"
+
+# Phase 1 default. Phase 2 flips this to PROVIDER_MSSQL_ODBC via a documented release.
+_DEFAULT_PROVIDER = PROVIDER_MSODBCSQL18
+
+# Provider -> import package that ships its native binaries.
+_PACKAGE_BY_PROVIDER: Dict[str, str] = {
+    PROVIDER_MSODBCSQL18: "mssql_python_odbc",
+    PROVIDER_MSSQL_ODBC: "mssql_py_core",
+}
+
+# Provider -> the pip distribution that installs its package (for error hints).
+_DIST_BY_PROVIDER: Dict[str, str] = {
+    PROVIDER_MSODBCSQL18: "mssql-python-odbc",
+    PROVIDER_MSSQL_ODBC: "mssql-python-rs",
+}
+
+
+def _normalize(value: str) -> str:
+    """Return the canonical provider id for ``value`` or raise ``ValueError``.
+
+    An unrecognized selection is rejected so a typo fails closed instead of
+    silently loading the default provider.
+    """
+    canonical = value.strip().lower()
+    if canonical not in _PACKAGE_BY_PROVIDER:
+        valid = ", ".join(sorted(_PACKAGE_BY_PROVIDER))
+        raise ValueError(f"Unknown ODBC provider {value!r}. Valid providers are: {valid}.")
+    return canonical
+
+
+class ProviderManager:
+    """Process-wide, resolve-once selector for the ODBC provider.
+
+    The selection freezes when :meth:`resolve` first runs (at native driver
+    load). A later change to the module property is ignored with a warning,
+    mirroring the connection-pool configuration model.
+    """
+
+    _lock: threading.Lock = threading.Lock()
+    _property_value: Optional[str] = None
+    _resolved: Optional[str] = None
+    _source: Optional[str] = None
+
+    @classmethod
+    def _compute(cls) -> Tuple[str, str]:
+        """Apply precedence env var -> module property -> default (lock-free)."""
+        env_value = os.environ.get(NATIVE_PROVIDER_ENV_VAR)
+        if env_value and env_value.strip():
+            return _normalize(env_value), "environment"
+        if cls._property_value is not None:
+            return cls._property_value, "property"
+        return _DEFAULT_PROVIDER, "default"
+
+    @classmethod
+    def set_property(cls, value: Optional[str]) -> None:
+        """Set the module-property selection.
+
+        Accepts a provider id or ``None`` to clear. A change after the provider
+        has been resolved is ignored with a warning; the env var still takes
+        precedence over this value when both are set.
+        """
+        with cls._lock:
+            canonical = _normalize(value) if value is not None else None
+            if cls._resolved is not None:
+                if canonical != cls._resolved:
+                    cls._warn_frozen()
+                return
+            cls._property_value = canonical
+            env_value = os.environ.get(NATIVE_PROVIDER_ENV_VAR)
+            if canonical is not None and env_value and env_value.strip():
+                try:
+                    env_provider = _normalize(env_value)
+                except ValueError:
+                    # Preserve the existing fail-closed error at connection time.
+                    return
+                if canonical != env_provider:
+                    cls._warn_env_override(canonical, env_provider)
+
+    @classmethod
+    def resolve(cls) -> str:
+        """Resolve and freeze the provider, returning its canonical id."""
+        with cls._lock:
+            if cls._resolved is None:
+                cls._resolved, cls._source = cls._compute()
+                logger.info(
+                    "ODBC provider resolved to '%s' (source=%s)",
+                    cls._resolved,
+                    cls._source,
+                )
+            return cls._resolved
+
+    @classmethod
+    def effective(cls) -> str:
+        """Return the provider that would be used, without freezing it.
+
+        Reports the release default for an invalid selection (e.g. a mistyped
+        env var) rather than raising - this backs the public getter and
+        diagnostics, which must stay safe to read at any time. The hard
+        failure for a bad selection surfaces at :meth:`resolve`/
+        :meth:`ensure_available` instead.
+        """
+        with cls._lock:
+            if cls._resolved is not None:
+                return cls._resolved
+            try:
+                provider, _ = cls._compute()
+            except ValueError:
+                return _DEFAULT_PROVIDER
+            return provider
+
+    @classmethod
+    def package_name(cls, provider: Optional[str] = None) -> str:
+        """Return the import package that ships ``provider``'s native binaries."""
+        provider = provider or cls.effective()
+        return _PACKAGE_BY_PROVIDER[provider]
+
+    @classmethod
+    def ensure_available(cls) -> str:
+        """Verify the selected provider's package is installed, then freeze it.
+
+        Called before the native driver loads. Fails closed with an actionable
+        error if the package is missing. The selection is only frozen (via
+        :meth:`resolve`) once the package has been confirmed importable, so a
+        failed check here does not permanently lock in a provider that never
+        actually loaded - a later call can still select a different, installed
+        provider instead of requiring a process restart.
+        """
+        provider = cls.effective()
+        package = _PACKAGE_BY_PROVIDER[provider]
+        try:
+            importlib.import_module(package)
+        except ModuleNotFoundError as exc:
+            if exc.name != package:
+                # A transitive dependency of an installed package is missing,
+                # or the package is broken - don't mask it as "not installed".
+                raise
+            dist = _DIST_BY_PROVIDER[provider]
+            raise ImportError(
+                f"The '{provider}' ODBC provider is selected but its package "
+                f"'{package}' is not installed. Install it with: pip install {dist}"
+            ) from exc
+        return cls.resolve()
+
+    @classmethod
+    def is_frozen(cls) -> bool:
+        """Whether the provider has been resolved and can no longer change."""
+        return cls._resolved is not None
+
+    @classmethod
+    def get_info(cls) -> Dict[str, object]:
+        """Report the selected provider for diagnostics.
+
+        Never raises: an invalid selection is reported via the ``error`` key
+        (with ``id`` falling back to the default) instead of propagating, so
+        this stays safe to call at any time, including before a provider is
+        chosen or resolvable.
+        """
+        with cls._lock:
+            if cls._resolved is not None:
+                provider, source, error = cls._resolved, cls._source, None
+            else:
+                try:
+                    provider, source = cls._compute()
+                    error = None
+                except ValueError as exc:
+                    provider, source, error = _DEFAULT_PROVIDER, None, str(exc)
+            frozen = cls._resolved is not None
+
+        version = None
+        driver_path = None
+        package = _PACKAGE_BY_PROVIDER[provider]
+        try:
+            provider_module = importlib.import_module(package)
+            version = getattr(provider_module, "__version__", None)
+            module_file = getattr(provider_module, "__file__", None)
+            if module_file:
+                from mssql_python import ddbc_bindings
+
+                driver_path = ddbc_bindings._get_odbc_driver_path(
+                    os.path.dirname(os.path.abspath(module_file)), provider
+                )
+        except Exception:  # pylint: disable=broad-exception-caught
+            # Diagnostics must remain safe even for a broken provider package.
+            pass
+
+        info: Dict[str, object] = {
+            "id": provider,
+            "package": package,
+            "version": version,
+            "driver_path": driver_path,
+            "source": source,
+            "frozen": frozen,
+        }
+        if error is not None:
+            info["error"] = error
+        return info
+
+    @classmethod
+    def _warn_env_override(cls, requested: str, effective: str) -> None:
+        message = (
+            f"ODBC provider property was set to '{requested}', but "
+            f"{NATIVE_PROVIDER_ENV_VAR} selects '{effective}' and takes precedence."
+        )
+        logger.warning(message)
+        warnings.warn(message, RuntimeWarning, stacklevel=3)
+
+    @classmethod
+    def _warn_frozen(cls) -> None:
+        message = (
+            f"ODBC provider is already loaded as '{cls._resolved}'; ignoring the "
+            f"change. Select a provider before the first connection, or set the "
+            f"{NATIVE_PROVIDER_ENV_VAR} environment variable."
+        )
+        logger.warning(message)
+        warnings.warn(message, RuntimeWarning, stacklevel=3)
+
+    @classmethod
+    def _reset_for_testing(cls) -> None:
+        """Reset selection state - for testing purposes only."""
+        with cls._lock:
+            cls._property_value = None
+            cls._resolved = None
+            cls._source = None

mssql_python/pooling.py

@@ -62,6 +62,10 @@ def enable(cls, max_size: int = 100, idle_timeout: int = 600) -> None:
                 max_size,
                 idle_timeout,
             )
+            # enable_pooling() only configures the connection-pool manager; it
+            # does not load the native driver, so it must not resolve/freeze
+            # the ODBC provider (an explicit pooling() before selecting a
+            # provider would otherwise lock in the default prematurely).
             ddbc_bindings.enable_pooling(max_size, idle_timeout)
             cls._config["max_size"] = max_size
             cls._config["idle_timeout"] = idle_timeout