fastmssql 0.2.6__cp38-cp38-macosx_11_0_arm64.whl → 0.2.7__cp38-cp38-macosx_11_0_arm64.whl

fastmssql/__init__.py

@@ -1,5 +1,661 @@
-from .fastmssql import *
+"""
+FastMSSQL - High-Performance Microsoft SQL Server Driver for Python
+===================================================================
 
-__doc__ = fastmssql.__doc__
-if hasattr(fastmssql, "__all__"):
-    __all__ = fastmssql.__all__
+This library provides direct access to high-performance Rust implementations
+with minimal Python overhead for maximum performance. Built on top of the
+tiberius crate, it offers both synchronous and asynchronous database operations
+with advanced features like connection pooling, SSL/TLS configuration, and
+efficient parameter handling.
+
+Key Features:
+    - High-performance Rust backend with Python bindings
+    - Async/await support for non-blocking operations
+    - Connection pooling with configurable parameters
+    - SSL/TLS encryption with certificate validation
+    - Parameterized queries with automatic type conversion
+    - Memory-efficient result iteration
+    - Comprehensive error handling and logging
+
+Basic Usage (Async):
+    >>> import asyncio
+    >>> from fastmssql import Connection
+    >>> 
+    >>> async def main():
+    ...     async with Connection("Server=localhost;Database=test;Trusted_Connection=yes") as conn:
+    ...         # Simple query
+    ...         result = await conn.execute("SELECT * FROM users")
+    ...         async for row in result:
+    ...             print(f"User: {row['name']}, Age: {row['age']}")
+    ...         
+    ...         # Parameterized query
+    ...         result = await conn.execute(
+    ...             "SELECT * FROM users WHERE age > @P1 AND city = @P2", 
+    ...             [18, "New York"]
+    ...         )
+    ...         rows = await result.fetchall()
+    ...         print(f"Found {len(rows)} users")
+    >>> 
+    >>> asyncio.run(main())
+
+Basic Usage (Sync):
+    >>> from fastmssql import Connection
+    >>> 
+    >>> with Connection("Server=localhost;Database=test;Trusted_Connection=yes") as conn:
+    ...     result = conn.execute_with_python_params(
+    ...         "SELECT COUNT(*) as count FROM users WHERE active = ?", 
+    ...         [True]
+    ...     )
+    ...     print(f"Active users: {result[0]['count']}")
+
+Advanced Configuration:
+    >>> from fastmssql import Connection, PoolConfig, SslConfig, EncryptionLevel
+    >>> 
+    >>> # Configure connection pool
+    >>> pool_config = PoolConfig(
+    ...     max_connections=20,
+    ...     min_connections=2,
+    ...     acquire_timeout_seconds=30,
+    ...     idle_timeout_seconds=600
+    ... )
+    >>> 
+    >>> # Configure SSL/TLS
+    >>> ssl_config = SslConfig(
+    ...     encryption_level=EncryptionLevel.Required,
+    ...     trust_server_certificate=False,
+    ...     certificate_path="/path/to/cert.pem"
+    ... )
+    >>> 
+    >>> conn = Connection(
+    ...     server="myserver.database.windows.net",
+    ...     database="mydatabase",
+    ...     username="myuser",
+    ...     password="mypassword",
+    ...     pool_config=pool_config,
+    ...     ssl_config=ssl_config
+    ... )
+
+Performance Considerations:
+    - Use parameterized queries to prevent SQL injection and improve performance
+    - Leverage connection pooling for applications with multiple concurrent operations
+    - Use async methods for I/O-bound applications to improve throughput
+    - Consider batch operations for bulk data manipulation
+    - Monitor connection pool statistics to optimize pool configuration
+
+Thread Safety:
+    This library is thread-safe and can be used in multi-threaded applications.
+    Each Connection instance maintains its own connection pool and can be safely
+    shared across threads when using async methods.
+"""
+
+# Import from the maturin-generated module
+from .fastmssql import Connection as _RustConnection
+from .fastmssql import PoolConfig
+from .fastmssql import SslConfig  
+from .fastmssql import FastExecutionResult
+from .fastmssql import version, EncryptionLevel, Parameter, Parameters
+
+# Wrapper class to handle async execution result conversion
+class Connection:
+    """
+    High-performance connection to Microsoft SQL Server.
+    
+    This class provides a Python wrapper around the Rust-based connection implementation,
+    offering both synchronous and asynchronous database operations with advanced features
+    like connection pooling, SSL/TLS configuration, and efficient parameter handling.
+    
+    The Connection class supports multiple initialization patterns:
+    1. Connection string-based initialization
+    2. Individual parameter initialization 
+    3. Advanced configuration with pool and SSL settings
+    
+    Connection Patterns:
+        # Using connection string
+        conn = Connection("Server=localhost;Database=test;Trusted_Connection=yes")
+        
+        # Using individual parameters
+        conn = Connection(
+            server="localhost", 
+            database="test", 
+            trusted_connection=True
+        )
+        
+        # Using username/password authentication
+        conn = Connection(
+            server="myserver.database.windows.net",
+            database="mydatabase", 
+            username="myuser",
+            password="mypassword"
+        )
+    
+    Thread Safety:
+        This class is thread-safe and maintains an internal connection pool that can
+        be safely accessed from multiple threads when using async methods.
+    
+    Performance Notes:
+        - Async methods are recommended for I/O-bound applications
+        - Connection pooling is automatically managed for optimal resource usage
+        - Parameterized queries provide better performance and security
+        - Results are streamed efficiently to minimize memory usage
+    
+    Attributes:
+        _conn: The underlying Rust connection implementation
+    """
+    
+    def __init__(
+        self, 
+        connection_string=None, 
+        pool_config=None, 
+        ssl_config=None, 
+        server=None, 
+        database=None, 
+        username=None, 
+        password=None, 
+        trusted_connection=None
+    ):
+        """
+        Initialize a new SQL Server connection.
+        
+        Args:
+            connection_string (str, optional): Complete ADO.NET-style connection string.
+                Takes precedence over individual parameters if provided.
+                Example: "Server=localhost;Database=test;Trusted_Connection=yes"
+                
+            pool_config (PoolConfig, optional): Configuration for the connection pool.
+                Allows customization of pool size, timeouts, and behavior.
+                
+            ssl_config (SslConfig, optional): SSL/TLS configuration for secure connections.
+                Required for encrypted connections to Azure SQL Database and other
+                secure SQL Server instances.
+                
+            server (str, optional): SQL Server hostname or IP address.
+                Can include instance name (e.g., "localhost\\SQLEXPRESS") or port
+                (e.g., "localhost:1433").
+                
+            database (str, optional): Name of the database to connect to.
+                If not specified, connects to the default database for the user.
+                
+            username (str, optional): Username for SQL Server authentication.
+                Required when not using Windows Authentication.
+                
+            password (str, optional): Password for SQL Server authentication.
+                Required when username is provided.
+                
+            trusted_connection (bool, optional): Whether to use Windows Authentication.
+                When True, uses the current Windows user's credentials.
+                Mutually exclusive with username/password.
+        
+        Raises:
+            ValueError: If connection parameters are invalid or conflicting.
+            ConnectionError: If unable to establish initial connection pool.
+            
+        Examples:
+            # Connection string approach
+            >>> conn = Connection("Server=localhost;Database=AdventureWorks;Trusted_Connection=yes")
+            
+            # Individual parameters
+            >>> conn = Connection(
+            ...     server="localhost",
+            ...     database="AdventureWorks", 
+            ...     trusted_connection=True
+            ... )
+            
+            # SQL Server authentication
+            >>> conn = Connection(
+            ...     server="myserver.database.windows.net",
+            ...     database="mydatabase",
+            ...     username="myuser@mydomain.com",
+            ...     password="SecurePassword123!"
+            ... )
+            
+            # With advanced configuration
+            >>> from fastmssql import PoolConfig, SslConfig, EncryptionLevel
+            >>> pool_config = PoolConfig(max_connections=10, min_connections=2)
+            >>> ssl_config = SslConfig(encryption_level=EncryptionLevel.Required)
+            >>> conn = Connection(
+            ...     server="secure-server.example.com",
+            ...     database="production_db",
+            ...     username="app_user",
+            ...     password="app_password",
+            ...     pool_config=pool_config,
+            ...     ssl_config=ssl_config
+            ... )
+        """
+        self._conn = _RustConnection(
+            connection_string=connection_string,
+            pool_config=pool_config,
+            ssl_config=ssl_config,
+            server=server,
+            database=database,
+            username=username,
+            password=password,
+            trusted_connection=trusted_connection
+        )
+    
+    async def execute(self, query, parameters=None):
+        """
+        Execute a SQL query asynchronously and return a FastExecutionResult.
+        
+        This method executes SQL queries with optional parameterization for security
+        and performance. It supports all types of SQL statements including SELECT,
+        INSERT, UPDATE, DELETE, and stored procedure calls.
+        
+        Parameter Binding:
+            Parameters are bound using positional placeholders (@P1, @P2, etc.) in the
+            query string. The parameter values are provided as a list in the same order.
+            
+        Supported Parameter Types:
+            - None (NULL)
+            - bool
+            - int (32-bit and 64-bit)
+            - float (32-bit and 64-bit)
+            - str (varchar, nvarchar, text)
+            - bytes (varbinary, image)
+            - datetime.datetime (datetime, datetime2)
+            - datetime.date (date)
+            - datetime.time (time)
+            - decimal.Decimal (decimal, money)
+            - uuid.UUID (uniqueidentifier)
+        
+        Args:
+            query (str): SQL query to execute. Use @P1, @P2, etc. for parameters.
+                Example: "SELECT * FROM users WHERE age > @P1 AND city = @P2"
+                
+            parameters (list, optional): List of parameter values in order.
+                Values are automatically converted to appropriate SQL types.
+                Example: [18, "New York"]
+        
+        Returns:
+            FastExecutionResult: An async iterable result object that provides:
+                - Async iteration over result rows
+                - fetchone(), fetchmany(), fetchall() methods
+                - Row count and column metadata
+                - Efficient memory usage for large result sets
+        
+        Raises:
+            SqlError: If the SQL query contains syntax errors or constraint violations.
+            ConnectionError: If the database connection is lost during execution.
+            TimeoutError: If the query execution exceeds configured timeouts.
+            ParameterError: If parameter types cannot be converted or are invalid.
+            
+        Examples:
+            # Simple SELECT query
+            >>> result = await conn.execute("SELECT * FROM users")
+            >>> async for row in result:
+            ...     print(f"User ID: {row['id']}, Name: {row['name']}")
+            
+            # Parameterized query
+            >>> result = await conn.execute(
+            ...     "SELECT * FROM orders WHERE created_date > @P1 AND amount > @P2",
+            ...     [datetime(2023, 1, 1), 100.0]
+            ... )
+            >>> rows = await result.fetchall()
+            >>> print(f"Found {len(rows)} orders")
+            
+            # INSERT with parameters
+            >>> result = await conn.execute(
+            ...     "INSERT INTO users (name, email, age) VALUES (@P1, @P2, @P3)",
+            ...     ["John Doe", "john@example.com", 30]
+            ... )
+            >>> print(f"Inserted {result.rowcount} row(s)")
+            
+            # Stored procedure call
+            >>> result = await conn.execute(
+            ...     "EXEC GetUsersByDepartment @P1, @P2",
+            ...     ["Engineering", True]  # department, active_only
+            ... )
+            >>> users = await result.fetchall()
+            
+            # Complex query with multiple data types
+            >>> from decimal import Decimal
+            >>> from datetime import datetime
+            >>> import uuid
+            >>> 
+            >>> result = await conn.execute(
+            ...     \"\"\"UPDATE products 
+            ...        SET price = @P1, updated_date = @P2, active = @P3 
+            ...        WHERE product_id = @P4\"\"\",
+            ...     [Decimal('29.99'), datetime.now(), True, uuid.uuid4()]
+            ... )
+        
+        Performance Tips:
+            - Use parameterized queries instead of string formatting for better performance
+            - For large result sets, iterate asynchronously rather than calling fetchall()
+            - Reuse Connection instances to benefit from connection pooling
+            - Consider batch operations for bulk data manipulation
+        
+        Security Notes:
+            - Always use parameterized queries to prevent SQL injection attacks
+            - Parameter values are automatically escaped and type-checked
+            - Never concatenate user input directly into SQL query strings
+        """
+        # The Rust implementation now returns results directly
+        return await self._conn.execute(query, parameters)
+    
+    def execute_with_python_params(self, query, params):
+        """
+        Execute a SQL query synchronously with Python-style parameter substitution.
+        
+        This method provides a synchronous interface for executing SQL queries with
+        parameter substitution using Python's DB-API 2.0 style placeholders (?).
+        It's designed for compatibility with existing Python database code and
+        simple synchronous operations.
+        
+        Parameter Binding:
+            Uses question mark (?) placeholders in the query string, with parameters
+            provided as a list in the same order as the placeholders appear.
+            
+        Note:
+            This is a synchronous method that blocks until the query completes.
+            For better performance in async applications, prefer the async execute() method.
+        
+        Args:
+            query (str): SQL query with ? placeholders for parameters.
+                Example: "SELECT * FROM users WHERE age > ? AND city = ?"
+                
+            params (list): List of parameter values in order of appearance.
+                Values are automatically converted to appropriate SQL types.
+                Example: [18, "New York"]
+        
+        Returns:
+            list: A list of dictionaries representing the result rows.
+                Each dictionary maps column names to values.
+                For non-SELECT queries, returns an empty list.
+        
+        Raises:
+            SqlError: If the SQL query contains syntax errors or constraint violations.
+            ConnectionError: If the database connection is not available.
+            ParameterError: If parameter types cannot be converted or are invalid.
+            
+        Examples:
+            # Simple SELECT query
+            >>> rows = conn.execute_with_python_params(
+            ...     "SELECT id, name, email FROM users WHERE active = ?", 
+            ...     [True]
+            ... )
+            >>> for row in rows:
+            ...     print(f"User: {row['name']} ({row['email']})")
+            
+            # INSERT operation
+            >>> conn.execute_with_python_params(
+            ...     "INSERT INTO logs (message, level, timestamp) VALUES (?, ?, ?)",
+            ...     ["Application started", "INFO", datetime.now()]
+            ... )
+            
+            # UPDATE with multiple parameters
+            >>> conn.execute_with_python_params(
+            ...     "UPDATE users SET last_login = ?, login_count = login_count + 1 WHERE id = ?",
+            ...     [datetime.now(), 12345]
+            ... )
+            
+            # Complex query with various data types
+            >>> from decimal import Decimal
+            >>> rows = conn.execute_with_python_params(
+            ...     \"\"\"SELECT p.name, p.price, c.name as category
+            ...        FROM products p 
+            ...        JOIN categories c ON p.category_id = c.id
+            ...        WHERE p.price BETWEEN ? AND ? AND p.discontinued = ?\"\"\",
+            ...     [Decimal('10.00'), Decimal('100.00'), False]
+            ... )
+        
+        Migration from DB-API 2.0:
+            This method is designed to be compatible with Python's DB-API 2.0
+            specification, making it easier to migrate from libraries like pyodbc
+            or pymssql with minimal code changes.
+            
+            # Old pyodbc code:
+            # cursor.execute("SELECT * FROM users WHERE id = ?", [user_id])
+            # rows = cursor.fetchall()
+            
+            # New fastmssql code:
+            # rows = conn.execute_with_python_params("SELECT * FROM users WHERE id = ?", [user_id])
+        
+        Performance Considerations:
+            - This method is synchronous and will block the calling thread
+            - For high-throughput applications, use the async execute() method instead
+            - Connection pooling is still utilized for efficient resource management
+            - Results are loaded entirely into memory, so be cautious with large result sets
+        """
+        return self._conn.execute_with_python_params(query, params)
+    
+    async def is_connected(self):
+        """
+        Check if the connection is active and available for queries.
+        
+        This method performs a lightweight check to determine if the underlying
+        connection pool has active connections and can accept new queries.
+        It's useful for health checks and connection validation in long-running
+        applications.
+        
+        The check verifies:
+            - Connection pool is initialized and operational
+            - At least one connection in the pool is active
+            - Network connectivity to the SQL Server instance
+            - Authentication credentials are still valid
+        
+        Returns:
+            bool: True if the connection is active and ready for queries,
+                  False if the connection is closed, failed, or unavailable.
+        
+        Raises:
+            ConnectionError: If there's an unexpected error checking connection status.
+            
+        Examples:
+            # Basic connection check
+            >>> if await conn.is_connected():
+            ...     result = await conn.execute("SELECT COUNT(*) FROM users")
+            ... else:
+            ...     await conn.connect()  # Reconnect if needed
+            
+            # Health check in a web application
+            >>> async def health_check():
+            ...     try:
+            ...         if await conn.is_connected():
+            ...             return {"database": "healthy", "status": "connected"}
+            ...         else:
+            ...             return {"database": "unhealthy", "status": "disconnected"}
+            ...     except Exception as e:
+            ...         return {"database": "error", "status": str(e)}
+            
+            # Periodic connection monitoring
+            >>> import asyncio
+            >>> 
+            >>> async def monitor_connection():
+            ...     while True:
+            ...         if await conn.is_connected():
+            ...             print(f"{datetime.now()}: Database connection is healthy")
+            ...         else:
+            ...             print(f"{datetime.now()}: Database connection is down!")
+            ...             # Attempt to reconnect
+            ...             try:
+            ...                 await conn.connect()
+            ...                 print("Reconnection successful")
+            ...             except Exception as e:
+            ...                 print(f"Reconnection failed: {e}")
+            ...         
+            ...         await asyncio.sleep(60)  # Check every minute
+        
+        Performance Notes:
+            - This is a lightweight operation that doesn't execute actual SQL
+            - The check uses connection pool metadata and cached connection state
+            - Suitable for frequent health checks without performance impact
+            - Does not count against connection pool limits
+        
+        Use Cases:
+            - Application startup validation
+            - Periodic health monitoring
+            - Circuit breaker pattern implementation
+            - Load balancer health checks
+            - Graceful degradation in microservices
+        """
+        return await self._conn.is_connected()
+    
+    async def pool_stats(self):
+        """
+        Get comprehensive connection pool statistics and health metrics.
+        
+        This method provides detailed information about the current state of the
+        connection pool, including active connections, idle connections, and
+        configuration parameters. It's essential for monitoring, debugging, and
+        optimizing connection pool performance in production environments.
+        
+        The statistics help identify:
+            - Connection pool utilization patterns
+            - Potential connection leaks
+            - Optimal pool sizing configuration
+            - Performance bottlenecks
+            - Resource contention issues
+        
+        Returns:
+            dict: A dictionary containing pool statistics with the following keys:
+                
+                When connected:
+                    - 'connections' (int): Total number of connections in the pool
+                    - 'idle_connections' (int): Number of idle connections available
+                    - 'active_connections' (int): Number of connections currently in use
+                    - 'max_size' (int): Maximum allowed connections in the pool
+                    - 'min_idle' (int): Minimum idle connections maintained
+                    
+                When disconnected:
+                    - 'connected' (bool): False, indicating no active pool
+        
+        Raises:
+            ConnectionError: If unable to retrieve pool statistics due to connection issues.
+            
+        Examples:
+            # Basic pool monitoring
+            >>> stats = await conn.pool_stats()
+            >>> if stats.get('connected', True):  # Handle disconnected case
+            ...     print(f"Active connections: {stats['active_connections']}")
+            ...     print(f"Idle connections: {stats['idle_connections']}")
+            ...     print(f"Pool utilization: {stats['active_connections']/stats['max_size']*100:.1f}%")
+            
+            # Comprehensive pool monitoring
+            >>> async def monitor_pool():
+            ...     stats = await conn.pool_stats()
+            ...     
+            ...     if not stats.get('connected', True):
+            ...         print("❌ Connection pool is not active")
+            ...         return
+            ...     
+            ...     total = stats['connections']
+            ...     active = stats['active_connections']
+            ...     idle = stats['idle_connections']
+            ...     max_size = stats['max_size']
+            ...     min_idle = stats['min_idle']
+            ...     
+            ...     utilization = (active / max_size) * 100
+            ...     
+            ...     print(f"📊 Connection Pool Statistics:")
+            ...     print(f"   Total connections: {total}")
+            ...     print(f"   Active connections: {active}")
+            ...     print(f"   Idle connections: {idle}")
+            ...     print(f"   Max pool size: {max_size}")
+            ...     print(f"   Min idle: {min_idle}")
+            ...     print(f"   Utilization: {utilization:.1f}%")
+            ...     
+            ...     # Health assessment
+            ...     if utilization > 90:
+            ...         print("⚠️  High pool utilization - consider increasing max_size")
+            ...     elif idle < min_idle:
+            ...         print("⚠️  Low idle connections - pool may be under pressure")
+            ...     elif utilization < 10 and total > min_idle * 2:
+            ...         print("ℹ️  Low utilization - consider reducing max_size")
+            ...     else:
+            ...         print("✅ Pool appears healthy")
+            
+            # Pool statistics for alerting
+            >>> async def check_pool_health():
+            ...     stats = await conn.pool_stats()
+            ...     
+            ...     if not stats.get('connected', True):
+            ...         return {"status": "critical", "message": "Pool disconnected"}
+            ...     
+            ...     utilization = stats['active_connections'] / stats['max_size']
+            ...     idle_ratio = stats['idle_connections'] / stats['max_size']
+            ...     
+            ...     if utilization > 0.9:
+            ...         return {
+            ...             "status": "warning", 
+            ...             "message": f"High utilization: {utilization:.1%}",
+            ...             "stats": stats
+            ...         }
+            ...     elif idle_ratio < 0.1:
+            ...         return {
+            ...             "status": "warning",
+            ...             "message": f"Low idle connections: {stats['idle_connections']}",
+            ...             "stats": stats
+            ...         }
+            ...     else:
+            ...         return {"status": "healthy", "stats": stats}
+            
+            # Logging pool metrics
+            >>> import logging
+            >>> 
+            >>> async def log_pool_metrics():
+            ...     stats = await conn.pool_stats()
+            ...     if stats.get('connected', True):
+            ...         logging.info(
+            ...             "Pool metrics: active=%d, idle=%d, total=%d, utilization=%.1f%%",
+            ...             stats['active_connections'],
+            ...             stats['idle_connections'], 
+            ...             stats['connections'],
+            ...             (stats['active_connections'] / stats['max_size']) * 100
+            ...         )
+        
+        Monitoring Best Practices:
+            - Monitor pool utilization during peak load periods
+            - Set up alerts for utilization > 80% or idle connections < min_idle
+            - Track connection acquisition times and pool exhaustion events
+            - Use metrics for capacity planning and performance optimization
+            - Log pool statistics periodically for historical analysis
+        
+        Performance Impact:
+            - This operation has minimal performance overhead
+            - Safe to call frequently for monitoring purposes
+            - Does not affect active connections or pool operation
+            - Recommended for inclusion in health check endpoints
+        """
+        result_tuple = await self._conn.pool_stats()
+        
+        # Convert tuple to dictionary
+        connected, connections, idle_connections, max_size, min_idle = result_tuple
+        
+        if connected:
+            return {
+                'connections': connections,
+                'idle_connections': idle_connections,
+                'max_size': max_size,
+                'min_idle': min_idle,
+                'active_connections': connections - idle_connections,
+            }
+        else:
+            return {'connected': False}
+    
+    async def connect(self):
+        """Explicitly connect to the database."""
+        return await self._conn.connect()
+    
+    async def disconnect(self):
+        """Explicitly disconnect from the database."""
+        return await self._conn.disconnect()
+    
+    async def __aenter__(self):
+        await self._conn.__aenter__()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self._conn.__aexit__(exc_type, exc_val, exc_tb)
+        return None
+    
+    def __enter__(self):
+        return self._conn.__enter__()
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        return self._conn.__exit__(exc_type, exc_val, exc_tb)
+
+# Preserve module documentation
+if hasattr(_RustConnection, "__doc__"):
+    __doc__ = _RustConnection.__doc__
+
+__all__ = ["Connection", "PoolConfig", "SslConfig", "FastExecutionResult", "version", "EncryptionLevel", "Parameter", "Parameters"]

