# vapor/mysql-kit architecture

> Architecture diagram of the GitHub repository vapor/mysql-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/mysql-kit
- Repository: https://github.com/vapor/mysql-kit

## Overview

##### Project type and purpose
- This is a Swift package providing a MySQL driver implementation for the SQLKit interface (part of the Vapor ecosystem).
- It is a library (not a full application) whose sole purpose is to build, serialize, and execute MySQL‐dialect SQL queries asynchronously using SwiftNIO and AsyncKit.

##### File structure
- Top‐level:
- Package.swift, README.md, LICENSE (SPM module)
- Sources/MySQLKit: implementation of the driver
- Tests/MySQLKitTests: unit tests
- Key source files:
- MySQLConfiguration.swift (connection parameters)
- MySQLConnectionSource.swift (factory for TCP connections via MySQLNIO)
- ConnectionPool+MySQL.swift (EventLoopGroupConnectionPool extension)
- MySQLDatabase+SQL.swift (conformance to SQLKit’s SQLDatabase)
- DataEncoder/Decoder, Dialect, Row extensions, Optional converters
- Dependencies surfaced in README: SQLKit (interface), MySQLNIO (network protocol), AsyncKit (connection pooling), SwiftNIO (EventLoopGroup).

##### README for additional insights
- Configuration patterns: direct struct vs. URL init vs. UNIX socket
- Pooling: EventLoopGroupConnectionPool and EventLoopConnectionPool
- Runtime flow: user creates Configuration → ConnectionSource → Pool → MySQLDatabase → SQLDatabase
- Under the covers: asynchronous network I/O on event loops, pooling of connections.

a. Main components
1. User Application Code (calls into MySQLKit)
2. MySQLKit Library components:
- MySQLConfiguration
- MySQLConnectionSource
- EventLoopGroupConnectionPool / EventLoopConnectionPool
- MySQLDatabase (implements SQLDatabase)
- SQL query builder (builds AST via SQLKit)
- DataEncoder / DataDecoder
3. AsyncKit Connection Pool logic
4. MySQLNIO Protocol Handler (network framing, packet parsing)
5. SwiftNIO EventLoopGroup / EventLoop
6. External MySQL Server
b. Relationships & interactions
- The user code instantiates MySQLConfiguration.
- Configuration → MySQLConnectionSource (holds credentials).
- ConnectionSource + EventLoopGroup → EventLoopGroupConnectionPool.
- The pool hands out EventLoopConnectionPool on each event loop.
- The pool’s `withConnection` opens or reuses a MySQLNIO channel to the server.
- When executing queries, MySQLDatabase uses SQLKit to build SQL string, encodes parameters via MySQLDataEncoder, sends request via MySQLNIO on an EventLoop.
- Server replies parsed by MySQLDataDecoder, returned to user as rows or results.
c. Architectural patterns / design principles
- Layered architecture: SQLKit interface → MySQLKit driver → AsyncKit pooling → MySQLNIO transport → SwiftNIO event loops → MySQL server.
- Dependency inversion: MySQLDatabase implements SQLDatabase.
- Asynchronous, non‐blocking I/O with event loops.
- Separation of concerns: configuration, pooling, protocol, encoding, and SQL dialect are modular.
d. Key technologies / frameworks
- Swift Package Manager
- SwiftNIO (EventLoopGroup, Channel)
- MySQLNIO (MySQL protocol)
- AsyncKit (EventLoopGroupConnectionPool)
- SQLKit (SQL AST / builder interfaces)

