Actualizar Strapi de v4 a v5 en producción
Strapi v5 es una versión mayor con breaking changes, con una nueva API de acceso a datos en su núcleo. Así actualicé un CMS en producción de v4 a v5 sin pérdida de contenido ni tiempo de inactividad: una ruta por etapas, 19 hooks de ciclo de vida reescritos, una base de datos clonada para ensayar y una transición que dejó producción para el final.
Los cambios de versión mayor incluyeron hooks de ciclo de vida y verificaciones de comportamiento antes de la transición a producción.
La contribución de un vistazo
- Mi responsabilidad
- Actualización por etapas de la aplicación y el runtime, cambios en los hooks de ciclo de vida y verificaciones de compatibilidad.
- Alcance
- La migración de versión mayor de una plataforma de contenido con estado.
- Colaboración y límites
- Trabajé en la compatibilidad de la aplicación y la validación del despliegue; el contenido retenido y el comportamiento existente eran restricciones de aceptación.
- Resultado
- Adapté el comportamiento del ciclo de vida y validé la compatibilidad antes de la transición; el rendimiento continuo del servicio necesita una observación aparte.
Las actualizaciones de versión mayor de una aplicación con estado y cargada de contenido son donde muere el «es solo un cambio de versión». Strapi v5 cambia el modelo de acceso a datos, así que la actualización no consiste solo en dependencias nuevas: consiste en reescribir cómo la aplicación lee y escribe su propio contenido. El contenido de la base de datos tenía que sobrevivir, y el sitio no podía caerse. Así es como lo hice.
Primero sube hasta el último v4
El primer error habría sido saltar directamente de un v4 antiguo a v5. Actualicé el código base por etapas: v4 antiguo, luego el último v4 y después v5. Llegar primero al último v4 despeja las deprecaciones y saca a la luz los breaking changes mientras todavía estás en una versión mayor conocida, de modo que el salto final a v5 es lo único que queda por depurar. El mismo paso llevó el runtime a Node 20 y cambió el driver de la base de datos por el que recibe mantenimiento.
El verdadero breaking change: el Document Service
Strapi v5 reemplaza la antigua API de datos a nivel de entidad por un nuevo Document Service, y eso toca cada pieza de lógica personalizada. La parte más pesada de la migración fue reescribir los 19 hooks de ciclo de vida a la nueva API. Los hooks de ciclo de vida son el comportamiento personalizado que se ejecuta cuando se crea, actualiza o elimina contenido, así que equivocarse en ellos es la forma de corromper datos en silencio. Cada uno se migró y se verificó de manera individual.
Ensaya sobre un clon, no en producción
Antes de tocar nada en vivo, cloné la base de datos de desarrollo en un esquema v5 aislado y ejecuté toda la migración contra ese. La migración de datos funciona sobre una copia de contenido real o no funciona; averiguarlo en un clon desechable es gratis, averiguarlo en producción no lo es.
Haz la transición por fases, producción al final
El build de v5 corría como un flujo nuevo junto al de v4 existente. Hice la transición entorno por entorno, empezando por los de menor riesgo (sandbox / legacy), validando cada uno antes de seguir. Producción se preparó y luego se mantuvo en espera, con la transición hecha solo tras una aprobación explícita. En ningún momento hubo un único cambio de golpe sin vuelta atrás.
La actualización también lo hizo más resiliente
Trabajar tan de cerca con la aplicación sacó a la luz una fragilidad latente: los pods entraban en crash-loop cuando el upstream del CMS tenía un breve fallo, y una ráfaga de tráfico a un endpoint podía saturarlo. Agregué un manejador de errores compartido en cada manejador de solicitudes y endurecí el pool de conexiones de la base de datos frente a fallos de red transitorios, además de alertas de uptime. La actualización dejó el servicio no solo más nuevo, sino más difícil de tumbar.
Lo que le diría a alguien que empieza esto
- Sube hasta la última versión menor de tu versión mayor actual antes del gran salto. Despeja las deprecaciones donde el terreno es conocido.
- Trata el cambio de la API de acceso a datos como el trabajo real. En Strapi v5 eso es el Document Service y cada hook de ciclo de vida, no la simple actualización de dependencias.
- Ensaya la migración de datos sobre un clon de contenido real. Una copia te dice la verdad gratis.
- Haz la transición por fases y deja producción para el final, detrás de una aprobación explícita. Ejecuta el flujo nuevo junto al antiguo para que siempre haya una vuelta atrás.
Decisiones y próximos pasos
Una mirada retrospectiva al enfoque y sus límites. La próxima mejora es una propuesta, no un resultado entregado.
Alternativa y justificación
Un salto directo de versión mayor combina deprecaciones y el nuevo comportamiento de la API. Llegar primero al último v4 aísla parte de ese riesgo.
Concesión
Los cambios en la API de acceso a datos pueden preservar la salud HTTP mientras cambian el comportamiento del negocio. Valida el contenido y los hooks, no solo el arranque.
Lo que mejoraría a continuación
Próxima mejora: mantener contenido representativo y verificaciones de regresión del ciclo de vida para las actualizaciones posteriores.