Tutorial de actualización de Aurora MySQL en el lugar - Amazon Aurora
Búsqueda de motivos de los errores de actualizaciónSolución de problemas para la actualización Aurora MySQL en el lugarLimpieza posterior a la actualización para Aurora MySQL versión 3

Tutorial de actualización de Aurora MySQL en el lugar

En los siguientes ejemplos de Linux se muestra cómo se pueden realizar los pasos generales del procedimiento de actualización en el lugar utilizando AWS CLI.

Este primer ejemplo crea un clúster de base de datos Aurora que ejecuta una versión 2.x de Aurora MySQL. El clúster incluye una instancia de base de datos de escritura y una instancia de base de datos de lector. El comando wait db-instance-available se detiene hasta que la instancia de base de datos del escritor esté disponible. Ese es el momento en que el clúster está listo para ser actualizado.

aws rds create-db-cluster --db-cluster-identifier mynewdbcluster --engine aurora-mysql \
  --db-cluster-version 5.7.mysql_aurora.2.10.2
...
aws rds create-db-instance --db-instance-identifier mynewdbcluster-instance1 \
  --db-cluster-identifier mynewdbcluster --db-instance-class db.t4g.medium --engine aurora-mysql
...
aws rds wait db-instance-available --db-instance-identifier mynewdbcluster-instance1

Las versiones de Aurora MySQL 3.x en las que puede actualizar el clúster dependen de la versión 2.x en la que se está ejecutando actualmente el clúster y en la Región de AWS donde se encuentra el clúster. El primer comando, con --output text, solo muestra la versión de destino disponible. El segundo comando muestra la salida JSON completa de la respuesta. En esa respuesta, puede ver detalles como el valor aurora-mysql que utiliza para el parámetro engine. También puede ver el hecho de que la actualización a 3.02.0 es una actualización de la versión principal.

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].{EngineVersion:EngineVersion}' --output text
5.7.mysql_aurora.2.10.2

aws rds describe-db-engine-versions --engine aurora-mysql --engine-version 5.7.mysql_aurora.2.10.2 \
  --query '*[].[ValidUpgradeTarget]'
...
{
    "Engine": "aurora-mysql",
    "EngineVersion": "8.0.mysql_aurora.3.02.0",
    "Description": "Aurora MySQL 3.02.0 (compatible with MySQL 8.0.23)",
    "AutoUpgrade": false,
    "IsMajorVersionUpgrade": true,
    "SupportedEngineModes": [
        "provisioned"
    ],
    "SupportsParallelQuery": true,
    "SupportsGlobalDatabases": true,
    "SupportsBabelfish": false
},
...

En este ejemplo, se muestra que si ingresa un número de versión de destino que no es un destino de actualización válido para el clúster, Aurora no realiza la actualización. Aurora tampoco realiza una actualización de versión principal, a menos que incluya el parámetro --allow-major-version-upgrade. De esta manera, no puede realizar accidentalmente una actualización que tenga el potencial de requerir pruebas exhaustivas y cambios en el código de su aplicación.

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 5.7.mysql_aurora.2.09.2 --apply-immediately
An error occurred (InvalidParameterCombination) when calling the ModifyDBCluster operation: Cannot find upgrade target from 5.7.mysql_aurora.2.10.2 with requested version 5.7.mysql_aurora.2.09.2.

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 8.0.mysql_aurora.3.02.0 --region us-east-1 --apply-immediately
An error occurred (InvalidParameterCombination) when calling the ModifyDBCluster operation: The AllowMajorVersionUpgrade flag must be present when upgrading to a new major version.

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 8.0.mysql_aurora.3.02.0 --apply-immediately --allow-major-version-upgrade
{
  "DBClusterIdentifier": "mynewdbcluster",
  "Status": "available",
  "Engine": "aurora-mysql",
  "EngineVersion": "5.7.mysql_aurora.2.10.2"
}

El estado del clúster y las instancias de base de datos asociadas tardan unos minutos en cambiar a upgrading. Los números de versión del clúster y de las instancias de base de datos solo cambian cuando finaliza la actualización. De nuevo, puede utilizar el comando wait db-instance-available para que la instancia de base de datos de escritor espere hasta que finalice la actualización antes de continuar. 

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].[Status,EngineVersion]' --output text
upgrading 5.7.mysql_aurora.2.10.2

