# fastify/fastify-postgres architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Fastify plugin (@fastify/postgres) that integrates PostgreSQL connection pooling into a Fastify server.
- It wraps the node-postgres (pg) library, exposes methods (connect, query, transact, Client, pool) on the Fastify instance, and manages lifecycle hooks (preHandler, onError, onSend).

##### File structure
- Top-level:
- index.js / index.d.ts – plugin entry point (register function, option parsing).
- lib/add-handler.js – code that injects connect/query/transact handlers and hooks into Fastify.
- examples/ – sample TypeScript apps demonstrating single-DB, multi-DB, transactions.
- test/ and test-types/ – JavaScript and TypeScript test suites.
- ci_scripts/ – build & install scripts for CI.
- Pattern: a single module exporting a Fastify plugin. It follows Fastify’s plugin architecture, uses hooks to manage transactions.

##### README for additional insights
- Describes plugin features (connect, query, transact, named connections, native option, custom pg module).
- Explains how the plugin attaches to Fastify, and how it uses Fastify’s lifecycle hooks to manage transactions.

##### Detail
- Every decoration (`fastify.pg`, `fastify.pg.foo`) and lifecycle hook.
- Utility methods (connect, query, transact) and their internal flows (acquire/release, commit/rollback).
- How custom pg module or pg-native option replaces the default pg library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Fastify Layer"
        FS["Fastify Server"]:::fastify
        RH["Route Handler"]:::fastify
    end

    subgraph "Plugin Module"
        IDX["index.js"]:::plugin
        DTS["index.d.ts"]:::plugin
        AH["lib/add-handler.js"]:::plugin
    end

    subgraph "Database Layer"
        POOL["Connection Pool"]:::db
        CLIENT["Client Instance"]:::db
        DB["PostgreSQL DB"]:::db
    end

    subgraph "Optional Extensions"
        NAT["pg-native / custom pg"]:::optional
    end

    FS -->|"register(plugin, options)"| IDX
    IDX --> AH
    AH --> FS
    FS --> RH
    RH -->|"calls fastify.pg.connect() / query() / transact()"| AH
    AH --> POOL
    POOL --> CLIENT
    CLIENT --> DB
    DB --> CLIENT
    CLIENT -->|"return results"| RH

    RH -->|"preHandler hook"| AH
    AH -->|"begin transaction"| CLIENT
    RH -->|"onError hook"| AH
    AH -->|"rollback"| CLIENT
    RH -->|"onSend hook"| AH
    AH -->|"commit"| CLIENT

    AH -.-> NAT

    subgraph "Examples"
        E1["examples/typescript/single-db/app.ts"]:::examples
        E2["examples/typescript/multiple-db/app.ts"]:::examples
        E3["examples/typescript/transactions/app.ts"]:::examples
    end
    subgraph "Tests & CI"
        TJS["test/"]:::tests
        TTS["test-types/"]:::tests
        CI["ci_scripts/"]:::tests
    end

    E1 --> FS
    E2 --> FS
    E3 --> FS
    TJS --> IDX
    TTS --> DTS
    CI -->|"build/install"| IDX

    PM["package.json"]:::meta
    RD["README.md"]:::meta
    FS --> PM
    FS --> RD

    click IDX "https://github.com/fastify/fastify-postgres/blob/main/index.js"
    click DTS "https://github.com/fastify/fastify-postgres/blob/main/index.d.ts"
    click AH "https://github.com/fastify/fastify-postgres/blob/main/lib/add-handler.js"
    click E1 "https://github.com/fastify/fastify-postgres/blob/main/examples/typescript/single-db/app.ts"
    click E2 "https://github.com/fastify/fastify-postgres/blob/main/examples/typescript/multiple-db/app.ts"
    click E3 "https://github.com/fastify/fastify-postgres/blob/main/examples/typescript/transactions/app.ts"
    click TJS "https://github.com/fastify/fastify-postgres/tree/main/test/"
    click TTS "https://github.com/fastify/fastify-postgres/tree/main/test-types/"
    click CI "https://github.com/fastify/fastify-postgres/tree/main/ci_scripts/"
    click PM "https://github.com/fastify/fastify-postgres/blob/main/package.json"
    click RD "https://github.com/fastify/fastify-postgres/blob/main/README.md"

    classDef fastify fill:#cce5ff,stroke:#004085,color:#004085
    classDef plugin fill:#b8daff,stroke:#004085,color:#004085
    classDef db fill:#d4edda,stroke:#155724,color:#155724
    classDef optional fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-dasharray:5 5
    classDef examples fill:#fff3cd,stroke:#856404,color:#856404
    classDef tests fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef meta fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
