workspace/projects/gamilit/apps/database/scripts/QUICK-START.md

🚀 GUÍA RÁPIDA - Scripts de Base de Datos GAMILIT

Actualizado: 2025-11-08 Versión: 3.0

---

⚡ Inicio Rápido

Para Desarrollo (Primera Vez)

cd /home/isem/workspace/projects/gamilit/apps/database/scripts

# Inicializar BD completa (crea usuario + BD + DDL + seeds)
./init-database.sh --env dev --force

Para Producción (Primera Vez)

# Con dotenv-vault (RECOMENDADO)
./manage-secrets.sh generate --env prod
./manage-secrets.sh sync --env prod
./init-database.sh --env prod

# O con password manual
./init-database.sh --env prod --password "tu_password_seguro_32chars"

---

📋 Scripts Disponibles (3 principales)

1. init-database.sh - Inicialización Completa ⭐

¿Cuándo usar? Primera vez, o cuando el usuario NO existe

./init-database.sh --env dev              # Desarrollo
./init-database.sh --env prod             # Producción
./init-database.sh --env dev --force      # Sin confirmación

¿Qué hace?

• ✅ Crea usuario gamilit_user (si no existe)
• ✅ Genera password seguro de 32 caracteres
• ✅ Crea base de datos gamilit_platform
• ✅ Ejecuta DDL (13 schemas, 61 tablas, 61 funciones, 288 índices, 114 RLS policies)
• ✅ Carga seeds del ambiente
• ✅ Actualiza archivos .env automáticamente

---

2. reset-database.sh - Reset Rápido (Mantiene Usuario)

¿Cuándo usar? Usuario ya existe, solo quieres resetear datos

./reset-database.sh --env dev --password "password_existente"
./reset-database.sh --env prod --password "prod_pass"

¿Qué hace?

• ⚠️ Elimina la BD gamilit_platform
• ✅ Mantiene el usuario gamilit_user (NO cambia password)
• ✅ Recrea BD con DDL y seeds
• ℹ️ NO actualiza .env (credenciales no cambian)

---

3. recreate-database.sh - Recreación Completa (DESTRUYE TODO)

¿Cuándo usar? Cuando quieres empezar desde cero COMPLETAMENTE

⚠️ ADVERTENCIA: ELIMINA USUARIO Y TODOS LOS DATOS

./recreate-database.sh --env dev
./recreate-database.sh --env prod        # Requiere confirmación adicional

¿Qué hace?

• ⚠️ Termina todas las conexiones
• ⚠️ Elimina completamente la BD
• ⚠️ Elimina el usuario
• ✅ Ejecuta init-database.sh para recrear todo
• ✅ Actualiza archivos .env automáticamente

---

🎯 Casos de Uso Comunes

Caso 1: Primera vez en proyecto (Setup inicial)

./init-database.sh --env dev --force

Caso 2: Resetear datos pero mantener usuario

# Si conoces el password
./reset-database.sh --env dev --password "mi_password"

# Si no conoces el password, usa recreate
./recreate-database.sh --env dev

Caso 3: Actualizar estructura de BD (nueva migración)

# Opción A: Reset rápido (si tienes password)
./reset-database.sh --env dev --password "password"

# Opción B: Recrear completo (genera nuevo password)
./recreate-database.sh --env dev

Caso 4: Aplicar cambios de DDL

# Si solo cambiaron DDL/seeds (sin cambios de usuario)
./reset-database.sh --env dev --password "password_actual"

Caso 5: Olvidé el password del usuario

# Única opción: recrear todo
./recreate-database.sh --env dev

---

📊 Comparación Rápida

Acción	init-database.sh	reset-database.sh	recreate-database.sh
Elimina usuario	❌	❌	✅
Elimina BD	⚠️ Si existe	✅	✅
Crea usuario	✅ Si no existe	❌	✅
Genera password	✅	❌	✅
Requiere password	❌	✅	❌
Actualiza .env	✅	❌	✅
Tiempo aprox	30-60s	20-30s	40-70s

---

🔑 Gestión de Credenciales

¿Dónde están las credenciales?

