Merge branch 'bewithgaurav/publish_symbols' of https://github.com/microsoft/mssql-python into bewithgaurav/publish_symbols

Author: bewithgaurav

.github/PULL_REQUEST_TEMPLATE.MD

@@ -1,9 +1,20 @@
-### ADO Work Item Reference  
-<!-- Insert your ADO Work Item ID below (e.g. AB#37452) -->
+### Work Item / Issue Reference  
+<!-- 
+IMPORTANT: Please follow the PR template guidelines below.
+For mssql-python maintainers: Insert your ADO Work Item ID below (e.g. AB#37452)
+For external contributors: Insert Github Issue number below (e.g. #149)
+Only one reference is required - either GitHub issue OR ADO Work Item.
+-->
+
+<!-- mssql-python maintainers: ADO Work Item -->
 > AB#<WORK_ITEM_ID>
+
+<!-- External contributors: GitHub Issue -->
+> GitHub Issue: #<ISSUE_NUMBER>
+
 -------------------------------------------------------------------
 ### Summary   
-<!-- Insert your Copilot Generated Summary below -->  
+<!-- Insert your summary of changes below. Minimum 10 characters required. -->  
 
 
 <!-- 
@@ -29,4 +40,16 @@ REFACTOR: (short-description)
 
 > For release related changes, without any feature changes
 RELEASE: #<RELEASE_VERSION> (short-description) 
+
+### Contribution Guidelines
+
+External contributors:
+- Create a GitHub issue first: https://github.com/microsoft/mssql-python/issues/new
+- Link the GitHub issue in the "GitHub Issue" section above
+- Follow the PR title format and provide a meaningful summary
+
+mssql-python maintainers:
+- Create an ADO Work Item following internal processes
+- Link the ADO Work Item in the "ADO Work Item" section above  
+- Follow the PR title format and provide a meaningful summary
 -->

.github/workflows/pr-format-check.yml

@@ -17,49 +17,62 @@ jobs:
           script: |
             const title = context.payload.pull_request.title;
             const body = context.payload.pull_request.body;
+            const prAuthor = context.payload.pull_request.user.login;
 
+            // Validate title prefix for all contributors
             const validTitlePrefixes = [
-              'FEAT:', 'CHORE:', 'FIX:', 'DOC:', 'STYLE:', 'REFACTOR:', 'RELEASE:'
+              'FEAT:', 'CHORE:', 'FIX:', 'DOC:', 'STYLE:', 'REFACTOR:', 
+              'RELEASE:'
             ];
 
-            const hasValidPrefix = validTitlePrefixes.some(prefix => title.startsWith(prefix));
+            const hasValidPrefix = validTitlePrefixes.some(prefix => 
+              title.startsWith(prefix));
 
             if (!hasValidPrefix) {
               core.setFailed(`❌ PR title must start with one of the allowed prefixes:\n${validTitlePrefixes.join(', ')}`);
             }
 
-            const azureWorkItemLinkPattern = /https:\/\/sqlclientdrivers\.visualstudio\.com\/[^\/]+\/_workitems\/edit\/\d+/i;
+            // Validate that either GitHub issue link or ADO Work Item link is present
+            const azureWorkItemLinkPattern = 
+              /https:\/\/sqlclientdrivers\.visualstudio\.com\/[^\/]+\/_workitems\/edit\/\d+/i;
+            const githubIssueLinkPattern = 
+              /(https:\/\/github\.com\/microsoft\/mssql-python\/issues\/\d+|#\d+)/i;
+            
             const hasWorkItemLink = azureWorkItemLinkPattern.test(body);
+            const hasGitHubIssueLink = githubIssueLinkPattern.test(body);
 
-            if (!hasWorkItemLink) {
-              core.setFailed(`❌ PR should contain a valid ADO Work Item ID.\nExpected a hyperlink in the format: https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/<ID>\nPlease ensure the ADO task hyperlink is present in the PR description.`);
+            if (!hasWorkItemLink && !hasGitHubIssueLink) {
+              core.setFailed(`❌ PR must contain either a valid GitHub issue link OR a valid ADO Work Item link.\nGitHub issue format: https://github.com/microsoft/mssql-python/issues/XXX or #XXX\nADO Work Item format: https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/<ID>\nPlease include at least one reference in the PR description.\nFor more information, see CONTRIBUTING.md.`);
             }
-            
-            // Check if PR description contains a meaningful summary section with actual content
-            const summaryPattern = /###\s*Summary\s*\r?\n([\s\S]*?)(\r?\n###|$)/;
+
+            // Check if PR description contains a meaningful summary section 
+            // with actual content (for all contributors)
+            const summaryPattern = 
+              /###\s*Summary\s*\r?\n([\s\S]*?)(\r?\n###|$)/;
             const summaryMatch = body.match(summaryPattern);
-            
+
             let hasValidSummary = false;
-            
+
             if (summaryMatch && summaryMatch[1]) {
               // Extract the summary content
               const summaryContent = summaryMatch[1];
-              
+
               // Remove all HTML comments including the template placeholder
-              const contentWithoutComments = summaryContent.replace(/<!--[\s\S]*?-->/g, '');
-              
+              const contentWithoutComments = 
+                summaryContent.replace(/<!--[\s\S]*?-->/g, '');
+
               // Remove whitespace and check if there's actual text content
               const trimmedContent = contentWithoutComments.trim();
-              
+
               // Check if there's at least 10 characters of meaningful content
               hasValidSummary = trimmedContent.length >= 10;
             }
-            
+
             if (!hasValidSummary) {
-              core.setFailed(`❌ PR must contain a meaningful summary section with actual text content (minimum 10 characters). 
-              Please add a clear description under the '### Summary' heading in your PR description.`);
+              core.setFailed(`❌ PR must contain a meaningful summary section with actual text content (minimum 10 characters).\nPlease add a clear description under the '### Summary' heading in your PR description.`);
             }
       - name: Add size label based on PR diff
+        if: github.event.pull_request.head.repo.full_name == github.repository
         uses: actions/github-script@v7
         with:
           script: |

CONTRIBUTING.md

@@ -11,4 +11,32 @@ instructions provided by the bot. You will only need to do this once across all
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
-or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Before Contributing
+
+### For External Contributors
+
+If you are an external contributor (not a Microsoft organization member), please follow these steps:
+
+1. **Create a GitHub Issue First**: Before submitting a pull request, create a GitHub issue describing the bug, feature request, or improvement you want to contribute.
+2. **Link the Issue in Your PR**: When you submit your pull request, please use the PR template and include a link to the GitHub issue in the PR description using the format: `https://github.com/microsoft/mssql-python/issues/XXX`
+3. **Follow PR Guidelines**: Ensure your PR title follows the required prefix format (FEAT:, FIX:, DOC:, etc.) and includes a meaningful summary.
+
+### For Microsoft Organization Members
+
+If you are a Microsoft organization member (internal contributor):
+
+1. **Create an ADO Work Item**: Follow your internal process to create an Azure DevOps (ADO) work item.
+2. **Link the ADO Work Item**: Include the ADO work item link in your PR description using the format: `https://sqlclientdrivers.visualstudio.com/.../workitems/edit/ID`
+3. **Follow PR Guidelines**: Ensure your PR title follows the required prefix format and includes a meaningful summary.
+
+## Pull Request Requirements
+
+All pull requests must include:
+
+- **Valid Title Prefix**: Your PR title must start with one of: `FEAT:`, `CHORE:`, `FIX:`, `DOC:`, `STYLE:`, `REFACTOR:`, or `RELEASE:`
+- **Meaningful Summary**: Include a clear description of your changes under the "### Summary" section in the PR description (minimum 10 characters)
+- **Issue/Work Item Link** (only one required): 
+  - External contributors: Link to a GitHub issue
+  - Microsoft org members: Link to an ADO work item

PyPI_Description.md

@@ -9,9 +9,10 @@ We are making progress - The Public Preview of our driver is now available! This
 ### What's Included:
 
 - Everything from previous releases
-- **Linux Support**: The mssql-python driver now supports Linux OS (manylinux2014) - Ubuntu, Debian and RHEL, enabling seamless development on Linux based systems. Added Linux driver libraries and related logic for architecture-specific handling and ODBC driver path resolution. Support for other Linux based distros will come in subsequent releases.
-- **Connection Pooling Support for MacOS and Linux**: Implemented connection pooling features for MacOS and Linux, including tests and unified code support for pooling across platforms.
-Expanded Pipeline/Test Matrix: Added/expanded support for Python versions < 3.13 and enhanced database setup for testing, including LocalDB and Docker-based SQL Server.
+- **Azure Active Directory Authentication:** New authentication module supporting Azure AD login options (ActiveDirectoryInteractive, ActiveDirectoryDeviceCode, ActiveDirectoryDefault) for secure and flexible cloud integration.
+- **Batch Execution Performance:** Refactored `executemany` for efficient bulk operations and improved C++ bindings for performance.
+- **Robust Logging System:** Overhauled logging with a singleton manager, sensitive data sanitization, and better exception handling.
+- **Improved Row Representation:** Enhanced output and debugging via updated `Row` object string and representation methods.
 
 For more information, please visit the project link on Github: https://github.com/microsoft/mssql-python
 

README.md

@@ -48,17 +48,24 @@ By adhering to the DB API 2.0 specification, the mssql-python module ensures com
 
 ### 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 various authentication methods, including username and password, Microsoft Entra managed identity, and Integrated Windows Authentication in a federated, domain-joined environment. Additionally, the driver supports Microsoft Entra interactive authentication and Microsoft Entra managed identity authentication for both system-assigned and user-assigned managed identities.
+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.
 
 EntraID authentication is now fully supported on MacOS and Linux but with certain limitations as mentioned in the table:
 
 | Authentication Method | Windows Support | macOS/Linux Support | Notes |
 |----------------------|----------------|---------------------|-------|
 | ActiveDirectoryPassword | ✅ Yes | ✅ Yes | Username/password-based authentication |
-| ActiveDirectoryInteractive | ✅ Yes | ❌ No | Only works on Windows |
+| 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) |
+| 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 |
+
+**NOTE**: 
+ - **Access Token**: the connection string **must not** contain `UID`, `PWD`, `Authentication`, or `Trusted_Connection` keywords.
+ - **Device Code**: make sure to specify a `Connect Timeout` that provides enough time to go through the device code flow authentication process.
+ - **Default**: Ensure you're authenticated via az login, or running within a managed identity-enabled environment.
 
 ### Enhanced Pythonic Features
 

benchmarks/README.md

@@ -0,0 +1,40 @@
+# Benchmarks
+
+This directory contains benchmark scripts for testing the performance of various database operations using `pyodbc` and `mssql_python`. The goal is to evaluate and compare the performance of these libraries for common database operations.
+
+## Why Benchmarks?
+- To measure the efficiency of `pyodbc` and `mssql_python` in handling database operations.
+- To identify performance bottlenecks and optimize database interactions.
+- To ensure the reliability and scalability of the libraries under different workloads.
+
+## How to Run Benchmarks
+1. **Set Up the Environment Variable**:
+   - Ensure you have a running SQL Server instance.
+   - Set the `DB_CONNECTION_STRING` environment variable with the connection string to your database. For example:
+     ```cmd
+     set DB_CONNECTION_STRING=Server=your_server;Database=your_database;UID=your_user;PWD=your_password;
+     ```
+
+2. **Install Richbench - Benchmarking Tool**:
+   - Install richbench :
+     ```cmd
+     pip install richbench
+     ```
+
+3. **Run the Benchmarks**:
+   - Execute richbench from the parent folder (mssql-python) :
+     ```cmd
+     richbench benchmarks
+     ```
+     Results will be displayed in the terminal with detailed performance metrics.
+
+## Key Features of `bench_mssql.py`
+- **Comprehensive Benchmarks**: Includes SELECT, INSERT, UPDATE, DELETE, complex queries, stored procedures, and transaction handling.
+- **Error Handling**: Each benchmark function is wrapped with error handling to ensure smooth execution.
+- **Progress Messages**: Clear progress messages are printed during execution for better visibility.
+- **Automated Setup and Cleanup**: The script automatically sets up and cleans up the database environment before and after the benchmarks.
+
+## Notes
+- Ensure the database user has the necessary permissions to create and drop tables and stored procedures.
+- The script uses permanent tables prefixed with `perfbenchmark_` for benchmarking purposes.
+- A stored procedure named `perfbenchmark_stored_procedure` is created and used during the benchmarks.