PostgreSQL Playground (pgpg)

A production-ready Docker Compose environment for PostgreSQL development, learning, and experimentation. This setup provides a complete, isolated PostgreSQL environment with pgAdmin web interface, featuring automatic configuration and zero manual setup steps.

Table of Contents

• Overview
• Features
• Quick Start
• Documentation
• Contributing
• License

Overview

PostgreSQL Playground (pgpg) is a containerized development environment that provides:

• PostgreSQL Database Server: Latest stable PostgreSQL running on Alpine Linux for minimal resource footprint
• pgAdmin Web Interface: Industry-standard PostgreSQL administration and development platform
• Automated Configuration: Zero-configuration setup with automatic server registration and passwordless authentication
• Persistent Storage: All data stored in Docker volumes, isolated from your local filesystem
• Health Monitoring: Built-in health checks ensure services are ready before dependencies start

This environment is ideal for:

• Learning PostgreSQL and SQL
• Developing and testing database applications
• Experimenting with PostgreSQL features
• Prototyping database schemas
• Local development without installing PostgreSQL directly

Features

• PostgreSQL (Alpine-based): Latest stable PostgreSQL with minimal image size
• pgAdmin Web UI: Full-featured web-based administration interface
• Automatic Server Registration: PostgreSQL connection automatically configured in pgAdmin
• Passwordless Authentication: Pre-configured .pgpass file enables seamless connections
• One-Command Setup: Start all services with a single command; waits until fully ready
• Persistent Data: All database and configuration data persists across container restarts
• Clean Filesystem: No local filesystem pollution; all data in Docker volumes
• Health Checks: Services wait for dependencies to be healthy before starting
• Fully Configurable: All settings managed via .env file with sensible defaults

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Ports 5432 (PostgreSQL) and 5050 (pgAdmin) available (or configure custom ports)

Step 1: Review Environment Configuration (Optional)

The .env file is pre-configured with sensible defaults and is ready to use. You may want to:

• Review the configuration: Open .env to see all documented variables
• Change default passwords: Especially if this will be accessible to others
• Adjust ports: If ports 5432 or 5050 are already in use on your system

The .env file contains comprehensive inline documentation explaining each variable, its purpose, default values, and usage notes.

Security Note: The .env file contains sensitive credentials. Change default passwords before using in shared environments.

Step 2: Start Services

Start all services and wait for them to be ready:

make start

This command:

• Generates pgAdmin configuration files from your .env file
• Sets up the PostgreSQL server connection automatically
• Configures passwordless authentication
• Waits until all services are fully initialized and healthy
• Attempts to open pgAdmin in your default browser automatically

Step 3: Access pgAdmin

1. Open http://localhost:5050 (or your custom PGADMIN_PORT from .env) in your browser
2. Log in with your credentials:
   • Email: pgadmin4@pgadmin.org (or your PGADMIN_USER)
   • Password: admin (or your PGADMIN_PASSWORD)
3. The PostgreSQL server is already configured and appears in the server list
4. Click on the server to connect — no password prompt required!

Documentation

• Usage - Using pgAdmin, psql, and external clients
• Configuration - Environment variables and setup
• Data Persistence - Data storage and volume management
• Architecture - System architecture and services
• Operations - Managing the environment and troubleshooting

Contributing

For information about the project structure and development setup, including pre-commit hooks configuration, see CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.