aws rds describe-db-instances --db-instance-identifier mynewdbcluster-instance1 \
  --query '*[].{DBInstanceIdentifier:DBInstanceIdentifier,DBInstanceStatus:DBInstanceStatus} | [0]'
{
    "DBInstanceIdentifier": "mynewdbcluster-instance1",
    "DBInstanceStatus": "upgrading"
}

aws rds wait db-instance-available --db-instance-identifier mynewdbcluster-instance1

En este punto, el número de versión del clúster coincide con el especificado para la actualización. 

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].[EngineVersion]' --output text

8.0.mysql_aurora.3.02.0

En el ejemplo anterior se realizó una actualización inmediata especificando el parámetro --apply-immediately. Para permitir que la actualización se realice en un momento conveniente cuando no se espera que el clúster esté ocupado, puede especificar el parámetro --no-apply-immediately. Al hacerlo, la actualización se iniciará durante la siguiente ventana de mantenimiento del clúster. La ventana de mantenimiento define el período durante el cual se pueden iniciar las operaciones de mantenimiento. Es posible que una operación de larga duración no finalice durante el período de mantenimiento. Por lo tanto, no necesita definir una ventana de mantenimiento más grande, incluso si espera que la actualización pueda tardar mucho tiempo.

En el ejemplo siguiente, se actualiza un clúster que ejecuta inicialmente Aurora MySQL 2.10.2. En la salida de describe-db-engine-versions, los valores False y True representan la propiedad IsMajorVersionUpgrade. Desde la versión 2.10.2, puede actualizar a otras versiones 2.*. Esas actualizaciones no se consideran actualizaciones de versión principales, por lo que no requieren una actualización in situ. La actualización local solo está disponible para las actualizaciones a las versiones 3.* que se muestran en la lista.

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].{EngineVersion:EngineVersion}' --output text
5.7.mysql_aurora.2.10.2

aws rds describe-db-engine-versions --engine aurora-mysql --engine-version 5.7.mysql_aurora.2.10.2 \
  --query '*[].[ValidUpgradeTarget]|[0][0]|[*].[EngineVersion,IsMajorVersionUpgrade]' --output text

5.7.mysql_aurora.2.10.3 False
5.7.mysql_aurora.2.11.0 False
5.7.mysql_aurora.2.11.1 False
8.0.mysql_aurora.3.01.1 True
8.0.mysql_aurora.3.02.0 True
8.0.mysql_aurora.3.02.2 True


aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 8.0.mysql_aurora.3.02.0 --no-apply-immediately --allow-major-version-upgrade
...

Cuando se crea un clúster sin una ventana de mantenimiento especificada, Aurora selecciona un día aleatorio de la semana. En este caso, el comando modify-db-cluster se envía un lunes. Por lo tanto, cambiamos la ventana de mantenimiento para que sea el martes por la mañana. Todas las horas se representan en la zona horaria UTC. El periodo tue:10:00-tue:10:30 se corresponde a las 2:00-2:30 h, hora del Pacífico. El cambio en la ventana de mantenimiento surte efecto inmediatamente.

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster --query '*[].[PreferredMaintenanceWindow]'
[
    [
        "sat:08:20-sat:08:50"
    ]
]

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster --preferred-maintenance-window tue:10:00-tue:10:30"
aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster --query '*[].[PreferredMaintenanceWindow]'
[
    [
        "tue:10:00-tue:10:30"
    ]
]

En el siguiente ejemplo se muestra cómo obtener un informe de los eventos generados por la actualización. El argumento --duration representa el número de minutos para recuperar la información del evento. Este argumento es necesario porque, de forma predeterminada, describe-events solo devuelve eventos de la última hora.

