Gestión de cambios en la base de datos durante las actualizaciones de módulos en PrestaShop

Hay un tipo de incidencia de soporte que me da pavor. Un comerciante actualiza un módulo; parece que todo va bien, pero luego algo deja de funcionar. Nunca falla toda la tienda. Puede ser una página del controlador de PrestaShop que no funciona correctamente, un valor de configuración que no se guarda o una columna de listado que se vacía sola. Cuando reviso, el código del módulo está en la nueva versión, pero la base de datos subyacente sigue en la antigua.

Este artículo trata precisamente de esa discrepancia. Un módulo de PrestaShop no solo incluye el código PHP que se distribuye, sino también las tablas y columnas que espera encontrar. Si se omite la actualización de la base de datos de PrestaShop, que debería incluirse en cada lanzamiento de código, el resultado es un módulo instalado, aparentemente funcional, pero con un error oculto.

Me he hecho esto a mí mismo más de una vez. Lo que sigue es lo que aprendí sobre Actualizaciones de la base de datos del módulo PrestaShop, por las malas.

1.0 Cómo gestionan las actualizaciones de los módulos de PrestaShop la base de datos

Aquí circulan muchas suposiciones, y algunas son erróneas.

Coloca una nueva versión en /módulos/ y su rutina de instalación no se vuelve a ejecutar. Las tablas permanecen intactas. Lo que sucede en su lugar: PrestaShop lee el módulo mejorar/ carpeta, encuentra los archivos llamados mejora- .php Se sitúa entre la versión grabada y la que declara la clase de tu módulo, y las ejecuta en orden.

Una tienda en la versión 1.9.0 que recibe la versión 2.1.0 ejecuta tres scripts, en orden.

De eso se derivan tres cosas, y las tres son importantes para Cambios en la base de datos de PrestaShop.

La versión que aparece en la tabla `module` es la fuente de verdad. No es el que está en tu archivo de clase principal. PrestaShop lee ambos. Actúa sobre el que está registrado, y ese es el que determina cuántos scripts de actualización vas a ejecutar.

El método `install()` es solo para instalaciones nuevas. Digamos que la versión 2.0 necesita una nueva tabla. Colóquela en instalar() Y cualquiera que actualice a la versión 2.0 desde cero estará cubierto. La tienda que todavía usa la versión 1.9 no recibirá nada, porque su instalación se ejecutó hace un año y ya no se ejecutará.

Un solo fallo lo paraliza todo. Devoluciones false Al ejecutar una función de actualización, ocurren tres cosas: PrestaShop se detiene, registra qué versión falló y desactiva el módulo. No se puede continuar con el siguiente script. Esto es intencional, aunque significa que un cambio de esquema aplicado parcialmente deja el sistema deshabilitado en lugar de dañado.

El habilitar la actualización automática para los módulos Esta página describe las reglas para nombrar archivos. Léala bien una vez, en lugar de memorizarla.

La trampa de nombres de la función de actualización

Este me costó una tarde. O actualización_módulo_2_0_1 or Módulo de actualización 201 funciona como nombre de función, y PrestaShop busca ambos. Además, antes de incluir tu archivo, comprueba si alguno de esos nombres ya existe. Si lo encuentra, el archivo se marca como duplicado y se omite.

Copiar un script de actualización antiguo como plantilla es precisamente la forma en que la gente llega a este punto. El nombre que contiene nunca se modifica. No se actualiza nada y el mensaje de error no proporciona mucha información.

Migración de la base de datos de PrestaShop 2.0: ¿qué falla en las tiendas reales?

Todo esto ocurrió en las tiendas en las que trabajé.

Cambios en el esquema de la base de datos de PrestaShop que varían entre instalaciones

La versión 2.0 necesita una nueva columna, así que actualice instalar() y escribir un script de actualización. Ambas correctas. Tres versiones después, alguien cambia el nombre de la carpeta del módulo o un comerciante lo reinstala. En algunas instalaciones, install() creó esa columna. En otras, lo hizo la ruta de actualización. Dos definiciones que se distancian, y ahora un único número de versión las abarca a ambas.

Por lo tanto, la definición reside en un único método al que llaman ambas rutas. Los cambios en el esquema de la base de datos de PrestaShop no pueden variar si solo existe uno.

Scripts de actualización que parten de un punto de partida limpio

MODIFICAR TABLA … AÑADIR COLUMNA Si una columna ya existe genera un error, la función devuelve falso y el módulo se desactiva. Interrumpir una actualización anterior, restaurar una copia de seguridad parcial, sincronizar desde el entorno de pruebas dos veces: cualquiera de estas opciones te llevará a ese punto.

