DOC: Update Roadmap.md and Readme.md (#335)

gargsaumya · web-flow · commit e18584112949 · 2025-11-18T17:40:11.000+05:30
### Work Item / Issue Reference   > AB#<WORK_ITEM_ID>  > GitHub Issue: #<ISSUE_NUMBER> ------------------------------------------------------------------- ### Summary  This pull request updates the documentation to reflect the transition of the `mssql-python` driver to General Availability (GA), clarifies platform and authentication support, and reorganizes feature and roadmap information for clarity and accuracy. The most important changes are grouped below. **Documentation Updates:** * The driver is now marked as Generally Available (GA) and ready for production use, replacing the previous "Public Preview" notice in `README.md`. * The support note for SUSE Linux ARM64 has been clarified to indicate that only x64 architecture is supported for SUSE deployments. **Authentication and Platform Support:** * Entra ID `ActiveDirectoryIntegrated` authentication is now documented as supported on Windows, macOS, and Linux, with a note about required Kerberos/SSPI configuration. **Feature and Example Reorganization:** * The DBAPI v2.0 compliance and Enhanced Pythonic Features sections have been moved and improved for clarity, and the example code now demonstrates a realistic query using Entra ID Interactive authentication. **Roadmap Updates:** * The `ROADMAP.md` file has been replaced with a concise feature matrix table, showing planned and in-progress features with estimated timelines, instead of a narrative roadmap.
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ The driver is compatible with all the Python versions >= 3.10
 [Documentation](https://github.com/microsoft/mssql-python/wiki) | [Release Notes](https://github.com/microsoft/mssql-python/releases) | [Roadmap](https://github.com/microsoft/mssql-python/blob/main/ROADMAP.md)
  
 > **Note:**
-> This project is currently in Public Preview, meaning it is still under active development. We are working on core functionalities and gathering more feedback before GA. Please use with caution and avoid production environments.
+> This project is now Generally Available (GA) and ready for production use. We’ve completed core functionality and incorporated feedback from the preview phase.
 > 
 ## Installation
  
@@ -47,20 +47,8 @@ pip install mssql-python
 Windows, MacOS and Linux (manylinux - Debian, Ubuntu, RHEL, SUSE (x64 only) & musllinux - Alpine)
 
 > **Note:**
-> SUSE Linux ARM64 is not supported by Microsoft ODBC Driver. Use x64 architecture for SUSE deployments.
- 
-### DBAPI v2.0 Compliance
- 
-The Microsoft **mssql-python** module is designed to be fully compliant with the DB API 2.0 specification. This ensures that the driver adheres to a standardized interface for database access in Python, providing consistency and reliability across different database systems. Key aspects of DBAPI v2.0 compliance include:
- 
-- **Connection Objects**: Establishing and managing connections to the database.
-- **Cursor Objects**: Executing SQL commands and retrieving results.
-- **Transaction Management**: Supporting commit and rollback operations to ensure data integrity.
-- **Error Handling**: Providing a consistent set of exceptions for handling database errors.
-- **Parameter Substitution**: Allowing the use of placeholders in SQL queries to prevent SQL injection attacks.
- 
-By adhering to the DB API 2.0 specification, the mssql-python module ensures compatibility with a wide range of Python applications and frameworks, making it a versatile choice for developers working with Microsoft SQL Server, Azure SQL Database, and Azure SQL Managed Instance.
- 
+> SUSE Linux ARM64 is not supported. Please use x64 architecture for SUSE deployments.
+
 ### Support for Microsoft Entra ID Authentication
  
 The Microsoft mssql-python driver enables Python applications to connect to Microsoft SQL Server, Azure SQL Database, or Azure SQL Managed Instance using Microsoft Entra ID identities. It supports a variety of authentication methods, including username and password, Microsoft Entra managed identity (system-assigned and user-assigned), Integrated Windows Authentication in a federated, domain-joined environment, interactive authentication via browser, device code flow for environments without browser access, and the default authentication method based on environment and configuration. This flexibility allows developers to choose the most suitable authentication approach for their deployment scenario.
@@ -73,39 +61,65 @@ EntraID authentication is now fully supported on MacOS and Linux but with certai
 | ActiveDirectoryInteractive | ✅ Yes | ✅ Yes | Interactive login via browser; requires user interaction |
 | ActiveDirectoryMSI (Managed Identity) | ✅ Yes | ✅ Yes | For Azure VMs/containers with managed identity |
 | ActiveDirectoryServicePrincipal | ✅ Yes | ✅ Yes | Use client ID and secret or certificate |
-| ActiveDirectoryIntegrated | ✅ Yes | ❌ No | Only works on Windows (requires Kerberos/SSPI) |
+| ActiveDirectoryIntegrated | ✅ Yes | ✅ Yes | Now supported on Windows, macOS, and Linux (requires Kerberos/SSPI or equivalent configuration) |
 | ActiveDirectoryDeviceCode | ✅ Yes | ✅ Yes | Device code flow for authentication; suitable for environments without browser access |
 | ActiveDirectoryDefault | ✅ Yes | ✅ Yes | Uses default authentication method based on environment and configuration |
 
 > For more information on Entra ID please refer this [document](https://github.com/microsoft/mssql-python/wiki/Microsoft-Entra-ID-support)
 
-### Enhanced Pythonic Features
- 
-The driver offers a suite of Pythonic enhancements that streamline database interactions, making it easier for developers to execute queries, manage connections, and handle data more efficiently.
- 
 ### Connection Pooling
  
 The Microsoft mssql_python driver provides built-in support for connection pooling, which helps improve performance and scalability by reusing active database connections instead of creating a new connection for every request. This feature is enabled by default. For more information, refer [Connection Pooling Wiki](https://github.com/microsoft/mssql-python/wiki/Connection#connection-pooling).
+
+### DBAPI v2.0 Compliance
+ 
+The Microsoft **mssql-python** module is designed to be fully compliant with the DB API 2.0 specification. This ensures that the driver adheres to a standardized interface for database access in Python, providing consistency and reliability across different database systems. Key aspects of DBAPI v2.0 compliance include:
+ 
+- **Connection Objects**: Establishing and managing connections to the database.
+- **Cursor Objects**: Executing SQL commands and retrieving results.
+- **Transaction Management**: Supporting commit and rollback operations to ensure data integrity.
+- **Error Handling**: Providing a consistent set of exceptions for handling database errors.
+- **Parameter Substitution**: Allowing the use of placeholders in SQL queries to prevent SQL injection attacks.
+ 
+By adhering to the DB API 2.0 specification, the mssql-python module ensures compatibility with a wide range of Python applications and frameworks, making it a versatile choice for developers working with Microsoft SQL Server, Azure SQL Database, and Azure SQL Managed Instance.
+ 
+### Enhanced Pythonic Features
+ 
+The driver offers a suite of Pythonic enhancements that streamline database interactions, making it easier for developers to execute queries, manage connections, and handle data more efficiently.
  
 ## Getting Started Examples
 Connect to SQL Server and execute a simple query:
  
 ```python
 import mssql_python
- 
+
 # Establish a connection
-# Specify connection string
-connection_string = "SERVER=<your_server_name>;DATABASE=<your_database_name>;UID=<your_user_name>;PWD=<your_password>;Encrypt=yes;"
+# Specify connection string (semicolon-delimited key=value format preserved)
+# Uses Azure Entra ID Interactive authentication — no password in the string.
+connection_string = "SERVER=tcp:mssql-python-driver-eastus01.database.windows.net,1433;DATABASE=AdventureWorksLT;Authentication=ActiveDirectoryInteractive;Encrypt=yes;"
 connection = mssql_python.connect(connection_string)
- 
-# Execute a query
+
+# Execute a realistic query against AdventureWorksLT:
+# Top 10 customers by number of orders, with their total spend
 cursor = connection.cursor()
-cursor.execute("SELECT * from customer")
+cursor.execute("""
+    SELECT TOP 10
+        c.CustomerID,
+        c.FirstName,
+        c.LastName,
+        COUNT(h.SalesOrderID) AS OrderCount,
+        SUM(h.TotalDue) AS TotalSpend
+    FROM SalesLT.Customer AS c
+    INNER JOIN SalesLT.SalesOrderHeader AS h
+        ON c.CustomerID = h.CustomerID
+    GROUP BY c.CustomerID, c.FirstName, c.LastName
+    ORDER BY OrderCount DESC, TotalSpend DESC
+""")
 rows = cursor.fetchall()
- 
+
 for row in rows:
     print(row)
- 
+
 # Close the connection
 connection.close()
  
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,51 +1,18 @@
 # Roadmap for Python Driver for SQL Server
 
-We are thrilled to introduce Python driver for SQL Server (Public Preview) – a modern, high performant, and developer-friendly SDK designed to enhance your SQL Server database connectivity experience. This roadmap outlines the key structural improvements, new features and upcoming enhancements that will set our driver apart from existing solutions.
-
-Why a New Driver?
-
-Unlike existing Python SQL Server drivers, we are making substantial improvements to performance, maintainability, and usability by re-architecting the core internals. Our focus is on seamless integration between Python and C++, efficient memory management, better state handling, and advanced DBAPI enhancements.
-
-Here’s what’s coming:
-
-**1. Structural changes for abstraction of C++ and Python codebase**
-
-We are undertaking significant structural changes to provide a clear abstraction between C++ code and Python. This will ensure better maintainability, improved performance, and a cleaner codebase. By leveraging existing pybind11 module, we aim to create a seamless integration between the two languages, allowing for efficient execution and easier debugging.
-
-This will improve:
-- Maintainability via simplified modular architecture
-- Performance via optimized C++ code
-- Debugging, traceability and seamless interaction between C++ and Python via with PyBind11 module integration
-
-**2. Future DBAPI Enhancements**
-
-In future releases, we plan to add several DBAPI enhancements, including:
-- `Callproc()` : Support for calling stored procedures.   
-- `setinputsize()` and `setoutputsize()`
-- `Output` and `InputOutput` Parameters: Handling of output and input-output parameters in stored procedures.
-- Optional DBAPIs: Additional optional DBAPI features to provide more flexibility and functionality for developers.
-
-**3. Cross-Platform Support: Additional Linux Distributions** 
-
-We are committed to providing cross-platform support for our Python driver. In the next few weeks, we will release support for additional Linux distributions viz Alpine, SUSE Linux & Oracle Linux.
-
-**4. Bulk Copy (BCP)**
-
-Bulk Copy API (BCP) support is coming soon to the Python Driver for SQL Server. It enables high-speed data ingestion and offers fine-grained control over batch operations, making it ideal for large-scale ETL workflows.
-
-**5. Asynchronous Query Execution**
-
-We are also working on adding support for asynchronous query execution. This feature will allow developers to execute queries without blocking the main thread, enabling more responsive and efficient applications. Asynchronous query execution will be particularly beneficial for applications that require high concurrency and low latency.
-- No blocking of the main thread
-- Faster parallel processing – ideal for high-concurrency applications
-- Better integration with async frameworks like asyncio
-
-We are dedicated to continuously improving the Python driver for SQL Server and welcome feedback from the community. Stay tuned for updates and new features as we work towards delivering a high-quality driver that meets your needs.
-Join the Conversation!
-
-We are building this for developers, with developers. Your feedback will shape the future of the driver.
-- Follow our [Github Repo](https://github.com/microsoft/mssql-python)
-- Join Discussions – Share your ideas and suggestions
-- Try our alpha release – Help us refine and optimize the experience
-
-Stay tuned for more updates, and lets build something amazing together. Watch this space for announcements and release timelines.
+The following roadmap summarizes the features planned for the Python Driver for SQL Server.
+
+| Feature                        | Description                                                       | Status       | Target Timeline          |
+| ------------------------------ | ----------------------------------------------------------------- | ------------ | ------------------------ |
+| Parameter Dictionaries         | Allow parameters to be supplied as Python dicts                   | Planned      | Q4 2025                  |
+| Return Rows as Dictionaries    | Fetch rows as dictionaries for more Pythonic access               | Planned      | Q4 2025                  |
+| Bulk Copy (BCP)                | High-throughput ingestion API for ETL workloads                   | Under Design | Q1 2026                  |
+| Asynchronous Query Execution   | Non-blocking queries with asyncio support                         | Planned      | Q1 2026                  |
+| Vector Datatype Support        | Native support for SQL Server vector datatype                     | Planned      | Q1 2026                  |
+| Table-Valued Parameters (TVPs) | Pass tabular data structures into stored procedures               | Planned      | Q1 2026                  |
+| C++ Abstraction                | Modular separation via pybind11 for performance & maintainability | In Progress  | ETA will be updated soon |
+| JSON Datatype Support          | Automatic mapping of JSON datatype to Python dicts/lists          | Planned      | ETA will be updated soon |
+| callproc()                     | Full DBAPI compliance & stored procedure enhancements             | Planned      | ETA will be updated soon |
+| setinputsize()                 | Full DBAPI compliance & stored procedure enhancements             | Planned      | ETA will be updated soon |
+| setoutputsize()                | Full DBAPI compliance & stored procedure enhancements             | Planned      | ETA will be updated soon |
+| Output/InputOutput Params      | Full DBAPI compliance & stored procedure enhancements             | Planned      | ETA will be updated soon |
