SerpentRace/Documentations/DATABASE_MANAGEMENT_GUIDE.md

🗄️ SerpentRace Database Management Guide

🎯 Overview

This guide provides comprehensive information about managing all database services in the SerpentRace project, including PostgreSQL, Redis, MinIO, and administration tools.

📊 Quick Status Check

Check All Services

npm run db:status

Check Individual Services

npm run db:status:pg      # PostgreSQL only
npm run db:status:redis   # Redis only
npm run db:status:docker  # Docker containers only

Simple Connection Test

npm run test:connections

🐘 PostgreSQL Database

Connection Details

• Host: localhost:5432
• Database: serpentrace
• Username: postgres
• Password: postgres
• Admin Tool: pgAdmin at http://localhost:8080

Database Operations

Run Migrations

npm run migration:run

Create New Migration

npm run migration:create src/migrations/YourMigrationName

Generate Migration from Entity Changes

npm run migration:generate src/migrations/YourMigrationName

Check Migration Status

npm run migration:show

Rollback Last Migration

npm run migration:revert

Direct Database Access

Using psql (if installed)

psql -h localhost -p 5432 -U postgres -d serpentrace

Using pgAdmin

1. Open http://localhost:8080
2. Login with: admin@serpentrace.dev / admin
3. Server should be pre-configured as "SerpentRace"

Common SQL Queries

Check Database Size

SELECT pg_size_pretty(pg_database_size('serpentrace')) as size;

List All Tables

SELECT tablename FROM pg_tables WHERE schemaname = 'public';

Check Active Connections

SELECT count(*) FROM pg_stat_activity WHERE datname = 'serpentrace';

🔴 Redis Cache

Connection Details

• Host: localhost:6379
• No Authentication: Default Redis setup
• Admin Tool: Redis Commander at http://localhost:8081

Redis Operations

Direct Redis Access (if redis-cli installed)

redis-cli -h localhost -p 6379

Common Redis Commands

# Get all keys
KEYS *

# Get key count
DBSIZE

# Check memory usage
INFO memory

# Flush all data (careful!)
FLUSHALL

Using Redis Commander

1. Open http://localhost:8081
2. Browse keys, view data, execute commands

🗄️ MinIO Object Storage

Connection Details

• Endpoint: localhost:9000
• Console: http://localhost:9001
• Access Key: serpentrace
• Secret Key: serpentrace123
• Default Bucket: serpentrace

MinIO Operations

Access MinIO Console

1. Open http://localhost:9001
2. Login with: serpentrace / serpentrace123
3. Create buckets, upload files, manage storage

Health Check

curl http://localhost:9000/minio/health/live

File Upload Example (Node.js)

const Minio = require('minio');

const minioClient = new Minio.Client({
    endPoint: 'localhost',
    port: 9000,
    useSSL: false,
    accessKey: 'serpentrace',
    secretKey: 'serpentrace123'
});

// Upload file
minioClient.fPutObject('serpentrace', 'test-file.txt', './file.txt');

🐳 Docker Container Management

View All Containers

docker ps -a

View SerpentRace Containers Only

docker ps -a --filter "name=serpentrace"

Container Operations

Restart All Services

cd d:\munka\SzeSnake\SerpentRace_Docker
docker-compose -f docker-compose.dev.yml restart

Restart Individual Service

docker restart serpentrace-postgres-dev    # PostgreSQL
docker restart serpentrace-redis-dev       # Redis
docker restart serpentrace-minio-dev       # MinIO
docker restart serpentrace-pgadmin-dev     # pgAdmin

View Container Logs

docker logs serpentrace-postgres-dev
docker logs serpentrace-redis-dev -f     # Follow logs

Stop All Services

cd d:\munka\SzeSnake\SerpentRace_Docker
docker-compose -f docker-compose.dev.yml down

Start All Services

cd d:\munka\SzeSnake\SerpentRace_Docker
docker-compose -f docker-compose.dev.yml up -d

🛠️ Troubleshooting

PostgreSQL Issues

Connection Refused

# Check if container is running
docker ps | grep postgres

# Check container logs
docker logs serpentrace-postgres-dev

# Restart if needed
docker restart serpentrace-postgres-dev

Migration Errors

# Check migration status
npm run migration:show

# Revert last migration if problematic
npm run migration:revert

# Re-run migrations
npm run migration:run

Redis Issues

Cannot Connect

# Check Redis container
docker ps | grep redis

# Test connection
redis-cli -h localhost -p 6379 ping
# Expected response: PONG

MinIO Issues

Health Check Failed

# Check MinIO container
docker ps | grep minio

# Test health endpoint
curl http://localhost:9000/minio/health/live
# Expected response: 200 OK

pgAdmin Issues

Cannot Login

• Default credentials: admin@serpentrace.dev / admin
• If issues persist, restart container:

  docker restart serpentrace-pgladmin-dev
  

Server Not Found

• pgAdmin should auto-configure the PostgreSQL server
• If not visible, add manually:
  • Host: postgres
  • Port: 5432
  • Database: serpentrace
  • Username: postgres
  • Password: postgres

🔧 Environment Variables

Default Development Settings

# PostgreSQL
DB_HOST=localhost
DB_PORT=5432
DB_NAME=serpentrace
DB_USERNAME=postgres
DB_PASSWORD=postgres

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# MinIO
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=serpentrace
MINIO_SECRET_KEY=serpentrace123

Production Configuration

Create .env.production with secure values:

DB_HOST=your-production-host
DB_PASSWORD=secure-password
REDIS_PASSWORD=secure-redis-password
MINIO_SECRET_KEY=secure-minio-secret

📈 Monitoring & Maintenance

Daily Health Check

npm run db:status

Weekly Maintenance

# Check database size growth
npm run db:status:pg

# Review Redis memory usage
npm run db:status:redis

# Clean up old Docker logs
docker system prune

Backup Procedures

PostgreSQL Backup

docker exec serpentrace-postgres-dev pg_dump -U postgres serpentrace > backup.sql

Redis Backup

docker exec serpentrace-redis-dev redis-cli BGSAVE

MinIO Backup

Use MinIO Console or mc client to backup buckets.

🎯 Performance Optimization

PostgreSQL

• Monitor active connections with npm run db:status:pg
• Use connection pooling in production
• Regular VACUUM and ANALYZE operations

Redis

• Monitor memory usage
• Configure appropriate eviction policies
• Use Redis persistence (RDB/AOF) in production

MinIO

• Configure appropriate bucket policies
• Use lifecycle management for old files
• Monitor storage usage through console

🚀 Quick Reference Commands

# Status and Health
npm run db:status              # Full system status
npm run test:connections       # Quick connection test

# Database Operations  
npm run migration:run          # Apply migrations
npm run migration:show         # Check migration status

# Docker Management
docker ps                      # Show running containers
docker logs <container>        # View logs
docker restart <container>     # Restart service

# Direct Access
psql -h localhost -U postgres -d serpentrace    # PostgreSQL CLI
redis-cli -h localhost                          # Redis CLI

🌐 Web Interfaces Summary

Service	URL	Credentials
pgAdmin	http://localhost:8080	admin@serpentrace.dev / admin
Redis Commander	http://localhost:8081	No auth required
MinIO Console	http://localhost:9001	serpentrace / serpentrace123
Backend API	http://localhost:3000	When running
Frontend	http://localhost:5173	When running

---

This guide is automatically updated when database configurations change. Last updated: 2025-08-23