Después de ejecutar init-database.sh o recreate-database.sh:

apps/database/database-credentials-{env}.txt  ← Credenciales guardadas aquí

Ejemplo de contenido:

Database Host: localhost
Database Port: 5432
Database Name: gamilit_platform
Database User: gamilit_user
Database Password: xB9k2mN...Zp8Q
Connection String: postgresql://gamilit_user:xB9k2mN...@localhost:5432/gamilit_platform

Archivos .env actualizados automáticamente

• apps/backend/.env.{env}
• apps/database/.env.{env}
• ../../gamilit-deployment-scripts/.env.{env} (si existe)

---

⚠️ Advertencias de Seguridad

Desarrollo

• ✅ OK usar --force para automatización
• ✅ OK regenerar passwords
• ✅ OK recrear BD frecuentemente

Producción

• ⚠️ NUNCA usar --force sin validación
• ⚠️ SIEMPRE hacer backup antes de recreate-database.sh
• ⚠️ Confirmar que tienes backup antes de eliminar
• ✅ Usar dotenv-vault para gestión de secrets

---

🐛 Troubleshooting

Error: "No se puede conectar a PostgreSQL"

# Verificar que PostgreSQL está corriendo
sudo systemctl status postgresql

# O verificar proceso
ps aux | grep postgres

# Iniciar si está detenido
sudo systemctl start postgresql

Error: "Usuario ya existe"

# Opción A: Usar reset (si conoces password)
./reset-database.sh --env dev --password "password_existente"

# Opción B: Recrear todo
./recreate-database.sh --env dev

Error: "Base de datos no se puede eliminar (conexiones activas)"

# El script ya maneja esto, pero si falla:
sudo -u postgres psql -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='gamilit_platform';"

Error: "Permisos denegados"

# Dar permisos de ejecución
chmod +x *.sh

# Verificar permisos de PostgreSQL
sudo -u postgres psql -c "SELECT version();"

---

📁 Estructura de Archivos

scripts/
├── init-database.sh          ⭐ Script principal (v3.0)
├── reset-database.sh         🔄 Reset rápido
├── recreate-database.sh      ⚠️  Recreación completa
├── manage-secrets.sh         🔐 Gestión de secrets
├── update-env-files.sh       🔧 Sincronización .env
├── cleanup-duplicados.sh     🧹 Limpieza
├── QUICK-START.md            📖 Esta guía
├── README.md                 📚 Documentación completa
├── deprecated/               📦 Scripts antiguos
│   ├── init-database-v1.sh
│   ├── init-database-v2.sh
│   └── init-database.sh.backup-*
├── config/                   ⚙️  Configuraciones
│   ├── dev.conf
│   └── prod.conf
├── inventory/                📊 Scripts de inventario
└── utilities/                🛠️  Utilidades

---

🎓 Flujo Recomendado para Nuevos Desarrolladores

Día 1 - Setup Inicial

# 1. Clonar repositorio
git clone <repo-url>
cd gamilit/projects/gamilit/apps/database/scripts

# 2. Inicializar BD
./init-database.sh --env dev --force

# 3. Verificar credenciales
cat ../database-credentials-dev.txt

# 4. ¡Listo! Backend puede conectarse

Día a Día - Desarrollo

# Aplicar cambios de DDL
./reset-database.sh --env dev --password "$(grep 'Database Password' ../database-credentials-dev.txt | cut -d: -f2 | xargs)"

# O más simple: recrear todo
./recreate-database.sh --env dev --force

---

✅ Checklist Pre-Deployment Producción

• Backup completo de BD actual
• Verificar que manage-secrets.sh tiene secrets generados
• Probar script en staging primero
• Tener plan de rollback
• Notificar al equipo del deployment
• Ejecutar con --env prod (SIN --force)
• Validar conexiones post-deployment
• Verificar que seeds de producción se cargaron

---

📞 Soporte

• Documentación completa: README.md
• Scripts de inventario: inventory/
• Logs: Revisa output del script (se muestra en consola)

---

Última actualización: 2025-11-08 Versión de scripts: 3.0 Mantenido por: Equipo de Base de Datos GAMILIT