Esquema de la base de datos

Tablas, columnas clave, relaciones y estados de la base de datos de VANTS en Neon por área: torneos, matchmaking, ranked, bus de eventos, agente y bot.

La base de datos de VANTS es un Postgres en Neon. Su esquema se versiona como migraciones SQL en VantsBasededatos. Esta página resume qué guarda cada área y cómo se relacionan las tablas principales.

Datos al 23 de octubre de 2026: 69 tablas en producción y 34 migraciones. Las migraciones de este repositorio crean 39 de esas tablas. Las otras 30, como players, seasons y season_player_stats, no las crea ninguna migración: las migraciones solo las referencian o las modifican. Las migraciones son la fuente de verdad: si algo no coincide con esta página, manda el SQL.

Mapa por áreas

Área	Tablas	Qué guarda
Plataforma de torneos	pt_games, pt_torneos, pt_teams, pt_matches, pt_players, pt_articulos	Catálogo público de juegos, torneos, equipos, partidas, jugadores y artículos
Torneos de VANTS y presencia	tournament_teams, tournament_matches, presence	Inscripciones, cuadro de eliminatorias y quién está conectado
Matchmaking	mm_tickets, mm_matches, mm_match_players, mm_invites, mm_ready	Cola, partidas, participantes, invitaciones y confirmaciones
Ranked y FACEIT	series_ranked, faceit_matches, faceit_webhook_events, rr_historial	Series, partidas de FACEIT, XP e historial de RR
Bus de eventos	vants_events, vants_consumers, vants_bus_dedup, vants_feed	Eventos que se intercambian los proyectos
Agente	agent_runs, agent_events, agent_comandos, agent_memoria, agent_archivos, agent_sandbox_execs	Vigilancia automática de la plataforma
Bot y eventos web	bot_heartbeat, bot_settings, discord_channels, bot_alerts, vant_sync_events, web_events	Estado del bot, alertas y eventos de la web
Jugadores y temporadas	players, seasons, season_player_stats, profiles	Perfiles, temporadas y estadísticas por temporada (rating, MMR, rango, victorias y derrotas)
Cuentas y pagos	vants_links, purchases, entitlements, audit_logs	Cuentas externas vinculadas, compras, accesos y auditoría

Convenciones

• Las claves primarias son uuid generados con gen_random_uuid(), salvo claves naturales como slug, ticket o event_id.
• Las fechas son timestamptz.
• Los estados son text con una restricción CHECK que lista los valores permitidos.
• Los datos de demostración llevan is_demo = true y se pueden ocultar con ese filtro.
• Los nombres de columnas mezclan español e inglés, según la migración que los creó.

Plataforma de torneos

Catálogo público con prefijo pt_ (migraciones 28 y 29). Lo lee la API pública y es independiente de los torneos propios de VANTS. Cada torneo, partida y jugador indica su origen en source.

El diagrama muestra solo las columnas principales. Tres detalles que conviene conocer:

• pt_matches.equipo_a y equipo_b guardan el nombre del equipo como texto, no una clave foránea.
• pt_players.team_slug apunta a pt_teams.slug sin clave foránea, así que borrar un equipo no toca a sus jugadores.
• Torneos, partidas y jugadores son únicos por (source, external_id), lo que permite importar datos externos sin duplicarlos.

Juegos registrados en pt_games: valorant, cs2 y dota2 están activos; lol, r6s y cod existen pero están inactivos. No se puede borrar un juego que tenga torneos o partidas.

Campo	Valores permitidos
source (torneos, partidas y jugadores)	vants, faceit, demo
pt_torneos.estado	upcoming, ongoing, finished, cancelled
pt_torneos.location_type	online, lan
pt_matches.estado	upcoming, live, finished, cancelled
pt_articulos.estado	draft, published

Torneos de VANTS y presencia

Los torneos propios de VANTS usan sus propias tablas (migración 17). tournament_id es un identificador de texto, no una clave foránea a pt_torneos.

tournament_teams guarda las inscripciones.