##### Diagramming conventions
Layer 1: Application Code
Layer 2: SQLKit → MySQLKit
Layer 3: AsyncKit Pooling → MySQLNIO Protocol
Layer 4: SwiftNIO EventLoopGroup
Layer 5: MySQL Server
- Config → ConnectionSource
- ConnectionSource → Pool
- Pool → EventLoop (multiple)
- Pool → MySQLNIO channel → Server
- SQL builder → Encoder → NIO pipeline → Decoder → Rows
- Blue for SQLKit/MySQLKit code
- Green for pooling (AsyncKit)
- Orange for network transport (MySQLNIO / SwiftNIO)
- Grey for external services (MySQL server)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Application
    subgraph "Layer 1: Application"
        direction TB
        App["User Application Code"]
    end

    %% Layer 2: SQLKit & MySQLKit
    subgraph "Layer 2: SQLKit → MySQLKit"
        direction TB
        SQLKit["SQLKit (SQL AST/Builder)"]:::blue
        Exports["Exports"]:::blue
        MySQLConfig["MySQLConfiguration"]:::blue
        MySQLSource["MySQLConnectionSource"]:::blue
        MySQLDB["MySQLDatabase (SQLDatabase)"]:::blue
        SQLDialect["MySQLDialect"]:::blue
        DataEnc["MySQLDataEncoder"]:::blue
        DataDec["MySQLDataDecoder"]:::blue
        RowExt["MySQLRow+SQL"]:::blue
        OptConv["Optional+MySQLDataConvertible"]:::blue
        Docs["Docs (MySQLKit.md)"]:::blue
        Tests["MySQLKitTests"]:::blue
    end

    %% Layer 3: Pooling & Protocol
    subgraph "Layer 3: AsyncKit Pooling → MySQLNIO Protocol"
        direction TB
        PoolExt["ConnectionPool+MySQL"]:::green
        MySQLNIO["MySQLNIO Protocol Handler"]:::orange
    end

    %% Layer 4: EventLoopGroup
    subgraph "Layer 4: SwiftNIO EventLoopGroup"
        direction TB
        EventLoopGroup["EventLoopGroup"]:::orange
        EventLoop["EventLoop"]:::orange
    end

    %% Layer 5: External Service
    subgraph "Layer 5: External MySQL Server"
        direction TB
        MySQLServer["MySQL Server"]:::grey
    end

    %% Relationships
    App -->|"create Configuration"| MySQLConfig
    MySQLConfig -->|"init ConnectionSource"| MySQLSource
    MySQLSource -->|"with EventLoopGroup"| PoolExt
    PoolExt -->|"allocates"| EventLoopGroup
    EventLoopGroup -->|"provides"| EventLoop
    PoolExt -->|"withConnection()"| EventLoop
    EventLoop -->|"opens channel"| MySQLNIO
    SQLKit -->|"builds AST"| MySQLDB
    MySQLDB -->|"uses encoder"| DataEnc
    MySQLDB -->|"uses decoder"| DataDec
    MySQLDB -->|"uses dialect"| SQLDialect
    MySQLDB -->|"uses row ext"| RowExt
    MySQLDB -->|"uses converters"| OptConv
    PoolExt -->|"executes simpleQuery() via"| MySQLNIO
    MySQLNIO -->|"network I/O"| EventLoop
    MySQLNIO -->|"talks to"| MySQLServer
    MySQLServer -->|"sends response"| MySQLNIO
    MySQLNIO -->|"parsed by"| DataDec
    DataDec -->|"rows returned to"| MySQLDB
    MySQLDB -->|"results to"| App

    %% Click Events
    click MySQLConfig "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/MySQLConfiguration.swift"
    click MySQLSource "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/MySQLConnectionSource.swift"
    click PoolExt "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/ConnectionPool+MySQL.swift"
    click MySQLDB "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/MySQLDatabase+SQL.swift"
    click SQLDialect "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/MySQLDialect.swift"
    click DataEnc "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/MySQLDataEncoder.swift"
    click DataDec "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/MySQLDataDecoder.swift"
    click RowExt "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/MySQLRow+SQL.swift"
    click OptConv "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/Optional+MySQLDataConvertible.swift"
    click Exports "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/Exports.swift"
    click Docs "https://github.com/vapor/mysql-kit/blob/main/Sources/MySQLKit/Docs.docc/MySQLKit.md"
    click Tests "https://github.com/vapor/mysql-kit/blob/main/Tests/MySQLKitTests/MySQLKitTests.swift"

    %% Styles
    classDef blue fill:#D0E6FF,stroke:#4D90FE,color:#000
    classDef green fill:#DFFFD0,stroke:#4CAF50,color:#000
    classDef orange fill:#FFE6C7,stroke:#FF9800,color:#000
    classDef grey fill:#F0F0F0,stroke:#999,color:#000
```
