GERYON
Three Bodies. One Proxy. Every Connection.

A high-performance, multi-database connection pooler and proxy built in pure Go. Named after the three-bodied giant of Greek mythology, Geryon speaks PostgreSQL, MySQL, and MSSQL wire protocols — all from a single static binary.

Running PostgreSQL, MySQL, and MSSQL? Today you need separate tools for each:

Three tools. Three configs. Three monitoring setups. Three failure modes.

Geryon replaces all of them with one binary.

• Prepared Statement Cache — Transparent re-preparation across pooled connections with LRU eviction
• Query Result Cache — In-memory LRU cache with TTL, write invalidation, and per-pattern rules
• Connection Prefetching — Proactively maintains min_server_connections idle connections for low-latency startup
• Read/Write Splitting — Route SELECTs to replicas, writes to primary, transaction-aware
• Auth Interception — Manage proxy users, map N clients to M backend credentials
• TLS/mTLS — Full TLS termination with mutual TLS client certificate validation
• Hot Reload — Config changes via YAML watch, SIGHUP, or API — zero downtime

• Raft Consensus — Configuration replication and leader election across nodes
• SWIM Gossip — Node discovery, failure detection, metadata dissemination
• Backend Health Sharing — Avoid thundering herd on failover

# Download latest release
curl -sSL https://github.com/GeryonProxy/geryon/releases/latest/download/geryon-linux-amd64 -o geryon
chmod +x geryon

# Generate example config
./geryon --generate-config > geryon.yaml

# Edit config (set your database backends)
vim geryon.yaml

# Start
./geryon --config geryon.yaml

docker run -d \
  --name geryon \
  -p 5432:5432 \
  -p 3306:3306 \
  -p 1433:1433 \
  -p 8080:8080 \
  -v ./geryon.yaml:/etc/geryon/geryon.yaml \
  ghcr.io/geryonproxy/geryon:latest

services:
  geryon:
    image: ghcr.io/geryonproxy/geryon:latest
    ports:
      - "5432:5432"   # PostgreSQL
      - "3306:3306"   # MySQL
      - "1433:1433"   # MSSQL
      - "8080:8080"   # Dashboard + REST API
    volumes:
      - ./geryon.yaml:/etc/geryon/geryon.yaml
    restart: unless-stopped

git clone https://github.com/GeryonProxy/geryon.git
cd geryon
make build
# Binary at bin/geryon

pools:
  - name: "my-postgres"
    body: postgresql
    mode: transaction
    listen:
      host: "0.0.0.0"
      port: 5432
    backend:
      hosts:
        - host: "pg.internal"
          port: 5432
      database: "myapp"
      auth:
        username: "postgres"
        password_file: "/etc/geryon/secrets/pg"
    limits:
      max_client_connections: 10000
      max_server_connections: 100

admin:
  rest:
    listen: "0.0.0.0:8080"
  dashboard:
    enabled: true

pools:
  - name: "primary-pg"
    body: postgresql
    mode: transaction
    listen:
      host: "0.0.0.0"
      port: 5432
    backend:
      hosts:
        - host: "pg-primary.internal"
          port: 5432
          role: primary
        - host: "pg-replica.internal"
          port: 5432
          role: replica
      database: "myapp"
      auth:
        method: scram-sha-256
        username: "geryon_pool"
        password_file: "/etc/geryon/secrets/pg-password"
    limits:
      max_client_connections: 10000
      max_server_connections: 100

  - name: "analytics-mysql"
    body: mysql
    mode: session
    listen:
      host: "0.0.0.0"
      port: 3306
    backend:
      hosts:
        - host: "mysql-primary.internal"
          port: 3306
      database: "analytics"
      auth:
        method: caching_sha2_password
        username: "geryon_pool"
        password_file: "/etc/geryon/secrets/mysql-password"

  - name: "reporting-mssql"
    body: mssql
    mode: transaction
    listen:
      host: "0.0.0.0"
      port: 1433
    backend:
      hosts:
        - host: "mssql.internal"
          port: 1433
      database: "reporting"
      auth:
        username: "geryon_pool"
        password_file: "/etc/geryon/secrets/mssql-password"

routing:
  read_write_split: true

admin:
  rest:
    listen: "0.0.0.0:8080"
  dashboard:
    enabled: true
  mcp:
    transport: sse
    listen: "0.0.0.0:8081"

Connect your application to Geryon instead of directly to the database:

# PostgreSQL
psql -h localhost -p 5432 -U app -d myapp

# MySQL
mysql -h 127.0.0.1 -P 3306 -u app -p analytics

