Thom LambandClaude Opus 4.7
c121dfa611
The standard `TryParse(...)` prelude — null/empty check, parser construction, comment-preserving normalize, statement-prefix regex validation, setup/finish clause extraction — was copy-pasted in **eight** breakdown classes across the SqlServer and Snowflake dialects. Sonar flagged it as a six-way duplicate cluster on the shorter (~17-line) common block, and as additional pairwise duplicates on the longer (~30-line) version. Introduces `Strata.SqlTools.Statements.SqlServer.ParsePreparation` with a single `TryRunPrelude(sql, parser, prefixRegex, prefixDescription, out ...)` method. Each `TryParse` now calls it once and proceeds straight to dialect-specific match logic. Touched callers: - `SqlServer.InsertBreakdown`, `SqlServer.DeleteBreakdown`, `SqlServer.UpdateBreakdown`, `SqlServer.ProcedureBreakdown` - `Snowflake.InsertBreakdown`, `Snowflake.DeleteBreakdown`, `Snowflake.UpdateBreakdown`, `Snowflake.ProcedureBreakdown` The Microsoft-SQL fallback path in the Snowflake breakdowns (which delegates to the SqlServer breakdown's TryParse before the prelude even runs) is preserved unchanged. `ParsePreparation` is `public` because it sits in the SqlServer assembly and is consumed cross-assembly by Snowflake/PostgreSql. This is a new public type but it's deliberately a thin scaffold — external consumers should still be calling the breakdown classes' own `TryParse` methods. 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)