# vapor/sql-kit architecture

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

- Interactive diagram: https://gitdiagram.com/vapor/sql-kit
- Repository: https://github.com/vapor/sql-kit

## Overview

##### Project Type and Purpose
- This is an open-source Swift library (SQLKit) for building, serializing, and executing SQL queries in a database-agnostic way.
- Its main purpose is to provide a protocol-based, fluent API for DQL, DML, and DDL across multiple SQL dialects (Postgres, MySQL, SQLite, etc.), without managing connections.

##### File Structure Analysis
- Sources/SQLKit – core library
- Builders (Prototypes & Implementations) – fluent query builder API
- Expressions – AST types representing SQL statements/fragments
- SQLSerializer – serializes AST to SQL strings with bindings
- Database – `SQLDatabase`, `SQLDialect` interfaces
- Rows – encoding/decoding of results (`SQLRow`, `SQLRowDecoder`)
- Utilities – helpers (coding keys, string handling)
- Deprecated – backward-compat layers
- Docs.docc – inline documentation
- Sources/SQLKitBenchmark – benchmarking suite for library performance
- Tests/SQLKitTests – unit/integration tests covering builders, serialization, decoding, dialect features
- Configuration:
- Package.swift – SwiftPM manifest
- .github – CI workflows, codecov, dependabot
- .gitignore, LICENSE

##### README Insights
- Confirms SQLKit is purely a query-building/serialization library.
- Describes core abstractions (`SQLDatabase`, `SQLExpression`, various builders).
- Mentions external “kit” packages (PostgresKit, MySQLKit, SQLiteKit) that supply drivers implementing `SQLDatabase`.

##### Main Components
a. Core Library Modules (internal):
– Protocol Layer: `SQLExpression`, `SQLDatabase`, `SQLDialect`, `SQLQueryBuilder` protocols
– Builders: Prototype interfaces → Concrete Implementations → Fluent API
– Expressions/AST: clauses, queries, syntax nodes
– Serializer: `SQLSerializer` producing SQL + bindings
– Rows: `SQLRow`, encoders/decoders for results
– Utilities: shared helpers
b. External Integrations:
– Database Driver Packages (PostgresKit, MySQLKit, SQLiteKit)
– Underlying SwiftNIO for async I/O
c. Consumer Application:
– Calls `db.select()`, `db.insert()`, `db.update()`, etc.
– Supplies Codable models for `run()` / `all(decoding:)`

##### Relationships and Data Flow
1. Consumer Code → calls methods on `SQLDatabase` (driver)
2. Driver’s `SQLDatabase` extension methods → instantiate appropriate Builder
3. Fluent Builder → constructs an `SQLExpression` (AST) via Prototypes & Implementations
4. `SQLSerializer` + `SQLDialect` → serialize AST to SQL string + parameter bindings
5. Driver hands SQL + bindings to real DB connection (via SwiftNIO)
6. DB returns raw rows → driver wraps into `SQLRow`
7. `SQLRowDecoder` / Codable flows decode rows into models → returned to Consumer

##### Architectural Patterns & Principles
- Protocol-based, dependency inversion: Core protocols aren’t tied to any one database.
- Fluent builder pattern: Prototypes → chaining → implementations produce AST.
- Separation of concerns: AST (Expressions) vs. Serialization (Serializer & Dialect) vs. Execution (Driver).
- Extensibility points: New dialects, custom expressions, custom builders.

