pgproxy/
├── app/
│   ├── main.go              # Main application entry point
│   ├── config/
│   │   └── config.go        # Configuration loading and parsing
│   ├── proxy/
│   │   └── proxy.go         # Main proxy logic
│   └── utils/
│       └── env.go           # Environment variable utilities
├── config.yaml              # Configuration file
├── go.mod                   # Go module definition
└── README.md                # This file

Configuration

The proxy is configured via a YAML configuration file (config.yaml):

# Listen address and port
listen:
  address: "0.0.0.0"
  port: 5400

debug: true # Set to true to enable debug logging

# Hostname mappings
# External hostname -> Internal hostname and port
mappings:
  - external: "host1.example.com"
    internal: "host1.example.internal"
    port: 5432  # Optional, defaults to 5432 if not specified
  - external: "host2.example.com"
    internal: "host2.example.internal"
    port: 5432  # Optional, defaults to 5432 if not specified

Environment Variables

CONFIG_PATH: Path to the configuration file. Defaults to config.yaml if not set.

Usage

Configure the config.yaml file with your hostname mappings
Install dependencies: go mod tidy
Run the proxy: go run cmd/pgproxy/main.go [config.yaml]
- If no config file is specified, it defaults to config.yaml in the current directory

Example

All DNS records are pointing to this service.

postgres://user:password@host1.example.com:5400/database -> postgres://user:password@host1.example.internal:5432/database
postgres://user:password@host2.example.com:5400/database -> postgres://user:password@host2.example.internal:5432/database

How it works

The proxy extracts the hostname from incoming connections using TLS SNI (Server Name Indication) for TLS-encrypted connections. For non-TLS connections, if only one mapping is configured, it uses that as the default backend. It then maps the external hostname to the internal hostname according to the configuration and forwards the connection to the appropriate backend PostgreSQL server.

Roadmap

Short-term (Next Release)

Connection Pooling: Implement connection pooling to backend PostgreSQL servers for better performance and resource management
Health Checks: Add health check endpoints and periodic backend server health monitoring
Metrics & Observability: Integrate Prometheus metrics for connection counts, latency, error rates, and throughput
Graceful Shutdown: Implement graceful shutdown handling to allow in-flight connections to complete before termination
Configuration Validation: Add comprehensive validation for configuration files with clear error messages

Medium-term (Future Releases)

Load Balancing: Support multiple backend servers per hostname with round-robin, least-connections, or weighted load balancing
TLS Termination: Add support for TLS termination at the proxy level with configurable certificates per hostname
Connection Limits: Implement per-hostname and global connection limits with configurable thresholds
Request/Response Logging: Add optional detailed logging of PostgreSQL protocol messages for debugging
Rate Limiting: Implement rate limiting per client IP or hostname to prevent abuse
Authentication Proxy: Support for PostgreSQL authentication passthrough with optional credential mapping
Dynamic Configuration: Support for hot-reloading configuration without service restart

Long-term (Future Considerations)

High Availability: Support for active-passive or active-active proxy clustering
Query Routing: Advanced query routing based on database name, user, or query patterns
Connection Multiplexing: Implement connection multiplexing to reduce backend connections
Audit Logging: Comprehensive audit logging for compliance and security monitoring
Web Dashboard: Web-based management interface for monitoring and configuration
REST API: RESTful API for configuration management and monitoring
Plugin System: Extensible plugin system for custom routing and filtering logic