# vapor/mysql-nio architecture

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

## Overview

##### Project Type and Purpose
- This is a low-level Swift library (“MySQLNIO”) implementing the MySQL wire protocol on top of SwiftNIO.
- Purpose: Provide a non-blocking, event-driven client API for connecting to, authenticating with, and querying a MySQL server.

##### File Structure Analysis
- Top-level files:
- Package.swift, .spi.yml, README.md, LICENSE, .dockerignore, .gitignore
- .github/ workflows for CI, API docs, tests
- Sources/MySQLNIO:
- Core client types (MySQLConnection.swift, MySQLDatabase.swift, MySQLQueryCommand.swift, etc.)
- Packet subpackage (encoder, decoder, sequence)
- Protocol subpackage (COM_QUERY, COM_STMT_PREPARE, OK/ERR packet handlers, capability flags, etc.)
- Utilities (CryptoUtils for password hashing, NIOUtils)
- Docs.docc for documentation
- Tests/MySQLNIOTests: unit tests for commands, packet handlers, utilities

##### README Insights
- Core concepts: NIO channel handlers, request/response connection, support for text vs. binary queries, MySQLData conversion utilities
- Dependencies: apple/swift-nio, swift-nio-ssl, swift-log, swift-crypto

##### Main Components
a. MySQLNIO Client API
- MySQLConnection (implements MySQLDatabase protocol)
- Query methods: simpleQuery(text), query(prepared + parameters)
- MySQLRow & MySQLData conversion
b. SwiftNIO Network Layer
- EventLoop & ChannelPipeline
- NIOBootstrap / ClientBootstrap
c. Protocol Handlers (Channel Handlers)
- MySQLPacketEncoder → ByteBuffer
- MySQLPacketDecoder ← ByteBuffer
- Command/Response handlers (COM_QUERY, COM_STMT_PREPARE, handshake, OK/ERR)
d. Utilities & Crypto
- CryptoUtils (password hashing)
- NIOUtils (buffer management)
e. External Dependencies
- SwiftNIO (I/O)
- SwiftNIO-SSL (TLS)
- SwiftLog (logging)
- SwiftCrypto (cryptography)
f. External MySQL Server

##### Component Interactions and Data Flow
- Application code invokes MySQLConnection.query(...)
→ builds a Command object (e.g. MySQLQueryCommand)
→ passes through ChannelPipeline: PacketEncoder serializes to ByteBuffer
→ sent over TCP/TLS to MySQL server
→ server responds with ByteBuffer stream
→ PacketDecoder produces MySQLPacket objects
→ Protocol handlers interpret packets into rows or errors
→ MySQLConnection collates responses into MySQLRow/MySQLData
→ results returned as EventLoopFuture to caller

##### Architectural Patterns and Principles
- Non-blocking, event-driven I/O (Reactor pattern via SwiftNIO)
- Pipeline of composable ChannelHandlers (Separation of concerns: framing, encoding, decoding, command semantics)
- Protocol-oriented API (MySQLDatabase protocol)
- Minimal abstractions; unopinionated low-level library

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    App["Application Code"]:::application

    %% Client API Layer
    subgraph "Client API Layer"
        Conn["MySQLConnection"]:::client
        DB["MySQLDatabase Protocol"]:::client
        SimpleCmd["MySQLSimpleQueryCommand"]:::client
        PreparedCmd["MySQLQueryCommand"]:::client
        Row["MySQLRow"]:::client
        Data["MySQLData & Conversion"]:::client
        Exports["Exports"]:::client
    end

    %% Command Builders
    subgraph "Command Builders"
        SimpleCmd
        PreparedCmd
    end

    %% Channel Pipeline Handlers
    subgraph "ChannelPipeline (Protocol Handlers)"
        Encoder["MySQLPacketEncoder"]:::protocol
        Decoder["MySQLPacketDecoder"]:::protocol
        Seq["MySQLPacketSequence"]:::protocol
        Packet["MySQLPacket Model"]:::protocol
        Protocol["MySQLProtocol Handlers"]:::protocol
    end

    %% Network/I/O Layer
    subgraph "Network/I/O Layer"
        PipelineHandler["MySQLConnectionHandler"]:::network
        NIO["SwiftNIO & TLS"]:::external
    end

    %% Utilities & Crypto
    subgraph "Utilities & Crypto"
        Crypto["CryptoUtils"]:::utility
        NIOUtils["NIOUtils"]:::utility
    end

    %% External Server
    MySQLServer[(MySQL Server)]:::server

    %% Data Flow
    App --> Conn
    Conn --> DB
    Conn --> SimpleCmd
    Conn --> PreparedCmd
    SimpleCmd --> Encoder
    PreparedCmd --> Encoder
    Encoder -->|"ByteBuffer"| PipelineHandler
    PipelineHandler -->|"TCP/TLS"| MySQLServer
    MySQLServer -->|"ByteBuffer"| PipelineHandler
    PipelineHandler --> Decoder
    Decoder --> Packet
    Packet --> Seq
    Seq --> Protocol
    Protocol --> Row
    Row --> Data
    Data --> Conn

    %% Dependency Edges
    PipelineHandler --> NIO
    Conn --> Crypto
    Conn --> NIOUtils

    %% Click Events for File Mapping
    click Conn "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLConnection.swift"
    click DB "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLDatabase.swift"
    click SimpleCmd "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLSimpleQueryCommand.swift"
    click PreparedCmd "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLQueryCommand.swift"
    click Row "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLRow.swift"
    click Data "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLData.swift"
    click Data "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLDataConvertible.swift"
    click Exports "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Exports.swift"
    click PipelineHandler "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/MySQLConnectionHandler.swift"
    click Encoder "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Packet/MySQLPacketEncoder.swift"
    click Decoder "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Packet/MySQLPacketDecoder.swift"
    click Seq "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Packet/MySQLPacketSequence.swift"
    click Packet "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Packet/MySQLPacket.swift"
    click Protocol "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Protocol/MySQLProtocol.swift"
    click Crypto "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Utilities/CryptoUtils.swift"
    click NIOUtils "https://github.com/vapor/mysql-nio/blob/main/Sources/MySQLNIO/Utilities/NIOUtils.swift"

    %% Styling
    classDef application fill:#E8F0FE,stroke:#333,stroke-width:1px
    classDef client fill:#D6EFFF,stroke:#333,stroke-width:1px
    classDef network fill:#D6FFD6,stroke:#333,stroke-width:1px
    classDef protocol fill:#FFF5CC,stroke:#333,stroke-width:1px
    classDef utility fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef server fill:#CCCCCC,stroke:#333,stroke-width:1px
```
