mssql-python 1.0.0__cp314-cp314-win_amd64.whl

mssql_python/libs/windows/x64/MICROSOFT_VISUAL_STUDIO_LICENSE.txt

@@ -0,0 +1,54 @@
+MICROSOFT SOFTWARE LICENSE TERMS
+MICROSOFT VISUAL STUDIO 2017 TOOLS, ADD-ONs and EXTENSIONS
+
+These license terms are an agreement between Microsoft Corporation (or based on where you live, one of its affiliates) and you. 
+They apply to the software named above. The terms also apply to any Microsoft services or updates for the 
+software, except to the extent those have different terms.
+
+IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW.
+
+1. INSTALLATION AND USE RIGHTS.
+    You may install and use any number of copies of the software.
+
+2. TERMS FOR SPECIFIC COMPONENTS.
+    a. Utilities. The software may contain some items on the Utilities List at https://go.microsoft.com/fwlink/?linkid=823097. You may copy and install these Utilities, if included with the software, onto devices to debug and deploy your applications and databases you developed with the software. Please note that Utilities are designed for temporary use, that Microsoft may not be able to patch or update Utilities separately from the rest of the software, and that some Utilities by their nature may make it possible for others to access devices on which the Utilities are installed. As a result, you should delete all Utilities you have installed after you finish debugging or deploying your applications and databases. Microsoft is not responsible for any third party use or access of Utilities you install on any device.
+    b. Build Tools. The software may include build tools which have specific use terms. For build tools, you may copy and install files from the software onto your build devices, including physical devices and virtual machines or containers on those machines, whether on-premises or remote machines that are owned by you, hosted on Azure for you, or dedicated solely to your use (collectively, “Build Devices”). You and others in your organization may use these files on your Build Devices solely to compile, build, and verify applications or run quality or performance tests of those applications as part of the build process. For clarity, “applications” means applications developed by you and others in your organization who are each licensed to use the software.
+    c. Microsoft Platforms. The software may include components from Microsoft Windows; Microsoft Windows Server; Microsoft SQL Server; Microsoft Exchange; Microsoft Office; and Microsoft SharePoint. These components are governed by separate agreements and their own product support policies, as described in the Microsoft “Licenses” folder accompanying the software, except that, if license terms for those components are also included in the associated installation directory, those license terms control.
+    d. Third Party Components. The software may include third party components with separate legal notices or governed by other agreements, as may be described in the ThirdPartyNotices file(s) accompanying the software.
+
+3. DATA.
+    a. Data Collection. The software may collect information about you and your use of the software, and send that to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may opt-out of many of these scenarios, but not all, as described in the product documentation. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications and you should provide a copy of Microsoft’s privacy statement to your users. The Microsoft privacy statement is located here https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.
+    b. Processing of Personal Data. To the extent Microsoft is a processor or subprocessor of personal data in connection with the software, Microsoft makes the commitments in the European Union General Data Protection Regulation Terms of the Online Services Terms to all customers effective May 25, 2018, at http://go.microsoft.com/?linkid=9840733.
+
+4. SCOPE OF LICENSE. The software is licensed, not sold. This agreement only gives you some rights to use the software. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this agreement. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways. You may not
+    · work around any technical limitations in the software;
+    · reverse engineer, decompile or disassemble the software, or otherwise attempt to derive the source code for the software except, and only to the extent required by third party licensing terms governing the use of certain open source components that may be included in the software;
+    · remove, minimize, block or modify any notices of Microsoft or its suppliers in the software;
+    · use the software in any way that is against the law; or
+    · share, publish, rent or lease the software, or provide the software as a stand-alone hosted as solution for others to use, or transfer the software or this agreement to any third party.
+
+5. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit www.microsoft.com/exporting.
+
+6. SUPPORT SERVICES. Because this software is “as is,” we may not provide support services for it.
+
+7. ENTIRE AGREEMENT. This agreement, and the terms for supplements, updates, Internet-based services and support services that you use, are the entire agreement for the software and support services.
+
+8. APPLICABLE LAW. If you acquired the software in the United States, Washington law applies to interpretation of and claims for breach of this agreement, and the laws of the state where you live apply to all other claims. If you acquired the software in any other country, its laws apply.
+
+9. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you:
+    a. Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights.
+    b. Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software.
+    c. Germany and Austria.
+    (i) Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software.
+    (ii) Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law.
+
+    Subject to the foregoing clause (ii), Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence.
+
+10. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS-IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES OR CONDITIONS. TO THE EXTENT PERMITTED UNDER YOUR LOCAL LAWS, MICROSOFT EXCLUDES THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+11. LIMITATION ON AND EXCLUSION OF DAMAGES. YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES.
+This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law.
+
+It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages.
+
+EULA ID: VS 2017_TOOLS_ADDONs_C++_RTW.3_ENU