Cada cambio de esquema que escribo ahora verifica primero. Agregar una columna significa que MOSTRAR COLUMNAS de antemano, crear una tabla significa MOSTRAR MESAS, un índice significa MOSTRAR ÍNDICEUnas pocas líneas, y el script sobrevive a una segunda ejecución. Eso importa, porque la base de datos de un desconocido puede estar en cualquier estado. Hay SI NO EXISTE en ambos MySQL y MariaDB, pero solo en algunas operaciones, por lo que la verificación explícita funciona mejor.

Multitienda: filas de configuración escritas solo para una tienda

Silencioso y desagradable, este. La nueva versión incluye una configuración por tienda. La fila predeterminada fue creada por el script de actualización, probada por el desarrollador, y todo parecía correcto. Pero se generó una fila, para la tienda que estuviera en contexto, y el comerciante administra cuatro.

Tres tiendas ahora no lo tienen. Dependiendo de cómo tu código lo lea, obtendrás un aviso de PHP, un valor vacío tratado como una configuración real o un espacio en blanco donde debería haber un precio. documentación multitienda Cubre las reglas de contexto. Recorre cada ID de tienda en cualquier actualización que afecte la configuración o los datos por tienda.

En una instalación para una sola tienda, este error es invisible.

ALTER TABLE bloquea las tablas de catálogo grandes.

Agregar una columna a una tabla de 400 000 filas no es instantáneo. Dependiendo de la operación, la versión de MySQL y el motor de almacenamiento, es posible que se copie la tabla completa. En una tienda en línea, durante el horario comercial, este bloqueo se prolonga lo suficiente como para que los clientes lo noten.

Por lo tanto, verifico el tamaño de la tabla antes de escribir la migración. Si es grande: ventana de mantenimiento, o reestructurar para evitar la reconstrucción.

La clave de configuración sin valor predeterminado

Es la que veo con más frecuencia en los módulos de otras personas, y no incluye ninguna tabla.

Agregas una configuración en la nueva versión. El formulario de administración la lee. También lo hace el controlador frontal. Ambos fueron escritos en una máquina donde la página de configuración ya se había guardado al menos una vez. Por lo tanto, la clave existe y todo parece correcto. Implementa eso y cada instalación existente leerá una Configuration clave que nadie escribió jamás.

Lo que regresa es falseTu valor predeterminado nunca aparece, ni siquiera una cadena vacía que pudieras comprobar. A partir de ahí, se utiliza como un número o se pasa a una función que requiere una cadena. Con el modo de depuración desactivado, a menudo no pasa nada: el comerciante ve una página con un pequeño error y no le da importancia. Con el modo de depuración activado, aparece como un aviso o un error de tipo. Así es como te llega la noticia de que “el módulo falla en modo de depuración”, cuando el modo de depuración es la única parte honesta implicada.

El mismo código, con y sin el valor predeterminado escrito.

La solución es sencilla. Cada nueva clave de configuración tiene su valor predeterminado escrito en el script de actualización, para cada tienda, y se envía con el código que lo lee. Léalo con precaución, ya que no puede estar seguro de que la actualización se haya ejecutado correctamente.

Migración de la base de datos del módulo PrestaShop frente a cambio de esquema

Los cambios de esquema son la parte fácil. La parte difícil es cuando cambia el significado de los datos existentes: dividir una columna en dos, mover un campo CSV a una tabla relacionada, recodificar un estado.

Ahí es donde he visto el mayor daño. Un trabajo mal hecho. ALTERAR MESA Un fallo estrepitoso; una transformación de datos fallida tiene éxito y genera datos sin sentido. La migración de la base de datos de un módulo de PrestaShop requiere un recuento antes y después de la actualización, para luego compararlos. Es mejor descubrirlo dentro del script de actualización que a través de un comerciante tres semanas después.

Las mejores prácticas para la actualización del módulo PrestaShop 3.0 que yo defendería

Los que me han salvado:

Hacer que cada migración sea idempotente

Nada debería cambiar en la segunda ejecución que la primera ejecución no haya manejado ya. Obtenga esa propiedad y toda una categoría de problema de soporte desaparece, porque el estado de la base de datos deja de ser algo que necesita establecer primero. Antes de escribir SQL puro contra tablas principales, PrestaShop Notas sobre la capa de base de datos valen la pena una hora.

La versión protegida sobrevive a una segunda ejecución.

Registra cada fallo en lugar de devolver falso silenciosamente.

Un desnudo falso retorno Esto basta para que PrestaShop detenga y desactive el módulo. No es suficiente para ti. Así que encapsula el trabajo. Captura todo lo que se genere y envíalo a PrestaShopLogger con el nombre y la versión del módulo. De lo contrario, un comerciante informará de una actualización fallida y estarás adivinando.

En PHP 7 y versiones posteriores, se puede encontrar Error al igual que Excepción. Se produce un error de tipo en su propio código de migración y llega como un Error, por lo que un encargado vigila solo para Excepción lo deja pasar.

Ofrece soporte para todas las versiones que hayas lanzado.

