# vapor/sqlite-nio architecture

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

## Overview

##### Project Type & Purpose
- This is an open-source Swift client library (“SQLiteNIO”) that provides non-blocking, event-driven access to SQLite databases by building on Apple’s SwiftNIO framework.
- It wraps the native SQLite C API (via a small C module under Sources/CSQLite) in a SwiftNIO-style asynchronous API (under Sources/SQLiteNIO).

##### File Structure Analysis
- Top-level:
– .github, .gitignore, LICENSE, CI workflows → repository governance & CI.
– Package.swift → Swift Package Manager manifest.
– Plugins/VendorSQLite → patches & utilities for vendoring SQLite3 for SwiftPM builds.
– Sources/CSQLite → low-level C wrapper exposing sqlite3 C symbols to Swift.
– Sources/SQLiteNIO → the high-level Swift implementation (connection, statements, row parsing, custom functions, types, error model).
– Tests/SQLiteNIOTests → unit tests for the SwiftNIO API.

##### Key Architecture Insights from README
- Emphasizes non-blocking, event-driven model.
- Uses SwiftNIO event loops & futures/promises for all database operations.
- Targets multiple platforms supported by SwiftNIO (Linux, macOS, iOS, etc.).

##### Main Components & Their Relationships
a. Client Application Layer (your app)
– Calls SQLiteNIO API (e.g., SQLiteDatabase.connect, .query(), .prepare).
b. SQLiteNIO Swift Module
– Exposes high-level types: SQLiteDatabase, SQLiteConnection, SQLiteStatement, SQLiteRow, SQLiteError, SQLiteDataConvertible.
– Implements internals as SwiftNIO ChannelHandlers & NIOFuture chains.
c. SwiftNIO Core
– Provides EventLoop, Channel, ChannelPipeline, ByteBuffer, NIOFutures.
– Drives asynchronous I/O and thread scheduling.
d. CSQLite Wrapper Module
– Thin C library (sqlite_nio_sqlite3.c/.h) with Swift-compatible symbols.
– Includes vendored patches under Plugins/VendorSQLite for platform compatibility.
e. Native SQLite3 Engine
– The actual embedded database engine operating on a file or in-memory.
f. File System / OS
– Underlying storage (journal files, database files) and OS primitives.

##### Architectural Patterns & Design Principles
- Event-driven / Reactor Pattern (SwiftNIO)
- Adapter/Wrapper Pattern (wrapping SQLite3 C API in Swift types)
- Single Responsibility (each SwiftNIO ChannelHandler handles one aspect: statement, row decoding, error mapping)
- Modular layering (API ↔ NIO Core ↔ C wrapper ↔ OS)

