workspace/projects/gamilit/docs/95-guias-desarrollo/GUIA-CREAR-BASE-DATOS.md

Guía: Crear Base de Datos Gamilit

Fecha: 2025-11-08 Versión: 1.0 Estado: ✅ Listo para usar

---

Descripción

Este directorio contiene todos los archivos DDL (Data Definition Language) necesarios para crear la base de datos completa de Gamilit desde cero.

---

Estructura de Archivos

apps/database/
├── create-database.sh          ← Script maestro de creación
├── 00-prerequisites.sql        ← Schemas y ENUMs base
├── ddl/
│   └── schemas/
│       ├── auth/               ← Autenticación base
│       ├── auth_management/    ← Gestión de usuarios
│       ├── educational_content/← Contenido educativo
│       ├── gamification_system/← Sistema de gamificación
│       ├── progress_tracking/  ← Seguimiento de progreso
│       ├── social_features/    ← Características sociales
│       ├── content_management/ ← Gestión de contenido
│       ├── audit_logging/      ← Auditoría y logs
│       ├── system_configuration/← Configuración
│       ├── admin_dashboard/    ← Dashboard administrativo
│       ├── gamilit/            ← Funciones compartidas
│       └── storage/            ← Storage del sistema
└── migrations/                 ← Migraciones de BD

---

Requisitos Previos

1. PostgreSQL 14 o superior

# Verificar versión instalada
psql --version

2. Base de datos creada

# Crear base de datos local
createdb gamilit

3. Variable DATABASE_URL configurada

# Formato para PostgreSQL local
export DATABASE_URL="postgresql://usuario:password@localhost:5432/gamilit"

---

Método 1: Script Automático (Recomendado)

Opción A: Usando variable de entorno

# 1. Configurar DATABASE_URL
export DATABASE_URL="postgresql://usuario:password@localhost:5432/gamilit"

# 2. Ejecutar script
cd apps/database
./create-database.sh

Opción B: Pasando URL como argumento

cd apps/database
./create-database.sh "postgresql://usuario:password@localhost:5432/gamilit"

Salida Esperada

============================================================================
INICIO: Creación de Base de Datos Gamilit
============================================================================
DATABASE_URL: postgresql://localhost:5432/gamilit
DDL_DIR: /path/to/ddl
LOG_FILE: /path/to/create-database-20251108_143022.log

✅ Conexión exitosa a la base de datos

============================================================================
FASE 1: PREREQUISITES - Schemas y ENUMs
============================================================================
✅ Completado: Crear schemas y ENUMs base
✅ FASE 1 completada

============================================================================
FASE 2: FUNCIONES COMPARTIDAS
============================================================================
✅ Completado: Funciones compartidas (gamilit schema) (13 archivos)
✅ FASE 2 completada

... (continúa con todas las fases)

============================================================================
RESUMEN FINAL
============================================================================
Objetos creados:
  - Schemas: 13
  - Tablas: 63
  - ENUMs: 35
  - Funciones: 80
  - Triggers: 45

✅ BASE DE DATOS CREADA EXITOSAMENTE
============================================================================

Log completo disponible en: create-database-20251108_143022.log

---

Método 2: Paso a Paso Manual

1. Ejecutar prerequisites

psql "$DATABASE_URL" -f ddl/00-prerequisites.sql

2. Ejecutar esquemas en orden

