trading-platform-database-v2/README.md

Trading Platform Database

Definiciones DDL y scripts de base de datos para Trading Platform.

Stack Tecnologico

• DBMS: PostgreSQL 16
• Extension ML: pgvector (embeddings LLM)
• Contenedor: Docker (pgvector/pgvector:pg16)

Estructura del Proyecto

database/
├── ddl/
│   └── schemas/          # Definiciones DDL por schema
│       ├── audit/        # Logs de auditoria
│       ├── auth/         # Autenticacion y sesiones
│       ├── education/    # Cursos y gamificacion
│       ├── financial/    # Transacciones y wallets
│       ├── investment/   # Inversiones y portfolios
│       ├── llm/          # Embeddings y contextos LLM
│       ├── ml/           # Modelos y predicciones ML
│       └── trading/      # Ordenes y operaciones
├── schemas/              # _MAP.md e indices
├── scripts/              # Scripts de gestion
│   ├── create-database.sh
│   ├── drop-and-recreate-database.sh
│   └── validate-ddl.sh
└── seeds/                # Datos iniciales (dev)

Schemas

Schema	Tablas	Descripcion
auth	12	Usuarios, sesiones, tokens, OAuth
education	15	Cursos, lecciones, quizzes, progreso
trading	18	Ordenes, posiciones, historial
investment	12	Portfolios, assets, distribuciones
financial	10	Wallets, transacciones, pagos
ml	8	Modelos, predicciones, senales
llm	6	Embeddings, conversaciones, contextos
audit	9	Logs, eventos, trazabilidad

Total: ~90 tablas, 102+ foreign keys

Instalacion

Opcion 1: Docker (Recomendado)

# Desde raiz del proyecto trading-platform
docker-compose up -d postgres

# Crear base de datos
cd apps/database/scripts
./create-database.sh

Opcion 2: PostgreSQL Local

# Requiere PostgreSQL 16 con pgvector instalado
# Ubuntu/Debian:
sudo apt install postgresql-16-pgvector

# Crear base de datos
cd apps/database/scripts
./create-database.sh

Scripts Disponibles

Script	Descripcion
create-database.sh	Crear BD y cargar DDL
drop-and-recreate-database.sh	Recrear BD desde cero
validate-ddl.sh	Validar sintaxis SQL

Variables de Entorno

# Database connection - Instancia nativa compartida
# Ref: orchestration/inventarios/DEVENV-PORTS-INVENTORY.yml
DB_HOST=localhost
DB_PORT=5432              # Instancia NATIVA (NO Docker)
DB_NAME=trading_platform
DB_USER=trading_user
DB_PASSWORD=trading_dev_2025

IMPORTANTE: El workspace usa arquitectura de instancia única compartida. PostgreSQL nativo en puerto 5432, NO Docker. Los proyectos se separan por DATABASE + USER.

Uso de Scripts

Crear Base de Datos

cd apps/database/scripts

# Con variables de entorno (instancia nativa)
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=trading_platform
export DB_USER=trading_user
export DB_PASSWORD=trading_dev_2025

./create-database.sh

Recrear Base de Datos (Development)

# ADVERTENCIA: Elimina todos los datos
./drop-and-recreate-database.sh

Estructura DDL

Cada schema sigue la estructura:

ddl/schemas/{schema}/
├── 00-extensions.sql     # Extensiones (si aplica)
├── tables/
│   ├── 01-{tabla}.sql
│   ├── 02-{tabla}.sql
│   └── ...
├── functions/
│   ├── 01-{funcion}.sql
│   └── ...
└── triggers/
    └── 01-{trigger}.sql

Convencion de Nombres

• Tablas: snake_case plural (users, trading_orders)
• Columnas: snake_case (created_at, user_id)
• Primary Keys: id (UUID)
• Foreign Keys: {tabla_singular}_id
• Indices: idx_{tabla}_{columna}
• Triggers: trg_{tabla}_{accion}

Seguridad

• Row Level Security (RLS) habilitado en tablas multi-tenant
• Funciones con SECURITY DEFINER donde corresponde
• Passwords hasheados con bcrypt (en aplicacion)
• Audit logs automaticos via triggers

Migraciones

Actualmente se usa DDL directo sin sistema de migraciones. Para cambios:

1. Modificar archivo DDL correspondiente
2. Documentar en _MAP.md del schema
3. Ejecutar drop-and-recreate-database.sh (dev)
4. En produccion: scripts de migracion manuales

Documentacion Relacionada

• Mapa de Schemas
• Inventario Database
• Politica de Carga Limpia

---

Proyecto: Trading Platform Version: 0.1.0 Actualizado: 2026-01-07