Un comerciante puede usar cualquier versión que hayas publicado. Si alguien actualiza de la versión 1.4 a la 3.0, ejecuta todos los scripts intermedios en orden, por lo que cada uno debe trabajar con el esquema que dejó el anterior. Por eso, los archivos de actualización antiguos permanecen en el módulo. Si alguien lleva dos años de retraso, no hay otra forma de actualizar.

Prueba en un entorno de prueba, no en una instalación local limpia.

Una instalación limpia de la nueva versión no demuestra nada sobre la actualización. Lo que necesitas es instalar la versión anterior, introducir datos reales y luego actualizar. También en tiendas multidispositivo, si lo admites.

Mejor aún: toma una copia de una tienda real y realiza la actualización a través de ella. Tu instalación local tiene datos limpios y cuatro productos, por eso no muestra nada. Una tienda real contiene importaciones a medio terminar, filas dejadas por un módulo desinstalado hace dos años, columnas que un desarrollador anterior agregó a mano, un catálogo lo suficientemente grande como para… ALTERAR MESA toma un tiempo.

Luego está el momento oportuno. Es mejor aprender sobre una actualización que requiere seis minutos en comparación con datos reales al programar una ventana de mantenimiento que a las once de la mañana de un viernes.

Realice una copia de seguridad antes de que cambie el esquema y avísenos.

Antes de actualizar un módulo, no se realiza ninguna copia de seguridad de tus tablas. Ni PrestaShop ni ningún otro sistema lo hace. Por lo tanto, si el comerciante no tiene una copia de seguridad y la migración se detiene a mitad de la transformación de datos, estos se perderán. Es mejor indicarlo en el registro de cambios que descubrirlo juntos.

Cómo recuperar una actualización fallida de la base de datos de PrestaShop

Se produjo un error al actualizar una tienda en producción; el módulo se deshabilitó. Aproximadamente en este orden:

Descubre qué versión falló. Eso queda registrado, y si escribiste un mensaje de registro, también quedará ahí. Gracias a ello, sabrás qué script abrir y qué cambios se aplicaron antes de que se detuviera.

Comprueba el esquema real, no el número de versión. Todos los módulo La tabla sabe lo que escribió la última actualización exitosa. Las tablas reales son donde está la respuesta, contrastándola con lo que el script fallido intentaba hacer.

Arregla hacia adelante, no hacia atrás. Revertir la versión es tentador, pero generalmente incorrecto, ya que los scripts anteriores ya se ejecutaron y volver a ejecutarlos sobre un esquema parcialmente modificado convierte un problema en tres. Escriba una migración correctiva desde donde se encuentra el esquema hasta donde debería estar.

Luego, averigüe por qué la migración no fue idempotente. Ese es el verdadero error.

Una breve lista de verificación antes de enviar una actualización de módulo.

La lista que utilizo:

1. Versión de clase principal, la más alta actualización-*.php Archivo: ¿coinciden?
2. ¿Cada función de actualización recibe el nombre de la versión de su propio archivo?
3. ¿Se comprueba primero si un cambio de esquema ya se ha aplicado?
4. ¿Cada escritura de configuración itera sobre todas las tiendas?
5. ¿Cada nueva clave de configuración tiene un valor predeterminado para las instalaciones existentes?
6. ¿Has hecho alguna prueba contra una réplica de una tienda real?
7. ¿Versión antigua instalada, datos añadidos y luego actualizada?
8. ¿El mismo camino en varias tiendas?
9. Algo útil registrado antes de cada falso retorno?
10. Atractivo Error al igual que Excepción?
11. ¿Los archivos de actualización antiguos siguen presentes para los comerciantes que tienen varias versiones de retraso?
12. ¿El registro de cambios les indica a los comerciantes que retrocedan?
13. En una mesa grande, ¿cuánto mide eso? ALTER ¿Sujetando un candado?

Los puntos 6 y 7 son los que la gente suele saltarse, y entre ambos captan la mayor parte.

Conclusión

Actualización del módulo PrestaShop Los problemas resultan incómodos por una razón: no hay avisos. El módulo informa de su nueva versión sin problemas. La página de administración se carga. No hay registros, a menos que los hayas escrito. Mientras tanto, tu código espera una cosa, la base de datos contiene otra, y esta permanece intacta hasta que alguien utiliza la función que se encuentra en ese punto intermedio.

Trate el esquema como parte de la versión. Escriba migraciones que sobrevivan a una segunda ejecución. Registre lo que sucedió. Póngalo en el entorno de pruebas antes de que lo haga cualquier comerciante. En el lado del framework, PrestaShop documentación de desarrollo de módulos Es el lugar para comenzar.

Si tiene preguntas o necesita ayuda con el rendimiento o la migración de su sitio web, nuestros expertos están aquí para ayudarle. Póngase en contacto con el equipo de Knowband en [email protected] Hoy encontrará plugins de comercio electrónico fiables y adaptados a sus necesidades.