postgres-handholder

Django application to manage Postgres clusters, including rolling updates, connection pooling, and more.

Overview

Postgres hand-holder is a Django application designed to simplify the management of Postgres clusters in Docker and local Linux environments. It provides a user-friendly interface for performing various operations on Postgres databases, such as rolling updates, connection pooling, and backup management.

postgres-handholder will automate the creation and management of Postgres clusters, making it easier for developers and startups to deploy and maintain their database infrastructure. It is particularly useful for those who want to manage Postgres clusters without the complexity of traditional database management systems.

Features

• Rolling updates on Postgres cluster changes, incl. quick minor version updates
• Database connection pooling with PGBouncer
• Support fast in place major version upgrade. Supports global upgrade of all clusters.
• Restore and cloning Postgres clusters on demand
• Additionally logical backups to S3 or GCS bucket can be configured
• Standby cluster from S3 or GCS WAL archive
• Configurable for non-cloud environments
• Basic credential and user management on Django interface, eases application deployments
• Support for custom TLS certificates
• UI to create and edit Postgres cluster configurations
• Supports PostgreSQL 17, starting from 13+
• Add easy way to preload libraries: bg_mon, pg_stat_statements, pgextwlist, pg_auth_mon
• Add easy way to include popular Postgres extensions such as decoderbufs, hypopg, pg_cron, pg_partman, pg_stat_kcache, pgq, pgvector, plpgsql_check, postgis, set_user and timescaledb

Quick Start

Prerequisites

• Python 3.11+
• Docker and Docker Compose
• PostgreSQL 13+ (for the Django app database)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/postgres-handholder.git
cd postgres-handholder

2. Set up the environment:

# Copy environment file
cp .env.example .env

# Edit environment variables
nano .env

3. Start the application with Docker Compose:

docker-compose up -d

4. Run database migrations:

docker-compose exec web python manage.py migrate

5. Create a superuser:

docker-compose exec web python manage.py createsuperuser

6. Access the application at http://localhost:8000

Development Setup

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Set up the database:

# Create PostgreSQL database
createdb postgres_handholder

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

4. Start the development server:

python manage.py runserver

Configuration

Environment Variables

Create a .env file with the following variables:

# Django
DEBUG=True
SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DB_NAME=postgres_handholder
DB_USER=postgres
DB_PASSWORD=your-password
DB_HOST=localhost
DB_PORT=5432

# Celery
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# Cloud Storage (optional)
AWS_ACCESS_KEY_ID=your-aws-key
AWS_SECRET_ACCESS_KEY=your-aws-secret
AWS_STORAGE_BUCKET_NAME=your-bucket
AWS_S3_REGION_NAME=us-east-1

GOOGLE_CLOUD_STORAGE_BUCKET=your-gcs-bucket
GOOGLE_APPLICATION_CREDENTIALS=path/to/credentials.json

Usage

Creating a Cluster

1. Navigate to the Clusters section
2. Click "Create Cluster"
3. Fill in the configuration details:
   • Cluster name and description
   • PostgreSQL version (13-17)
   • Deployment type (Docker, Kubernetes, Local)
   • Resource limits (CPU, Memory, Storage)
   • Network configuration
   • Extensions and libraries

Managing Clusters

• Start/Stop: Control cluster lifecycle
• Update: Perform rolling updates
• Monitor: View real-time metrics and logs
• Backup: Create and manage backups
• Users: Manage database users and permissions
• Databases: Create and manage databases

Backup Management

• Create automated backups
• Store backups in S3 or Google Cloud Storage
• Restore clusters from backups
• Clone clusters for testing

Architecture

The application is built with:

• Django 4.2+: Web framework
• PostgreSQL: Primary database
• Redis: Message broker for Celery
• Celery: Background task processing
• Docker: Containerization
• Bootstrap 5: UI framework

Apps Structure

• clusters/: Core cluster management
• backups/: Backup and restore functionality
• monitoring/: Metrics and monitoring

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Support

For support and questions, please open an issue on GitHub.