How ajmaidak/ruby-pg works
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