aws rds describe-events --source-type db-cluster --source-identifier mynewdbcluster --duration 20160
{
    "Events": [
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "DB cluster created",
            "EventCategories": [
                "creation"
            ],
            "Date": "2022-11-17T01:24:11.093000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Performing online pre-upgrade checks.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T22:57:08.450000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Performing offline pre-upgrade checks.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T22:57:59.519000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Creating pre-upgrade snapshot [preupgrade-mynewdbcluster-5-7-mysql-aurora-2-10-2-to-8-0-mysql-aurora-3-02-0-2022-11-18-22-55].",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:00:22.318000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Cloning volume.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:01:45.428000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Purging undo records for old row versions. Records remaining: 164",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:02:25.141000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Purging undo records for old row versions. Records remaining: 164",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:06:23.036000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Upgrading database objects.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:06:48.208000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster major version has been upgraded",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:10:28.999000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        }
    ]
}

Búsqueda de motivos de los errores de actualización

En el tutorial anterior, la actualización de Aurora MySQL versión 2 a la versión 3 se realizó correctamente. Pero si la actualización hubiera fallado, querría saber por qué.

Puede empezar por utilizar el comando describe-events de la AWS CLI para ver los eventos del clúster de base de datos. En este ejemplo, se muestran los eventos de mydbcluster de las últimas 10 horas.

aws rds describe-events \
    --source-type db-cluster \
    --source-identifier mydbcluster \
    --duration 600

En este caso, se produjo un error en la comprobación previa de la actualización.

{
    "Events": [
        {
            "SourceIdentifier": "mydbcluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster engine version upgrade started.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2024-04-11T13:23:22.846000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster"
        },
        {
            "SourceIdentifier": "mydbcluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster is in a state that cannot be upgraded: Upgrade prechecks failed. For more details, see the  
             upgrade-prechecks.log file. For more information on troubleshooting the cause of the upgrade failure, see 
             https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.MajorVersionUpgrade.html#AuroraMySQL.Upgrading.Troubleshooting.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2024-04-11T13:23:24.373000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster"
        }
    ]
}

Para diagnosticar la causa exacta del problema, examine los registros de la base de datos de la instancia de base de datos de escritor. Cuando se produce un fallo en una actualización a Aurora MySQL versión 3, la instancia de escritor contiene un archivo de registro con el nombre upgrade-prechecks.log. En este ejemplo se muestra cómo detectar la presencia de ese registro y, luego, descargarlo en un archivo local para su análisis.

aws rds describe-db-log-files --db-instance-identifier mydbcluster-instance \
    --query '*[].[LogFileName]' --output text

error/mysql-error-running.log
error/mysql-error-running.log.2024-04-11.20
error/mysql-error-running.log.2024-04-11.21
error/mysql-error.log
external/mysql-external.log
upgrade-prechecks.log

aws rds download-db-log-file-portion --db-instance-identifier mydbcluster-instance \
    --log-file-name upgrade-prechecks.log \
    --starting-token 0 \
    --output text >upgrade_prechecks.log

El archivo upgrade-prechecks.log está en formato JSON. Lo descargamos con la opción --output text para evitar codificar la salida JSON dentro de otro contenedor JSON. Para las actualizaciones a la versión 3 de Aurora MySQL, este registro siempre incluye ciertos mensajes informativos y de advertencia. Solo incluye mensajes de error si no se puede actualizar. Si se actualiza correctamente, el archivo de registro ya no se produce.

Para resumir todos los errores y mostrar los campos de objeto y descripción asociados, puede ejecutar el comando grep -A 2 '"level": "Error"' en el contenido del archivo upgrade-prechecks.log. Al hacerlo, se muestra cada línea de error y las dos líneas posteriores. Estas contienen el nombre del objeto de base de datos correspondiente e instrucciones sobre cómo corregir el problema.

$ cat upgrade-prechecks.log | grep -A 2 '"level": "Error"'

"level": "Error",
"dbObject": "problematic_upgrade.dangling_fulltext_index",
"description": "Table `problematic_upgrade.dangling_fulltext_index` contains dangling FULLTEXT index. Kindly recreate the table before upgrade."

En este ejemplo, puede ejecutar el siguiente comando de SQL en la tabla infractora para intentar solucionar el problema, o bien puede volver a crear la tabla sin el índice pendiente.