{fastmssql-0.2.6.dist-info → fastmssql-0.2.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmssql
-Version: 0.2.6
+Version: 0.2.7
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: Other/Proprietary License
@@ -33,12 +33,14 @@ A Python library for Microsoft SQL Server built with Rust using the [Tiberius](h
 
 [![Language](https://img.shields.io/badge/Language-Rust_Backend-red)](https://github.com/Rivendael/pymssql-rs)
 [![Async](https://img.shields.io/badge/Async-Native_Tokio-blue)](https://github.com/Rivendael/pymssql-rs)
+[![Performance](https://img.shields.io/badge/Performance-17%2C800%2B_RPS-brightgreen)](https://github.com/Rivendael/pymssql-rs)
 
 ## Features
 
+- **High Performance**: Exceptional throughput with 17,800+ RPS capability
 - **Rust-Powered Backend**: Built with Rust for memory safety and reliability
 - **No ODBC Required**: Direct native SQL Server connection without ODBC drivers
-- **Connection Pooling**: bb8-based connection pool for efficient resource management
+- **Connection Pooling**: Intelligent bb8-based connection pooling (default: 75 max, 25 min idle)
 - **Async-Only Design**: Built on Tokio with clean async/await API
 - **Context Managers**: Automatic resource management with `async with`
 - **Type Safety**: Strong typing with automatic Python type conversion
@@ -46,15 +48,39 @@ A Python library for Microsoft SQL Server built with Rust using the [Tiberius](h
 - **Cross-Platform**: Works on Windows, macOS, and Linux
 - **Simple API**: Clean, intuitive async-only interface
 
-## Features
+## Performance Highlights
 
-Fastmssql provides reliable database connectivity with modern Python patterns:
+Fastmssql delivers exceptional database performance through Rust-powered architecture:
 
+- **Outstanding Throughput**: Up to **17,800+ RPS** with multiple connection pattern
+- **High Performance**: **5,000+ RPS** with single connection (default usage)
+- **Low Latency**: ~2ms average query latency under high load
+- **Scalable Architecture**: Linear scaling with multiple connection objects
 - **Production Ready**: Stable API with comprehensive error handling
 - **Connection Pooling**: Efficient resource management with configurable pools
 - **Type Conversion**: Automatic conversion between SQL Server and Python types
 - **SSL/TLS Support**: Secure connections with flexible encryption options
 
+### Performance Benchmarks
+
+| Pattern | RPS | Configuration | Use Case |
+|---------|-----|---------------|----------|
+| Single Connection (Default) | **5,000+** | Default pool (75/25) | Standard applications |
+| Multiple Connections | **17,800+** | 50 workers, high_throughput() | High-concurrency scenarios |
+| Conservative Load | 3,500+ | Shared connection | Traditional pooling |
+
+**Benchmark Environment:**
+- Database: SQL Server (local instance)
+- Query: `SELECT 1` (minimal overhead)  
+- Test Duration: 15-30 seconds per test
+- Hardware: Modern development machine
+
+**Key Performance Insights:**
+1. **Multiple Connection Objects**: Creating separate `Connection()` objects eliminates serialization bottlenecks
+2. **Pool Configuration**: Use `PoolConfig.high_throughput()` for demanding workloads
+3. **Optimal Worker Count**: 30-50 concurrent workers provides best throughput
+4. **Tokio Optimization**: Aggressive threading configuration maximizes async performance
+
 ## Installation
 
 ### From PyPI (Recommended)
@@ -87,8 +113,6 @@ cd mssql-python-rust
 
 ## Quick Start
 
-> **💡 Performance Tip**: Always reuse `Connection` objects! Each `Connection` manages a connection pool, so creating multiple `Connection` instances defeats the purpose of pooling and hurts performance. Create one `Connection` per database and reuse it throughout your application.
-
 ### Basic Async Usage (Recommended)
 
 ```python
@@ -157,6 +181,40 @@ async def main():
 asyncio.run(main())
 ```
 
+### Performance Patterns
+
+For maximum performance in high-concurrency scenarios, create multiple Connection objects:
+
+```python
+import asyncio
+from fastmssql import Connection, PoolConfig
+
+async def high_performance_pattern():
+    """Optimal pattern for maximum throughput."""
+    connection_string = "Server=localhost;Database=master;User Id=myuser;Password=mypass"
+    config = PoolConfig.high_throughput()  # Optimized settings
+    
+    async def worker():
+        # Each worker gets its own Connection object for maximum throughput
+        async with Connection(connection_string, pool_config=config) as conn:
+            for _ in range(1000):
+                # Use proper SQL Server parameterization with @param syntax
+                result = await conn.execute("SELECT data FROM my_table WHERE id = @id", {"id": 123})
+                # Process results...
+    
+    # Launch multiple workers - each with their own connection
+    workers = [asyncio.create_task(worker()) for _ in range(50)]
+    await asyncio.gather(*workers)
+    
+    # This pattern can achieve 17,800+ RPS
+
+asyncio.run(high_performance_pattern())
+```
+
+**Key Performance Insight**: While a single Connection object provides excellent performance (5,000+ RPS), 
+creating multiple Connection objects eliminates serialization bottlenecks and can achieve 17,800+ RPS 
+for maximum throughput scenarios.
+
 ### Connection Pool Configuration
 
 Configure the connection pool for your specific needs:
@@ -178,95 +236,29 @@ async def main():
     async with Connection(connection_string, pool_config) as conn:
         result = await conn.execute("SELECT * FROM users")
         
-    # Predefined configurations for common scenarios
-    high_throughput_config = PoolConfig.high_throughput()  # 20 connections, optimized for load
-    low_resource_config = PoolConfig.low_resource()        # 3 connections, minimal resources  
-    dev_config = PoolConfig.development()                  # 5 connections, shorter timeouts
-
-asyncio.run(main())
-```
-
-### Connection Pool Configuration
-
-For high-throughput applications, you can configure the connection pool:
-
-```python
-import asyncio
-from fastmssql import Connection, PoolConfig
-
-async def main():
-    # High-throughput pool setup
-    config = PoolConfig.high_throughput()  # Optimized for concurrent access
+    # Predefined configurations for different scenarios
+    high_throughput_config = PoolConfig.high_throughput()     # 100 connections, optimized for high RPS
+    maximum_performance = PoolConfig.maximum_performance()     # 150 connections, optimized for peak load
+    low_resource_config = PoolConfig.low_resource()           # 3 connections, minimal resources  
+    dev_config = PoolConfig.development()                     # 5 connections, shorter timeouts
+
+    # Default configuration is optimized for high performance
+    # Default: max_size=75, min_idle=25 - ready for production workloads
     
-    async with Connection(connection_string, config) as conn:
-        # Pool configured for concurrent operations
-        
-        # Concurrent workers for high throughput
-        async def worker():
-            result = await conn.execute("SELECT @@VERSION")
+    # For maximum throughput, use multiple Connection objects:
+    async def high_perf_worker():
+        async with Connection(connection_string, maximum_performance) as conn:
+            result = await conn.execute("SELECT * FROM fast_table")
             return result.rows()
-        
-        # Run multiple concurrent workers
-        tasks = [worker() for _ in range(20)]
-        results = await asyncio.gather(*tasks)
-        
-        # Pool monitoring
-        stats = await conn.pool_stats()
-        print(f"Pool utilization: {stats['active_connections']}/{stats['max_size']}")
+    
+    # Each worker gets its own connection for optimal performance
+    tasks = [asyncio.create_task(high_perf_worker()) for _ in range(50)]
+    results = await asyncio.gather(*tasks)
 
 asyncio.run(main())
 ```
 
-**Performance Tips:**
-- **Reuse Connection objects**: Create one `Connection` per database and reuse it across your application
-- Use `PoolConfig.high_throughput()` for high-throughput applications
-- Leverage `asyncio.gather()` for concurrent operations  
-- Monitor pool stats to optimize connection count
-- Consider connection lifetime for long-running applications
 
-**⚠️ Performance Anti-Pattern:**
-```python
-# DON'T DO THIS - Creates new pool for each operation
-async def bad_example():
-    async with Connection(conn_str) as conn:  # New pool created
-        return await conn.execute("SELECT 1")
-    
-    async with Connection(conn_str) as conn:  # Another new pool created
-        return await conn.execute("SELECT 2")
-```
-
-**✅ Correct Pattern:**
-```python
-# DO THIS - Reuse the same connection pool
-async def good_example():
-    async with Connection(conn_str) as conn:  # Single pool created
-        result1 = await conn.execute("SELECT 1")
-        result2 = await conn.execute("SELECT 2")  # Reuses same pool
-        return result1, result2
-```
-
-### Connection Pool Benefits
-
-The bb8 connection pool provides significant performance improvements over traditional Python libraries:
-
-| Metric | Traditional Python | fastmssql | Improvement |
-|--------|-------------------|-----------|-------------|
-| **Connection Setup** | 50ms | 0.1ms | **500x faster** |
-| **Memory per Query** | 50-200 KB | 0.5 KB | **100-400x less** |
-| **10 Concurrent Queries** | 500ms | 150ms | **3.3x faster** |
-| **100 Concurrent Queries** | 5000ms | 400ms | **12.5x faster** |
-| **1000 Concurrent Queries** | Timeouts/Errors | 2.9s | **Stable** |
-| **Memory Leaks** | Common | None | **Zero leaks** |
-
-**Key Benefits:**
-- **Connection Reuse**: Eliminates connection establishment overhead (500x improvement)
-- **Memory Efficiency**: Uses 100-400x less memory per operation (0.5 KB vs 50-200 KB)
-- **Zero Memory Leaks**: Automatic cleanup with decreasing memory usage over time
-- **Concurrency**: Safe multi-threaded access with automatic pooling
-- **Resource Management**: Intelligent memory and connection lifecycle management
-- **Load Balancing**: Intelligent connection distribution across threads
-- **Fault Tolerance**: Built-in retry logic and connection health checks
-- **Timeouts**: Configurable timeouts prevent hanging connections
 
 ### Connection Strings
 
@@ -362,89 +354,6 @@ async def main():
 asyncio.run(main())
 ```
 
-### Performance Comparison: bb8 Connection Pool
-
-The bb8 connection pool dramatically improves performance, especially under load:
-
-```python
-import asyncio
-import time
-from fastmssql import Connection
-
-async def performance_comparison():
-    connection_string = "Server=localhost;Database=test;User Id=myuser;Password=mypass"
-    
-    # Sequential async operations (still efficient with pool reuse)
-    start = time.time()
-    async with Connection(connection_string) as conn:
-        for i in range(10):
-            result = await conn.execute("SELECT COUNT(*) FROM users")
-    sequential_time = time.time() - start
-
-    # Concurrent async operations (much faster with bb8 pool)
-    start = time.time()
-    async def concurrent_queries():
-        tasks = []
-        for i in range(10):
-            async def query():
-                async with Connection(connection_string) as conn:  # Pool reuse
-                    return await conn.execute("SELECT COUNT(*) FROM users")
-            tasks.append(query())
-        return await asyncio.gather(*tasks)
-    
-    await concurrent_queries()
-    concurrent_time = time.time() - start
-    
-    print(f"Sequential: {sequential_time:.3f}s")
-    print(f"Concurrent: {concurrent_time:.3f}s") 
-    print(f"Improvement: {sequential_time/concurrent_time:.1f}x faster")
-
-asyncio.run(performance_comparison())
-```
-
-**Real-world Performance Benefits:**
-- **Web Applications**: Handle 100+ concurrent requests without connection exhaustion
-- **Batch Processing**: Process large datasets with optimal resource usage
-- **Microservices**: Reliable database connections across service boundaries
-- **Data Analytics**: Concurrent query execution for faster insights
-
-## Examples
-
-Run the provided examples to see async patterns and features:
-
-```bash
-# Basic asynchronous usage
-python examples/basic_usage.py
-
-# Advanced asynchronous features  
-python examples/advanced_usage.py
-
-# Asynchronous usage patterns
-python examples/async_usage.py
-
-# Advanced pool configuration
-python examples/advanced_pool_config.py
-
-# Connection parameters demonstration
-python examples/connection_parameters_demo.py
-```
-
-### Key API Improvements
-
-Our async-only design provides a clean, intuitive interface:
-
-```python
-# ✅ Clean async API (New Design)
-async with Connection(connection_string) as conn:
-    result = await conn.execute(sql)           # Intuitive!
-    rows_affected = await conn.execute_non_query(sql)
-
-# ❌ Old confusing API (Removed)
-# async with Connection(connection_string) as conn:
-#     result = await conn.execute_async(sql)   # Confusing suffixes
-#     rows_affected = await conn.execute_non_query_async(sql)
-```
-
 ## Development
 
 ### Building from Source
@@ -627,19 +536,6 @@ async with mssql.connect_async(conn_str) as conn:
     print(f"Pool utilization: {stats['active_connections']}/{stats['connections']}")
 ```
 
-**Features:**
-- Async-only operations for optimal concurrency
-- Automatic connection pooling with bb8
-- Configurable pool settings via `PoolConfig`
-- Pool statistics and monitoring
-- Improved concurrent performance
-- Better resource management
-
-**Breaking Changes:**
-- None - the API is fully backward compatible
-- All existing code continues to work without modification
-- Performance improvements are automatic
-
 ## Advanced Usage Patterns
 
 ### Custom Pool Configuration for Different Scenarios
@@ -728,7 +624,7 @@ async def olap_operations():
         return quarterly_report
 ```
 
-## Troubleshooting
+## API Reference
 
 ### Common Issues
 

fastmssql-0.2.7.dist-info/RECORD

@@ -0,0 +1,6 @@
+fastmssql-0.2.7.dist-info/RECORD,,
+fastmssql-0.2.7.dist-info/WHEEL,sha256=uCxAYGR8mh7ybiMWkA6Fu-BNUURLCTLWDXY7SKDjVCA,102
+fastmssql-0.2.7.dist-info/METADATA,sha256=pF7dtgu6k6kSZfz-_kLln9dlcjYgWi5yKzbu-L02TU0,24664
+fastmssql-0.2.7.dist-info/licenses/LICENSE,sha256=NwufX3BNj7RvVtnrshWhkpFOLvWc_YVpGpr3UZGFz_E,4765
+fastmssql/__init__.py,sha256=1DZiNk-l6MFhxGVWikdxDQiaXh_6FyhQWtz6UxyxO9s,29041
+fastmssql/fastmssql.cpython-38-darwin.so,sha256=RJkHfHiNbD64UjGIRYoWLhCIOkdU9b_jUYl5nBsDXYQ,3838720

fastmssql-0.2.6.dist-info/RECORD

@@ -1,6 +0,0 @@
-fastmssql-0.2.6.dist-info/RECORD,,
-fastmssql-0.2.6.dist-info/WHEEL,sha256=uCxAYGR8mh7ybiMWkA6Fu-BNUURLCTLWDXY7SKDjVCA,102
-fastmssql-0.2.6.dist-info/METADATA,sha256=skDVnYNSe4ny1dYxsHrlehGnRLo8ij-pQFsBGNaJvwg,27674
-fastmssql-0.2.6.dist-info/licenses/LICENSE,sha256=NwufX3BNj7RvVtnrshWhkpFOLvWc_YVpGpr3UZGFz_E,4765
-fastmssql/__init__.py,sha256=2I8gj3Ump7-VdoqnLpp4iiZjFrFZeyeG7iwOFJEz544,119
-fastmssql/fastmssql.cpython-38-darwin.so,sha256=Gd34lEX_dJykh-tMeFhjEUU5l9x-JHXCAMHybmSCNwU,4163776