# Funciones compartidas
psql "$DATABASE_URL" -f ddl/schemas/gamilit/functions/*.sql

# Auth (sistema)
psql "$DATABASE_URL" -f ddl/schemas/auth/enums/*.sql
psql "$DATABASE_URL" -f ddl/schemas/auth/tables/*.sql

# Auth Management
psql "$DATABASE_URL" -f ddl/schemas/auth_management/tables/*.sql
psql "$DATABASE_URL" -f ddl/schemas/auth_management/triggers/*.sql
psql "$DATABASE_URL" -f ddl/schemas/auth_management/rls-policies/*.sql

# Educational Content
psql "$DATABASE_URL" -f ddl/schemas/educational_content/tables/*.sql
psql "$DATABASE_URL" -f ddl/schemas/educational_content/functions/*.sql
psql "$DATABASE_URL" -f ddl/schemas/educational_content/triggers/*.sql

# ... (continuar con otros schemas)

---

Método 3: Aplicar Migraciones (Base de Datos Existente)

Si ya tienes una base de datos con el schema public legacy y quieres migrar a la nueva arquitectura:

1. Migrar ENUMs de public a schemas correctos

cd migrations

# P1: Alta Prioridad
psql "$DATABASE_URL" -f 2025-11-08-migrate-auth-provider-enum.sql
psql "$DATABASE_URL" -f 2025-11-08-migrate-notification-enums.sql

# P2: Media Prioridad
psql "$DATABASE_URL" -f 2025-11-08-migrate-difficulty-level-enum.sql
psql "$DATABASE_URL" -f 2025-11-08-migrate-content-management-enums.sql
psql "$DATABASE_URL" -f 2025-11-08-migrate-setting-type-enum.sql

# P3: Baja Prioridad (si aplica)
# ... migraciones adicionales

2. Aplicar otras migraciones

psql "$DATABASE_URL" -f 2025-11-08-add-fk-profiles-school.sql

---

Orden de Ejecución (Fases)

El script create-database.sh ejecuta los archivos DDL en este orden:

Fase	Schema	Componentes	Archivos
1	prerequisites	Schemas + ENUMs	1
2	gamilit	Funciones comunes	~13
3	auth	Tables + Enums	~5
4	storage	Enums	~1
5	auth_management	Tables + Functions + Triggers + RLS	~25
6	educational_content	Tables + Functions + Triggers + RLS	~50
7	gamification_system	Tables + Functions + Triggers + Views + RLS	~55
8	progress_tracking	Tables + Functions + Triggers + Views + RLS	~25
9	social_features	Tables + Functions + Triggers + RLS	~20
10	content_management	Tables + Triggers + RLS	~10
11	audit_logging	Tables + Functions + Triggers + RLS	~15
12	system_configuration	Tables + Triggers + RLS	~3
13	admin_dashboard	Views	~1

Total: ~225 archivos DDL

---

Verificación Post-Creación

1. Verificar schemas creados

SELECT schema_name
FROM information_schema.schemata
WHERE schema_name NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
ORDER BY schema_name;

Resultado esperado: 13 schemas

2. Verificar tablas creadas

SELECT
    table_schema,
    COUNT(*) as table_count
FROM information_schema.tables
WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
GROUP BY table_schema
ORDER BY table_schema;

Resultado esperado: ~63 tablas distribuidas en los schemas

3. Verificar ENUMs creados

SELECT
    n.nspname as schema,
    t.typname as enum_name,
    COUNT(e.enumlabel) as value_count
FROM pg_type t
JOIN pg_namespace n ON t.typnamespace = n.oid
LEFT JOIN pg_enum e ON t.oid = e.enumtypid
WHERE t.typcategory = 'E'
AND n.nspname NOT IN ('pg_catalog', 'information_schema')
GROUP BY n.nspname, t.typname
ORDER BY n.nspname, t.typname;

Resultado esperado: 35 ENUMs distribuidos en los schemas

4. Verificar funciones creadas

SELECT
    n.nspname as schema,
    COUNT(*) as function_count
FROM pg_proc p
JOIN pg_namespace n ON p.pronamespace = n.oid
WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
GROUP BY n.nspname
ORDER BY n.nspname;

Resultado esperado: ~80 funciones distribuidas en los schemas

---

Troubleshooting

Error: "psql: command not found"

# Ubuntu/Debian
sudo apt-get install postgresql-client

# macOS
brew install postgresql

# Windows
# Descargar desde https://www.postgresql.org/download/windows/

Error: "connection refused"

# Verificar que PostgreSQL esté corriendo
sudo systemctl status postgresql  # Linux
brew services list                # macOS

# Verificar la URL de conexión
echo $DATABASE_URL

Error: "permission denied"

# Asegurarse de tener permisos de superusuario
psql "$DATABASE_URL" -c "SELECT current_user, current_database();"

# Si es necesario, conectarse como superusuario
export DATABASE_URL="postgresql://postgres:password@localhost:5432/gamilit"

Error: "duplicate key value violates unique constraint"

# La base de datos ya tiene datos
# Opción 1: Borrar y recrear
dropdb gamilit && createdb gamilit

# Opción 2: Usar migraciones en lugar de create-database.sh
cd migrations
psql "$DATABASE_URL" -f [migration-file].sql

Error en fase específica

# Revisar el log generado
cat apps/database/create-database-YYYYMMDD_HHMMSS.log

# Ejecutar manualmente la fase que falló
psql "$DATABASE_URL" -f ddl/schemas/[schema]/[type]/[file].sql

---

Logs y Depuración

Ubicación de logs

Cada ejecución de create-database.sh genera un log con timestamp:

apps/database/create-database-20251108_143022.log

Contenido del log

• Timestamp de cada operación
• Archivos ejecutados
• Errores de PostgreSQL
• Warnings y notices
• Resumen de objetos creados

Ver log en tiempo real

tail -f create-database-*.log

---

Siguientes Pasos

Después de crear la base de datos:

1. Verificar integridad: Ejecutar queries de verificación
2. Aplicar datos semilla (si existen): psql "$DATABASE_URL" -f seed-data.sql
3. Configurar backend: Actualizar .env con DATABASE_URL
4. Ejecutar migraciones: Si hay migraciones pendientes
5. Testing: Ejecutar tests de integración del backend

---

Scripts Relacionados

• create-database.sh - Script maestro de creación
• migrations/*.sql - Migraciones individuales
• seed-data.sql - Datos iniciales (si existe)
• backup-database.sh - Backup de base de datos (si existe)
• reset-database.sh - Resetear base de datos (si existe)

---

Documentación Adicional

• REPORTE-COMPLETITUD-DDL-2025-11-08.md - Inventario completo de archivos DDL
• PLAN-MIGRACION-ENUMS-PUBLIC-SCHEMA.md - Plan de migración de ENUMs
• REPORTE-MIGRACION-ENUMS-2025-11-08.md - Reporte de migración de ENUMs
• docs/02-especificaciones-tecnicas/arquitectura-base-datos/ - Documentación técnica

---

Contacto y Soporte

Para problemas o preguntas:

1. Revisar este README y los logs
2. Consultar documentación en docs/
3. Crear issue en el repositorio del proyecto

---

Documento creado: 2025-11-08 Última actualización: 2025-11-08 Versión del script: 1.0