# 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:
```bash
git clone https://github.com/yourusername/postgres-handholder.git
cd postgres-handholder
```

2. Set up the environment:
```bash
# Copy environment file
cp .env.example .env

# Edit environment variables
nano .env
```

3. Start the application with Docker Compose:
```bash
docker-compose up -d
```

4. Run database migrations:
```bash
docker-compose exec web python manage.py migrate
```

5. Create a superuser:
```bash
docker-compose exec web python manage.py createsuperuser
```

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

### Development Setup

1. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Set up the database:
```bash
# Create PostgreSQL database
createdb postgres_handholder

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser
```

4. Start the development server:
```bash
python manage.py runserver
```

## Configuration

### Environment Variables

Create a `.env` file with the following variables:

```env
# 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](LICENSE) file for details.

## Support

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