analiticaNucleo/POSTGRES_SETUP.md

# Configuración de PostgreSQL y PostgREST

Esta aplicación utiliza PostgreSQL como base de datos principal y PostgREST para exponer las tablas y vistas como una API REST.

## Arquitectura

```
Airbyte → PostgreSQL → PostgREST → Nuxt App
```

- **Airbyte**: Sincroniza datos de diversas fuentes hacia PostgreSQL
- **PostgreSQL**: Base de datos principal que almacena todos los datos
- **PostgREST**: Expone las tablas y vistas de PostgreSQL como API REST
- **Nuxt App**: Consume los datos desde la API de PostgREST

## Configuración Inicial

### 1. Variables de Entorno

Copia el archivo `.env.example` a `.env` y configura las siguientes variables:

```bash
# PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=tu-contraseña-segura
POSTGRES_DB=analitica

# PostgREST
PGRST_DB_AUTHENTICATOR_PASSWORD=tu-contraseña-authenticator
PGRST_DB_SCHEMA=public
PGRST_DB_ANON_ROLE=web_anon
PGRST_JWT_SECRET=tu-jwt-secret-minimo-32-caracteres
PGRST_OPENAPI_SERVER_PROXY_URI=https://api.analitica.nucleoriofrio.com
NUXT_PUBLIC_POSTGREST_URL=https://api.analitica.nucleoriofrio.com
```

### 2. Generar JWT Secret

El JWT secret debe tener al menos 32 caracteres. Puedes generarlo con:

```bash
openssl rand -base64 32
```

### 3. Iniciar los Servicios

```bash
docker-compose up -d
```

Esto iniciará:
- PostgreSQL en el puerto interno 5432
- PostgREST expuesto vía Traefik en `api.analitica.nucleoriofrio.com`
- La aplicación Nuxt en `analitica.nucleoriofrio.com`

## Estructura de Base de Datos

### Esquemas

Por defecto, PostgREST expone el esquema `public`. Puedes cambiar esto modificando la variable `PGRST_DB_SCHEMA`.

### Roles y Permisos

Se crean automáticamente dos roles:

1. **web_anon**: Rol anónimo con permisos de solo lectura
   - Se usa para consultas sin autenticación
   - Solo tiene permiso SELECT en las tablas

2. **authenticator**: Rol de conexión para PostgREST
   - Usado por PostgREST para conectarse a la base de datos
   - Puede cambiar al rol web_anon según sea necesario

### Scripts de Inicialización

Los scripts en `/init-db` se ejecutan automáticamente cuando se crea la base de datos por primera vez:

- `01-init.sql`: Crea el rol web_anon y configura permisos
- `02-create-authenticator.sh`: Crea el rol authenticator

## Uso de PostgREST

### API REST Automática

PostgREST expone automáticamente todas las tablas y vistas del esquema configurado como endpoints REST:

#### Listar registros
```bash
GET https://api.analitica.nucleoriofrio.com/nombre_tabla
```

#### Filtrar registros
```bash
GET https://api.analitica.nucleoriofrio.com/nombre_tabla?columna=eq.valor
```

#### Seleccionar columnas específicas
```bash
GET https://api.analitica.nucleoriofrio.com/nombre_tabla?select=columna1,columna2
```

#### Ordenar resultados
```bash
GET https://api.analitica.nucleoriofrio.com/nombre_tabla?order=columna.desc
```

### Documentación de la API

PostgREST genera automáticamente documentación OpenAPI en:
```
https://api.analitica.nucleoriofrio.com/
```

## Airbyte → PostgreSQL

### Configurar Destino en Airbyte

1. En Airbyte, crea un nuevo destino de tipo PostgreSQL
2. Usa los siguientes parámetros de conexión:
   - **Host**: `analiticanucleo-postgres` (si Airbyte está en la misma red Docker) o la IP del servidor
   - **Port**: `5432`
   - **Database**: El valor de `POSTGRES_DB`
   - **User**: El valor de `POSTGRES_USER`
   - **Password**: El valor de `POSTGRES_PASSWORD`
   - **Schema**: `public` o el esquema que prefieras

3. Configura tus conexiones en Airbyte para sincronizar datos hacia este destino

## Mantenimiento

### Ver logs de PostgreSQL
```bash
docker logs analiticanucleo-postgres
```

### Ver logs de PostgREST
```bash
docker logs analiticanucleo-postgrest
```

### Conectarse a PostgreSQL
```bash
docker exec -it analiticanucleo-postgres psql -U postgres -d analitica
```

### Reiniciar la base de datos (¡CUIDADO!)
```bash
docker-compose down
docker volume rm analiticanucleo_postgres_data
docker-compose up -d
```

## Crear Vistas para la API

Para exponer datos procesados, crea vistas en PostgreSQL:

```sql
CREATE VIEW vista_resumen AS
SELECT
    columna1,
    COUNT(*) as total,
    AVG(columna2) as promedio
FROM tabla_origen
GROUP BY columna1;

-- Dar permisos al rol web_anon
GRANT SELECT ON vista_resumen TO web_anon;
```

Esta vista estará automáticamente disponible en:
```
GET https://api.analitica.nucleoriofrio.com/vista_resumen
```

## Seguridad

### Autenticación JWT (Opcional)

Para proteger endpoints específicos, puedes configurar autenticación JWT. PostgREST validará automáticamente los tokens JWT firmados con `PGRST_JWT_SECRET`.

### Permisos Granulares

Puedes crear roles adicionales con permisos más específicos:

```sql
CREATE ROLE usuario_lectura NOLOGIN;
GRANT USAGE ON SCHEMA public TO usuario_lectura;
GRANT SELECT ON tabla_especifica TO usuario_lectura;
GRANT usuario_lectura TO authenticator;
```

## Próximos Pasos

1. Configurar Airbyte para sincronizar datos hacia PostgreSQL
2. Crear vistas y tablas según tus necesidades
3. Consumir la API desde la aplicación Nuxt
4. (Opcional) Configurar autenticación JWT para endpoints protegidos