Columna	Detalle
name	De 2 a 32 caracteres. No se admiten dos equipos con el mismo nombre en un torneo, sin distinguir mayúsculas
tag	De 2 a 4 caracteres
game	Por defecto valorant
captain, region	Capitán y región del equipo
status	pendiente, confirmado o rechazado

tournament_matches guarda el cuadro. Cada fila es única por (tournament_id, ronda, slot).

Columna	Detalle
ronda	q, s, f, l1, l2 o lf
slot	De 0 a 3
team_a, team_b	Nombres de los equipos
score_a, score_b	Marcador
estado	pendiente, en_curso o final
ganador	Equipo ganador. El cuadro avanza cuando la partida está en final y tiene ganador

Cuadro de 8 equipos

El cuadro es de doble eliminación. Cuando un torneo llega a 8 equipos confirmados, un trigger lo siembra una sola vez: los 8 primeros por orden de inscripción forman los 4 cruces de cuartos y se crean vacías el resto de partidas. Con menos de 8 equipos confirmados no hay cuadro.

Al marcar una partida como final con su ganador, otro trigger mueve a los equipos:

Ronda	Slots	El ganador pasa a	El perdedor pasa a
q (cuartos)	0 a 3	s	l1
s (semifinales)	0 y 1	f	l2
l1 (inferiores, ronda 1)	0 y 1	l2	Queda eliminado
l2 (inferiores, ronda 2)	0 y 1	lf	Queda eliminado
lf (final inferior)	0	f, si ese hueco sigue libre	Queda eliminado

La gran final (f, slot 0) cierra el cuadro. Si un equipo no avanza solo, el propietario puede colocarlo a mano.

Presencia

presence tiene una fila por jugador conectado.

Columna	Detalle
player_id	Clave primaria, referencia a players
estado	online, jugando o ausente
juego	Juego actual
actualizado	Se renueva en cada actualización

La web y la app de escritorio envían un latido cada 60 segundos.

Vistas

Para mostrar datos públicos usa estas vistas en lugar de las tablas.

Vista	Qué devuelve
v_en_vivo	Jugadores con presencia en los últimos 120 segundos y estado distinto de ausente, con sus datos básicos y su MMR más reciente
v_torneo_equipos	Equipos inscritos en un torneo, sin los rechazados y sin datos de quien inscribe
v_torneo_bracket	Todas las partidas del cuadro

Matchmaking

El matchmaking persiste la cola en Postgres (migraciones 21 a 24, 30 a 32) para que sobreviva a los reinicios y el emparejamiento sea transaccional. Cada fila guarda además la identidad del jugador; esas columnas no se detallan aquí.

mm_tickets.match_id no es una clave foránea: es la referencia a la partida a la que se asignó el ticket.

Modos

Modo	Jugadores por partida
duo	2 (1v1)
team	10 (5v5)

Cada ticket indica game, mode y region (por defecto EU). Un jugador solo puede tener un ticket activo por juego. El emparejador toma los primeros jugadores de la cola por orden de llegada (FIFO) y crea la partida solo si hay exactamente los necesarios, sin bloquear a otros emparejadores en paralelo.

Estados

Ticket:

Partida:

• propuesto: el emparejador creó la partida y fijó ready_deadline a 120 segundos.
• reportado y verificado: un participante reporta el marcador, se aplica el RR a cada jugador y se guardan rr_before y rr_after. Aplicar el resultado es idempotente.
• anulado: venció el plazo sin que todos confirmaran. La anulación es perezosa: la dispara el primer participante que consulta la partida después del plazo. Los tickets quedan como historial y los jugadores pueden volver a ponerse en cola.

Invitaciones

mm_invites guarda invitaciones entre jugadores para jugar duo o team. Caducan a los 10 minutos y pasan de pendiente a aceptada, rechazada, cancelada o expirada. Solo puede haber una pendiente por pareja de jugadores y juego.

Funciones

El cliente web y la app de escritorio usan las mismas funciones SQL, de modo que hay una sola fuente de verdad.

