# ajmaidak/ruby-pg architecture

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

- Interactive diagram: https://gitdiagram.com/ajmaidak/ruby-pg
- Repository: https://github.com/ajmaidak/ruby-pg

## Overview

##### Main Components

a. Core Components:
- Native Extension Layer (ext/)
- Ruby Interface Layer (lib/)
- PostgreSQL Database Connection
- Type System Components
- Thread/Fiber Management

b. Supporting Components:
- Test Framework
- Build System
- Documentation System

**┌─────────────────────────────────────────────────────────┐**
- Ruby Application                        │
- ┬─────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- ruby-pg Gem                         │
- ┌────────────────┐    ┌────────────────┐              │
- Ruby Layer   │    │  Native Layer  │              │
- (lib/pg)     │←──→│    (ext/)     │              │
- ┘    └────────────────┘              │
- ↓                     ↓                        │
- ┌────────────────────────────────────────┐            │
- Type System                   │            │
- ┌─────────────┐      ┌─────────────┐  │            │
- Encoders   │      │  Decoders   │  │            │
- ┘      └─────────────┘  │            │
- ┌─────────────────────────────────┐   │            │
- Type Maps               │   │            │
- ┘   │            │
- ┘            │
- ┬─────────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- libpq (PostgreSQL C API)               │
- ┬─────────────────────────────┘
- ↓
**┌─────────────────────────────────────────────────────────┐**
- PostgreSQL Database                     │
- ┘

##### Component Details

a. Ruby Layer (lib/pg):
- High-level Ruby interfaces
- Connection management
- Result handling
- Async operation support

b. Native Extension Layer (ext/):
- C extension components
- GVL (Global VM Lock) handling
- Connection management
- Type casting implementation

c. Type System:
- Both text and binary encoders/decoders
- Type map hierarchy
- Supported data types
- Conversion flow

##### Important Interactions to Highlight

- Thread safety boundaries
- Fiber scheduler integration
- Ractor compatibility
- Asynchronous operations
- Type conversion paths

##### Additional Elements

- Notes about thread safety
- Fiber scheduler integration points
- Ractor boundaries
- Type conversion paths
- Async operation flows

##### Implementation Details to Consider

- How the GVL is managed
- Where type casting occurs
- Connection pooling boundaries
- Thread-safe boundaries
- Error handling paths

- The clear separation between Ruby and C layers
- The sophisticated type system
- Thread and Fiber safety mechanisms
- The asynchronous operation capability
- Integration with PostgreSQL's libpq

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Application
        RubyApp["Ruby Application"]
    end

    subgraph RubyPG["ruby-pg Gem"]
        subgraph RubyLayer["Ruby Interface Layer"]
            MainInterface["Main Interface"]:::ruby
            ConnHandler["Connection Handler"]:::ruby
            ResultHandler["Result Handler"]:::ruby
            ExceptionHandler["Exception Handler"]:::ruby
        end

        subgraph NativeLayer["Native Extension Layer"]
            CoreExt["Core Extension"]:::native
            GVLMgmt["GVL Management"]:::native
            NativeConn["Native Connection"]:::native
            NativeResult["Native Result"]:::native
            ErrorImpl["Error Implementation"]:::native
        end

        subgraph TypeSystem["Type System"]
            subgraph Encoders
                BinEnc["Binary Encoders"]:::type
                TextEnc["Text Encoders"]:::type
            end
            
            subgraph Decoders
                BinDec["Binary Decoders"]:::type
                TextDec["Text Decoders"]:::type
            end
            
            subgraph TypeMaps["Type Mapping System"]
                BaseTypeMap["Base Type Map"]:::type
                ByColumn["By Column Map"]:::type
                ByClass["By Class Map"]:::type
                ByOid["By OID Map"]:::type
                ByMriType["By MRI Type Map"]:::type
            end
        end
    end

    subgraph PostgreSQL
        LibPQ["libpq (PostgreSQL C API)"]:::postgres
        PGDatabase["PostgreSQL Database"]:::postgres
    end

    %% Connections
    RubyApp --> MainInterface
    MainInterface --> ConnHandler
    MainInterface --> ResultHandler
    MainInterface --> ExceptionHandler
    
    ConnHandler --> NativeConn
    ResultHandler --> NativeResult
    ExceptionHandler --> ErrorImpl
    
    NativeConn --> LibPQ
    NativeResult --> LibPQ
    LibPQ --> PGDatabase
    
    CoreExt --> GVLMgmt
    
    %% Type System Connections
    ConnHandler --> TypeSystem
    ResultHandler --> TypeSystem
    TypeSystem --> LibPQ

    %% Click Events
    click MainInterface "https://github.com/ajmaidak/ruby-pg/blob/master/lib/pg.rb"
    click ConnHandler "https://github.com/ajmaidak/ruby-pg/blob/master/lib/pg/connection.rb"
    click ResultHandler "https://github.com/ajmaidak/ruby-pg/blob/master/lib/pg/result.rb"
    click ExceptionHandler "https://github.com/ajmaidak/ruby-pg/blob/master/lib/pg/exceptions.rb"
    click CoreExt "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg.c"
    click GVLMgmt "https://github.com/ajmaidak/ruby-pg/blob/master/ext/gvl_wrappers.c"
    click NativeConn "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_connection.c"
    click NativeResult "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_result.c"
    click ErrorImpl "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_errors.c"
    click BinEnc "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_binary_encoder.c"
    click TextEnc "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_text_encoder.c"
    click BinDec "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_binary_decoder.c"
    click TextDec "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_text_decoder.c"
    click BaseTypeMap "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_type_map.c"
    click ByColumn "https://github.com/ajmaidak/ruby-pg/blob/master/lib/pg/type_map_by_column.rb"
    click ByClass "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_type_map_by_class.c"
    click ByOid "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_type_map_by_oid.c"
    click ByMriType "https://github.com/ajmaidak/ruby-pg/blob/master/ext/pg_type_map_by_mri_type.c"

    %% Styles
    classDef ruby fill:#6b8e23,stroke:#333,stroke-width:2px;
    classDef native fill:#4169e1,stroke:#333,stroke-width:2px;
    classDef type fill:#ffa500,stroke:#333,stroke-width:2px;
    classDef postgres fill:#663399,stroke:#333,stroke-width:2px;
    
    %% Legend
    subgraph Legend
        Ruby["Ruby Components"]:::ruby
        Native["Native Components"]:::native
        Type["Type System Components"]:::type
        PG["PostgreSQL Components"]:::postgres
    end
```
