# Actualizaciones, respaldos y retención

> Cómo actualizar un motor con alojamiento propio sin perder datos, qué respaldar y cómo restaurarlo, y cómo elegir cuánto tiempo se guarda cada tipo de dato.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/self-hosting/upgrades-backups-retention/

Para agentes: Operar en el tiempo un motor de Sypnia con alojamiento propio: el orden de una actualización (registro de cambios, respaldar Postgres, sypnia migrate, reemplazar el motor, sypnia doctor), qué prometen las reglas de compatibilidad, cómo volver atrás, qué hay que respaldar (Postgres) y qué se puede reconstruir desde el bucket con sypnia aggregate --from, los pasos para restaurar, y los cinco ajustes de retención con lo que hace cambiarlos.

**\[Motor]** Esta página es para quien mantiene corriendo un motor con alojamiento propio después del primer día. En Sypnia Cloud los tres trabajos son nuestros: nosotros actualizamos, nosotros respaldamos, y tu plan define la retención.

## Actualizaciones

### Qué puede cambiar una actualización

El motor está hecho para que una actualización dentro de la versión 1 sea aburrida. Estas reglas son parte de su contrato:

| Regla                                                                                   | Qué significa para ti                                                                                                                                            |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Las migraciones de la base de datos solo agregan.                                       | Un motor más viejo sigue funcionando contra un esquema más nuevo. Puedes migrar primero, reemplazar el motor después, y volver atrás sin tocar la base de datos. |
| La API dentro de `/v1` solo agrega.                                                     | Los scripts, la CLI, el servidor MCP y tu agente de código siguen funcionando.                                                                                   |
| Los eventos crudos conservan los campos que el motor no conoce.                         | Un SDK más nuevo nunca rompe un motor más viejo. Actualiza el motor y tus apps en cualquier orden.                                                               |
| Una variable `SYPNIA_…` desconocida es una advertencia en `sypnia doctor`, no un error. | Un ajuste que cambió de nombre o se quitó no detiene una actualización. El [registro de cambios](https://docs.sypnia.com/es/reference/changelog) lo nombra.      |
| El procesamiento se puede repetir sin riesgo.                                           | Un worker que muere a mitad de una actualización no pierde nada ni cuenta nada dos veces.                                                                        |

Un cambio que rompa alguna de estas sería la versión 2, anunciada en el registro de cambios, nunca una sorpresa dentro de la versión 1.

Qué versión corres: `sypnia version`, o el encabezado `Sypnia-Version` de cualquier respuesta de la API. La etiqueta de imagen `ghcr.io/sypnia/sypnia:1` sigue la última publicación de la versión 1. Para decidir tú cuándo ocurre cada actualización, usa una etiqueta exacta como `ghcr.io/sypnia/sypnia:1.0.0` y cámbiala a mano.

### Actualizar

**Al final tendrás:** la versión nueva corriendo, los mismos datos, y un respaldo tomado justo antes.

**AWS**

Sigue [Actualizar el motor](https://docs.sypnia.com/es/self-hosting/deploy-aws#actualizar-el-motor) en la página de AWS: lee el registro de cambios, actualiza el comando y la plantilla, corre `sypnia migrate`, despliega. Antes, toma una instantánea de la base de datos:

```bash
aws rds create-db-snapshot \
  --db-instance-identifier <DatabaseIdentifier> \
  --db-snapshot-identifier sypnia-before-upgrade-$(date +%F)
```

La ingesta no se detiene: las funciones viejas responden hasta que las nuevas están listas.

**Docker**

### 1. Lee qué cambió

El [registro de cambios](https://docs.sypnia.com/es/reference/changelog) dice qué cambia cada versión y si te pide algo.

### 2. Respalda la base de datos

```bash
docker compose exec -T db pg_dump -U sypnia -Fc sypnia > sypnia-before-upgrade-$(date +%F).dump
ls -lh sypnia-before-upgrade-*.dump
```

**Deberías ver:**Un archivo de unos pocos megabytes a unos pocos gigabytes, según tu tráfico.

### 3. Trae la imagen nueva y reinicia el motor

```bash
docker compose pull sypnia
docker compose up -d sypnia
docker compose logs --tail 20 sypnia
```

**Deberías ver:**

El motor aplica sus migraciones al arrancar, porque `SYPNIA_AUTO_MIGRATE` está en `true`, y luego dice que está listo:

```text
schema 12 -> 13
applied 0013_…  (0.3 s)
sypnia 1.1.0  role=all  listen=0.0.0.0:8080
ready     https://sypnia.example.com
```

### 4. Comprueba

```bash
docker compose exec sypnia sypnia doctor --skip ai
```

**Deberías ver:**`all checks passed`.

El motor se ausenta unos segundos mientras el contenedor reinicia. Los SDK guardan sus eventos y reintentan a los 1, 4 y 15 segundos, así que un reinicio de esa duración no pierde nada.

Si corres varios procesos con `SYPNIA_AUTO_MIGRATE` en `false`, migra una vez antes de reiniciar cualquiera, y luego reinícialos de a uno:

```bash
docker compose run --rm sypnia sypnia migrate
```

### Volver atrás

Arranca otra vez la versión anterior: la etiqueta de imagen anterior, o la plantilla anterior. Deja la base de datos como está. El motor más viejo funciona contra el esquema más nuevo, y lo que llegó entre tanto se conserva.

No restaures un respaldo de la base de datos para deshacer una actualización. Una restauración es para una base de datos perdida o dañada, y descarta todo lo que las personas hicieron desde el respaldo.

## Respaldos

### Qué necesita uno

| Datos                                                                                                                                 | Dónde                                         | ¿Se puede reconstruir?                                              | ¿Respaldarlo?                                                |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ |
| Proyectos, llaves de ingesta, tokens de API, configuración de proyectos, reglas de alerta, webhooks, comprobaciones de disponibilidad | Postgres                                      | No                                                                  | **Sí**                                                       |
| Lo que hicieron las personas: problemas resueltos o ignorados, notas, alertas reconocidas                                             | Postgres                                      | No                                                                  | **Sí**                                                       |
| Los análisis del agente                                                                                                               | Postgres                                      | Solo corriendo el agente otra vez, lo que cuesta llamadas al modelo | **Sí**                                                       |
| Los conteos de los problemas, el índice de sesiones, los números de rendimiento, el índice de trazas                                  | Postgres                                      | Sí, desde `events/` en el bucket, mientras los eventos se conserven | Viene con el mismo respaldo                                  |
| Eventos crudos, archivos por sesión, grabaciones, capturas de página                                                                  | Bucket                                        | No. Son la fuente                                                   | Tú decides, ver abajo                                        |
| Source maps                                                                                                                           | Bucket                                        | Sí: tu CI los vuelve a subir en la próxima compilación              | No                                                           |
| La configuración del motor y el token raíz                                                                                            | Tu archivo `.env`, o los parámetros del stack | No                                                                  | **Sí**, en un gestor de contraseñas o un almacén de secretos |

Así que la regla es corta: **respalda Postgres todos los días, y guarda la configuración en un lugar seguro.** Un respaldo de la base de datos es pequeño, porque los eventos crudos nunca están ahí.

El bucket es otra decisión. Un almacenamiento alojado, como Amazon S3 o Cloudflare R2, ya guarda varias copias de cada objeto; la mayoría se queda ahí. Un MinIO en un solo disco, como en el archivo de Compose, es un solo disco: si muere, los eventos crudos y las grabaciones se pierden, y Sypnia conserva solo lo que tiene Postgres. Si eso te importa, copia el bucket a otro lugar con una programación, o usa un almacenamiento alojado.

### Respaldar Postgres

**AWS**

AWS respalda todos los días la base de datos que crea la plantilla, y cada respaldo se guarda 7 días. También puedes volver a cualquier minuto de esos 7 días. No hay nada que configurar. Para comprobarlo:

```bash
aws rds describe-db-instances --db-instance-identifier <DatabaseIdentifier> \
  --query "DBInstances[0].[BackupRetentionPeriod,LatestRestorableTime]"
```

**Deberías ver:**`7` y una hora de hace pocos minutos.

Si trajiste tu propio Postgres, sus respaldos son de tu proveedor o tuyos.

**Docker**

Agrega una línea al `crontab` del servidor. Escribe un volcado cada noche a las 03:00 y borra los volcados de más de 14 días.

```bash
0 3 * * * cd /opt/sypnia && docker compose exec -T db pg_dump -U sypnia -Fc sypnia > backups/sypnia-$(date +\%F).dump && find backups -name 'sypnia-*.dump' -mtime +14 -delete
```

Luego copia `backups/` fuera del servidor, con lo que ya uses. Un respaldo que vive en el mismo disco que la base de datos protege de un error, no de perder el disco.

### Restaurar

**Al final tendrás:** la base de datos como estaba en el respaldo, más todo lo que se puede reconstruir a partir de los eventos que llegaron desde entonces.

### 1. Detén el motor

```bash
docker compose stop sypnia
```

Los SDK siguen reintentando un rato corto; lo que no pueden retener se pierde. Una restauración no es una operación de rutina.

### 2. Restaura el volcado

```bash
docker compose exec -T db pg_restore -U sypnia -d sypnia --clean --if-exists < backups/sypnia-2026-03-12.dump
```

**Deberías ver:**Sin errores. En AWS, restaura la instantánea o el punto en el tiempo a una instancia nueva, y dale su dirección al stack como `DatabaseUrl`.

### 3. Arranca el motor y comprueba

```bash
docker compose start sypnia
docker compose exec sypnia sypnia doctor --skip ai
```

**Deberías ver:**`all checks passed`. Si el respaldo es más viejo que el motor, el motor lo migra al arrancar.

### 4. Procesa otra vez lo que llegó después del respaldo

El bucket todavía tiene todos los eventos. Dile al worker que los lea otra vez desde la hora del respaldo:

```bash
docker compose exec sypnia sypnia aggregate --from 2026-03-12T03:00:00Z
```

**Deberías ver:**

```text
shop  events 48211 -> 361 sessions, 4 problems (1 new), 22 routes   9.4 s
done in 11.0 s, data through 2026-03-12T16:20:05Z
```

Lista el bucket para ese rango, así que también encuentra eventos de los que la base de datos restaurada nunca supo. Correrlo dos veces no hace daño.

Lo que una restauración no puede traer de vuelta es lo que las personas escribieron después del respaldo:

- Un problema resuelto o ignorado desde entonces vuelve a estar abierto.
- Las llaves de ingesta y los tokens de API creados desde entonces ya no existen. Las apps que los usan son rechazadas: créalos otra vez y despliega.
- Un problema visto por primera vez desde entonces es nuevo otra vez, así que **vuelve a alertar**, y tu webhook lo recibe una segunda vez.
- Los análisis escritos desde entonces se corren otra vez cuando su problema crece, o cuando lo pides.

Prueba una restauración una vez, sobre una copia, antes del día en que la necesites.

### Si se pierde el bucket

Postgres todavía tiene cada problema, su frase y sus conteos, y todos los números. Las sesiones siguen en la lista y responden `410 expired` al abrirlas, porque sus archivos ya no están. Apunta el motor a un bucket nuevo y vacío, corre `sypnia doctor`, y los datos nuevos fluyen. Los source maps vuelven con tu próxima compilación.

## Retención

El motor borra por su cuenta los datos viejos, una vez al día. Tú eliges el número de días para cada tipo; el bucket no necesita ninguna regla para eso.

| Datos                                                                                   | Por defecto                                       | Ajuste                                                   |
| --------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------- |
| Eventos crudos, sesiones con sus líneas de tiempo, trazas, los archivos Parquet diarios | 90 días                                           | `SYPNIA_RETENTION_EVENTS_DAYS` (1 a 3650)                |
| Grabaciones                                                                             | 30 días                                           | `SYPNIA_RETENTION_REPLAYS_DAYS` (no más que los eventos) |
| Capturas de página                                                                      | 90 días                                           | `SYPNIA_RETENTION_SNAPSHOTS_DAYS`                        |
| Números por hora y por día: rendimiento, mapas de clics, uso, disponibilidad            | 400 días                                          | `SYPNIA_RETENTION_NUMBERS_DAYS`                          |
| Source maps                                                                             | 90 días desde la última vez que se vio la versión | `SYPNIA_RETENTION_SOURCEMAPS_DAYS`                       |
| Problemas: la frase, el análisis, el estado, los conteos diarios y un ejemplo           | Mientras exista el proyecto                       | Ninguno                                                  |
| Proyectos, llaves, tokens, configuración                                                | Hasta que los elimines                            | Ninguno                                                  |

Cómo funciona:

- La edad de una sesión se cuenta desde su último evento. Los datos se borran dentro de las 24 horas siguientes a pasar su edad.
- Los ajustes son para todo el motor. Un motor con alojamiento propio no tiene retención por proyecto; `GET /v1/usage` devuelve la retención que aplica.
- Un problema vive más que las sesiones que afectó. Eso es lo que le permite a Sypnia decir «volvió» meses después. Sus sesiones, grabaciones y trazas enlazadas vencen cada una a su tiempo.
- Después de eso, pedir datos vencidos responde `410 expired`, no un resultado vacío.

### Cambiarla

Pon la variable y reinicia el motor. En AWS, agrega la línea a la plantilla como en [Cambiar un ajuste](https://docs.sypnia.com/es/self-hosting/deploy-aws#cambiar-un-ajuste).

```bash
SYPNIA_RETENTION_EVENTS_DAYS=30
SYPNIA_RETENTION_REPLAYS_DAYS=14
```

- **Más corta:** todo lo que sea más viejo que el número nuevo se borra en la siguiente limpieza diaria. No se puede deshacer, salvo desde un respaldo.
- **Más larga:** los datos se guardan más tiempo de ahora en adelante. Lo que ya se borró no vuelve.

Para correr la limpieza ahora en vez de esperar la diaria:

```bash
sypnia aggregate --task retention
```

### Cómo elegir

- **Las grabaciones son lo que más espacio cuesta** y lo que más rápido envejece: una grabación sirve mientras el problema está fresco. De 14 a 30 días le alcanza a la mayoría de los equipos. Ver [Estructura del almacenamiento](https://docs.sypnia.com/es/self-hosting/storage-layout#qu%C3%A9-tan-grande-se-pone).
- **Los eventos** son lo que te permite reconstruir la base de datos y abrir la línea de tiempo de una sesión vieja. Guárdalos al menos tanto como tu respaldo más viejo de la base de datos.
- **Los números** son pequeños y no guardan nada sobre personas. Guardarlos un año te deja comparar este mes con el mismo mes del año pasado.
- **Datos personales.** Las grabaciones, las sesiones y los nombres que tu app envió con `identify()` son datos personales. Guárdalos solo el tiempo que puedas justificar. Para eliminar antes a una persona o una sesión, ver [Eliminar datos](https://docs.sypnia.com/es/privacy/deleting-data).

### Lo que la retención no cubre

- **Tus respaldos.** Un volcado de la base de datos conserva lo que se borró después, hasta que el volcado mismo se borra. No guardes respaldos por más tiempo del que deben vivir los datos que contienen.
- **Los logs.** El motor escribe logs en la salida estándar y nunca registra cuerpos, llaves ni tokens. Cuánto se guardan depende de quien los recoja: Docker, CloudWatch (30 días en la plantilla de AWS), tu propio recolector. Los logs del proxy que está delante del motor guardan direcciones IP.
- **Las versiones del bucket.** Si encendiste el versionado, las versiones viejas sobreviven a los borrados del motor hasta que una regla tuya las quite.

## Relacionado
