# jackc/pgx architecture

> Architecture diagram of the GitHub repository jackc/pgx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jackc/pgx
- Repository: https://github.com/jackc/pgx

## Overview

##### Core Components
- Main pgx driver interface
- Connection Pool (pgxpool)
- Protocol Implementation (pgproto3)
- Type System (pgtype)
- Standard Library Adapter (stdlib)

##### Supporting Components
- Tracing System
- Logging System
- Statement Cache
- Connection Management

##### Main Layers (Top to Bottom)

- Application Layer
- ↓
- Interface Layer (pgx API, database/sql adapter)
- ↓
- Core Services Layer
- ↓
- Protocol Layer
- ↓
- PostgreSQL Server

##### Component Organization

- Rectangles: Main modules (pgx, pgxpool, pgtype)
- Hexagons: Interfaces and adapters
- Clouds: External systems (PostgreSQL)

- Blue: Core components
- Green: Supporting services
- Yellow: Interfaces/Adapters
- Gray: External systems

##### Connection Flows

- Application → pgx interface
- pgx interface → connection pool
- connection pool → protocol handler
- protocol handler → PostgreSQL

##### Special Features Section

- LISTEN/NOTIFY support
- COPY protocol
- Large object support
- Binary format support

##### Cross-Cutting Concerns

As vertical bars spanning across layers:
- Tracing
- Logging
- Error handling
- Context management

Specific Implementation Details:

##### Below that, show the connection pool (pgxpool) with
- Connection management
- Statement cache
- Connection lifecycle hooks

- pgproto3 implementation
- Message flow handling
- Authentication methods

##### Type system (pgtype) showing
- Type mapping between PostgreSQL and Go
- Custom type support
- Array and composite type handling

##### Supporting systems
- Tracing infrastructure
- Logging framework
- Error handling

Important Considerations:

##### Integration points
- Third-party tracers
- Custom type adapters
- Logging adapters

##### Version compatibility information
- Go version support
- PostgreSQL version support

## Diagram (Mermaid)

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

    subgraph "Interface Layer"
        PgxAPI["PGX Driver Interface"]:::core
        StdLib["Standard Library Adapter"]:::adapter
        click PgxAPI "https://github.com/jackc/pgx/blob/master/conn.go"
        click StdLib "https://github.com/jackc/pgx/blob/master/stdlib/sql.go"
    end

    subgraph "Core Services Layer"
        ConnPool["Connection Pool"]:::core
        StmtCache["Statement Cache"]:::storage
        ConnMgmt["Connection Management"]:::core
        TypeSystem["Type System"]:::core
        click ConnPool "https://github.com/jackc/pgx/blob/master/pgxpool/pool.go"
        click StmtCache "https://github.com/jackc/pgx/blob/master/internal/stmtcache/stmtcache.go"
        click ConnMgmt "https://github.com/jackc/pgx/blob/master/pgconn/pgconn.go"
        click TypeSystem "https://github.com/jackc/pgx/blob/master/pgtype/pgtype.go"
    end

    subgraph "Protocol Layer"
        Proto["Protocol Handler"]:::protocol
        click Proto "https://github.com/jackc/pgx/blob/master/pgproto3/frontend.go"
    end

    subgraph "Special Features"
        ListenNotify["LISTEN/NOTIFY"]:::feature
        CopyProto["COPY Protocol"]:::feature
        LargeObj["Large Objects"]:::feature
        BinaryFmt["Binary Format"]:::feature
        click CopyProto "https://github.com/jackc/pgx/blob/master/copy_from.go"
        click LargeObj "https://github.com/jackc/pgx/blob/master/large_objects.go"
    end

    subgraph "Cross-Cutting Concerns"
        Tracing["Tracing System"]:::support
        Logging["Logging System"]:::support
        ErrorHandling["Error Handling"]:::support
        ContextMgmt["Context Management"]:::support
        click Tracing "https://github.com/jackc/pgx/blob/master/tracelog/tracelog.go"
        click Logging "https://github.com/jackc/pgx/blob/master/log/testingadapter/adapter.go"
    end

    PostgreSQL[("PostgreSQL Server")]:::external

    %% Connections
    App --> PgxAPI
    App --> StdLib
    PgxAPI --> ConnPool
    StdLib --> ConnPool
    ConnPool --> ConnMgmt
    ConnPool --> StmtCache
    ConnMgmt --> Proto
    Proto --> PostgreSQL
    TypeSystem --> Proto

    %% Special Features Connections
    Proto --> ListenNotify
    Proto --> CopyProto
    Proto --> LargeObj
    Proto --> BinaryFmt

    %% Cross-Cutting Concerns Connections
    Tracing -.- PgxAPI
    Tracing -.- ConnPool
    Tracing -.- Proto
    Logging -.- PgxAPI
    Logging -.- ConnPool
    ErrorHandling -.- PgxAPI
    ErrorHandling -.- Proto
    ContextMgmt -.- ConnPool
    ContextMgmt -.- Proto

    %% Styling
    classDef core fill:#2374ab
    classDef adapter fill:#ffd700
    classDef protocol fill:#34a853
    classDef storage fill:#4285f4
    classDef feature fill:#fbbc05
    classDef support fill:#95c8d8
    classDef external fill:#cccccc

    %% Legend
    subgraph Legend
        CoreComp["Core Component"]:::core
        AdapterComp["Adapter"]:::adapter
        ProtocolComp["Protocol"]:::protocol
        StorageComp["Storage"]:::storage
        FeatureComp["Feature"]:::feature
        SupportComp["Support"]:::support
        ExternalComp["External System"]:::external
    end
```
