cataRio/scripts/README.md

# Scripts de rioCata

Esta carpeta contiene scripts helper para facilitar la gestión de la base de datos y servicios de rioCata.

## Contenido

- **riocata.sh** - Script principal de gestión y administración

---

## riocata.sh

Script bash para gestionar servicios de Docker Compose y operaciones comunes de la base de datos.

### Requisitos

- Docker y Docker Compose instalados
- Bash 4.0 o superior
- Permisos de ejecución (`chmod +x riocata.sh`)

### Uso

```bash
./riocata.sh [comando]
```

O desde el directorio raíz del proyecto:

```bash
./scripts/riocata.sh [comando]
```

### Comandos Disponibles

#### Gestión de Servicios

**`start`** - Iniciar todos los servicios
```bash
./riocata.sh start
```
Levanta los contenedores de Docker Compose y espera a que PostgreSQL esté listo. Muestra el estado de los servicios al finalizar.

**`stop`** - Detener todos los servicios
```bash
./riocata.sh stop
```
Detiene los contenedores sin eliminar los volúmenes. Los datos se preservan.

**`restart`** - Reiniciar todos los servicios
```bash
./riocata.sh restart
```
Reinicia los contenedores manteniendo los datos. Útil después de cambios en configuración.

**`reset`** - Reiniciar servicios y borrar TODOS los datos
```bash
./riocata.sh reset
```
⚠️ **ADVERTENCIA**: Este comando elimina todos los volúmenes de Docker, borrando completamente la base de datos. Los scripts de inicialización se ejecutarán de nuevo, restaurando los datos de prueba.

Requiere confirmación explícita escribiendo `SI`.

**`status`** - Ver estado de servicios
```bash
./riocata.sh status
```
Muestra el estado actual de todos los contenedores.

**`logs`** - Ver logs de PostgreSQL en tiempo real
```bash
./riocata.sh logs
```
Muestra los logs de PostgreSQL en modo follow. Presiona `Ctrl+C` para salir.

#### Base de Datos

**`psql`** - Conectarse a PostgreSQL
```bash
./riocata.sh psql
```
Abre una sesión interactiva de psql conectada a la base de datos rioCata.

Comandos útiles dentro de psql:
- `\dt` - Listar tablas
- `\d nombre_tabla` - Describir estructura de una tabla
- `\df` - Listar funciones
- `\q` - Salir

**`test`** - Ejecutar suite de tests
```bash
./riocata.sh test
```
Ejecuta el archivo `postgres/tests/test_all.sql` que contiene 18 tests de validación:
- Existencia de tablas y tipos
- Funcionamiento de triggers
- Validación de constraints
- Queries típicas
- Funciones auxiliares

**`queries`** - Ejecutar queries de ejemplo
```bash
./riocata.sh queries
```
Ejecuta el archivo `postgres/tests/example_queries.sql` que contiene 17 queries de ejemplo mostrando:
- Sesiones, muestras y evaluaciones
- Top evaluaciones por puntaje
- Evaluaciones con defectos
- Análisis de notas y sabores
- Estadísticas por catador

#### Backup y Restauración

**`backup`** - Crear backup de la base de datos
```bash
./riocata.sh backup
```
Crea un archivo de backup con formato `backup_YYYYMMDD_HHMMSS.sql` en el directorio actual usando `pg_dump`.

Ejemplo:
```bash
./riocata.sh backup
# Crea: backup_20251017_143022.sql
```

**`restore <archivo>`** - Restaurar backup
```bash
./riocata.sh restore backup_20251017_143022.sql
```
Restaura la base de datos desde un archivo de backup SQL.

⚠️ **Nota**: La restauración no elimina datos existentes. Si necesitas una restauración limpia, primero ejecuta `reset` y luego `restore`.

#### Ayuda

**`help`** - Mostrar ayuda
```bash
./riocata.sh help
```
Muestra la lista de comandos disponibles.

### Ejemplos de Uso

#### Iniciar el proyecto por primera vez
```bash
./riocata.sh start
./riocata.sh test     # Verificar que todo funciona
./riocata.sh queries  # Ver datos de ejemplo
```

#### Desarrollo diario
```bash
# Iniciar
./riocata.sh start

# Trabajar con la base de datos
./riocata.sh psql

# Ver logs si hay problemas
./riocata.sh logs

# Detener al terminar
./riocata.sh stop
```

#### Crear backup antes de cambios importantes
```bash
./riocata.sh backup
# Hacer cambios...
# Si algo sale mal:
./riocata.sh restore backup_20251017_143022.sql
```

#### Reiniciar completamente el proyecto
```bash
./riocata.sh reset
# Escribir 'SI' cuando lo solicite
./riocata.sh test  # Verificar
```

### Variables de Configuración

El script utiliza las siguientes variables configurables al inicio del archivo:

```bash
COMPOSE="docker-compose"    # Comando de docker-compose
DB_USER="riocata_user"      # Usuario de PostgreSQL
DB_NAME="riocata"           # Nombre de la base de datos
```

Si necesitas cambiar las credenciales o nombres, edita estas variables en el script.

### Códigos de Salida

- `0` - Ejecución exitosa
- `1` - Error (comando desconocido, archivo no encontrado, etc.)

### Troubleshooting

**Error: "docker-compose: command not found"**
- Solución: Instala Docker Compose o cambia la variable `COMPOSE` a `docker compose` (sin guión)

**Error al conectar con psql**
- Verifica que los servicios estén corriendo: `./riocata.sh status`
- Revisa los logs: `./riocata.sh logs`
- Intenta reiniciar: `./riocata.sh restart`

**Los tests fallan**
- Si es la primera vez, puede ser que PostgreSQL aún no haya terminado de inicializar
- Espera unos segundos y vuelve a ejecutar: `./riocata.sh test`
- Si persiste, revisa los logs: `./riocata.sh logs`

**El backup falla**
- Verifica que los servicios estén corriendo: `./riocata.sh status`
- Verifica que tengas permisos de escritura en el directorio actual

### Personalización

Puedes agregar tus propios comandos al script editando el `case` statement al final del archivo:

```bash
case "${1:-help}" in
    mi_comando)
        mi_funcion
        ;;
    # ... otros comandos
esac
```

### Contribuir

Si agregas nuevos scripts útiles a esta carpeta:

1. Hazlos ejecutables: `chmod +x nombre_script.sh`
2. Documéntalos en este README
3. Usa las mismas variables de configuración que `riocata.sh`
4. Sigue el mismo formato de colores y mensajes

### Notas de Seguridad

- ⚠️ No uses estos scripts en producción sin revisar las credenciales
- ⚠️ Los backups NO están encriptados
- ⚠️ El comando `reset` es destructivo y no se puede deshacer
- ⚠️ Almacena los backups en un lugar seguro fuera del repositorio

### Información Adicional

- Las credenciales por defecto están en `docker-compose.yml`
- Los scripts SQL están en `postgres/init/` y `postgres/tests/`
- La documentación general está en `README.md` en el directorio raíz

---

**Desarrollado para Nucleo Rio Frio**