##### Technologies & Frameworks
- Swift (5.10+)
- Swift Package Manager
- SwiftNIO (EventLoop, Channels, Futures)
- SQLite3 C library (vendored or system)
- XCTest (unit tests)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Application Layer"
        App["Client App"]:::client
    end

    subgraph "SQLiteNIO Swift API Layer"
        DB["SQLiteDatabase"]:::api
        Conn["SQLiteConnection"]:::api
        Stmt["SQLiteStatement"]:::api
        Row["SQLiteRow"]:::api
        Err["SQLiteError"]:::api
        DataConv["SQLiteDataConvertible"]:::api
        DataType["SQLiteDataType"]:::api
        Data["SQLiteData"]:::api
        CustomFn["SQLiteCustomFunction"]:::api
        Exports["Exports (public API)"]:::api
    end

    subgraph "SwiftNIO Core"
        EL["EventLoop"]:::nio
        Chan["ChannelPipeline"]:::nio
        Buf["ByteBuffer"]:::nio
        Fut["NIOFuture"]:::nio
    end

    subgraph "CSQLite Wrapper Module"
        CHdr["sqlite_nio_sqlite3.h"]:::cwrap
        CImpl["sqlite_nio_sqlite3.c"]:::cwrap
        Version["version.txt"]:::cwrap
    end

    subgraph "SQLite3 Engine & File System"
        Engine["SQLite3 Engine"]:::engine
        DBFile["Database & Journal Files"]:::engine
        FS["File System / OS"]:::engine
    end

    subgraph "Build & Packaging"
        Manifest["Package.swift"]:::build
        Vendor["Plugins/VendorSQLite"]:::build
    end

    subgraph "CI & Governance"
        Workflows[".github/workflows"]:::ci
        Codeowners[".github/CODEOWNERS"]:::ci
        Dependabot[".github/dependabot.yml"]:::ci
        License["LICENSE / NOTICES.txt"]:::ci
    end

    subgraph "Test Harness"
        Test1["SQLiteNIOTests.swift"]:::test
        Test2["SQLiteCustomFunctionTests.swift"]:::test
        Async["XCTAsyncAssertions.swift"]:::test
    end

    %% Connections
    App -->|"connect()"| DB
    DB -->|"uses"| Conn
    Conn -->|"prepare()/query()"| Stmt
    Stmt -->|"parses rows"| Row
    Row -->|"wrapped in"| Data
    Data -->|"converted via"| DataConv
    DataConv -->|"may use"| DataType
    Stmt -->|"returns"| Fut
    DB -->|"returns"| Fut
    Fut -.->|"fulfills promise"| App

    DB -->|"schedules on"| EL
    EL -->|"drives"| Chan
    Chan -->|"buffers data in"| Buf
    Chan -->|"invokes"| CHdr
    CHdr -->|"implemented by"| CImpl
    CImpl -->|"calls into"| Engine
    Engine -->|"reads/writes"| DBFile
    DBFile -->|"managed by"| FS

    DB -.->|"re-exports in"| Exports
    DB -.->|"allows custom functions"| CustomFn

    Manifest -.->|builds| DB
    Vendor -.->|patches C library| CImpl

    Workflows -.->|test & CI| Test1
    Workflows -.->|test & CI| Test2
    Workflows -.->|test & CI| Async

    %% Click Events
    click DB "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteDatabase.swift"
    click Conn "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteConnection.swift"
    click Stmt "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteStatement.swift"
    click Row "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteRow.swift"
    click Err "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteError.swift"
    click DataConv "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteDataConvertible.swift"
    click DataType "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteDataType.swift"
    click Data "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteData.swift"
    click CustomFn "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/SQLiteCustomFunction.swift"
    click Exports "https://github.com/vapor/sqlite-nio/blob/main/Sources/SQLiteNIO/Exports.swift"
    click CHdr "https://github.com/vapor/sqlite-nio/blob/main/Sources/CSQLite/include/sqlite_nio_sqlite3.h"
    click CImpl "https://github.com/vapor/sqlite-nio/blob/main/Sources/CSQLite/sqlite_nio_sqlite3.c"
    click Version "https://github.com/vapor/sqlite-nio/blob/main/Sources/CSQLite/version.txt"
    click Vendor "https://github.com/vapor/sqlite-nio/tree/main/Plugins/VendorSQLite"
    click Manifest "https://github.com/vapor/sqlite-nio/blob/main/Package.swift"
    click Workflows "https://github.com/vapor/sqlite-nio/tree/main/.github/workflows"
    click Codeowners "https://github.com/vapor/sqlite-nio/tree/main/.github/CODEOWNERS"
    click Dependabot "https://github.com/vapor/sqlite-nio/blob/main/.github/dependabot.yml"
    click License "https://github.com/vapor/sqlite-nio/tree/main/LICENSE"
    click Test1 "https://github.com/vapor/sqlite-nio/blob/main/Tests/SQLiteNIOTests/SQLiteNIOTests.swift"
    click Test2 "https://github.com/vapor/sqlite-nio/blob/main/Tests/SQLiteNIOTests/SQLiteCustomFunctionTests.swift"
    click Async "https://github.com/vapor/sqlite-nio/blob/main/Tests/SQLiteNIOTests/XCTAsyncAssertions.swift"

    %% Legend
    subgraph "Legend"
        A1["Rounded rectangle: Module/Package"]
        A2["Cylinder: Storage/File"]
        A3["Solid arrow: sync call"]
        A4["Dashed arrow: async/future"]
    end

    %% Styles
    classDef api fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef nio fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef cwrap fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef engine fill:#e2e3e5,stroke:#333,stroke-width:1px;
    classDef build fill:#f0f0f0,stroke:#333,stroke-width:1px;
    classDef ci fill:#f5f5f5,stroke:#333,stroke-width:1px;
    classDef test fill:#f5f0ff,stroke:#333,stroke-width:1px;
    classDef client fill:#d1ecf1,stroke:#333,stroke-width:1px;
```
