# filipeesch/dynamic-sql architecture

> Architecture diagram of the GitHub repository filipeesch/dynamic-sql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filipeesch/dynamic-sql
- Repository: https://github.com/filipeesch/dynamic-sql

## Overview

##### Project Type and Purpose
- This is a library that provides a new approach to dynamically compose SQL queries. Its design focuses on performance and type-safe parsing of SQL with support for conditional rendering, automatic parameter generation, and custom segment rendering.
- The README explains how developers can use special << >> tags, conditional operators, and interpolated strings to build SQL queries. As a result, the primary consumers of this library will be other .NET applications that need flexible, high-performance SQL generation.

##### File Structure for Architectural Insights
- The top-level contains several projects:
- DynamicSQL – the core library with subdirectories like Compiler, Parser, and Extensions.
- DynamicSQL.Sample – a sample implementation showing how to use the library.
- DynamicSQL.Tests – unit tests to verify functionality.
- DynamicSQL.Benchmark and DynamicSQL.PerformanceTests – modules for performance evaluations.
- Inside the DynamicSQL project, there are distinct submodules:
a. Compiler: Contains classes for compiling the SQL (e.g., CodeCompiler, StatementCompiler, StatementProcessor) which compile the parsed SQL into native code.
b. Parser: Includes parsers and expression evaluation logic (various Expression classes) that interpret the custom SQL string interpolation syntax.
c. Extensions: Implements helper methods for ADO.NET, asynchronous enumeration, and string manipulations.
d. Supporting utilities such as segment rendering and output readers.
- The presence of GitHub workflows indicates continuous integration and publishing pipelines.

##### Main Components of the System (to include
a. Client/Consumer Application:
- Represents the calling application (e.g., in the Sample).
- Provides input in the form of interpolated SQL queries that include conditional and dynamic segments.
b. DynamicSQL Library:
- Parser Module:
- Processes the interpolated SQL string.
- Contains classes like StatementParser, ExpressionStack, and various Expression types that handle specific tokens (e.g., ConditionalExpression, InterpolationExpression).
- Compiler Module:
- Uses components like StatementCompiler and CodeCompiler to convert parsed results into executable native code.
- Handles caching of compiled statements for high performance.
- Renderer/Segment Module:
- Responsible for segment rendering (SegmentRenderer, SegmentRendererContext) that assembles SQL parts.
- Extensions:
- Provides ADO.NET and other helper methods to facilitate query execution (AdoNetExtensions, AsyncEnumerableExtensions).
- Utilities:
- Various helpers (e.g., OutputReader, ReaderHelper, ValueStringBuilder) that support the build and execution of dynamic queries.
c. Database (External System):
- Represents the target SQL database that executes the dynamically created queries.

##### Relationships and Interactions
- Directional data flow starts at the client application, which sends an interpolated SQL string to the DynamicSQL library.
- The Parser module tokenizes and parses the input string into an intermediate representation.
- Next, the Compiler module compiles this representation into native code tailored for performance.
- The Renderer assembles the final SQL string along with properly generated SQL parameters.
- Finally, the application uses the Extensions (e.g., ADO.NET helpers) to send the generated SQL command to the database, which returns the results.

##### Architectural Patterns and Design Principles
- Separation of concerns: Distinct modules for parsing, compiling, and rendering.
- Pipeline architecture: Sequential processing from SQL string input → parsing → compilation → execution.
- Caching and performance optimization: The compiler compiles SQL to native code and caches the result to speed up subsequent executions.
- Extensibility: The design supports custom segment rendering and conditional logic, making it flexible for complex SQL query scenarios.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main pipeline
    Client["Client/Consumer Application"]:::client
    Parser["Parser Module"]:::module
    Compiler["Compiler Module"]:::module
    %% Renderer subgraph with individual components
    subgraph "Renderer/Segment Module"
        SegRenderer["SegmentRenderer"]:::module
        SegRendererCtx["SegmentRendererContext"]:::module
    end
    Extensions["Extensions"]:::module
    DB["External Database"]:::external

    %% Main flow arrows
    Client -->|"provides SQL input"| Parser
    Parser -->|"parses to intermediate representation"| Compiler
    Compiler -->|"compiles SQL code"| SegRenderer
    SegRenderer -->|"assembles SQL segments"| Extensions
    Extensions -->|"executes SQL commands"| DB

    %% Supporting utilities subgraph (side component)
    subgraph "Supporting Utilities"
        VSB["ValueStringBuilder"]:::utility
        OutputReader["OutputReader"]:::utility
        ReaderHelper["ReaderHelper"]:::utility
    end

    %% Dotted connections to indicate support
    Parser -.->|"uses"| VSB
    Compiler -.->|"supports"| OutputReader
    SegRendererCtx -.->|"assists"| ReaderHelper

    %% Validation modules subgraph (Testing & Benchmarking)
    subgraph "Validation Modules"
        Tests["DynamicSQL.Tests"]:::validation
        Benchmark["DynamicSQL.Benchmark"]:::validation
        Performance["DynamicSQL.PerformanceTests"]:::validation
    end

    %% Dotted arrow indicating validation and performance evaluation support
    Extensions -.->|"validated by"| Tests
    Extensions -.->|"benchmarked by"| Benchmark
    Extensions -.->|"performance-tested by"| Performance

    %% Click Events
    click Client "https://github.com/filipeesch/dynamic-sql/blob/main/DynamicSQL.Sample"
    click Parser "https://github.com/filipeesch/dynamic-sql/tree/main/DynamicSQL/Parser"
    click Compiler "https://github.com/filipeesch/dynamic-sql/tree/main/DynamicSQL/Compiler"
    click SegRenderer "https://github.com/filipeesch/dynamic-sql/blob/main/DynamicSQL/SegmentRenderer.cs"
    click SegRendererCtx "https://github.com/filipeesch/dynamic-sql/blob/main/DynamicSQL/SegmentRendererContext.cs"
    click Extensions "https://github.com/filipeesch/dynamic-sql/tree/main/DynamicSQL/Extensions"
    click VSB "https://github.com/filipeesch/dynamic-sql/blob/main/DynamicSQL/ValueStringBuilder.cs"
    click OutputReader "https://github.com/filipeesch/dynamic-sql/blob/main/DynamicSQL/OutputReader.cs"
    click ReaderHelper "https://github.com/filipeesch/dynamic-sql/blob/main/DynamicSQL/ReaderHelper.cs"

    %% Styling Definitions
    classDef client fill:#bbf,stroke:#333,stroke-width:2px;
    classDef module fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
    classDef utility fill:#fcf,stroke:#333,stroke-width:2px;
    classDef validation fill:#ffd,stroke:#333,stroke-width:2px;
```
