Thom LambandClaude Opus 4.7
d4b66838b5
Tackles the in-file copy-paste duplications SonarQube flagged on
`sql-utilities`, narrowing the dedup target to the cases where the
extraction is a clear readability win.
- `LinqToSql.Converters.ReverseConverterExtensions`: the three
`ToLinqQueryBreakdown` overloads (SqlServer / PostgreSql / Snowflake)
had identical 26-line bodies. Routes all three through a single
`BuildLinqBreakdownFrom(QueryBreakdown)` private helper — works
because Snowflake/PostgreSql `QueryBreakdown` derive from the
SqlServer one, so the parameter type accepts all three. Public API
preserved.
- `Markdown.Expressions.ExpressionGenerator`: `VisitInExpression` and
`VisitNotInExpression` had identical 18-line bodies differing only in
the "IN"/"NOT IN" label. Both now delegate to a new private
`RenderInList(label, searchExpression, values)`.
- `PostgreSql.Statements.StatementExpressionParser`: the qualified-
column-name building loop and the column-id switch were duplicated
across `HandleStringToken` (qualified-column branch) and
`GrabColumnExpression`. Extracted to a shared
`BuildQualifiedColumnExpression(seededBuilder, reader)` private helper.
Deliberately *not* refactored: `PostgreSql.Statements.StatementReader`'s
`<` / `>` operator handlers, which Sonar also flags as duplicate. The
shared pattern there is a structural sequence of "MovePosition;
character check; emit Token; return" repeated across single-/two-char
operator variants; folding it into a helper would replace four short,
self-explanatory inline checks with `TryMatchTwoCharOperator('=', ...)`
indirection that obscures what each branch actually emits. The dedup
isn't worth the readability tax.
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)