Función	Qué hace
mm_encolar	Pone al jugador en cola y devuelve su ticket, reutilizando uno vivo si existe
mm_ticket_estado	Devuelve la posición, el estado y la partida del ticket. En cola añade el total de tickets vivos y cuántos jugadores hacen falta
mm_salir	Saca al jugador de la cola
mm_listo	Confirma la participación en una partida propuesta
mm_estado_ready	Devuelve cuántos participantes están listos, el plazo y si ya venció
mm_anular_si_timeout	Anula la partida si venció el plazo sin todas las confirmaciones
mm_reportar	Reporta el marcador y aplica el RR
mm_historial_de	Devuelve el historial de RR de un jugador
mm_invitar	Envía una invitación a otro jugador, al que se localiza por su nick
mm_invites_pendientes	Lista las invitaciones pendientes
mm_responder_invite	Acepta o rechaza una invitación

La vista mm_historial reúne, por jugador, las partidas en las que participó, con su equipo, el marcador, el RR antes y después y el resultado.

Ranked y FACEIT

Escala de rango

El rango se calcula a partir del rating del jugador. El RR que se muestra es el rating multiplicado por 100.

Rating mínimo	Rango
Menos de 0.95	FUNDICIÓN (solo en la web de vants-dev-launcher)
0.95	ACERO
1.00	TITANIO
1.05	OBSIDIANA
1.11	CROMO
1.17	PLASMA
1.24	ÉTER
1.30	VANTS

La web de vants-dev-launcher muestra el rango VANTS con el nombre APEX. La web de Vantsgames no muestra estos nombres: en /ranking#rangos presenta VANTS RANKED, una escalera de 9 rangos por XP que va de CENIZA (0 XP) a SUPREMO (8000 XP) en pasos de 1000 XP. Está definida en vants-server/public/ranking.html y vants-server/public/static/js/perfil_pagina.js.

Sin rating no hay rango y el jugador está en partidas de colocación, que parten de 0.95. Las partidas de FACEIT y las internas aplican la misma regla (migraciones 10 y 22):

Resultado	Cambio de rating
Victoria	+0.015
Empate	+0.002
Derrota	-0.012

El rating siempre queda entre 0.50 y 1.60.

Series

series_ranked guarda series entre un retador y un rival. Las reporta un jugador y las confirma el rival o el propietario (pendiente, confirmada o rechazada). Al confirmarse, se aplica el Elo a players.rating y se actualizan victorias, derrotas, MMR y rango en season_player_stats. La tabla guarda el rating de ambos antes y después. Las funciones son reportar_serie, confirmar_serie, rechazar_serie y mis_series.

FACEIT

• faceit_matches: una fila por partida de FACEIT ya procesada. faceit_match_id es único, así que una partida nunca da XP dos veces. Guarda result (win, loss o draw), xp_awarded y elo_delta.
• faceit_webhook_events: eventos crudos que llegan por webhook, con su payload y la marca processed. Las funciones faceit_procesar_eventos y faceit_aplicar_resultado los convierten en partidas.

La experiencia sube +100 XP por victoria y +25 por empate; la derrota no suma. El nivel es 1 + floor(xp / 500). El procesador soporta cs2 (csgo se normaliza a cs2) y valorant.

Historial de RR

rr_historial registra cada cambio de rating, venga de donde venga.

Columna	Detalle
motivo	faceit_partida, match_interno o ajuste_manual
fuente	faceit, interno o manual
partida_id	Identificador de la partida de origen
temporada	Temporada activa en ese momento
game, mode, region	Contexto de la partida
rr_before, rr_after	RR antes y después
rr_delta	Columna generada: rr_after - rr_before

Es única por (player_id, fuente, partida_id), así que repetir una llamada no duplica líneas. Las vistas rr_historial_jugador y rr_resumen leen de ella, y rr_temporada_actual devuelve la temporada vigente.

Bus de eventos

