cleanstart/pgbouncer repository overview

CleanStart Container for PgBouncer

PgBouncer is a lightweight connection pooler for PostgreSQL databases. This container provides a production-ready PgBouncer instance with enhanced security features and enterprise-grade configuration. It manages PostgreSQL database connections efficiently by maintaining a pool of connections and providing connection pooling, connection limiting, and query caching capabilities. The container includes built-in monitoring, metrics exposure, and advanced connection management features optimized for high-throughput database environments.

📌 CleanStart Foundation: Security-hardened, minimal base OS designed for enterprise containerized environments.

Key Features

• Advanced connection pooling for PostgreSQL databases
• Query caching and connection load balancing
• Session-based and transaction-based pooling modes
• Built-in monitoring and metrics exposure

Common Use Cases

• High-performance database connection management
• Database connection pooling for microservices architectures
• Resource optimization for PostgreSQL deployments
• Scale PostgreSQL connections in cloud environments

Quick Start

Pull Latest Image Download the container image from the registry

docker pull cleanstart/pgbouncer:latest
docker pull cleanstart/pgbouncer:latest-dev

Basic Run Run the container with basic configuration

docker run -d --name pgbouncer -p 6432:6432 cleanstart/pgbouncer:latest

Production Deployment Deploy with production security settings

docker run -d --name pgbouncer-prod \
  --read-only \
  --security-opt=no-new-privileges \
  --user 1000:1000 \
  -p 6432:6432 \
  -v pgbouncer-config:/etc/pgbouncer \
  cleanstart/pgbouncer:latest

Port Forwarding Run with custom port mappings

docker run -p 6432:6432 cleanstart/pgbouncer:latest

Configuration

Environment Variables

Security & Best Practices

Recommended Security Context

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  runAsGroup: 1000
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop: ['ALL']

Best Practices

• Use specific image tags for production (avoid latest)
• Configure resource limits: memory and CPU constraints
• Enable read-only root filesystem when possible
• Run containers with non-root user (--user 1000:1000)
• Use --security-opt=no-new-privileges flag
• Regularly update container images for security patches
• Implement proper network segmentation
• Monitor container metrics for anomalies

Architecture Support

Multi-Platform Images

docker pull --platform linux/amd64 cleanstart/pgbouncer:latest
docker pull --platform linux/arm64 cleanstart/pgbouncer:latest

• CleanStart Website: https://www.cleanstart.com⁠
• PgBouncer Documentation: https://www.pgbouncer.org/usage.html⁠
• CleanStart Community Images: https://hub.docker.com/u/cleanstart⁠
• CleanStart All Images: https://images.cleanstart.com/images/pgbouncer/details⁠
• How-to-Run CleanStart Images & Sample Projects: https://github.com/cleanstart-containers/pgbouncer⁠,
  • how-to-Run sample projects using dockerfile
  • how-to-Deploy via Kubernete YAML
  • how-to-Migrate from public images to CleanStart images

⁠Vulnerability Disclaimer

CleanStart offers Docker images that include third-party open-source libraries and packages maintained by independent contributors. While CleanStart maintains these images and applies industry-standard security practices, it cannot guarantee the security or integrity of upstream components beyond its control.

Users acknowledge and agree that open-source software may contain undiscovered vulnerabilities or introduce new risks through updates. CleanStart shall not be liable for security issues originating from third-party libraries, including but not limited to zero-day exploits, supply chain attacks, or contributor-introduced risks.

Security remains a shared responsibility: CleanStart provides updated images and guidance where possible, while users are responsible for evaluating deployments and implementing appropriate controls.