OPTIMIZE TABLE problematic_upgrade.dangling_fulltext_index;

A continuación, vuelva a intentar la actualización.

Solución de problemas para la actualización Aurora MySQL en el lugar

Utilice las siguientes sugerencias para solucionar problemas con las actualizaciones in situ de Aurora MySQL. Estas sugerencias no se aplican a los clústeres de base de datos de Aurora Serverless.

Motivo por el que la actualización en el lugar se cancela o se ralentiza Efecto Solución para permitir que la actualización en el lugar se complete dentro de la ventana de mantenimiento
La réplica entre regiones de Aurora asociadas aún no cuenta con revisión Aurora cancela la actualización. Actualice la réplica entre regiones de Aurora e inténtelo de nuevo.
El clúster tiene transacciones XA en el estado preparado Aurora cancela la actualización. Confirme o revierta todas las transacciones XA preparadas.
El clúster está procesando cualquier declaración de lenguaje de definición de datos (DDL) Aurora cancela la actualización. Considere la posibilidad de esperar y realizar la actualización una vez finalizadas todas las instrucciones DDL.
El clúster tiene cambios no confirmados para muchas filas Esto puede llevar mucho tiempo.

El proceso de actualización revierte los cambios no confirmados. El indicador para esta condición es el valor de TRX_ROWS_MODIFIED en la INFORMATION_SCHEMA.INNODB_TRX tabla.

Considere la posibilidad de realizar la actualización solo después de que todas las transacciones grandes se hayan confirmado o deshecho.
El clúster tiene un gran número de registros de deshacer Esto puede llevar mucho tiempo.

Incluso si las transacciones no confirmadas no afectan a un gran número de filas, pueden implicar un gran volumen de datos. Por ejemplo, puede que esté insertando BLOBs grandes. Aurora no detecta ni genera automáticamente un evento para este tipo de actividad de transacción. El indicador de esta condición es la longitud de la lista de historial (HLL). El proceso de actualización revierte los cambios no confirmados.

Puede comprobar el HLL en la salida del comando SQL SHOW ENGINE INNODB STATUS o directamente mediante la siguiente consulta SQL:

SELECT count FROM information_schema.innodb_metrics WHERE name = 'trx_rseg_history_len';

También puede monitorizar la métrica RollbackSegmentHistoryListLength en Amazon CloudWatch.

Considere la posibilidad de realizar la actualización solo después de que la HLL sea menor.
El clúster está en el proceso de confirmar una transacción de registro binario grande Esto puede llevar mucho tiempo.

El proceso de actualización espera hasta que se apliquen los cambios en el registro binario. Más transacciones o instrucciones DDL podrían comenzar durante este período, lo que ralentiza aún más el proceso de actualización.

Programe el proceso de actualización cuando el clúster no esté ocupado con la generación de cambios de reproducción de registros binarios. Aurora no detecta ni genera automáticamente un evento para esta condición.
Inconsistencias en el esquema causadas por la eliminación o la corrupción de un archivo Aurora cancela la actualización.

Cambie el motor de almacenamiento predeterminado para las tablas temporales de MyISAM a InnoDB. Siga estos pasos:

  1. Modifique el parámetro de base de datos default_tmp_storage_engine por InnoDB.

  2. Reinicie el clúster de base de datos.

  3. Tras reiniciar, confirme que el parámetro de base de datos default_tmp_storage_engine se haya establecido en InnoDB. Utilice el siguiente comando:

    show global variables like 'default_tmp_storage_engine';

  4. Asegúrese de no crear ninguna tabla temporal que utilice el motor de almacenamiento MyISAM. Le recomendamos que ponga en pausa la carga de trabajo de la base de datos y no cree ninguna conexión nueva a la base de datos, ya que la actualizará pronto.

  5. Vuelva a intentar la actualización in situ.
Se ha eliminado el usuario maestro Aurora cancela la actualización.
importante

No elimine el usuario maestro.

Sin embargo, si por alguna razón elimina el usuario maestro, restáurelo mediante los siguientes comandos SQL:

