# brianc/node-postgres architecture

> Architecture diagram of the GitHub repository brianc/node-postgres, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brianc/node-postgres
- Repository: https://github.com/brianc/node-postgres

## Overview

##### Main Components

a. Core Components:
- pg (main client package)
- pg-pool (connection pooling)
- pg-native (native libpq bindings)
- pg-protocol (communication protocol)
- Application Layer (user code)
- PostgreSQL Database

b. Supporting Components:
- pg-cursor (cursor functionality)
- pg-query-stream (streaming interface)
- pg-connection-string (connection string parsing)

**[Application Layer]**
- ↓
**[node-postgres Core]**
- ↙     ↓     ↘
**[Pools] [Protocol] [Native Bindings]**
- ↓
**[PostgreSQL Database]**

##### Component Relationships

- Application → pg (main client)
- pg → pg-pool (connection management)
- pg → pg-protocol (data communication)
- pg → pg-native (optional native bindings)
- All components → PostgreSQL Database

##### Special Features to Highlight

- Connection pooling mechanisms
- Query execution paths (JavaScript vs. Native)
- Data type coercion system
- COPY operations
- LISTEN/NOTIFY support

##### Implementation Details

For each major component, include:
- Input/Output interfaces
- Key methods and operations
- Data flow direction
- Connection states

##### Additional Elements

Annotations for:
- SSL/TLS connections
- Query parsing and planning
- Result handling
- Error management
- Connection lifecycle

##### Notes for Implementation

- The dual nature of pure JavaScript and native bindings
- The connection pooling architecture
- The protocol implementation
- The extensible type system
- The async/non-blocking nature of operations

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Application
        AppCode[Application Code]
    end

    subgraph Core["Core Components"]
        Client["Main Client"]:::core
        Pool["Connection Pool"]:::core
        Native["Native Bindings"]:::native
        Protocol["Protocol Layer"]:::protocol
    end

    subgraph Features["Supporting Features"]
        Cursor["Cursor"]:::utility
        QueryStream["Query Stream"]:::utility
        ConnString["Connection String Parser"]:::utility
    end

    subgraph Implementation["Implementation Layer"]
        Query["Query Handler"]:::impl
        Result["Result Handler"]:::impl
        TypeSystem["Type System"]:::impl
        ConnMgmt["Connection Manager"]:::impl
        SASL["SASL Auth"]:::impl
        Config["Configuration"]:::impl
    end

    DB[(PostgreSQL Database)]:::database

    %% Connections
    AppCode --> Client
    Client --> Pool
    Client --> Protocol
    Client --> Native
    Pool --> Protocol
    Protocol --> DB
    Native --> DB
    
    %% Feature connections
    Client --> Cursor
    Client --> QueryStream
    Client --> ConnString
    
    %% Implementation connections
    Client --> Query
    Client --> Result
    Client --> TypeSystem
    Client --> ConnMgmt
    ConnMgmt --> SASL
    Client --> Config

    %% Click events
    click Client "https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/client.js"
    click Pool "https://github.com/brianc/node-postgres/blob/master/packages/pg-pool/index.js"
    click Native "https://github.com/brianc/node-postgres/tree/master/packages/pg-native/lib"
    click Protocol "https://github.com/brianc/node-postgres/tree/master/packages/pg-protocol/src"
    click ConnString "https://github.com/brianc/node-postgres/blob/master/packages/pg-connection-string/index.js"
    click Cursor "https://github.com/brianc/node-postgres/blob/master/packages/pg-cursor/index.js"
    click QueryStream "https://github.com/brianc/node-postgres/blob/master/packages/pg-query-stream/src/index.ts"
    click Query "https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/query.js"
    click Result "https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/result.js"
    click TypeSystem "https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/type-overrides.js"
    click ConnMgmt "https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/connection.js"
    click SASL "https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/crypto/sasl.js"
    click Config "https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/defaults.js"

    %% Styling
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef protocol fill:#4CAF50,stroke:#2E7D32,color:white
    classDef native fill:#FF9800,stroke:#EF6C00,color:white
    classDef utility fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef database fill:#607D8B,stroke:#37474F,color:white
    classDef impl fill:#795548,stroke:#3E2723,color:white

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Protocol Layer"]:::protocol
        L3["Native Bindings"]:::native
        L4["Utility Modules"]:::utility
        L5["Implementation"]:::impl
        L6[(Database)]:::database
    end
```
