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
```bash
npm run db:status
```

### Check Individual Services
```bash
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
```bash
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
```bash
npm run migration:run
```

#### Create New Migration
```bash
npm run migration:create src/migrations/YourMigrationName
```

#### Generate Migration from Entity Changes
```bash
npm run migration:generate src/migrations/YourMigrationName
```

#### Check Migration Status
```bash
npm run migration:show
```

#### Rollback Last Migration
```bash
npm run migration:revert
```

### Direct Database Access

#### Using psql (if installed)
```bash
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
```sql
SELECT pg_size_pretty(pg_database_size('serpentrace')) as size;
```

#### List All Tables
```sql
SELECT tablename FROM pg_tables WHERE schemaname = 'public';
```

#### Check Active Connections
```sql
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)
```bash
redis-cli -h localhost -p 6379
```

#### Common Redis Commands
```bash
# 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
```bash
curl http://localhost:9000/minio/health/live
```

### File Upload Example (Node.js)
```javascript
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
```bash
docker ps -a
```

### View SerpentRace Containers Only
```bash
docker ps -a --filter "name=serpentrace"
```

### Container Operations

#### Restart All Services
```bash
cd d:\munka\SzeSnake\SerpentRace_Docker
docker-compose -f docker-compose.dev.yml restart
```

#### Restart Individual Service
```bash
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
```bash
docker logs serpentrace-postgres-dev
docker logs serpentrace-redis-dev -f     # Follow logs
```

#### Stop All Services
```bash
cd d:\munka\SzeSnake\SerpentRace_Docker
docker-compose -f docker-compose.dev.yml down
```

#### Start All Services
```bash
cd d:\munka\SzeSnake\SerpentRace_Docker
docker-compose -f docker-compose.dev.yml up -d
```

## 🛠️ Troubleshooting

### PostgreSQL Issues

#### Connection Refused
```bash
# 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
```bash
# 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
```bash
# Check Redis container
docker ps | grep redis

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

### MinIO Issues

#### Health Check Failed
```bash
# 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:
  ```bash
  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
```bash
# 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:
```bash
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
```bash
npm run db:status
```

### Weekly Maintenance
```bash
# 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
```bash
docker exec serpentrace-postgres-dev pg_dump -U postgres serpentrace > backup.sql
```

#### Redis Backup
```bash
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

```bash
# 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*