Thom LambandClaude Opus 4.7
4038b3dab5
SonarQube Analysis / sonarqube (pull_request) Successful in 3m42s
Final cluster Sonar was reporting: the 82-line copy-paste between `Markdown.SqlServer.QueryBreakdownCollectionGenerator` and `Markdown.PostgreSql.QueryBreakdownCollectionGenerator`. Both classes existed because each dialect has a different concrete `QueryBreakdownCollection` type with its own `ParameterUsageReport` class — no shared base for the methods to operate on. Resolves it with an adapter pattern in `Markdown.Common`: - **`ICollectionMarkdownData`** (new, internal): dialect-neutral view exposing query count, parameter / column / table totals, queries- for-report list, and parameter-rows (already-mapped to the writer's `ParameterUsageRow` type). - **`CollectionMarkdownGenerator`** (new, internal static): single template that takes the data + `MarkdownDialectFormat` and routes through `CollectionReportWriter`. The six `GenerateX` methods that were duplicated three times now live here once. - **SqlServer / PostgreSql wrappers**: shrunk to a `Format` static, a thin one-line forwarder per public method, and a private sealed `Adapter : ICollectionMarkdownData` nested class that does the dialect-specific extraction (including the `ParameterUsageReport → ParameterUsageRow` mapping that was previously duplicated three times as `MapParameters`). Public API unchanged — the existing `Markdown.SqlServer.QueryBreakdownCollectionGenerator.GenerateCollectionReport(collection, title)` etc. continue to work as before; their bodies just delegate. The three dialect-specific `ParameterUsageReport` classes are deliberately *not* unified yet — their `ToString()` overrides differ meaningfully per dialect and unifying would be a separate API discussion. Snowflake wrapper not touched in this commit — Sonar didn't flag it (its `GenerateSnowflakeFeaturesAnalysis` and feature-aware `QueryCompositionReport` callback make it structurally distinct). Consistency follow-up could move it onto the same adapter pattern without behavior change. All 1180 tests stay green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Strata.SqlTools
General Information
This library provides SQL utilities for parsing, analyzing, and manipulating SQL queries programmatically. It includes:
Core Features
- QueryBreakdown: Deep parsing of SELECT statements into component parts (SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY)
- Expression Trees: Type-safe expression building with operator overloading
- WITH Clause Support: Common Table Expressions (CTEs) parsing and generation
- Comment Preservation: Round-trip parsing that preserves SQL comments
SQL Dialect Support
- SQL Server: Full T-SQL dialect support with bracket identifiers and @parameters
- PostgreSQL: PostgreSQL syntax with $n positional and :named parameters
- Snowflake: Snowflake SQL dialect with :parameters and uppercase identifiers
- LINQ to SQL: Expression tree analysis for IQueryable queries
Visualization
- Mermaid Diagrams: Generate flowcharts, sequence diagrams, and ER diagrams
- Query Structure Visualization: Visual representation of query clauses and flow
- LINQ Method Chain Diagrams: Visualize LINQ query execution pipelines
- Collection Analysis: Batch query analysis with parameter usage reports
Integration
- Entity Framework Core: Persist and query QueryBreakdown objects with EF Core
Credits
This library is developed and maintained by Strata Decision Technology
Documentation
Comprehensive documentation is available in the docs folder:
Core Documentation
- Architecture Review - Design patterns, class hierarchies, and extensibility guide
- API Documentation - Complete API reference with examples
- NuGet Packaging - Build and publishing guidelines
Dialect-Specific Guides
- SQL Server Guide - T-SQL specific features
- PostgreSQL Guide - PostgreSQL syntax and parameter support
- Snowflake Guide - Snowflake SQL specific features
- LINQ to SQL Guide - LINQ query analysis and expression trees
Integration & Visualization
- Markdown Visualization - Mermaid diagram generation guide
- EFCore Integration - Entity Framework Core patterns
- WITH Clause Implementation - CTE feature details
See the documentation index for a complete list.
Branching and Versioning
| branch | version format | example |
|---|---|---|
| main | #.#.# | 1.2.3 |
| feature/* | #.#+1.0-featureName.# | 1.3.0-newfeat.1 |
| fix/* | #.#.#+1-fixName.# | 1.2.4-bug.1 |
See our confluence page for more information
Usage
Build and Test
Build the solution:
dotnet build Strata.SqlTools.sln
Run tests:
dotnet test Strata.SqlTools.sln
TestContainer Integration Tests
The testContainers folder contains real-world integration tests for PostgreSQL and SQL Server using Docker containers. These tests are not included in the main solution to keep CI/CD builds fast and avoid Docker dependencies in the build pipeline.
Requirements:
- Docker Desktop installed and running
- Tests take 1-2 minutes to run (container startup time)
Run TestContainer Tests:
# Run SQL Server integration tests (18 tests)
dotnet test testContainers/Strata.SqlTools.SqlServer.TestContainers
# Run PostgreSQL integration tests (17 tests)
dotnet test testContainers/Strata.SqlTools.PostgreSql.TestContainers
# Run all TestContainer tests (35 tests)
dotnet test testContainers/Strata.SqlTools.SqlServer.TestContainers
dotnet test testContainers/Strata.SqlTools.PostgreSql.TestContainers
Note: These integration tests are excluded from the main solution to support Docker-less build environments. They remain fully functional for local development and can be run independently as shown above.
Core & Dialect Packages
- Strata.SqlTools - Core SQL parsing and expression library
- Strata.SqlTools.SqlServer - SQL Server (T-SQL) specific implementations
- Strata.SqlTools.PostgreSql - PostgreSQL specific implementations with parameter analysis
- Strata.SqlTools.Snowflake - Snowflake SQL specific implementations
- Strata.SqlTools.LinqToSql - LINQ to SQL query analysis and expression tree parsing
Integration & Visualization Packages
- Strata.SqlTools.Markdown - Mermaid diagram generation for all SQL dialects
- Strata.SqlTools.EFCore - Entity Framework Core integration for QueryBreakdown persistence
- Strata.SqlTools.Rules - Rule engine for SQL query validation and analysis
NuGet Packages
This solution produces the following NuGet packages:
- Strata.SqlTools - Core SQL parsing and expression library
- Strata.SqlTools.SqlServer - SQL Server (T-SQL) specific implementations
- Strata.SqlTools.Snowflake - Snowflake SQL specific implementations
Package Features
Package Metadata:
- Symbol packages (snupkg) for debugging support
- Source Link enabled for debugging into package source
- XML documentation included
- MIT License
- README included in package
Code Quality:
- .NET 9.0 target framework
- Nullable reference types enabled
- .NET Analyzers and code style enforcement
- Full XML documentation on public APIs
- EditorConfig for consistent code style
Creating NuGet Packages
Build and create packages:
dotnet pack Strata.SqlTools.sln -c Release
Packages will be output to the bin/Release folders of each project.
Create a specific package:
dotnet pack src/Strata.SqlTools/Strata.SqlTools.csproj -c Release -o ./nupkg
Publishing to NuGet
Validate package before publishing:
dotnet tool install -g dotnet-validate
dotnet validate package nupkg/Strata.SqlTools.1.0.0.nupkg
Publish to NuGet.org:
dotnet nuget push nupkg/Strata.SqlTools.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json
Publishing Checklist
Before publishing to NuGet.org:
- Verify all public APIs have XML documentation
- Run full test suite and ensure 100% pass rate
- Update version number according to SemVer
- Update PackageReleaseNotes with changes
- Test package installation in a clean project
- Validate package contents using
dotnet validate - Push symbols to symbol server for debugging support
Development
Prerequisites
- .NET 9.0 SDK or later
- Visual Studio 2022 or VS Code with C# extension
Code Quality Tools
- Analyzers: Enabled for all projects
- Code Coverage: Run tests with coverage using your preferred tool
- SonarQube: Static analysis issues are tracked
API Guidelines
- All public APIs must have XML documentation
- Follow .NET API Design Guidelines
- Maintain backward compatibility within major versions (SemVer)