194 lines
5.0 KiB
Markdown
194 lines
5.0 KiB
Markdown
# 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.
|