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

./riocata.sh [comando]

O desde el directorio raíz del proyecto:

./scripts/riocata.sh [comando]

Comandos Disponibles

Gestión de Servicios

start - Iniciar todos los servicios

./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

./riocata.sh stop

Detiene los contenedores sin eliminar los volúmenes. Los datos se preservan.

restart - Reiniciar todos los servicios

./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

./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

./riocata.sh status

Muestra el estado actual de todos los contenedores.

logs - Ver logs de PostgreSQL en tiempo real

./riocata.sh logs

Muestra los logs de PostgreSQL en modo follow. Presiona Ctrl+C para salir.

Base de Datos

psql - Conectarse a PostgreSQL

./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

./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

./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

./riocata.sh backup

Crea un archivo de backup con formato backup_YYYYMMDD_HHMMSS.sql en el directorio actual usando pg_dump.

Ejemplo:

./riocata.sh backup
# Crea: backup_20251017_143022.sql

restore <archivo> - Restaurar backup

./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

./riocata.sh help

Muestra la lista de comandos disponibles.

Ejemplos de Uso

Iniciar el proyecto por primera vez

./riocata.sh start
./riocata.sh test     # Verificar que todo funciona
./riocata.sh queries  # Ver datos de ejemplo

Desarrollo diario

# 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

./riocata.sh backup
# Hacer cambios...
# Si algo sale mal:
./riocata.sh restore backup_20251017_143022.sql

Reiniciar completamente el proyecto

./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:

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:

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