vlbsio/keel repository overview

⁠KEEL — Database Connection Pooler & Proxy

KEEL is a correctness-first PostgreSQL connection pooler and intelligent database proxy. Its production candidate profile is conservative PostgreSQL transaction pooling with prepared-statement virtualization. Broader routing, MySQL, sharding, and cluster features exist, but are labelled by maturity and should be enabled deliberately.

⁠Why KEEL?

⁠Available Images

All images are multi-arch: linux/amd64 and linux/arm64.

Production deployments should pin an immutable release tag or digest.

⁠Quick Start

⁠Minimal PostgreSQL pool (replacing PgBouncer)

docker run -d \
  -e KEEL_SERVER_HOST=your-postgres-host \
  -e KEEL_SERVER_PORT=5432 \
  -e KEEL_SERVER_USER=app \
  -e KEEL_SERVER_PASSWORD=secret \
  -e KEEL_SERVER_DATABASE=mydb \
  -p 7432:7432 \
  vlbsio/keel:<release-tag>

Then connect your app to localhost:7432 exactly as you would connect to PostgreSQL directly.

⁠With a config file

docker run -d \
  -v /path/to/keel.ini:/etc/keel/keel.ini \
  -p 7432:7432 \
  vlbsio/keel:<release-tag>

⁠Docker Compose

services:
  keel:
    image: vlbsio/keel:<release-tag>
    ports:
      - "7432:7432"   # PostgreSQL proxy
      - "9101:9101"   # Prometheus metrics
    volumes:
      - ./keel.ini:/etc/keel/keel.ini
    restart: unless-stopped

⁠Feature Readiness

KEEL has a broad feature surface. Features are labelled by production maturity. The canonical maturity matrix lives in docs/PRODUCTION_READINESS.md⁠; the summary below mirrors it.

⁠Production candidate

These are the supported production candidate capabilities when configured conservatively and validated against your workload.

⁠🔶 Hardening (works, needs validation in your environment)

These features are implemented and tested but the full failure-mode surface is still being hardened. Enable deliberately with monitoring.

⁠🧪 Experimental (opt-in, not production defaults)

These require experimental_features = true in config. Use in non-critical environments or staging only.

⁠Database & Platform Support

The supported PostgreSQL version list and database maturity notes live in docs/COMPATIBILITY.md⁠. PostgreSQL is the production candidate baseline; MySQL, MariaDB, and Percona topologies are in the Hardening bucket.

⁠Cloud databases

No password rotation scripts needed — KEEL handles token generation and caching automatically.

⁠Linux kernel requirements

⁠Security Hardening

KEEL supports defense-in-depth controls:

• Seccomp BPF filter — allowlist-only syscall policy (baseline or strict mode), opt-in by config
• Privilege drop — drops to unprivileged user after binding ports, opt-in by config
• mTLS — optional client certificate verification with CN/SAN identity extraction
• LDAP / PAM integration — enterprise authentication via ldap_bind() or pam_authenticate()
• Structured audit log — NDJSON audit trail for auth, admin, query, and pool events; filterable by event type
• Cipher enforcement — configurable TLS 1.2/1.3 cipher suites and minimum version
• Certificate hot-reload — SIGHUP triggers atomic TLS context swap without dropping connections
• Known limits surfaced — review docs/LIMITATIONS.md before enabling Hardening or Experimental features

⁠Configuration Example

[keel]
log_level = info

[worker_group.myapp]
protocol          = postgresql
bind_addr         = 0.0.0.0
bind_port         = 7432
num_workers       = 4
mode              = pool
prepared_statement = virtualize     # transparent PS replay for ORMs
min_pool_size     = 10
max_pool_size     = 100
auth_method       = scram-sha-256

[worker_group.myapp.servers]
primary  = host=db1.internal port=5432 dbname=myapp user=app password=secret role=RW weight=100

For the full configuration reference, see docs/DOCKER.md⁠.

⁠Exposed Ports

⁠Environment Variables

Common overrides for container deployments (no config file required for simple setups):

KEEL_LOG_LEVEL=2              # 0=trace … 5=fatal
KEEL_SERVER_HOST=db.internal
KEEL_SERVER_PORT=5432
KEEL_SERVER_USER=app
KEEL_SERVER_PASSWORD=secret
KEEL_SERVER_DATABASE=mydb
KEEL_POOL_MIN=10
KEEL_POOL_MAX=100
KEEL_BIND_PORT=7432

⁠Documentation

⁠Kubernetes

KEEL ships a Helm chart and a Kubernetes operator:

helm install keel oci://ghcr.io/virtlabs-io/helm/keel \
  --set config.server.host=postgres-primary.default.svc \
  --set config.server.password=secret \
  --set monitoring.enabled=true

The operator (KeelPool CRD) handles pool lifecycle, config reconciliation, and HPA integration via the pool_wait_queue_enqueued metric.

⁠License

AGPL-3.0 — free to use, modify, and distribute. Network use (SaaS) requires source disclosure.
See LICENSE⁠ for details.

KEEL — the missing link between your application and a truly elastic database.