# Bases de datos

## Para qué sirve

Con **Bases de datos** ves la salud y el rendimiento de tus bases: cuántas conexiones usan, qué tan rápido responden, si hay bloqueos, cuánto espacio ocupan y cuáles son las consultas más lentas. No instalás nada en la base: un [gateway](https://lymen.app/docs/instalacion/gateways/) de tu red (o el gateway de un [cluster de Kubernetes](https://lymen.app/docs/instalacion/kubernetes/#bases-de-datos)) se conecta con un usuario de solo lectura y lee sus estadísticas internas cada cierto tiempo.

Soporta cuatro motores:

| Motor | Puerto de fábrica | Qué pide como "nombre de la base" |
|---|---|---|
| **PostgreSQL** | 5432 | **Base de datos**: la base a la que se conecta el agente. |
| **MySQL** (y MariaDB) | 3306 | **Base de datos**. |
| **SQL Server** | 1433 | **Base de datos**. |
| **Oracle** | 1521 | **Servicio**: el nombre del servicio (service name). |

## Cuándo usarlo

- Querés saber si una base se está quedando sin conexiones, sin espacio o sin memoria de caché.
- Querés ver cuáles son las consultas más lentas sin entrar a la base.
- Tu base está en Azure o AWS y querés ver, junto a las métricas de SQL, su CPU, su memoria y su almacenamiento (ver [Vínculo automático con la nube](#vinculo-automatico-con-la-nube)).

## Requisitos

- Un gateway que alcance la base por la red: un servidor con el agente 0.3.7 o más nuevo, o un cluster con el operador 0.3.5 y el agente 0.3.8 (ver [Gateways](https://lymen.app/docs/instalacion/gateways/)). Una misma instalación mide hasta 50 bases por servidor.
- Un **usuario de monitoreo de solo lectura** en la base (ver [Crear el usuario de monitoreo](#crear-el-usuario-de-monitoreo)).
- Ese usuario y su clave guardados en el [Llavero](https://lymen.app/docs/operacion/llavero/) como una credencial de tipo **Usuario y clave**. Si preferís que la clave nunca pase por Lymen, guardala con el alcance **Solo en tu red** sellada para el gateway que mide la base (hace falta el agente 0.3.8 o más nuevo).
- El permiso **Bases de datos › Administrar** para agregar, editar o eliminar. Con **Bases de datos › Ver** se miran.

## Crear el usuario de monitoreo

Pedile a quien administra la base que cree un usuario propio para Lymen, **de solo lectura**. Lymen ejecuta consultas fijas que solo leen las vistas de estadísticas del motor (nunca lee el contenido de tus tablas) y fija la conexión en modo de solo lectura donde el motor lo permite. Los permisos de abajo son los mínimos que necesitan esas consultas. Reemplazá `...` por una clave segura.

Si falta algún permiso, la base igual se mide: solo faltan las señales que ese permiso daba, y la pantalla avisa **La credencial no tiene todos los permisos: faltan algunas señales.**

### PostgreSQL

```sql
CREATE ROLE lymen_monitor LOGIN PASSWORD '...';
GRANT pg_monitor TO lymen_monitor;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```

- `pg_monitor` da la lectura de `pg_stat_activity`, `pg_stat_statements` y `pg_stat_replication`.
- En **Azure Database for PostgreSQL**, la extensión primero se habilita en el parámetro del servidor `azure.extensions` (agregá `pg_stat_statements` a la lista, desde el portal de Azure o con la CLI) y **recién después** se corre el `CREATE EXTENSION` en la base. Sin ese primer paso, el `CREATE EXTENSION` falla.
- `pg_stat_statements` se necesita para las **consultas más lentas** y las latencias. Corré el `CREATE EXTENSION` en la base a la que se conecta Lymen y, si PostgreSQL no la tiene cargada, agregá `pg_stat_statements` a `shared_preload_libraries` y reiniciá el servicio (lo pide el propio PostgreSQL). Sin la extensión, esas señales quedan vacías y el resto sigue andando.

### MySQL y MariaDB

```sql
CREATE USER 'lymen_monitor'@'%' IDENTIFIED BY '...';
GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO 'lymen_monitor'@'%';
```

- `SELECT` alcanza para leer `performance_schema` (consultas lentas y latencia) e `information_schema` (tamaño por esquema).
- `PROCESS` da la espera más vieja de un bloqueo.
- `REPLICATION CLIENT` da el estado de la réplica.
- `performance_schema` tiene que estar activo (lo está de fábrica desde MySQL 5.7). La latencia p95 se calcula desde MySQL 8.0; en versiones anteriores y en MariaDB no se muestra.

### SQL Server

```sql
CREATE LOGIN [lymen_monitor] WITH PASSWORD = '...';
GRANT VIEW SERVER STATE TO [lymen_monitor];
USE [<tu_base>];
CREATE USER [lymen_monitor] FOR LOGIN [lymen_monitor];
ALTER ROLE db_datareader ADD MEMBER [lymen_monitor];
```

- `VIEW SERVER STATE` da las vistas de rendimiento del servidor (sesiones, contadores, consultas, esperas y replicación Always On).
- El usuario de la base y `db_datareader` dan acceso al catálogo para calcular los tamaños. Lymen no lee tus tablas.
- El texto de las consultas lentas se limpia en el propio agente: los valores (textos entre comillas y números) se reemplazan por `?` antes de salir de tu red.

### Oracle

```sql
CREATE USER lymen_monitor IDENTIFIED BY "...";
GRANT CREATE SESSION TO lymen_monitor;
GRANT SELECT_CATALOG_ROLE TO lymen_monitor;
```

- `CREATE SESSION` permite conectarse.
- `SELECT_CATALOG_ROLE` da la lectura de las vistas `V$` y `DBA_*` que usan las métricas.
- En Oracle, el **Servicio** es el nombre del servicio de la base y el almacenamiento se informa **por tablespace**. Los valores de las consultas lentas también se reemplazan por `?`.

## Paso a paso

1. Creá el usuario de monitoreo en tu base (ver arriba).
2. En el [Llavero](https://lymen.app/docs/operacion/llavero/), creá una credencial de tipo **Usuario y clave** con ese usuario.
3. En el menú, andá a **Mirar › Infraestructura › Bases de datos** y tocá **Agregar base**.
4. Completá el diálogo **Agregar base de datos** (ver la tabla de campos).
5. Tocá **Guardar**. El botón se habilita cuando no falta nada; mientras tanto, el diálogo dice qué falta (por ejemplo, *Falta el host* o *Elegí una credencial*).
6. En el primer intervalo la base aparece con su salud y sus métricas. Si no responde, la lista dice **Crítica** y el detalle, **La base no responde.**

Si no hay gateways, el diálogo lo avisa y ofrece **Agregar datos** para instalar uno. Si no hay credenciales de tipo usuario y clave, ofrece **Crear en el Llavero**. La clave nunca se escribe ni se muestra en esta pantalla.

## Campos del diálogo

| Campo | Para qué sirve | Valor de fábrica | Valores válidos | Impacto de cambiarlo |
|---|---|---|---|---|
| **Motor** | Qué tipo de base es. | PostgreSQL | PostgreSQL, MySQL, SQL Server, Oracle | Cambia el puerto de fábrica (si no lo tocaste) y el nombre del campo siguiente. Con el motor equivocado la conexión falla. |
| **Nombre** | Cómo la ves en Lymen. | Vacío | Hasta 80 caracteres | Solo cambia lo que se muestra. |
| **Host** | Dirección de la base, por ejemplo `db-prod.miempresa.local`. | Vacío | Sin espacios, hasta 253 caracteres | Si es el de una base administrada de Azure o AWS, Lymen la vincula sola con su recurso (ver abajo). |
| **Puerto** | Puerto de la base. | El del motor | 1 a 65535 | Un puerto equivocado impide medir la base. |
| **Base de datos** / **Servicio** | La base a la que se conecta el agente (en Oracle, el nombre del servicio). | Vacío | Texto | En Azure SQL, también sirve para vincular la base con su recurso. |
| **Conexión cifrada (TLS)** | Cifra la conexión entre el gateway y la base. | Encendido | Encendido / apagado | Apagalo solo si la base no acepta conexiones cifradas: apagado, la clave y los datos viajan sin cifrar por tu red. |
| **Credencial del Llavero** | Usuario y clave de monitoreo. | Ninguna | Credenciales de tipo usuario y clave. Las de **Solo en tu red** aparecen cuando elegís el gateway donde están selladas. | Cambiarla cambia el usuario con el que se mide. |
| **Gateway que la monitorea** | Quién la mide: un gateway de un servidor o el gateway de un cluster de Kubernetes. | Ninguno | Gateways disponibles. Un cluster con operador o agente anteriores aparece deshabilitado, con el motivo. | Cambiarlo hace que otro gateway tome la medición: tiene que alcanzar la base por la red. |
| **Intervalo de refresco** | Cada cuánto se mide. | 1 minuto | 1 a 1.440 minutos | Menos minutos dan más detalle y más consultas contra tu base. |
| **Ambiente** | Prod, QA o Desarrollo. | El ambiente elegido arriba en el portal, o Prod | Prod, QA, Desarrollo | Ver [Ambientes](https://lymen.app/docs/operacion/ambientes/). |

Para editar, abrí la base y tocá el lápiz; para borrarla, el tacho. Eliminar una base deja de medirla y borra su configuración del gateway; las métricas ya guardadas no se borran. También podés ponerle [etiquetas y nivel](https://lymen.app/docs/datos/etiquetas/) desde su detalle.

## Qué se ve

La lista **Bases de datos** muestra, por base: su salud (**Funcionando**, **Atención**, **Crítica** o **Sin datos**), el motor, el host (parcialmente oculto), las conexiones, la latencia y el retraso de réplica. Se filtra por motor, estado y etiqueta.

El detalle muestra, para el período elegido (hasta 31 días):

| Métrica | Qué es |
|---|---|
| **Conexiones activas** | Cuántas conexiones hay, contra el máximo que permite la base. |
| **Cache hit** | Qué porcentaje de lecturas se resuelve en memoria. |
| **Transacciones por segundo** | Cuántas transacciones procesa. |
| **Latencia promedio** y **Latencia p95** | Cuánto tardan las consultas. La p95 es aproximada (en Oracle no se informa). |
| **Locks esperando** | Sesiones esperando un bloqueo, con la espera más vieja. |
| **Deadlocks** | Bloqueos cruzados acumulados. |
| **Disco usado** | Espacio que ocupa la base. |
| **Retraso de replicación** | Solo si la base es una réplica o tiene réplicas. Si no, se ve "—". |
| **Consultas más lentas** | El texto de cada consulta (con los valores ocultos), su tiempo promedio, cuántas veces corrió y su tiempo total. |
| **Almacenamiento por esquema** (por *tablespace* en Oracle) | Tamaño, crecimiento y cantidad de tablas. |

Un valor que no aplica en tu motor o versión se ve como "—". Arriba del detalle, **Alertas activas** avisa de lo que pide atención: la base no responde, conexiones al 80 % o más del máximo, réplica atrasada 30 segundos o más, sesiones esperando un bloqueo o permisos faltantes. Para que te avisen por mail o Telegram, armá una [regla de alerta](https://lymen.app/docs/operacion/reglas-de-alerta/).

## Vínculo automático con la nube

Si tu base es de Azure o AWS, hay datos que no se ven por SQL: CPU, memoria, IOPS y almacenamiento del plan. Los mide la nube. Para verlos, conectá la cuenta en [Azure](https://lymen.app/docs/instalacion/nube-azure/) o AWS (**Ajustes › Conectar › Integraciones › Nubes**). **Lymen vincula la base sola con su recurso** mirando únicamente su **host**:

| Si el host es… | Lymen busca… |
|---|---|
| `<nombre>.postgres.database.azure.com` (con o sin `privatelink`) | El servidor PostgreSQL de Azure llamado `<nombre>`. |
| `<nombre>.mysql.database.azure.com` (con o sin `privatelink`) | El servidor MySQL de Azure llamado `<nombre>`. |
| `<servidor>.database.windows.net` (con o sin `privatelink`) | La base de Azure SQL del servidor `<servidor>` cuyo nombre es la **Base de datos** que cargaste. |
| `<identificador>.<código>.<región>.rds.amazonaws.com` | La instancia o el cluster de RDS o Aurora con ese identificador y esa región. |

Lymen vincula solo cuando encuentra **exactamente un** recurso que coincide con el host y el motor, entre todas tus cuentas conectadas. Si no hay ninguno o hay más de uno, no vincula. Si cambiás el host de la base, el vínculo se corrige solo; si la base deja de coincidir, se quita.

Cuando hay vínculo, el detalle de la base muestra **arriba de todo** el bloque **Infraestructura (Azure)** o **Infraestructura (AWS)**, con la marca **Detectado por el host**, el nombre del recurso, la cuenta y los gráficos de CPU, memoria y almacenamiento, más los botones **Abrir en Azure** (o AWS) y **Ver todas las métricas**.

Si todavía no hay vínculo, ves **¿Esta base está en la nube?** con dos botones:

- **Conectar nube**: te lleva a **Integraciones › Nubes** para conectar la cuenta.
- **Vincular a mano**: solo para bases que se conectan por **IP o por un DNS propio**, donde el host no dice dónde está. Elegís la cuenta y un recurso del mismo motor. Un vínculo manual se puede **Desvincular**; el automático no hace falta tocarlo. El recurso se sigue monitoreando en **Nubes** y lo ya guardado no se borra.

Si el recurso de la nube todavía no se monitoreaba, vincularlo lo suma al monitoreo y agrega series a tu plan: el diálogo te dice cuántas.

## Registro de conexión

En el detalle de cada base, la tarjeta **Registro de conexión** guarda cada intento de conexión y cada cambio de estado hasta que la base queda bien. Sirve para saber qué falló y cuándo, sin entrar al gateway. Cada entrada es una de estas:

| Estado | Qué significa |
|---|---|
| **Sin conexión** | No se pudo conectar. Dice el motivo: DNS (no resuelve el host), red, timeout, TLS, usuario o clave, o base inexistente. |
| **Parcial** | Se conecta, pero hay señales que no se leen. Dice cuáles y por qué: falta un permiso, falta una extensión o la consulta tardó demasiado (timeout). |
| **OK** | Se conecta y se leen todas las señales. |

Cada problema trae una **sugerencia para corregirlo, según el motor** (por ejemplo, el `GRANT` que falta o la extensión que hay que crear). Mientras la base siga con problemas, Lymen repite un **recordatorio cada 15 minutos** en el registro.

**Qué necesitás:** el Registro de conexión lo manda el agente 0.3.9 o más nuevo del gateway que mide la base (en Kubernetes, el operador 0.3.6, que despliega el agente 0.3.9; ver [Kubernetes](https://lymen.app/docs/instalacion/kubernetes/#bases-de-datos)). Con un agente anterior la tarjeta queda vacía y solo ves el aviso general de arriba del detalle. Los requisitos para medir la base no cambian.

El aviso de arriba del detalle dice exactamente qué falta. Por ejemplo: *No se pueden leer latencias ni consultas lentas: falta la extensión pg_stat_statements.*

Los registros son logs con `lymen.evento = "base_datos.conexion"`, así que también los podés consultar con [LQL](https://lymen.app/docs/datos/lql/):

```
from logs where attrs["lymen.evento"] = "base_datos.conexion"
```

## Problemas comunes

| Qué pasa | Por qué | Qué hacer |
|---|---|---|
| La base figura **Crítica**: "La base no responde." | El gateway no llega a la base (host, puerto, firewall), la clave es incorrecta o TLS no coincide. | Revisá desde el gateway que alcance el host y el puerto; revisá el usuario del Llavero y la opción de TLS. |
| "La credencial no tiene todos los permisos: faltan algunas señales." | Al usuario le falta algún permiso o la extensión (por ejemplo `pg_stat_statements`). | Aplicá los permisos de [Crear el usuario de monitoreo](#crear-el-usuario-de-monitoreo). |
| Latencia o consultas lentas vacías en PostgreSQL | Falta la extensión `pg_stat_statements`. | Creala y, si hace falta, cargala en `shared_preload_libraries`. |
| El cluster aparece deshabilitado en **Quién la mide** | Su operador es anterior a 0.3.5 o su agente a 0.3.8. | Actualizá el cluster (ver [Kubernetes](https://lymen.app/docs/instalacion/kubernetes/#como-se-actualiza)). |
| "El gateway que medía esta base se quitó" | Quitaste ese gateway. | Editá la base y elegí otro gateway. |
| No aparece la infraestructura de la nube | El host no es el de un recurso reconocido, no hay cuenta conectada o hay más de un recurso posible. | Conectá la cuenta, o usá **Vincular a mano** si el host es una IP o un DNS propio. |
| Alguien cambió la base mientras la editabas | Otra persona guardó antes. | Cerrá y volvé a abrir. |
