fastmssql 0.2.2__cp313-cp313-macosx_11_0_arm64.whl → 0.3.0__cp313-cp313-macosx_11_0_arm64.whl

{fastmssql-0.2.2.dist-info → fastmssql-0.3.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: fastmssql
-Version: 0.2.2
+Version: 0.3.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: Other/Proprietary License
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -21,7 +21,7 @@ Provides-Extra: dev
 License-File: LICENSE
 Summary: A high-performance Python library for Microsoft SQL Server using Rust and Tiberius
 Author-email: Riveranda <riverb514@gmail.com>
-License: PolyForm Noncommercial License 1.0.0
+License: GPL-3.0-or-later OR Commercial
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Homepage, https://github.com/Rivendael/pymssql-rs
@@ -29,59 +29,73 @@ Project-URL: Homepage, https://github.com/Rivendael/pymssql-rs
 
 # Fastmssql ⚡
 
-A **blazingly fast** Python library for Microsoft SQL Server that delivers **significant performance improvements** over standard libraries. Built with Rust using the [Tiberius](https://github.com/prisma/tiberius) driver, [PyO3](https://github.com/PyO3/pyo3), and [bb8](https://github.com/djc/bb8) connection pooling.
+A Python library for Microsoft SQL Server built with Rust using the [Tiberius](https://github.com/prisma/tiberius) driver, [PyO3](https://github.com/PyO3/pyo3), and [bb8](https://github.com/djc/bb8) connection pooling.
 
-> **🚀 Performance Highlight**: Achieves **3,493 requests/second** and **0.08 KB memory per query** in our benchmarks
-
-[![Performance](https://img.shields.io/badge/Performance-3493_RPS-brightgreen)](https://github.com/Rivendael/pymssql-rs)
-[![Memory](https://img.shields.io/badge/Memory-0.08_KB/query-blue)](https://github.com/Rivendael/pymssql-rs)
-[![Speed](https://img.shields.io/badge/Speed-High_Performance-orange)](https://github.com/Rivendael/pymssql-rs)
 [![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**: Built with Rust for memory safety and speed
+- **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**: Advanced bb8-based connection pool for optimal performance
-- **Async-Only Design**: Built on Tokio for excellent concurrency with clean async/await API
+- **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
-- **Thread Safety**: Full support for concurrent operations
+- **Thread Safety**: Support for concurrent operations
 - **Cross-Platform**: Works on Windows, macOS, and Linux
-- **Simple API**: Clean, intuitive async-only interface
+- **Simple API**: Clean, intuitive async-only interface with separate `query()` and `execute()` methods
+
+## Key API Methods
 
-## ⚡ Performance
+FastMSSQL provides two distinct methods for database operations:
 
-Fastmssql delivers **excellent performance** that outperforms standard Python SQL Server libraries in our testing:
+- **`query()`** - For SELECT statements that return rows
+- **`execute()`** - For INSERT/UPDATE/DELETE statements that return affected row count
+
+```python
+# Use query() for SELECT statements
+result = await conn.query("SELECT * FROM users WHERE age > @P1", [25])
+rows = result.rows()
 
-### 🚀 Benchmark Results
+# Use execute() for data modification
+affected = await conn.execute("INSERT INTO users (name) VALUES (@P1)", ["John"])
+```
 
-| Library | RPS (Requests/Second) | Performance vs fastmssql |
-|---------|----------------------|--------------------------|
-| **fastmssql** | **3,493** | **Baseline** |
-| Other Python libraries | ~300-600* | **5-11x slower** |
+## Performance Highlights
 
-*Benchmarks performed with 20 concurrent workers executing `SELECT @@VERSION` queries on our test environment. Performance of other libraries may vary based on configuration, environment, and specific use cases. We recommend conducting your own benchmarks for your specific requirements.*
+Fastmssql delivers exceptional database performance through Rust-powered architecture:
 
-### 🧠 Memory Efficiency
+- **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
 
-Fastmssql delivers **exceptional memory efficiency** with minimal overhead:
+### Performance Benchmarks
 
-| Metric | Value | Description |
-|--------|-------|-------------|
-| **Per Query Overhead** | **0.08 KB** | Memory used per database query |
-| **Concurrent Overhead** | **3.52 KB** | Memory per concurrent operation |
-| **Connection Pool** | **5.26 MB** | One-time pool initialization |
-| **Memory Leaks** | **None** | Actually reduces memory over time |
+| 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 |
 
-**Memory Efficiency Highlights:**
-- **12,800 queries per MB** of memory overhead
-- **Zero memory leaks** - memory usage decreases over time
-- **100-1000x more efficient** than libraries without connection pooling
-- **Stable memory usage** under high concurrent load
+**Benchmark Environment:**
+- Database: SQL Server (local instance)
+- Query: `SELECT 1` (minimal overhead)  
+- Test Duration: 15-30 seconds per test
+- Hardware: Modern development machine
 
-*Traditional Python SQL Server libraries typically use 50-200 KB per operation due to connection overhead and lack of efficient pooling.*
+**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
 
@@ -115,8 +129,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
@@ -129,7 +141,9 @@ async def main():
     
     # Automatic connection pool management
     async with Connection(connection_string) as conn:
-        rows = await conn.execute("SELECT @@VERSION as version")
+        # Use query() for SELECT statements that return rows
+        result = await conn.query("SELECT @@VERSION as version")
+        rows = result.rows()
         for row in rows:
             print(row['version'])
         
@@ -155,8 +169,10 @@ async def main():
     connection_string = "Server=localhost;Database=master;User Id=myuser;Password=mypass"
     
     async with Connection(connection_string=connection_string) as conn:
-        result = await conn.execute("SELECT @@VERSION as version")
-        for row in result.rows():
+        # Use query() for SELECT statements that return rows
+        result = await conn.query("SELECT @@VERSION as version")
+        rows = result.rows()
+        for row in rows:
             print(row['version'])
 
 asyncio.run(main())
@@ -178,13 +194,50 @@ async def main():
         username="myuser",
         password="mypassword"
     ) as conn:
-        result = await conn.execute("SELECT SUSER_NAME() as login")
-        for row in result.rows():
+        # Use query() for SELECT statements that return rows
+        result = await conn.query("SELECT SUSER_NAME() as login")
+        rows = result.rows()
+        for row in rows:
             print(f"Logged in as: {row['login']}")
 
 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 query() for SELECT statements that return rows
+                result = await conn.query("SELECT data FROM my_table WHERE id = @P1", [123])
+                rows = result.rows()
+                # 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:
@@ -204,97 +257,36 @@ async def main():
     )
 
     async with Connection(connection_string, pool_config) as conn:
-        result = await conn.execute("SELECT * FROM users")
+        # Use query() for SELECT statements that return rows
+        result = await conn.query("SELECT * FROM users")
+        rows = result.rows()
+        for row in rows:
+            print(f"User: {row['name']}")
         
-    # 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())
-```
-
-### 🔥 Maximum Performance Configuration
-
-For applications requiring **extreme performance**, use the high-throughput configuration:
-
-```python
-import asyncio
-from fastmssql import Connection, PoolConfig
-
-async def main():
-    # Maximum performance setup
-    extreme_config = PoolConfig.high_throughput()  # Optimized for 3000+ RPS
+    # 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, extreme_config) as conn:
-        # This setup achieves 3,493 RPS in benchmarks
-        
-        # Concurrent workers for maximum 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:
+            # Use query() for SELECT statements that return rows
+            result = await conn.query("SELECT * FROM fast_table")
             return result.rows()
-        
-        # Run 20 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 maximum RPS
-- 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.08 KB | **625-2500x 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 625-2500x less memory per operation (0.08 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
 
@@ -319,21 +311,37 @@ from fastmssql import Connection
 
 async def main():
     async with Connection(connection_string) as conn:
-        # Execute queries
-        users = await conn.execute("SELECT id, name, email FROM users WHERE active = 1")
+        # === SELECT QUERIES - Use query() method (returns rows) ===
+        result = await conn.query("SELECT id, name, email FROM users WHERE active = 1")
+        rows = result.rows()
         
         # Iterate through results
-        for user in users:
-            print(f"User {user['id']}: {user['name']} ({user['email']})")
+        for row in rows:
+            print(f"User {row['id']}: {row['name']} ({row['email']})")
+        
+        # === DATA MODIFICATION - Use execute() method (returns affected row count) ===
+        # INSERT operation
+        rows_affected = await conn.execute(
+            "INSERT INTO users (name, email, active) VALUES (@P1, @P2, @P3)",
+            ["John Doe", "john@example.com", 1]
+        )
+        print(f"Inserted {rows_affected} row(s)")
         
-        # Execute non-query operations
-        rows_affected = await conn.execute_non_query(
-            "UPDATE users SET last_login = GETDATE() WHERE id = 123"
+        # UPDATE operation
+        rows_affected = await conn.execute(
+            "UPDATE users SET last_login = GETDATE() WHERE id = @P1",
+            [123]
         )
-        print(f"Updated {rows_affected} rows")
+        print(f"Updated {rows_affected} row(s)")
         
-        # Work with different data types
-        data = await conn.execute("""
+        # DELETE operation
+        rows_affected = await conn.execute(
+            "DELETE FROM users WHERE active = 0 AND last_login < DATEADD(year, -1, GETDATE())"
+        )
+        print(f"Deleted {rows_affected} inactive users")
+        
+        # === WORKING WITH DIFFERENT DATA TYPES ===
+        result = await conn.query("""
             SELECT 
                 42 as int_value,
                 3.14159 as float_value,
@@ -343,9 +351,11 @@ async def main():
                 NULL as null_value
         """)
         
-        row = data[0]
-        for column_name, value in row.items():
-            print(f"{column_name}: {value} (type: {type(value).__name__})")
+        rows = result.rows()
+        if rows:
+            row = rows[0]
+            for column_name, value in row.items():
+                print(f"{column_name}: {value} (type: {type(value).__name__})")
 
 asyncio.run(main())
 ```
@@ -365,7 +375,9 @@ async def main():
     
     # Async context manager with automatic pool management
     async with Connection(connection_string) as conn:
-        rows = await conn.execute("SELECT name FROM sys.databases")
+        # Use query() for SELECT statements that return rows
+        result = await conn.query("SELECT name FROM sys.databases")
+        rows = result.rows()
         for row in rows:
             print(row['name'])
             
@@ -376,7 +388,9 @@ async def main():
     # High-performance concurrent operations
     async def fetch_user_data(user_id):
         async with Connection(connection_string) as conn:
-            return await conn.execute(f"SELECT * FROM users WHERE id = {user_id}")
+            # Use query() for SELECT statements that return rows
+            result = await conn.query(f"SELECT * FROM users WHERE id = {user_id}")
+            return result.rows()
     
     # Execute multiple queries concurrently using the connection pool
     user_ids = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
@@ -390,89 +404,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
@@ -526,6 +457,29 @@ python examples/advanced_usage.py
 
 ## API Reference
 
+### Query vs Execute Methods
+
+FastMSSQL provides two distinct methods for database operations:
+
+- **`query()`** - For SELECT statements that return rows
+  - Returns a `QueryResult` object with a `rows()` method
+  - Use for retrieving data from the database
+
+- **`execute()`** - For INSERT, UPDATE, DELETE statements  
+  - Returns the number of affected rows as an integer
+  - Use for modifying data in the database
+
+**SQL Server Parameter Syntax**: Use positional parameters `@P1`, `@P2`, `@P3`, etc.
+
+```python
+# SELECT queries - use query()
+result = await conn.query("SELECT * FROM users WHERE age > @P1 AND city = @P2", [25, "New York"])
+rows = result.rows()
+
+# INSERT/UPDATE/DELETE - use execute()  
+affected = await conn.execute("INSERT INTO users (name, email) VALUES (@P1, @P2)", ["John", "john@example.com"])
+```
+
 ### Core Classes
 
 #### `Connection`
@@ -538,21 +492,45 @@ Connection(connection_string: str, pool_config: Optional[PoolConfig] = None)
 
 **Context Manager Support:**
 ```python
-# Synchronous
-with Connection(conn_str) as conn:
-    result = conn.execute("SELECT * FROM table")
-
-# Asynchronous  
+# Asynchronous (recommended)
 async with Connection(conn_str) as conn:
-    result = await conn.execute_async("SELECT * FROM table")
+    # Use query() for SELECT statements
+    result = await conn.query("SELECT * FROM table")
+    rows = result.rows()
+    
+    # Use execute() for INSERT/UPDATE/DELETE statements  
+    affected = await conn.execute("INSERT INTO table (col) VALUES (@P1)", ["value"])
+```
 ```
 
 **Methods:**
-- `execute(sql: str) -> List[Row]` - Execute a query synchronously
+- `query(sql: str, params: Optional[List] = None) -> QueryResult` - Execute SELECT queries that return rows
+- `execute(sql: str, params: Optional[List] = None) -> int` - Execute INSERT/UPDATE/DELETE statements, returns affected row count
 - `pool_stats() -> dict` - Get connection pool statistics
 - `disconnect()` - Close the connection pool
 - `is_connected() -> bool` - Check if pool is active
 
+**Method Details:**
+
+`query()` - For SELECT statements that return data:
+```python
+# Returns a QueryResult object with rows() method
+result = await conn.query("SELECT * FROM users WHERE age > @P1", [21])
+rows = result.rows()
+for row in rows:
+    print(row['name'])
+```
+
+`execute()` - For INSERT/UPDATE/DELETE statements:
+```python
+# Returns the number of affected rows
+affected = await conn.execute("INSERT INTO users (name) VALUES (@P1)", ["John"])
+print(f"Inserted {affected} row(s)")
+
+affected = await conn.execute("UPDATE users SET age = @P1 WHERE name = @P2", [25, "John"])
+print(f"Updated {affected} row(s)")
+```
+
 **Pool Statistics:**
 ```python
 stats = conn.pool_stats()
@@ -603,15 +581,17 @@ Represents a database row with column access.
 
 #### Connection Management
 ```python
-# Create connection with default pool settings
-connect(connection_string: str) -> Connection
-
-# Create async connection with default pool settings
-connect_async(connection_string: str) -> Connection
+# Create connection with connection pooling
+Connection(connection_string: str, pool_config: Optional[PoolConfig] = None) -> Connection
 
-# One-liner query execution
-execute(connection_string: str, sql: str) -> List[dict]
-execute_async(connection_string: str, sql: str) -> List[dict]
+# Usage with async context manager (recommended)
+async with Connection(connection_string) as conn:
+    # Use query() for SELECT statements that return rows
+    result = await conn.query("SELECT * FROM users")
+    rows = result.rows()
+    
+    # Use execute() for INSERT/UPDATE/DELETE statements that return affected count
+    affected = await conn.execute("INSERT INTO users (name) VALUES (@P1)", ["John"])
 ```
 
 #### Utility Functions
@@ -634,7 +614,8 @@ The library uses the bb8 connection pool for efficient resource management:
 ```python
 try:
     async with mssql.connect_async(connection_string) as conn:
-        result = await conn.execute("SELECT * FROM invalid_table")
+        result = await conn.query("SELECT * FROM invalid_table")
+        rows = result.rows()
 except Exception as e:
     print(f"Database error: {e}")
     # Connection automatically returned to pool even on error
@@ -648,26 +629,14 @@ This library has been upgraded to use async-only operations with the bb8 connect
 ```python  
 # Async-only with automatic connection pooling
 async with mssql.connect_async(conn_str) as conn:
-    result = await conn.execute("SELECT * FROM table")
+    result = await conn.query("SELECT * FROM table")
+    rows = result.rows()
     
     # Pool statistics
     stats = conn.pool_stats()
     print(f"Pool utilization: {stats['active_connections']}/{stats['connections']}")
 ```
 
-**Features:**
-- Async-only operations for maximum performance
-- 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
@@ -733,7 +702,7 @@ async def oltp_operations():
     async with mssql.connect_async(conn_str, oltp_config) as conn:
         # Fast, concurrent transactions
         tasks = [
-            conn.execute_async("SELECT * FROM users WHERE id = $1", [user_id])
+            conn.query("SELECT * FROM users WHERE id = @P1", [user_id])
             for user_id in range(1, 101)
         ]
         results = await asyncio.gather(*tasks)
@@ -743,7 +712,7 @@ olap_config = PoolConfig.low_resource()
 async def olap_operations():
     async with mssql.connect_async(conn_str, olap_config) as conn:
         # Long-running analytical queries
-        quarterly_report = await conn.execute_async("""
+        result = await conn.query("""
             SELECT 
                 DATE_TRUNC('quarter', order_date) as quarter,
                 SUM(total_amount) as total_revenue,
@@ -753,10 +722,10 @@ async def olap_operations():
             GROUP BY DATE_TRUNC('quarter', order_date)
             ORDER BY quarter
         """)
-        return quarterly_report
+        return result.rows()
 ```
 
-## Troubleshooting
+## API Reference
 
 ### Common Issues
 
@@ -773,7 +742,22 @@ Contributions are welcome! Please open an issue or submit a pull request for any
 
 ## License
 
-This project is licensed under the PolyForm Noncommercial License 1.0.0. See the LICENSE file for details.
+FastMSSQL is available under your choice of two licenses:
+
+### Option 1: GNU General Public License v3.0 (GPL-3.0)
+
+**Free for open source projects.** If you distribute your application, you must make your entire application open source under GPL-3.0.
+
+### Option 2: Commercial License
+
+**Paid license for proprietary applications.** Allows you to keep your application closed source. Contact riverb514@gmail.com for commercial licensing.
+
+See the [LICENSE](LICENSE) file for full GPL-3.0 terms and commercial licensing details.
+
+### Examples and Benchmarks
+
+- **Examples Directory**: All files in the `examples/` directory are licensed under the MIT License. See `examples/LICENSE` for full terms.
+- **Benchmarks Directory**: All files in the `benchmarks/` directory are licensed under the MIT License. See `licenses/MIT_LICENSE.txt` for full terms.
 
 ## Third-Party Attributions