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:

# 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:

openssl rand -base64 32

3. Iniciar los Servicios

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

GET https://api.analitica.nucleoriofrio.com/nombre_tabla

Filtrar registros

GET https://api.analitica.nucleoriofrio.com/nombre_tabla?columna=eq.valor

Seleccionar columnas específicas

GET https://api.analitica.nucleoriofrio.com/nombre_tabla?select=columna1,columna2

Ordenar resultados

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

docker logs analiticanucleo-postgres

Ver logs de PostgREST

docker logs analiticanucleo-postgrest

Conectarse a PostgreSQL

docker exec -it analiticanucleo-postgres psql -U postgres -d analitica

Reiniciar la base de datos (¡CUIDADO!)

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:

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:

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