FEAT: Refine Perf Benchmarking, test across different OSs and add it to CI (#315)

### 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#40134](https://sqlclientdrivers.visualstudio.com/c6d89619-62de-46a0-8b46-70b92a84d85e/_workitems/edit/40134)

-------------------------------------------------------------------
### Summary   
<!-- Insert your summary of changes below. Minimum 10 characters
required. -->
This pull request introduces a comprehensive performance benchmarking
workflow for comparing `mssql-python` and `pyodbc` on real-world SQL
Server workloads. The changes include a new benchmark script targeting
the AdventureWorks2022 database, enhancements to the documentation, and
updates to CI pipelines to automate database setup and benchmark
execution on both Windows and Ubuntu environments.

**Benchmarking infrastructure and documentation:**

* Added a new script `benchmarks/perf-benchmarking.py` for real-world
query performance comparisons between `mssql-python` and `pyodbc`,
including statistical analysis, speedup calculations, and detailed
reporting.
* Expanded the `benchmarks/README.md` with instructions and key features
for running both the new and existing benchmark scripts, clarifying
usage, output, and requirements.

**CI/CD pipeline automation:**

* Updated `eng/pipelines/pr-validation-pipeline.yml` to automatically
download and restore the AdventureWorks2022 database for both Windows
and Ubuntu environments, ensuring benchmarks run against a realistic
dataset.
[[1]](diffhunk://#diff-296c8f902bbd70f34ee1c8c32383c8c99165fe4c8e5b0f234f8f22246e56a621R183-R230)
[[2]](diffhunk://#diff-296c8f902bbd70f34ee1c8c32383c8c99165fe4c8e5b0f234f8f22246e56a621R550-R606)
* Integrated steps in the pipeline to install required dependencies and
execute the new benchmarking script, with conditional logic for platform
and SQL Server availability.
[[1]](diffhunk://#diff-296c8f902bbd70f34ee1c8c32383c8c99165fe4c8e5b0f234f8f22246e56a621R183-R230)
[[2]](diffhunk://#diff-296c8f902bbd70f34ee1c8c32383c8c99165fe4c8e5b0f234f8f22246e56a621R550-R606)

These changes provide a robust framework for evaluating and monitoring
database driver performance in CI, helping guide future optimizations
and ensuring reliability across platforms.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: bewithgaurav

benchmarks/README.md

@@ -2,39 +2,89 @@
 
 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.
 
+## Benchmark Scripts
+
+### 1. `bench_mssql.py` - Richbench Framework Benchmarks
+Comprehensive benchmarks using the richbench framework for detailed performance analysis.
+
+### 2. `perf-benchmarking.py` - Real-World Query Benchmarks
+Standalone script that tests real-world queries against AdventureWorks2022 database with statistical analysis.
+
 ## 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
+
+### Running bench_mssql.py (Richbench Framework)
+
 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;
+     ```bash
+     export DB_CONNECTION_STRING="Server=your_server;Database=AdventureWorks2022;UID=your_user;PWD=your_password;"
      ```
 
 2. **Install Richbench - Benchmarking Tool**:
-   - Install richbench :
-     ```cmd
-     pip install richbench
-     ```
+   ```bash
+   pip install richbench
+   ```
 
 3. **Run the Benchmarks**:
-   - Execute richbench from the parent folder (mssql-python) :
-     ```cmd
+   - Execute richbench from the parent folder (mssql-python):
+     ```bash
      richbench benchmarks
      ```
-     Results will be displayed in the terminal with detailed performance metrics.
+   - Results will be displayed in the terminal with detailed performance metrics.
+
+### Running perf-benchmarking.py (Real-World Queries)
+
+This script tests performance with real-world queries from the AdventureWorks2022 database.
+
+1. **Prerequisites**:
+   - AdventureWorks2022 database must be available
+   - Both `pyodbc` and `mssql-python` must be installed
+   - Update the connection string in the script if needed
+
+2. **Run from project root**:
+   ```bash
+   python benchmarks/perf-benchmarking.py
+   ```
+
+3. **Features**:
+   - Runs each query multiple times (default: 5 iterations)
+   - Calculates average, min, max, and standard deviation
+   - Provides speedup comparisons between libraries
+   - Tests various query patterns:
+     - Complex joins with aggregations
+     - Large dataset retrieval (10K+ rows)
+     - Very large dataset (1.2M rows)
+     - CTEs and subqueries
+   - Detailed summary tables and conclusions
+
+4. **Output**:
+   The script provides:
+   - Progress indicators during execution
+   - Detailed results for each benchmark
+   - Summary comparison table
+   - Overall performance conclusion with speedup factors
 
 ## 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.
 
+## Key Features of `perf-benchmarking.py`
+- **Statistical Analysis**: Multiple iterations with avg/min/max/stddev calculations
+- **Real-World Queries**: Tests against AdventureWorks2022 with production-like queries
+- **Automatic Import Resolution**: Correctly imports local `mssql_python` package
+- **Comprehensive Reporting**: Detailed comparison tables and performance summaries
+- **Speedup Calculations**: Clear indication of performance differences
+
 ## 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.
+- The `bench_mssql.py` script uses permanent tables prefixed with `perfbenchmark_` for benchmarking purposes.
+- A stored procedure named `perfbenchmark_stored_procedure` is created and used during the benchmarks.
+- The `perf-benchmarking.py` script connects to AdventureWorks2022 and requires read permissions only.