mssql_python/logging.py

@@ -0,0 +1,610 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+
+Enhanced logging module for mssql_python with JDBC-style logging levels.
+This module provides fine-grained logging control with zero overhead when disabled.
+"""
+
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+import sys
+import threading
+import datetime
+import re
+import platform
+import atexit
+from typing import Optional
+
+
+# Single DEBUG level - all or nothing philosophy
+# If you need logging, you need to see everything
+DEBUG = logging.DEBUG        # 10
+
+# Output destination constants
+STDOUT = 'stdout'  # Log to stdout only
+FILE = 'file'      # Log to file only (default)
+BOTH = 'both'      # Log to both file and stdout
+
+# Allowed log file extensions
+ALLOWED_LOG_EXTENSIONS = {'.txt', '.log', '.csv'}
+
+
+class ThreadIDFilter(logging.Filter):
+    """Filter that adds thread_id to all log records."""
+    
+    def filter(self, record):
+        """Add thread_id (OS native) attribute to log record."""
+        # Use OS native thread ID for debugging compatibility
+        try:
+            thread_id = threading.get_native_id()
+        except AttributeError:
+            # Fallback for Python < 3.8
+            thread_id = threading.current_thread().ident
+        record.thread_id = thread_id
+        return True
+
+
+
+
+class MSSQLLogger:
+    """
+    Singleton logger for mssql_python with single DEBUG level.
+    
+    Philosophy: All or nothing - if you enable logging, you see EVERYTHING.
+    Logging is a troubleshooting tool, not a production feature.
+    
+    Features:
+    - Single DEBUG level (no categorization)
+    - Automatic file rotation (512MB, 5 backups)
+    - Password sanitization
+    - Trace ID support with contextvars (automatic propagation)
+    - Thread-safe operation
+    - Zero overhead when disabled (level check only)
+    
+    ⚠️ Performance Warning: Logging adds ~2-5% overhead. Only enable when troubleshooting.
+    """
+    
+    _instance: Optional['MSSQLLogger'] = None
+    _lock = threading.Lock()
+    _init_lock = threading.Lock()  # Separate lock for initialization
+    
+    def __new__(cls) -> 'MSSQLLogger':
+        """Ensure singleton pattern"""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super(MSSQLLogger, cls).__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        """Initialize the logger (only once) - thread-safe"""
+        # Use separate lock for initialization check to prevent race condition
+        # This ensures hasattr check and assignment are atomic
+        with self._init_lock:
+            # Skip if already initialized
+            if hasattr(self, '_initialized'):
+                return
+            
+            self._initialized = True
+        
+        # Create the underlying Python logger
+        self._logger = logging.getLogger('mssql_python')
+        self._logger.setLevel(logging.CRITICAL)  # Disabled by default
+        self._logger.propagate = False  # Don't propagate to root logger
+        
+        # Add trace ID filter (injects thread_id into every log record)
+        self._logger.addFilter(ThreadIDFilter())
+        
+        # Output mode and handlers
+        self._output_mode = FILE  # Default to file only
+        self._file_handler = None
+        self._stdout_handler = None
+        self._log_file = None
+        self._custom_log_path = None  # Custom log file path (if specified)
+        self._handlers_initialized = False
+        self._handler_lock = threading.RLock()  # Reentrant lock for handler operations
+        self._cleanup_registered = False  # Track if atexit cleanup is registered
+        
+        # Don't setup handlers yet - do it lazily when setLevel is called
+        # This prevents creating log files when user changes output mode before enabling logging
+    
+    def _setup_handlers(self):
+        """
+        Setup handlers based on output mode.
+        Creates file handler and/or stdout handler as needed.
+        Thread-safe: Protects against concurrent handler removal during logging.
+        """
+        # Lock prevents race condition where one thread logs while another removes handlers
+        with self._handler_lock:
+            # Acquire locks on all existing handlers before closing
+            # This ensures no thread is mid-write when we close
+            old_handlers = self._logger.handlers[:]
+            for handler in old_handlers:
+                handler.acquire()
+            
+            try:
+                # Flush and close each handler while holding its lock
+                for handler in old_handlers:
+                    try:
+                        handler.flush()  # Flush BEFORE close
+                    except:
+                        pass  # Ignore flush errors
+                    handler.close()
+                    self._logger.removeHandler(handler)
+            finally:
+                # Release locks on old handlers
+                for handler in old_handlers:
+                    try:
+                        handler.release()
+                    except:
+                        pass  # Handler might already be closed
+            
+            self._file_handler = None
+            self._stdout_handler = None
+        
+        # Create CSV formatter
+        # Custom formatter to extract source from message and format as CSV
+        class CSVFormatter(logging.Formatter):
+            def format(self, record):
+                # Extract source from message (e.g., [Python] or [DDBC])
+                msg = record.getMessage()
+                if msg.startswith('[') and ']' in msg:
+                    end_bracket = msg.index(']')
+                    source = msg[1:end_bracket]
+                    message = msg[end_bracket+2:].strip()  # Skip '] '
+                else:
+                    source = 'Unknown'
+                    message = msg
+                
+                # Format timestamp with milliseconds using period separator
+                timestamp = self.formatTime(record, '%Y-%m-%d %H:%M:%S')
+                timestamp_with_ms = f"{timestamp}.{int(record.msecs):03d}"
+                
+                # Get thread ID
+                thread_id = getattr(record, 'thread_id', 0)
+                
+                # Build CSV row
+                location = f"{record.filename}:{record.lineno}"
+                csv_row = f"{timestamp_with_ms}, {thread_id}, {record.levelname}, {location}, {source}, {message}"
+                
+                return csv_row
+        
+        formatter = CSVFormatter()
+        
+        # Override format to use milliseconds with period separator
+        formatter.default_msec_format = '%s.%03d'
+        
+        # Setup file handler if needed
+        if self._output_mode in (FILE, BOTH):
+            # Use custom path or auto-generate
+            if self._custom_log_path:
+                self._log_file = self._custom_log_path
+                # Ensure directory exists for custom path
+                log_dir = os.path.dirname(self._custom_log_path)
+                if log_dir and not os.path.exists(log_dir):
+                    os.makedirs(log_dir, exist_ok=True)
+            else:
+                # Create log file in mssql_python_logs folder
+                log_dir = os.path.join(os.getcwd(), "mssql_python_logs")
+                if not os.path.exists(log_dir):
+                    os.makedirs(log_dir, exist_ok=True)
+                
+                timestamp = datetime.datetime.now().strftime("%Y%m%d%H%M%S")
+                pid = os.getpid()
+                self._log_file = os.path.join(
+                    log_dir,
+                    f"mssql_python_trace_{timestamp}_{pid}.log"
+                )
+            
+            # Create rotating file handler (512MB, 5 backups)
+            # Use UTF-8 encoding for unicode support on all platforms
+            self._file_handler = RotatingFileHandler(
+                self._log_file,
+                maxBytes=512 * 1024 * 1024,  # 512MB
+                backupCount=5,
+                encoding='utf-8'
+            )
+            self._file_handler.setFormatter(formatter)
+            self._logger.addHandler(self._file_handler)
+            
+            # Write CSV header to new log file
+            self._write_log_header()
+        else:
+            # No file logging - clear the log file path
+            self._log_file = None
+        
+        # Setup stdout handler if needed
+        if self._output_mode in (STDOUT, BOTH):
+            import sys
+            self._stdout_handler = logging.StreamHandler(sys.stdout)
+            self._stdout_handler.setFormatter(formatter)
+            self._logger.addHandler(self._stdout_handler)
+    
+    def _reconfigure_handlers(self):
+        """
+        Reconfigure handlers when output mode changes.
+        Closes existing handlers and creates new ones based on current output mode.
+        """
+        self._setup_handlers()
+    
+    def _cleanup_handlers(self):
+        """
+        Cleanup all handlers on process exit.
+        Registered with atexit to ensure proper file handle cleanup.
+        
+        Thread-safe: Protects against concurrent logging during cleanup.
+        
+        Note on RotatingFileHandler:
+            - File rotation (at 512MB) is already thread-safe
+            - doRollover() is called within emit() which holds handler.lock
+            - No additional synchronization needed for rotation
+        """
+        with self._handler_lock:
+            handlers = self._logger.handlers[:]
+            for handler in handlers:
+                handler.acquire()
+            
+            try:
+                for handler in handlers:
+                    try:
+                        handler.flush()
+                        handler.close()
+                    except:
+                        pass  # Ignore errors during cleanup
+                    self._logger.removeHandler(handler)
+            finally:
+                for handler in handlers:
+                    try:
+                        handler.release()
+                    except:
+                        pass
+    
+    def _validate_log_file_extension(self, file_path: str) -> None:
+        """
+        Validate that the log file has an allowed extension.
+        
+        Args:
+            file_path: Path to the log file
+            
+        Raises:
+            ValueError: If the file extension is not allowed
+        """
+        _, ext = os.path.splitext(file_path)
+        ext_lower = ext.lower()
+        
+        if ext_lower not in ALLOWED_LOG_EXTENSIONS:
+            allowed = ', '.join(sorted(ALLOWED_LOG_EXTENSIONS))
+            raise ValueError(
+                f"Invalid log file extension '{ext}'. "
+                f"Allowed extensions: {allowed}"
+            )
+    
+    def _write_log_header(self):
+        """
+        Write CSV header and metadata to the log file.
+        Called once when log file is created.
+        """
+        if not self._log_file or not self._file_handler:
+            return
+        
+        try:
+            # Get script name from sys.argv or __main__
+            script_name = os.path.basename(sys.argv[0]) if sys.argv else '<interactive>'
+            
+            # Get Python version
+            python_version = platform.python_version()
+            
+            # Get driver version (try to import from package)
+            try:
+                from mssql_python import __version__
+                driver_version = __version__
+            except:
+                driver_version = 'unknown'
+            
+            # Get current time
+            start_time = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+            
+            # Get PID
+            pid = os.getpid()
+            
+            # Get OS info
+            os_info = platform.platform()
+            
+            # Build header comment line
+            header_line = f"# MSSQL-Python Driver Log | Script: {script_name} | PID: {pid} | Log Level: DEBUG | Python: {python_version} | Driver: {driver_version} | Start: {start_time} | OS: {os_info}\n"
+            
+            # CSV column headers
+            csv_header = "Timestamp, ThreadID, Level, Location, Source, Message\n"
+            
+            # Write directly to file (bypass formatter)
+            with open(self._log_file, 'a') as f:
+                f.write(header_line)
+                f.write(csv_header)
+                
+        except Exception as e:
+            # Notify on stderr so user knows why header is missing
+            try:
+                sys.stderr.write(f"[MSSQL-Python] Warning: Failed to write log header to {self._log_file}: {type(e).__name__}\n")
+                sys.stderr.flush()
+            except:
+                pass  # Even stderr notification failed
+            # Don't crash - logging continues without header
+    
+    def _log(self, level: int, msg: str, add_prefix: bool = True, *args, **kwargs):
+        """
+        Internal logging method with exception safety.
+        
+        Args:
+            level: Log level (DEBUG, INFO, WARNING, ERROR)
+            msg: Message format string
+            add_prefix: Whether to add [Python] prefix (default True)
+            *args: Arguments for message formatting
+            **kwargs: Additional keyword arguments
+        
+        Note:
+            Callers are responsible for sanitizing sensitive data (passwords,
+            tokens, etc.) before logging. Use helpers.sanitize_connection_string()
+            for connection strings.
+        
+        Exception Safety:
+            NEVER crashes the application. Catches all exceptions:
+            - TypeError/ValueError: Bad format string or args
+            - IOError/OSError: Disk full, permission denied
+            - UnicodeEncodeError: Encoding issues
+            
+            On critical failures (ERROR level), attempts stderr fallback.
+            All other failures are silently ignored to prevent app crashes.
+        """
+        try:
+            # Fast level check (zero overhead if disabled)
+            if not self._logger.isEnabledFor(level):
+                return
+            
+            # Add prefix if requested (only after level check)
+            if add_prefix:
+                msg = f"[Python] {msg}"
+            
+            # Format message with args if provided
+            if args:
+                msg = msg % args
+            
+            # Log the message (no args since already formatted)
+            self._logger.log(level, msg, **kwargs)
+        except Exception:
+            # Last resort: Try stderr fallback for any logging failure
+            # This helps diagnose critical issues (disk full, permission denied, etc.)
+            try:
+                import sys
+                level_name = logging.getLevelName(level)
+                sys.stderr.write(f"[MSSQL-Python Logging Failed - {level_name}] {msg if 'msg' in locals() else 'Unable to format message'}\n")
+                sys.stderr.flush()
+            except:
+                pass  # Even stderr failed - give up silently
+    
+    # Convenience methods for logging
+    
+    def debug(self, msg: str, *args, **kwargs):
+        """Log at DEBUG level (all diagnostic messages)"""
+        self._log(logging.DEBUG, msg, True, *args, **kwargs)
+    
+    def info(self, msg: str, *args, **kwargs):
+        """Log at INFO level"""
+        self._log(logging.INFO, msg, True, *args, **kwargs)
+    
+    def warning(self, msg: str, *args, **kwargs):
+        """Log at WARNING level"""
+        self._log(logging.WARNING, msg, True, *args, **kwargs)
+    
+    def error(self, msg: str, *args, **kwargs):
+        """Log at ERROR level"""
+        self._log(logging.ERROR, msg, True, *args, **kwargs)
+    
+    # Level control
+    
+    def _setLevel(self, level: int, output: Optional[str] = None, log_file_path: Optional[str] = None):
+        """
+        Internal method to set logging level (use setup_logging() instead).
+        
+        Args:
+            level: Logging level (typically DEBUG)
+            output: Optional output mode (FILE, STDOUT, BOTH)
+            log_file_path: Optional custom path for log file
+        
+        Raises:
+            ValueError: If output mode is invalid
+        """
+        # Validate and set output mode if specified
+        if output is not None:
+            if output not in (FILE, STDOUT, BOTH):
+                raise ValueError(
+                    f"Invalid output mode: {output}. "
+                    f"Must be one of: {FILE}, {STDOUT}, {BOTH}"
+                )
+            self._output_mode = output
+        
+        # Store custom log file path if provided
+        if log_file_path is not None:
+            self._validate_log_file_extension(log_file_path)
+            self._custom_log_path = log_file_path
+        
+        # Setup handlers if not yet initialized or if output mode/path changed
+        # Handler setup is protected by _handler_lock inside _setup_handlers()
+        if not self._handlers_initialized or output is not None or log_file_path is not None:
+            self._setup_handlers()
+            self._handlers_initialized = True
+            
+            # Register atexit cleanup on first handler setup
+            if not self._cleanup_registered:
+                atexit.register(self._cleanup_handlers)
+                self._cleanup_registered = True
+        
+        # Set level (atomic operation, no lock needed)
+        self._logger.setLevel(level)
+        
+        # Notify C++ bridge of level change
+        self._notify_cpp_level_change(level)
+    
+    def getLevel(self) -> int:
+        """
+        Get the current logging level.
+        
+        Returns:
+            int: Current log level
+        """
+        return self._logger.level
+    
+    def isEnabledFor(self, level: int) -> bool:
+        """
+        Check if a given log level is enabled.
+        
+        Args:
+            level: Log level to check
+            
+        Returns:
+            bool: True if the level is enabled
+        """
+        return self._logger.isEnabledFor(level)
+    
+    # Handler management
+    
+    def addHandler(self, handler: logging.Handler):
+        """Add a handler to the logger (thread-safe)"""
+        with self._handler_lock:
+            self._logger.addHandler(handler)
+    
+    def removeHandler(self, handler: logging.Handler):
+        """Remove a handler from the logger (thread-safe)"""
+        with self._handler_lock:
+            self._logger.removeHandler(handler)
+    
+    @property
+    def handlers(self) -> list:
+        """Get list of handlers attached to the logger (thread-safe)"""
+        with self._handler_lock:
+            return self._logger.handlers[:]  # Return copy to prevent external modification
+    
+    def reset_handlers(self):
+        """
+        Reset/recreate handlers.
+        Useful when log file has been deleted or needs to be recreated.
+        """
+        self._setup_handlers()
+    
+    def _notify_cpp_level_change(self, level: int):
+        """
+        Notify C++ bridge that log level has changed.
+        This updates the cached level in C++ for fast checks.
+        
+        Args:
+            level: New log level
+        """
+        try:
+            # Import here to avoid circular dependency
+            from . import ddbc_bindings
+            if hasattr(ddbc_bindings, 'update_log_level'):
+                ddbc_bindings.update_log_level(level)
+        except (ImportError, AttributeError):
+            # C++ bindings not available or not yet initialized
+            pass
+    
+    # Properties
+    
+    @property
+    def output(self) -> str:
+        """Get the current output mode"""
+        return self._output_mode
+    
+    @output.setter
+    def output(self, mode: str):
+        """
+        Set the output mode.
+        
+        Args:
+            mode: Output mode (FILE, STDOUT, or BOTH)
+        
+        Raises:
+            ValueError: If mode is not a valid OutputMode value
+        """
+        if mode not in (FILE, STDOUT, BOTH):
+            raise ValueError(
+                f"Invalid output mode: {mode}. "
+                f"Must be one of: {FILE}, {STDOUT}, {BOTH}"
+            )
+        self._output_mode = mode
+        
+        # Only reconfigure if handlers were already initialized
+        if self._handlers_initialized:
+            self._reconfigure_handlers()
+    
+    @property
+    def log_file(self) -> Optional[str]:
+        """Get the current log file path (None if file output is disabled)"""
+        return self._log_file
+    
+    @property
+    def level(self) -> int:
+        """Get the current logging level"""
+        return self._logger.level
+
+
+# ============================================================================
+# Module-level exports (Primary API)
+# ============================================================================
+
+# Singleton logger instance
+logger = MSSQLLogger()
+
+# Expose the underlying Python logger for use in application code
+# This allows applications to access the same logger used by the driver
+# Usage: from mssql_python.logging import driver_logger
+driver_logger = logger._logger
+
+# ============================================================================
+# Primary API - setup_logging()
+# ============================================================================
+
+def setup_logging(output: str = 'file', log_file_path: Optional[str] = None):
+    """
+    Enable DEBUG logging for troubleshooting.
+    
+    ⚠️ PERFORMANCE WARNING: Logging adds ~2-5% overhead.
+    Only enable when investigating issues. Do NOT enable in production without reason.
+    
+    Philosophy: All or nothing - if you need logging, you need to see EVERYTHING.
+    Logging is a troubleshooting tool, not a production monitoring solution.
+    
+    Args:
+        output: Where to send logs (default: 'file')
+                Options: 'file', 'stdout', 'both'
+        log_file_path: Optional custom path for log file
+                      Must have extension: .txt, .log, or .csv
+                      If not specified, auto-generates in ./mssql_python_logs/
+    
+    Examples:
+        import mssql_python
+        
+        # File only (default, in mssql_python_logs folder)
+        mssql_python.setup_logging()
+        
+        # Stdout only (for CI/CD)
+        mssql_python.setup_logging(output='stdout')
+        
+        # Both file and stdout (for development)
+        mssql_python.setup_logging(output='both')
+        
+        # Custom log file path (must use .txt, .log, or .csv extension)
+        mssql_python.setup_logging(log_file_path="/var/log/myapp.log")
+        mssql_python.setup_logging(log_file_path="/tmp/debug.txt")
+        mssql_python.setup_logging(log_file_path="/tmp/data.csv")
+        
+        # Custom path with both outputs
+        mssql_python.setup_logging(output='both', log_file_path="/tmp/debug.log")
+    
+    Future Enhancement:
+        For performance analysis, use the universal profiler (coming soon)
+        instead of logging. Logging is not designed for performance measurement.
+    """
+    logger._setLevel(logging.DEBUG, output, log_file_path)
+    return logger