CREATE USER 'master_username'@'%' IDENTIFIED BY 'master_user_password' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK;

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, PROCESS, REFERENCES, INDEX, ALTER, SHOW DATABASES, CREATE TEMPORARY TABLES, 
LOCK TABLES, EXECUTE, REPLICATION SLAVE, REPLICATION CLIENT, CREATE VIEW, SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, CREATE USER, EVENT, 
TRIGGER, LOAD FROM S3, SELECT INTO S3, INVOKE LAMBDA, INVOKE SAGEMAKER, INVOKE COMPREHEND ON *.* TO 'master_username'@'%' WITH GRANT OPTION;

Para obtener más información sobre la solución de problemas que provocan el error de las comprobaciones previas a la actualización, consulte los siguientes blogs:

Puede utilizar los siguientes pasos para realizar sus propias comprobaciones de algunas de las condiciones de la tabla anterior. De esta forma, puede programar la actualización en un momento en que sepa que la base de datos se encuentra en un estado en el que la actualización puede completarse correctamente y rápidamente.

  • Puede comprobar si hay transacciones XA abiertas ejecutando la instrucción XA RECOVER. A continuación, puede confirmar o revertir las transacciones XA antes de iniciar la actualización.

  • Puede comprobar si hay instrucciones DDL ejecutando una instrucción SHOW PROCESSLIST y buscando las instrucciones CREATE, DROP, ALTER, RENAME y TRUNCATE en la salida. Permita que todas las instrucciones DDL finalicen antes de iniciar la actualización.

  • Puede comprobar el número total de filas no confirmadas consultando la tabla INFORMATION_SCHEMA.INNODB_TRX. La tabla contiene una fila para cada transacción. La columna TRX_ROWS_MODIFIED contiene el número de filas modificadas o insertadas por la transacción.

  • Puede verificar la longitud de la lista de historial de InnoDB ejecutando la instrucción SHOW ENGINE INNODB STATUS SQL y buscando el History list length en la salida. También puede comprobar el valor directamente ejecutando la siguiente consulta: 

    SELECT count FROM information_schema.innodb_metrics WHERE name = 'trx_rseg_history_len';

    La longitud de la lista de historial corresponde a la cantidad de información de deshacer almacenada por la base de datos para implementar el control de concurrencia multiversión (MVCC).

Limpieza posterior a la actualización para Aurora MySQL versión 3

Una vez que haya terminado de actualizar cualquier clúster de Aurora MySQL versión 2 a Aurora MySQL versión 3, puede realizar estas otras acciones de limpieza:

  • Cree nuevas versiones compatibles con MySQL 8.0 de cualquier grupo de parámetros personalizados. Aplique los valores de parámetros personalizados necesarios a los nuevos grupos de parámetros.

  • Actualice las alarmas de CloudWatch, los scripts de configuración, etc. para utilizar los nuevos nombres para cualquier métrica cuyos nombres se hayan visto afectados por cambios de idioma inclusivos. Para ver una lista de estas métricas, consulte Cambios de idioma inclusivos para Aurora MySQL versión 3.

  • Actualice cualquier plantilla AWS CloudFormation para utilizar los nuevos nombres para cualquier parámetro de configuración cuyos nombres se hayan visto afectados por cambios de idioma inclusivos. Para obtener una lista completa de estos parámetros, consulte Cambios de idioma inclusivos para Aurora MySQL versión 3.

Índices espaciales

Después de actualizar a Aurora MySQL versión 3, verifique si necesita eliminar o volver a crear objetos e índices relacionados con los índices espaciales. Antes de MySQL 8.0, Aurora podía optimizar las consultas espaciales utilizando índices que no contenían un identificador de recursos espaciales (SRID). Aurora MySQL versión 3 solo utiliza índices espaciales que contienen SRID. Durante una actualización, Aurora elimina automáticamente cualquier índice espacial sin SRID e imprime mensajes de advertencia en el registro de la base de datos. Si observa estos mensajes de advertencia, cree nuevos índices espaciales con SRID después de la actualización. Para obtener más información sobre los cambios en las funciones espaciales y los tipos de datos de MySQL 8.0, consulte Cambios en MySQL 8.0 en el Manual de referencia de MySQL.