Los proyectos de VANTS se comunican con eventos inmutables (migraciones 33 y 34). El diagrama sigue un resultado de FACEIT desde faceit_webhook_events (migración 09) hasta quienes leen el bus. En mayúsculas aparece lo que no es una tabla: FACEIT y los cursores de flask-agents y de VANTS HUB, que cada uno guarda en un archivo local.

Tabla	Para qué sirve
vants_events	Registro de eventos: id (evt_ más un ULID), type, source, ts y data en jsonb. Se conservan 30 días
vants_consumers	Posición de lectura (cursor) de cada proyecto consumidor. Ningún cliente la usa todavía: flask-agents y VANTS HUB guardan su cursor en un archivo local, y vants-consumer-playvants lo calcula a partir de vants_feed
vants_bus_dedup	Eventos ya vistos, para no procesar dos veces el mismo (por ejemplo, el webhook de FACEIT)
vants_feed	Eventos ya ordenados y listos para mostrar en la web (resultados, torneos, clips, alertas), con la marca consumed_at. Se conservan 7 días. La llena vants-consumer-playvants; la web todavía no la lee

Tipos de evento de ejemplo: match.finished, clip.published y alert.detected.

Agente

El agente vigila la plataforma y deja su trabajo en estas tablas (migraciones 25 y 26).

Tabla	Qué guarda
agent_runs	Cada ejecución: fuente (ci, api, cli o discord), modo (ciclo, informe o comando), estado global (UP, DEGRADED, DOWN o DESCONOCIDO), hallazgos, acciones y resumen
agent_events	Incidencias detectadas, con dedupe_key única, severidad (info, warn, error o critical) y estado (abierto, gestionando, resuelto o archivado)
agent_comandos	Órdenes enviadas con /agente comando, su estado (pendiente, hecho o error) y la respuesta que entrega el bot por mensaje directo
agent_memoria	Memoria del agente por clave: tipo (hecho, aprendizaje, preferencia o nota), importancia de 1 a 5 y caducidad opcional
agent_archivos	Archivos que genera el agente, únicos por ruta, con su tamaño y huella
agent_sandbox_execs	Comandos ejecutados en un entorno aislado, con su código de salida y duración

La vista agent_resumen cuenta las incidencias abiertas, los comandos pendientes y el estado de la última ejecución. La vista agent_memoria_resumen cuenta los recuerdos, los archivos y las ejecuciones.

Bot y eventos web

Tablas de la migración 02 y de la migración 01.

Tabla	Qué guarda
bot_heartbeat	Último latido del bot: last_seen, latency_ms, número de servidores y versión
bot_settings	Interruptores del bot por clave (key, enabled)
discord_channels	Canal de Discord que corresponde a cada categoría de aviso
bot_alerts	Alertas pendientes de enviar, únicas por (kind, ref_id), con su estado, intentos y error
vant_sync_events	Eventos de la web que se sincronizan con Discord, con el estado de cada intento de entrega
web_events	Eventos que la web envía al Supervisor Bot: tipo, severidad, página y estado de entrega a Discord

El detalle de los comandos del bot está en Bot de Discord.

Otras tablas

Hay además tablas en producción que ninguna migración crea. Por su nombre, parecen pertenecer a estas áreas. Revisa la base de datos antes de depender de ellas:

• Soporte: support_tickets, support_ticket_messages, tickets.
• Eventos y comunidad: events, event_rsvps, postulaciones.
• Pase y planes: pass_progreso, pass_recompensas, plan_content.
• Ranked: ranked_rules, ranked_matches, ranked_history.
• Torneos e inscripciones: tournaments, tournament_entries.

Las tablas de administración y de cuentas vinculadas son internas y no se documentan aquí.

Cómo añadir una migración

Crea un archivo nuevo en db/migrations/ con el siguiente número y escríbelo de forma idempotente. El flujo completo, con pruebas en una rama de Neon, está en VantsBasededatos.

Más información

• VantsBasededatos: estructura del repositorio y flujo de trabajo
• API pública: rutas que leen estas tablas
• Arquitectura: cómo encaja la base de datos con el resto de VANTS
• vants-faceit-webhook: origen de los eventos de FACEIT