# MSSQL
sqlcmd -S localhost,1433 -U app -d reporting

                     ┌─────────────────────────────────────────────────┐
                     │                  GERYON PROXY                    │
                     │                                                 │
  Clients ────────►  │  ┌───────────┐  ┌──────────┐  ┌─────────────┐  │
  (PG/MySQL/TDS)     │  │  BODY I   │  │ BODY II  │  │  BODY III   │  │
                     │  │PostgreSQL │  │  MySQL   │  │    MSSQL    │  │
                     │  │  :5432    │  │  :3306   │  │    :1433    │  │
                     │  └─────┬─────┘  └────┬─────┘  └──────┬──────┘  │
                     │        │             │               │          │
                     │        ▼             ▼               ▼          │
                     │  ┌─────────────────────────────────────────────┐│
                     │  │           UNIFIED POOL MANAGER              ││
                     │  │   Session │ Transaction │ Statement         ││
                     │  │   Prepared Stmt Cache │ Query Result Cache  ││
                     │  └──────────────────┬──────────────────────────┘│
                     │                     │                           │
                     │  ┌──────────────────┴──────────────────────────┐│
                     │  │            BACKEND CONNECTORS               ││
                     │  │  R/W Split │ Health Check │ Failover        ││
                     │  └─────────────────────────────────────────────┘│
                     └─────────────────────────────────────────────────┘

  Cluster:  N1 (Leader) ◄─── Raft + SWIM ───► N2, N3 (Followers)

Access the web dashboard at http://localhost:8080 after starting Geryon:

Built with vanilla HTML/CSS/JS — no npm, no bundler, embedded in the binary via embed.FS.

geryon                           # Start with geryon.yaml in current dir
geryon --config /path/to/config  # Start with specific config
geryon --validate                # Validate config without starting
geryon --version                 # Print version info
geryon --generate-config         # Output example config to stdout
geryon --generate-password       # Generate SCRAM-SHA-256 hash
geryon --generate-cert           # Generate self-signed TLS cert

The REST API provides full management capabilities. Default endpoint: http://localhost:8080

Create Pool Example:

curl -X POST http://localhost:8080/api/v1/pools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-pool",
    "body": "postgresql",
    "mode": "transaction",
    "listen": {"host": "0.0.0.0", "port": 5433},
    "backend": {
      "hosts": [{"host": "db.internal", "port": 5432, "role": "primary"}],
      "database": "myapp"
    },
    "limits": {
      "max_client_connections": 1000,
      "max_server_connections": 100
    }
  }'

Drain Backend Example:

curl -X POST http://localhost:8080/api/v1/backends/db.internal:5432/drain

Add Backend Example:

curl -X POST http://localhost:8080/api/v1/pools/my-postgres/backends \
  -H "Content-Type: application/json" \
  -d '{
    "host": "db-replica.internal",
    "port": 5432,
    "role": "replica",
    "weight": 1,
    "database": "myapp"
  }'

Remove Backend Example:

curl -X DELETE "http://localhost:8080/api/v1/pools/my-postgres/backends?address=db.internal:5432"

SSE Stats Stream:

curl -N http://localhost:8080/api/v1/stats/stream
# Returns: data: {"total_connections":42,"active_pools":3,...}

Geryon includes a built-in MCP server for AI-assisted database management, compatible with Claude Code, Claude Desktop, and other MCP clients.

Tools: geryon_pool_list, geryon_pool_stats, geryon_connection_list, geryon_backend_list, geryon_backend_drain, geryon_backend_detach, geryon_cache_stats, geryon_config_reload, geryon_query_stats, geryon_cluster_status, geryon_user_list

Resources: geryon://config, geryon://pools, geryon://pools/{name}, geryon://stats/overview

#NOFORKANYMORE — Geryon is built with a minimal-dependency philosophy:

• Pure Go — no C code, zero CGo for releases
• Single Binary — one file, runs anywhere Go compiles
• Minimal Dependencies — 3 production deps (yaml.v3, x/term, x/time), 2 test-only deps (lib/pq, go-sql-driver/mysql)
• No Vendor — no supply chain risk, no bloated dependency tree

git clone https://github.com/GeryonProxy/geryon.git
cd geryon
make build    # Build binary
make test     # Run tests
make lint     # Run go vet

Apache 2.0 — See LICENSE for details.

Built by ECOSTACK TECHNOLOGY OÜ

Geryon (Γηρυών) — the three-bodied giant, guardian of the red cattle of Erytheia. Defeating Geryon was the 10th of Heracles' twelve labors — one entity with three bodies, each a formidable force on its own.