# vapor/postgres-kit architecture

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

## Overview

##### Project Type and Purpose
- This is an open-source Swift package (library) named **PostgresKit**.
- It provides a non-blocking, event-driven client for PostgreSQL, built on top of SwiftNIO for async I/O and AsyncKit for connection pooling.
- It implements the SQLKit driver protocol to translate and serialize SQL queries in the Postgres dialect.

##### Main Components
a. **PostgresKit Library**
- Sources/PostgresKit: primary driver code
- Sub-packages:
- Connection and pooling (PostgresConnectionSource.swift, ConnectionPool+Postgres.swift)
- SQL translation (PostgresDataTranslation.swift, PostgresDialect.swift, PostgresRow+SQL.swift)
- Deprecations (legacy API shims)
- Exports.swift (public API surface)
- Docs.docc: embedded documentation
b. **External Dependencies**
- **PostgresNIO**: low-level PostgreSQL client over SwiftNIO
- **AsyncKit**: event-loop-based connection pooling abstractions
- **SQLKit**: generic SQL driver protocol
c. **Runtime Entities**
- **EventLoopGroup**: thread-pool of event loops
- **EventLoopGroupConnectionPool**: manages pools of connections per event loop
- **EventLoopConnectionPool**: pool for a single event loop
- **PostgresConnection**: actual TCP/UNIX-socket connection to Postgres server
- **PostgresDatabase / SQLDatabase**: high-level query execution interfaces
d. **PostgreSQL Server**
- External database server (self-hosted or cloud)

##### Relationships and Data Flow
- **Configuration** ⇒ **PostgresConnectionSource**
- **ConnectionSource + EventLoopGroup** ⇒ **EventLoopGroupConnectionPool**
- **EventLoopGroupConnectionPool** ⇒ multiple **EventLoopConnectionPool** instances
- On query execution:
EventLoop[User Code] → asks Pool.for(eventLoop) → acquires **PostgresConnection** → executes SQL → returns **Row** objects → hands back to calling EventLoop
- Interactions with **PostgresNIO** occur inside PostgresConnection to manage the wire protocol
- SQLKit adapter sits on top of PostgresDatabase to provide the fluent SQL DSL

##### Architectural Patterns and Design Principles
- **Asynchronous, non-blocking I/O** via SwiftNIO
- **Connection pooling** per event loop (sharding for performance)
- **Adapter pattern**: SQLKit protocol implemented by PostgresDatabase
- **Separation of concerns**:
- Transport layer (PostgresNIO)
- Connection management (AsyncKit)
- SQL generation (SQLKit + PostgresKit translator)
- **Deprecation pathways**: maintain legacy APIs under Deprecations module

## Diagram (Mermaid)

```mermaid
graph TB
    %% Application Layer
    Application["Application / User Code"]:::runtime

    %% Core Library Modules
    subgraph "PostgresKit Library (Core Modules)"
        PCSource["PostgresConnectionSource"]:::core
        ConnPoolExt["ConnectionPool+Postgres (Pool extensions)"]:::core
        subgraph "SQL Translation"
            DataTrans["PostgresDataTranslation"]:::core
            Dialect["PostgresDialect"]:::core
            RowSQL["PostgresRow+SQL"]:::core
        end
        SQLAdapter["PostgresDatabase+SQL (SQLKit Adapter)"]:::core
        Exports["Exports.swift (Public API)"]:::core
        Config["SQLPostgresConfiguration"]:::core
        Deprecations["Deprecations (legacy API shims)"]:::core
        Docs["Docs.docc"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PGNIO["PostgresNIO"]:::external
        AK["AsyncKit"]:::external
        SK["SQLKit"]:::external
    end

    %% Runtime Entities
    subgraph "Runtime Entities"
        ELG["EventLoopGroup"]:::runtime
        ELGPool["EventLoopGroupConnectionPool"]:::runtime
        ELP["EventLoopConnectionPool"]:::runtime
        PConn["PostgresConnection"]:::runtime
        PDB["PostgresDatabase/SQLDatabase"]:::runtime
    end

    %% External Database
    PGServer["PostgreSQL Server"]:::db

    %% Initialization and Configuration Flow
    Config -->|"configure"| PCSource
    PCSource -->|"pool creation"| ELGPool
    ELG --> ELGPool
    ELGPool -->|"assign pool per event loop"| ELP

    %% Application Query Flow
    Application -->|"execute query"| SQLAdapter
    SQLAdapter -->|"use pool"| ELGPool
    ELGPool -->|"for event loop"| ELP
    ELP -->|"acquire connection"| PConn
    PConn -->|"execute SQL"| PGServer
    PGServer -->|"return rows"| PConn
    PConn -->|"raw rows"| RowSQL
    RowSQL -->|"translated rows"| Application

    %% Adapter and Runtime Bindings
    SQLAdapter --> PDB
    PGNIO --> PConn
    AK --> ELGPool
    SK --> SQLAdapter
    SQLAdapter -->|"uses dialect"| Dialect
    Dialect -.->|"relates to"| DataTrans

    %% Click Events
    click PCSource "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/PostgresConnectionSource.swift"
    click ConnPoolExt "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/ConnectionPool+Postgres.swift"
    click DataTrans "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/PostgresDataTranslation.swift"
    click Dialect "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/PostgresDialect.swift"
    click RowSQL "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/PostgresRow+SQL.swift"
    click SQLAdapter "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/PostgresDatabase+SQL.swift"
    click Exports "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/Exports.swift"
    click Config "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/SQLPostgresConfiguration.swift"
    click Deprecations "https://github.com/vapor/postgres-kit/tree/main/Sources/PostgresKit/Deprecations"
    click Docs "https://github.com/vapor/postgres-kit/blob/main/Sources/PostgresKit/Docs.docc"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef external fill:#98FB98,stroke:#000
    classDef runtime fill:#FFA500,stroke:#000
    classDef db fill:#D3D3D3,stroke:#000
```
