Inicializar rioCata - Sistema de Catación de Café
- Base de datos PostgreSQL 16 con extensiones JSONB y arrays - Docker Compose para containerización - Scripts SQL de inicialización (schema, funciones, índices, datos de prueba) - Suite de tests de validación (18 tests) - Queries de ejemplo (17 queries) - Script helper para gestión (scripts/riocata.sh) - Documentación completa en README.md Estructura: - 4 tablas principales: sesion, auth.users, sesion_participante, muestra, evaluacion - Tipo ENUM para defectos - 2 triggers automáticos (updated_at, puntaje_final) - 19 índices de optimización (GIN, B-tree, funcionales) - Constraints de validación para arrays y JSONB - 2 funciones auxiliares para análisis
This commit is contained in:
253
scripts/README.md
Normal file
253
scripts/README.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user