# vapor/fluent-postgres-driver architecture

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

## Overview

##### Project Type and Purpose
- This is an open-source Swift package implementing a Fluent ORM driver for PostgreSQL.
- It acts as an adapter layer between FluentKit (the ORM) and the PostgreSQL database, leveraging PostgresKit/SQLKit, PostgresNIO, and AsyncKit.

##### Main Architectural Components
a. Consumer (FluentKit ORM)
- Sends high-level CRUD queries and schema operations.
b. FluentPostgresDriver Library
- Configuration: `FluentPostgresConfiguration.swift`
- Driver entry point: `FluentPostgresDriver.swift`
- Database wrapper: `FluentPostgresDatabase.swift`
- Converter delegate: `PostgresConverterDelegate.swift`
- Row mapping & error handling: `PostgresRow+Database.swift`, `PostgresError+Database.swift`
c. SQLKit Driver Layer (PostgresKit)
- Implements `SQLDatabase` protocols, builds SQL statements.
d. Low-Level Connection (PostgresNIO + AsyncKit)
- Handles TCP connection, protocol frames, pooling.
e. External Service
- PostgreSQL Server (database instance)

##### Relationships and Data Flow
- Directional flow:
FluentKit ORM → FluentPostgresDriver → PostgresKit/SQLKit → PostgresNIO → PostgreSQL
- Connection Pooling: AsyncKit provides pool between driver and PostgresNIO.
- Converter Delegate: Translates Fluent data types ↔ SQL literals.
- Error Surface: Database errors bubble up through driver into ORM.

##### Architectural Patterns and Principles
- Adapter Pattern: Driver implements FluentKit’s `DatabaseDriver` interface.
- Layered Architecture:
- Presentation (ORM)
- Driver/Adapter
- SQL Builder
- Protocol/IO
- External database
- Asynchronous, non-blocking I/O via Swift NIO.
- Separation of concerns: configuration, SQL building, connection management, error mapping.

## Diagram (Mermaid)

```mermaid
flowchart TD
    FK["FluentKit ORM"]:::orm

    subgraph "FluentPostgresDriver Library"
        FPC["Configuration\nFluentPostgresConfiguration.swift"]:::driver
        FPD["Driver Entry\nFluentPostgresDriver.swift"]:::driver
        FPDB["Database Wrapper\nFluentPostgresDatabase.swift"]:::driver
        PCD["Converter Delegate\nPostgresConverterDelegate.swift"]:::driver
        PR["Row Mapping\nPostgresRow+Database.swift"]:::driver
        PE["Error Mapping\nPostgresError+Database.swift"]:::driver
        EXP["Module Exports\nExports.swift"]:::driver
        DBID["DatabaseID Extension\nDatabaseID+PostgreSQL.swift"]:::driver
        DC["Deprecated Config API\nFluentPostgresConfiguration+Deprecated.swift"]:::driver
    end

    PSQ["PostgresKit / SQLKit"]:::framework
    PNIO["PostgresNIO + AsyncKit Pool"]:::framework
    PGDB[(PostgreSQL Server)]:::external

    FK -->|"execute(query)"| FPD
    FPD -->|"build SQL"| PSQ
    PSQ -->|"send packet"| PNIO
    PNIO -->|"network I/O"| PGDB
    PGDB -->|"response/error"| PNIO
    PNIO -->|"packet"| PSQ
    PSQ -->|"rows/errors"| FPD
    FPD -->|"results"| FK

    %% Click Events
    click FPC "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/FluentPostgresConfiguration.swift"
    click FPD "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/FluentPostgresDriver.swift"
    click FPDB "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/FluentPostgresDatabase.swift"
    click PCD "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/PostgresConverterDelegate.swift"
    click PR "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/PostgresRow+Database.swift"
    click PE "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/PostgresError+Database.swift"
    click EXP "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/Exports.swift"
    click DBID "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/DatabaseID+PostgreSQL.swift"
    click DC "https://github.com/vapor/fluent-postgres-driver/blob/main/Sources/FluentPostgresDriver/Deprecations/FluentPostgresConfiguration+Deprecated.swift"

    %% Styles
    classDef orm fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef driver fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef framework fill:#ffe5cc,stroke:#333,stroke-width:1px;
    classDef external fill:#ffcccc,stroke:#333,stroke-width:1px;
```