##### Essential Elements to Capture
- Protocol boundaries (`SQLDatabase`, `SQLExpression`, `SQLDialect`)
- Builder layering (Prototypes vs. Implementations)
- AST vs. Serializer separation
- External driver link implementing the core database interface
- Data flow loops for query execution and result decoding
- Extensibility hotspots for new dialects or custom builders

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application
    subgraph "Consumer Application"
        Consumer["Consumer Application"]:::external
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        SDDB["SQLDatabase"]:::protocol
        SDLT["SQLDialect"]:::protocol
        SEXP["SQLExpression"]:::protocol
        SQB["SQLQueryBuilder"]:::protocol
    end

    %% AST & Fluent API
    subgraph "AST & Fluent API"
        BP["Builders Prototypes"]:::builders
        BI["Builders Implementations"]:::builders
        EB["Expressions: Basics"]:::builders
        EC["Expressions: Clauses"]:::builders
        EQ["Expressions: Queries"]:::builders
        ES["Expressions: Syntax"]:::builders
    end

    %% Serialization & Dialect
    subgraph "Serialization & Dialect"
        SERS["SQLSerializer"]:::serializer
    end

    %% Execution & Drivers
    subgraph "Execution & Drivers"
        DRV["Database Drivers (PostgresKit, MySQLKit, SQLiteKit)"]:::drivers
        DB["Database (SQL)"]:::drivers
    end

    %% Row Handling
    subgraph "Row Handling"
        SR["SQLRow"]:::rows
        SRD["SQLRowDecoder"]:::rows
        SQE["SQLQueryEncoder"]:::rows
        SCU["SQLCodingUtilities"]:::rows
    end

    %% Utilities & Deprecated
    subgraph "Utilities & Deprecated"
        U1["StringHandling"]:::utilities
        U2["SomeCodingKey"]:::utilities
        DEP["Deprecated Compatibility"]:::deprecated
    end

    %% Documentation & Exports
    subgraph "Documentation & Exports"
        DOC["Docs.docc"]:::doc
        DOCB["BasicUsage.md"]:::doc
        EX["Exports.swift"]:::doc
    end

    %% Benchmark & Tests
    subgraph "Benchmark & Tests"
        BM["Benchmark Suite"]:::other
        TS["Test Suite"]:::other
    end

    %% Configuration & CI
    subgraph "Configuration & CI"
        PKG["Package.swift"]:::config
        WF[".github/workflows/test.yml"]:::config
        DBOT[".github/dependabot.yml"]:::config
        GI[".gitignore"]:::config
        LIC["LICENSE"]:::config
    end

    %% Extensibility
    subgraph "Extensibility"
        ED["Add New Dialect"]:::ext
        ECX["Custom Expression"]:::ext
    end

    %% Connections
    Consumer -->|"calls"| SDDB
    SDDB -->|"instantiates builder"| BP
    BP -->|"chain to"| BI
    BI -->|"builds"| EB
    BI -->|"builds"| EC
    BI -->|"builds"| EQ
    BI -->|"builds"| ES
    EB -->|"AST"| SEXP
    EC -->|"AST"| SEXP
    EQ -->|"AST"| SEXP
    ES -->|"AST"| SEXP
    SEXP -->|"to serializer"| SERS
    SERS -->|"SQL + Bindings"| DRV
    DRV -->|"executes SQL"| DB
    DB -->|"returns rows"| SR
    SR -->|"decode"| SRD
    SR -->|"encode"| SQE
    SR -->|"utils"| SCU
    SRD -->|"Model"| Consumer

    %% Extensibility links
    ED -.-> SDLT
    ECX -.-> EB

    %% Click Events
    click SDDB "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Database/SQLDatabase.swift"
    click SDLT "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Database/SQLDialect.swift"
    click SEXP "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Expressions/SQLExpression.swift"
    click SQB "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Builders/Prototypes/SQLQueryBuilder.swift"
    click BP "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKit/Builders/Prototypes"
    click BI "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKit/Builders/Implementations"
    click EB "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKit/Expressions/Basics"
    click EC "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKit/Expressions/Clauses"
    click EQ "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKit/Expressions/Queries"
    click ES "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKit/Expressions/Syntax"
    click SERS "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Expressions/SQLSerializer.swift"
    click SR "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Rows/SQLRow.swift"
    click SRD "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Rows/SQLRowDecoder.swift"
    click SQE "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Rows/SQLQueryEncoder.swift"
    click SCU "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Rows/SQLCodingUtilities.swift"
    click U1 "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Utilities/StringHandling.swift"
    click U2 "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Utilities/SomeCodingKey.swift"
    click DEP "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKit/Deprecated"
    click DOC "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Docs.docc"
    click DOCB "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Docs.docc/BasicUsage.md"
    click EX "https://github.com/vapor/sql-kit/blob/main/Sources/SQLKit/Exports.swift"
    click BM "https://github.com/vapor/sql-kit/tree/main/Sources/SQLKitBenchmark"
    click TS "https://github.com/vapor/sql-kit/tree/main/Tests/SQLKitTests"
    click PKG "https://github.com/vapor/sql-kit/blob/main/Package.swift"
    click WF "https://github.com/vapor/sql-kit/blob/main/.github/workflows/test.yml"
    click DBOT "https://github.com/vapor/sql-kit/blob/main/.github/dependabot.yml"
    click GI "https://github.com/vapor/sql-kit/blob/main/.gitignore"
    click LIC "https://github.com/vapor/sql-kit/tree/main/LICENSE"

    %% Styles
    classDef protocol fill:#A8D0E6,stroke:#333,stroke-width:1px
    classDef builders fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef serializer fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef rows fill:#D1C4E9,stroke:#333,stroke-width:1px
    classDef utilities fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef deprecated fill:#BDBDBD,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef doc fill:#F5F5F5,stroke:#333,stroke-width:1px
    classDef other fill:#F5F5F5,stroke:#333,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef drivers fill:#FFF59D,stroke:#333,stroke-width:1px
    classDef external fill:#FFECB3,stroke:#333,stroke-width:1px
    classDef ext fill:#FFCCBC,stroke:#FF5722,stroke-width:2px,stroke-dasharray: 5 5
```
